@polymorphism-tech/morph-spec 8.22.0 → 8.24.1

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

@@ -0,0 +1,237 @@
+/**
+ * usecase-registry.js — atomic, cross-worktree UC-{nn} number allocation.
+ *
+ * Two parallel worktrees planning at the same time each read the acervo
+ * (`.morph/specs/usecases/`) plus their OWN feature's `2-plan/usecases/`, take
+ * the max `UC-{nn}` and add one — but a worktree only ever sees its OWN tree.
+ * Sibling features' use cases live in SIBLING worktrees (feature.json and every
+ * UC file travel on the branch, not through any shared filesystem). Two
+ * worktrees both computing max+1 from the same stale max both mint `UC-07` —
+ * and at promotion time `usecase-promoter.js` overwrites by ID: the SECOND
+ * feature to close silently destroys the FIRST one's use case. A user lost
+ * work this way in production.
+ *
+ * This module closes the gap the same way `env-allocator.js` (port blocks) and
+ * `claim-registry.js` (feature ownership) already do: a registry file under the
+ * git COMMON dir, the one location every linked worktree of a repo shares —
+ * `<git-common-dir>/morph-spec/uc-registry.json`. Writes are tmp+rename; a
+ * corrupt registry reads as empty (fail-open — the cost is a re-seed from disk,
+ * never a crash).
+ *
+ * Unlike the other two registries, correctness here cannot be advisory: the
+ * whole point is that two concurrent callers must never receive the same
+ * number. `env-allocator`/`claim-registry` key by FEATURE, so two different
+ * features racing never contend for the same key; two worktrees reserving UC
+ * numbers race for the SAME counter. So allocation runs inside a real mutual
+ * exclusion lock (`uc-registry.lock`, `open(..., 'wx')` — atomic create-if-absent
+ * on every platform Node targets, including Windows) instead of the bare
+ * read-modify-write the other two registries use.
+ *
+ * No git (no common dir resolvable): falls back to a project-local registry
+ * under `.morph/logs/` (already gitignored) — this still prevents a single
+ * session from reserving the same number twice across repeated calls, but
+ * carries none of the cross-worktree guarantee. Callers must surface that
+ * degradation to the user.
+ */
+
+import {
+  closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
+  renameSync, statSync, unlinkSync, writeFileSync,
+} from 'fs';
+import { join } from 'path';
+
+/** A UC filename's leading `UC-{nn}` — deliberately NOT imported from
+ * `usecase-promoter.js`: that module will come to depend on THIS one (to look
+ * up who reserved a given number), and a two-way import would be circular. */
+const UC_ID_RE = /^(UC-(\d+))-/;
+
+/** `UC-7` (or any width) -> `UC-07` — the archive's zero-padded convention. */
+function formatUcId(n) {
+  return `UC-${String(n).padStart(2, '0')}`;
+}
+
+/** Directory holding both the registry file and its lock. */
+export function registryDir({ gitCommonDir, cwd }) {
+  return gitCommonDir ? join(gitCommonDir, 'morph-spec') : join(cwd, '.morph', 'logs');
+}
+
+/** Registry file path — shared (git common dir) or local-fallback (no git). */
+export function ucRegistryPath({ gitCommonDir, cwd }) {
+  return join(registryDir({ gitCommonDir, cwd }), 'uc-registry.json');
+}
+
+function readRegistry(path) {
+  try {
+    const raw = readFileSync(path, 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.reservations === 'object' && parsed.reservations !== null) {
+      return {
+        version: 1,
+        counter: Number.isInteger(parsed.counter) ? parsed.counter : 0,
+        reservations: parsed.reservations,
+      };
+    }
+  } catch { /* fail-open: absent or corrupt registry restarts empty */ }
+  return { version: 1, counter: 0, reservations: {} };
+}
+
+function writeRegistry(path, registry) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/** Synchronous sleep — Node (unlike browsers) allows `Atomics.wait` on the main thread. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Run `fn` while holding an exclusive filesystem lock at `lockPath`.
+ *
+ * `openSync(path, 'wx')` is `O_CREAT | O_EXCL` — atomic create-or-fail, the
+ * only primitive this needs and one that behaves identically on POSIX and
+ * Windows. A lock file whose mtime is older than `staleMs` is assumed to be
+ * left behind by a crashed process and is force-recovered — an orphaned lock
+ * must never strand every future reservation.
+ *
+ * @param {string} lockPath
+ * @param {() => T} fn
+ * @returns {T}
+ * @template T
+ */
+function withLock(lockPath, fn, { timeoutMs = 5000, pollMs = 20, staleMs = 15000 } = {}) {
+  mkdirSync(join(lockPath, '..'), { recursive: true });
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let fd;
+    try {
+      fd = openSync(lockPath, 'wx');
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const st = statSync(lockPath);
+        if (Date.now() - st.mtimeMs > staleMs) {
+          try { unlinkSync(lockPath); } catch { /* raced someone else's cleanup */ }
+          continue; // retry immediately — the stale lock is (probably) gone now
+        }
+      } catch { continue; } // lock vanished between openSync and statSync — retry
+      if (Date.now() >= deadline) {
+        throw new Error(`usecase-registry: could not acquire lock at ${lockPath} within ${timeoutMs}ms`);
+      }
+      sleepSync(pollMs);
+      continue;
+    }
+    try {
+      closeSync(fd);
+      return fn();
+    } finally {
+      try { unlinkSync(lockPath); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/** Highest `UC-{nn}` number found among files matching the pattern in `dir`. 0 if none/unreadable. */
+function maxUcNumberInDir(dir) {
+  let max = 0;
+  try {
+    if (!existsSync(dir)) return 0;
+    for (const name of readdirSync(dir)) {
+      const m = UC_ID_RE.exec(name);
+      if (!m) continue;
+      const n = parseInt(m[2], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  } catch { /* unreadable dir — treat as empty, never fatal */ }
+  return max;
+}
+
+/** Highest UC number across every feature's `2-plan/usecases/`, under both `.morph/features/` and `.morph/archive/`, in THIS tree. */
+function maxUcNumberLocalTree(cwd) {
+  let max = 0;
+  for (const bucket of ['features', 'archive']) {
+    const bucketDir = join(cwd, '.morph', bucket);
+    try {
+      if (!existsSync(bucketDir)) continue;
+      for (const entry of readdirSync(bucketDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        max = Math.max(max, maxUcNumberInDir(join(bucketDir, entry.name, '2-plan', 'usecases')));
+      }
+    } catch { /* unreadable bucket — treat as empty */ }
+  }
+  return max;
+}
+
+/**
+ * The highest UC number this project tree can see right now: the permanent
+ * acervo, plus every feature (active OR archived-but-not-yet-promoted, see
+ * `usecase-promoter.js`'s refusal path) in THIS tree. Exported for tests and
+ * for callers that want to preview the seed without reserving anything.
+ *
+ * @param {string} cwd
+ * @returns {number}
+ */
+export function scanLocalMax(cwd) {
+  const acervoMax = maxUcNumberInDir(join(cwd, '.morph', 'specs', 'usecases'));
+  return Math.max(acervoMax, maxUcNumberLocalTree(cwd));
+}
+
+/**
+ * Atomically reserve the next `count` UC numbers, shared across every worktree
+ * of this repo when a git common dir is resolvable.
+ *
+ * The seed is recomputed on EVERY call as `max(registry.counter, scanLocalMax(cwd))`
+ * — monotonic by construction (a max can only grow), so this doubles as both
+ * "seed the counter on the first-ever reservation" and "never regress even if
+ * the registry were somehow behind disk" without needing a separate seeded flag.
+ *
+ * @param {string} cwd
+ * @param {{ feature?: string|null, count?: number, gitCommonDir?: string|null }} opts
+ * @returns {{ numbers: string[], base: number, count: number, shared: boolean, registryPath: string }}
+ */
+export function reserveUseCases(cwd, { feature = null, count = 1, gitCommonDir = null } = {}) {
+  const n = Number.isInteger(count) && count > 0 ? count : 1;
+  const dir = registryDir({ gitCommonDir, cwd });
+  const path = ucRegistryPath({ gitCommonDir, cwd });
+  mkdirSync(dir, { recursive: true });
+
+  return withLock(join(dir, 'uc-registry.lock'), () => {
+    const registry = readRegistry(path);
+    const base = Math.max(registry.counter || 0, scanLocalMax(cwd));
+
+    // Test-only: widen the critical section so a concurrency test can prove
+    // two REAL processes racing for this lock actually serialize, instead of
+    // just happening not to overlap. Mirrors `finish.js`'s MORPH_GH_BIN test
+    // injection. Unset in every real invocation.
+    const testDelay = Number.parseInt(process.env.MORPH_UC_RESERVE_TEST_DELAY_MS, 10);
+    if (Number.isFinite(testDelay) && testDelay > 0) sleepSync(testDelay);
+
+    const numbers = [];
+    const now = new Date().toISOString();
+    for (let i = 1; i <= n; i += 1) {
+      const id = formatUcId(base + i);
+      numbers.push(id);
+      registry.reservations[id] = { feature: feature || null, reservedAt: now };
+    }
+    registry.counter = base + n;
+    writeRegistry(path, registry);
+
+    return { numbers, base, count: n, shared: !!gitCommonDir, registryPath: path };
+  });
+}
+
+/**
+ * Which feature (if any) holds the reservation for a given `UC-{nn}` id.
+ * Read-only — no lock, a slightly stale read is harmless for this use (the
+ * promoter's collision backstop, never the allocation itself).
+ *
+ * @param {string} id - e.g. "UC-07"
+ * @param {{ cwd: string, gitCommonDir?: string|null }} opts
+ * @returns {string|null}
+ */
+export function reservationOwner(id, { cwd, gitCommonDir = null }) {
+  const path = ucRegistryPath({ gitCommonDir, cwd });
+  const registry = readRegistry(path);
+  return registry.reservations?.[id]?.feature ?? null;
+}

package/src/lib/validators/traceability-check.js

@@ -0,0 +1,198 @@
+/**
+ * traceability-check.js — advisory, feature-scope-only check: do the files
+ * cited in recap.md's "**Files:**" bullet lists have an owning task in
+ * tasks.json's `outputs`?
+ *
+ * This is the DETERMINISTIC half of a two-layer fix. The NLH half lives in
+ * `framework/skills/core/morph-implement/SKILL.md` §7 ("outputs DEVE listar
+ * TODO arquivo criado ou modificado pela task") and targets the root cause: a
+ * file shipped without EVER being declared anywhere (not in outputs, not in
+ * recap.md — the real-world case that motivated this module, see the finding
+ * below). This module cannot catch THAT class of drift — a file absent from
+ * both documents is invisible to a check that only compares the two documents
+ * against each other. What it DOES catch is a narrower, complementary class:
+ * recap.md and tasks.json DISAGREEING — an author cited a file in the recap's
+ * prose but forgot (or a later task re-touched it without) declaring it in any
+ * task's `outputs`. That disagreement is real signal even though it is not the
+ * same defect the SKILL.md rule targets.
+ *
+ * Motivating evidence: run 2026-08-12T133732Z-vet-visit-followup-reminder —
+ * `ApplicationDbContextFactory.cs` shipped in production with no owning task
+ * in `outputs` AND no mention in recap.md (out of this module's reach by
+ * construction). Separately, `src/VetClinic.Api/appsettings.json` and
+ * `Properties/launchSettings.json` WERE cited in T1's recap `**Files:**` list
+ * but never appear in any task's `outputs` — exactly the disagreement this
+ * module flags.
+ *
+ * Advisory, never blocking: the returned `status` is only ever 'pass' | 'warn'
+ * | 'skip' — never 'fail'. `runVerify()` keeps this result OUTSIDE `nodes` on
+ * purpose so it can never flip the overall build/tests/validators/e2e status
+ * computed from `nodes` alone (see verify-runner.js).
+ *
+ * Fail-open throughout: no recap.md, no tasks.json, or a parse error all
+ * degrade to `{ status: 'skip' }` rather than throwing or warning about the
+ * absence itself — this is rastreabilidade tooling, not a completeness gate.
+ *
+ * @module traceability-check
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+/** Matches a `**Files:**` marker followed by one or more `- ` bullet lines. */
+const FILES_BLOCK_RE = /\*\*Files:\*\*[ \t]*\r?\n((?:^[ \t]*-[ \t].*\r?\n?)+)/gm;
+
+/** Backtick-quoted spans within a bullet line. */
+const BACKTICK_RE = /`([^`]+)`/g;
+
+/**
+ * Extract the set of file paths cited under every "**Files:**" block in a
+ * recap.md's text, applying a conservative decomposition of the natural
+ * language shorthand real recaps use:
+ *
+ *   - A line with exactly one backtick span: that span is a candidate,
+ *     whether or not it contains a `/` (a legitimate top-level file, e.g.
+ *     `` `VetClinic.sln` ``, has no slash).
+ *   - A line with multiple comma-separated backtick spans (e.g.
+ *     `` `a/b.json`, `c.json`, `d/e.json` ``): only the FIRST span and any
+ *     LATER span that itself contains `/` are candidates. A later span with
+ *     no `/` is ambiguous shorthand (a bare filename implicitly relative to
+ *     the first span's directory, or a suffix like `` `.Designer.cs` ``) and
+ *     is skipped rather than guessed — false negatives are the acceptable
+ *     failure mode for advisory tooling, false positives are not.
+ *   - Any span containing `{`/`}` (brace-expansion shorthand, e.g.
+ *     `` `Foo/{A,B,C}.cs` ``) is skipped entirely — decomposing it correctly
+ *     would require guessing at delimiters this format doesn't standardize.
+ *   - Any span ending in `/` is a directory reference, not a file — skipped.
+ *
+ * @param {string} recapText
+ * @returns {string[]} de-duplicated, normalized (forward-slash) candidate paths
+ */
+export function extractCitedFiles(recapText) {
+  const cited = new Set();
+  if (!recapText) return [];
+
+  FILES_BLOCK_RE.lastIndex = 0;
+  let blockMatch;
+  while ((blockMatch = FILES_BLOCK_RE.exec(recapText)) !== null) {
+    const block = blockMatch[1];
+    const lines = block.split(/\r?\n/).filter((l) => /^[ \t]*-[ \t]/.test(l));
+
+    for (const line of lines) {
+      const spans = [...line.matchAll(BACKTICK_RE)].map((m) => m[1].trim()).filter(Boolean);
+      spans.forEach((span, idx) => {
+        if (idx > 0 && !span.includes('/')) return; // ambiguous shorthand continuation
+        if (span.includes('{') || span.includes('}')) return; // brace-expansion, too ambiguous to decompose
+        if (span.endsWith('/')) return; // directory reference, not a file
+        cited.add(normalizePath(span));
+      });
+    }
+  }
+
+  return [...cited];
+}
+
+/** Backslashes to forward slashes, strip a leading `./`. */
+function normalizePath(p) {
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * Union of `outputs` across every `done` task in tasks.json, normalized.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {string[]|null} null when tasks.json is missing/unreadable/invalid
+ *   (the caller treats null as "cannot judge coverage" and skips, not warns)
+ */
+export function collectDoneOutputs(projectPath, featureName) {
+  let tasksPath;
+  try {
+    tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
+  } catch {
+    return null;
+  }
+  if (!existsSync(tasksPath)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(tasksPath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const outputs = [];
+  for (const task of tasks) {
+    if (task?.status !== 'done') continue;
+    for (const output of task.outputs || []) {
+      if (typeof output === 'string' && output.trim()) outputs.push(normalizePath(output));
+    }
+  }
+  return outputs;
+}
+
+/**
+ * A cited file is covered if some done task's `outputs` names it exactly, or
+ * names a directory (an entry ending in `/`) that the cited file falls under.
+ *
+ * @param {string} file
+ * @param {string[]} outputs
+ * @returns {boolean}
+ */
+function isCovered(file, outputs) {
+  for (const output of outputs) {
+    if (output === file) return true;
+    if (output.endsWith('/') && file.startsWith(output)) return true;
+  }
+  return false;
+}
+
+/**
+ * Run the recap-vs-outputs traceability check for a feature.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {{ status: 'pass'|'warn'|'skip', warnings: string[], reason: string|null, citedCount: number }}
+ */
+export function checkOutputsTraceability(projectPath, featureName) {
+  let recapPath;
+  try {
+    recapPath = getAbsoluteOutputPath(projectPath, featureName, 'recap');
+  } catch {
+    return { status: 'skip', warnings: [], reason: 'unknown feature', citedCount: 0 };
+  }
+
+  if (!existsSync(recapPath)) {
+    return { status: 'skip', warnings: [], reason: 'no recap.md', citedCount: 0 };
+  }
+
+  let recapText;
+  try {
+    recapText = readFileSync(recapPath, 'utf8');
+  } catch {
+    return { status: 'skip', warnings: [], reason: 'recap.md unreadable', citedCount: 0 };
+  }
+
+  const cited = extractCitedFiles(recapText);
+  if (cited.length === 0) {
+    return { status: 'skip', warnings: [], reason: 'no Files: entries found in recap.md', citedCount: 0 };
+  }
+
+  const outputs = collectDoneOutputs(projectPath, featureName);
+  if (outputs === null) {
+    return { status: 'skip', warnings: [], reason: 'no tasks.json', citedCount: cited.length };
+  }
+
+  const warnings = cited
+    .filter((file) => !isCovered(file, outputs))
+    .sort()
+    .map((file) => `${file} — cited in recap.md but not listed in any done task's outputs`);
+
+  return {
+    status: warnings.length > 0 ? 'warn' : 'pass',
+    warnings,
+    reason: null,
+    citedCount: cited.length,
+  };
+}

package/src/lib/validators/verify-runner.js

@@ -31,6 +31,7 @@ import { buildComposeEnv } from '../e2e/compose-env.js';
 import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
+import { checkOutputsTraceability } from './traceability-check.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 
 /** Default build timeout — dotnet cold build is slow; 30s (the Stop-hook default) is too short. */
@@ -56,6 +57,7 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
  * @param {Function} [options._runE2eCheck] - Injectable override for runE2eCheck (testing)
+ * @param {Function} [options._checkOutputsTraceability] - Injectable override for checkOutputsTraceability (testing)
  * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
  */
 export async function runVerify(projectPath, featureName, taskId, options = {}) {
@@ -70,6 +72,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     _runTestSuite = runTestSuite,
     _runValidation = runValidation,
     _runE2eCheck = runE2eCheck,
+    _checkOutputsTraceability = checkOutputsTraceability,
   } = options;
 
   const stack = readStack(projectPath);
@@ -105,6 +108,16 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   });
   appendE2eFeedback(feedback, nodes.e2e);
 
+  // 5. traceability — advisory-only, feature-scope only (see traceability-check.js
+  // for the recap-vs-outputs disagreement it flags, and what it deliberately
+  // cannot catch). Lives OUTSIDE `nodes` on purpose: `status` below is computed
+  // from `nodes` alone, so this can never flip build/tests/validators/e2e green
+  // to red — recap/outputs disagreement is a rastreabilidade signal, not a
+  // correctness gate.
+  const traceability = taskId
+    ? { status: 'skip', warnings: [], reason: 'task-scoped verify does not run traceability', citedCount: 0 }
+    : _checkOutputsTraceability(projectPath, featureName);
+
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
   return {
@@ -117,6 +130,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     status,
     nodes,
     feedback,
+    traceability,
   };
 }
 

package/src/lib/worktree/worktree-audit.js

@@ -131,7 +131,11 @@ export function auditWorktrees(cwd = process.cwd()) {
           type: 'non-morph-branch',
           path,
           detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga`,
-          fix: `git worktree remove "${path}"  (se já não serve)`,
+          // NEVER raw `git worktree remove` here: it follows the infra junctions
+          // out and empties the primary root's .claude/ and .morph/framework/.
+          // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
+          // --target precisely for worktrees like this one, with no feature.
+          fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
         });
       }
       continue;
@@ -142,7 +146,7 @@ export function auditWorktrees(cwd = process.cwd()) {
         type: 'no-feature',
         path,
         detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch)`,
-        fix: `git worktree remove "${path}"`,
+        fix: `morph-spec worktree remove --target "${path}"`,
       });
     }
   }

package/src/utils/hooks-installer.js

@@ -28,7 +28,7 @@ import { execSync } from 'child_process';
  * delivery — it makes `morph-spec update` report the change honestly instead
  * of "already current".
  */
-const HOOKS_VERSION = '3.6.0';
+const HOOKS_VERSION = '3.7.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -132,16 +132,20 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PreToolUse: Bash — denylist (irreversible commands only). Solo. ===
+  // === PreToolUse: Bash — irreversible-command guards, chained (block-first-
+  // wins, one process). pre-bash-denylist (static pattern list) runs before
+  // block-destructive-worktree-removal (dynamic: scans the target for reparse
+  // points), so the cheap check short-circuits the filesystem walk. The second
+  // one is the only defense against the raw-removal vector that does not depend
+  // on someone having read MORPH.md. ===
   {
     event: 'PreToolUse',
     matcher: 'Bash',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/pre-bash-denylist.js'
-      }
-    ]
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/chain.js',
+      args: ['pre-bash-denylist', 'block-destructive-worktree-removal']
+    }]
   },
 
   // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +