@polymorphism-tech/morph-spec 8.4.0 → 8.6.0

package/src/core/state/state-manager.js

@@ -123,7 +123,7 @@ export function atomicWriteJson(targetPath, data) {
  * A formatting mismatch is NOT free, though: the guard compares bytes, so a
  * sibling committed with a trailing newline fails it and gets rewritten. The
  * content is equivalent, but git sees ` M` on a file this caller never meant to
- * touch — enough to fail a whole-tree clean check (see worktreeFinishCommand).
+ * touch — enough to fail a whole-tree clean check (see the finish teardown's clearRootWorktreeRegistration).
  * And the guard only skips IDENTICAL content: a concurrent instance's CHANGED
  * write to a sibling would still be clobbered by the sweep.
  */
@@ -373,7 +373,7 @@ export function saveState(state) {
   //    and shows up as ` M` — dirtying the tree on behalf of a feature the
   //    caller never touched. Callers that need to change ONE feature's field
   //    should write that feature.json directly instead of round-tripping state
-  //    through here (see worktreeFinishCommand's registration cleanup).
+  //    through here (see the finish teardown's clearRootWorktreeRegistration).
   const thinFeatures = {};
   for (const [name, feature] of Object.entries(features)) {
     writeFeatureJson(name, feature);

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

@@ -35,7 +35,7 @@ export function scanState(projectDir) {
   // (.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
-  // `worktree finish`. This is read-only visibility for the dashboard — root
+  // `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.

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/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)'],
@@ -111,8 +113,8 @@ function nextAction(feature, phase, tasks, featureName) {
     }
     case 'review':
       return approved('review')
-        ? `Gate 3 aprovado — feche: \`morph-spec worktree finish ${featureName}\` e depois \`morph-spec archive ${featureName}\` na raiz.`
-        : `Produza \`4-review/review-report.md\` (avaliador independente) e aprove o Gate 3; depois \`worktree finish\` + \`archive\`.`;
+        ? `Gate 3 aprovado — feche: \`morph-spec finish ${featureName} --pr\` (abre PR) ou \`--merge\` (merge local na default). Arquiva + integra num passo.`
+        : `Produza \`4-review/review-report.md\` (avaliador independente) e aprove o Gate 3; depois \`morph-spec finish ${featureName} --pr|--merge\`.`;
     default:
       return `Rode \`morph-spec status ${featureName}\` para orientar o próximo passo.`;
   }

package/src/lib/git/default-branch.js

@@ -0,0 +1,73 @@
+import { execFileSync } from 'child_process';
+
+/**
+ * Git helpers shared by `create` (which branches `morph/{f}` off the default)
+ * and `finish` (which merges/PRs back into it). Kept tiny and pure so both
+ * call sites read the same source of truth for "what is the default branch"
+ * and "is there a remote to push to".
+ */
+
+/**
+ * Does a local branch exist? execFile (argv, never a cmd.exe string) so the
+ * name reaches git as one token — the same anti-injection discipline the rest
+ * of the worktree/finish path uses.
+ *
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function localBranchExists(branch, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the repository's default branch NAME (e.g. `main`), never assuming
+ * `master`. Strategy, in order:
+ *   1. `refs/remotes/origin/HEAD` symbolic ref — the remote's declared default,
+ *      the authoritative answer when a remote is configured.
+ *   2. A local `main`, then `master` — the fallback for a repo with no remote
+ *      (or one whose `origin/HEAD` was never set).
+ *
+ * Returns `null` when none of these resolve (a repo whose default is some other
+ * name, with no `origin/HEAD` set) — the caller decides: `create` fails open
+ * (no branch), `finish` refuses with a clear message.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null} the default branch name, or null if undeterminable
+ */
+export function detectDefaultBranch(cwd = process.cwd()) {
+  try {
+    const ref = execFileSync('git', ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], { cwd, stdio: 'pipe' })
+      .toString()
+      .trim();
+    // e.g. "refs/remotes/origin/main" → "main"
+    const m = ref.match(/^refs\/remotes\/origin\/(.+)$/);
+    if (m && m[1]) return m[1];
+  } catch { /* no origin/HEAD — fall back to a local default */ }
+
+  for (const candidate of ['main', 'master']) {
+    if (localBranchExists(candidate, cwd)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Is an `origin` remote configured? `--pr` needs one to push the feature branch;
+ * `--merge` is purely local and never calls this.
+ *
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+export function hasOriginRemote(cwd = process.cwd()) {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, stdio: 'pipe' }).toString().trim();
+    return url.length > 0;
+  } catch {
+    return false;
+  }
+}

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 };

package/src/lib/worktree/env-allocator.js

@@ -14,7 +14,7 @@
  * worktree of the repo shares.
  *
  * Allocation is deterministic (first free index), idempotent per feature, and
- * released only when `worktree finish` actually removed the worktree. Writes
+ * released only when `morph-spec finish` actually removed the worktree. Writes
  * are tmp+rename so a crash never leaves a torn registry; a corrupt registry
  * is treated as empty (fail-open — the cost is a re-allocation, never a crash).
  */

package/src/utils/file-copier.js

@@ -225,7 +225,7 @@ export async function updateGitignore(projectPath) {
  * Windows with `core.autocrlf=true` (the Git-for-Windows default) and no
  * attribute pinning EOL, Git flags EVERY rewritten feature.json as modified
  * even when the content is byte-identical. That silently breaks the whole-root
- * clean-check in `morph-spec worktree finish` as soon as a project has more
+ * clean-check in `morph-spec finish` as soon as a project has more
  * than one feature — precisely the multi-instance / parallel-worktree flow,
  * where one `saveState` touches sibling feature.json files and marks them dirty.
  * This mirrors the .gitattributes this framework repo already carries for its
@@ -242,7 +242,7 @@ export async function ensureGitattributes(projectPath) {
     `${MARKER} — LF-pin morph state so core.autocrlf never churns it`,
     '# (feature.json is committed + rewritten by saveState with LF; without this,',
     '#  Windows autocrlf marks every feature.json dirty and breaks the whole-root',
-    '#  clean-check in `morph-spec worktree finish`).',
+    '#  clean-check in `morph-spec finish`).',
     '.morph/** text=auto eol=lf',
   ];