@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/lib/worktree/dirs.js

@@ -0,0 +1,32 @@
+/**
+ * dirs.js — the ONE place the worktree container directory is named.
+ *
+ * Every reader that resolves worktrees BY CONVENTION (test discovery, graph
+ * ignore list, the installed .gitignore, the architecture scanner, the
+ * dashboard scanner) imports from here. Duplicating the string is how the
+ * C1 bug comes back: a reader keeps the old name and silently goes blind.
+ *
+ * Readers that go through `git worktree list` (fleet, finish, worktree list)
+ * never depended on this — git records absolute paths.
+ */
+
+/**
+ * The directory new worktrees are created under, relative to the primary root.
+ *
+ * NO leading dot, deliberately (C1). Jest escapes the `.` when it interpolates
+ * an absolute `rootDir` into the `testMatch` glob, so `<root>/.worktrees/...`
+ * stops matching and an entire frontend suite reports **0 tests without an
+ * error** — the suite "passes" having tested nothing. The dot bought nothing:
+ * the directory is gitignored either way.
+ */
+export const WORKTREES_DIR = 'worktrees';
+
+/**
+ * The pre-C1 directory name. New worktrees never land here, but every reader
+ * that resolves worktrees BY CONVENTION must still accept it, so a machine
+ * that already had `.worktrees/{f}` keeps working with no manual migration.
+ */
+export const LEGACY_WORKTREES_DIR = '.worktrees';
+
+/** Both names, new first — the read order for convention-based lookups. */
+export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];

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

@@ -0,0 +1,287 @@
+/**
+ * docker-audit.js — the part of "which worktrees exist" that the filesystem
+ * cannot answer: the docker stacks still running for them.
+ *
+ * `worktree-audit.js` reconciles git's registry, the disk and morph's features.
+ * None of the three can see a CONTAINER. A stack survives everything they look
+ * at: `finish` removes the worktree and the branch, the directory disappears,
+ * git forgets the registration — and `morph-{feature}` keeps running, holding
+ * the feature's whole port block (and its named volumes) against the next
+ * worktree that lands on the same block. The failure surfaces later, somewhere
+ * else, as `port is already allocated` during an `e2e up` that has nothing to
+ * do with the stack that is actually holding the port.
+ *
+ * Two findings, both `severity: 'warn'` — reported, never a failure of
+ * `doctor --worktrees` (`doctor.js` treats `info`/`warn` as non-problems):
+ *
+ *   • docker-stack-orphan — a `morph-*` compose project of THIS repository
+ *     running for a feature this tree does not know
+ *   • docker-port-held    — a port from a feature's allocated block published
+ *     by a container belonging to a DIFFERENT compose project
+ *
+ * This module does not go into `doctor --full`, on purpose (D10): every check
+ * there must be satisfiable in the framework repo itself, and a docker check in
+ * a repo with no compose file could only be permanently yellow. A check that
+ * can never pass where it runs teaches nothing.
+ *
+ * Nothing here mutates anything — not the registry it reads (see
+ * `allocatedFeatures`), and certainly not docker. The `fix` strings name the
+ * destructive command; a human runs it.
+ *
+ * @module lib/worktree/docker-audit
+ */
+
+import { execFileSync } from 'child_process';
+import { resolve } from 'path';
+
+// src/ → framework/hooks/shared/ is the allowed direction (hooks are installed
+// standalone into target projects, where src/ does not exist).
+import {
+  composeProjectName,
+  defaultExec,
+  isDockerAvailable,
+  parseComposePs,
+} from '../../../framework/hooks/shared/e2e-check.js';
+import { allocateEnvBlock, allocatedFeatures, portLayout, resolveFleetConfig } from './env-allocator.js';
+
+/**
+ * The prefix `composeProjectName()` stamps on every stack morph brings up,
+ * derived from the function itself rather than retyped — the string `morph-`
+ * living in two places is how the two stop agreeing.
+ */
+const PROJECT_PROBE = 'probe';
+const MORPH_PROJECT_PREFIX = composeProjectName(PROJECT_PROBE).slice(0, -PROJECT_PROBE.length);
+
+/**
+ * Same fail-open resolution the other callers use: the COMMON git dir is the
+ * one location every linked worktree shares, and it is where the port-block
+ * registry lives.
+ */
+function resolveGitCommonDir(cwd) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd, stdio: 'pipe', encoding: 'utf-8', windowsHide: true,
+    }).trim();
+    return common ? resolve(cwd, common) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Path comparison that matches the host's own rules. Windows paths differ in
+ * drive-letter case between what git reports and what docker echoes back;
+ * treating those as different paths would make every stack look foreign.
+ */
+const samePathCase = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+const norm = (p) => samePathCase(resolve(String(p)).replace(/\\/g, '/'));
+
+/**
+ * Is this compose project OURS to talk about?
+ *
+ * The `morph-` prefix is global to the host, not to a repository: two different
+ * repos that use morph-spec and both have a feature named `triagem` produce the
+ * SAME compose project name. Without this test, `doctor` in repo A would report
+ * repo B's live stack as an orphan and hand the reader a `down -v` — volumes
+ * included — for somebody else's running database. The compose file's path is
+ * what ties a stack to a repository, and it keeps pointing inside the root even
+ * after the worktree directory it named is gone.
+ *
+ * Unattributable (no config file in the listing) counts as NOT ours: an
+ * unknown owner is not evidence of ownership.
+ */
+function belongsToRoot(entry, rootNorm) {
+  const configFiles = String(entry?.ConfigFiles ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (configFiles.length === 0) return false;
+  return configFiles.some((f) => {
+    try {
+      return norm(f).startsWith(`${rootNorm}/`);
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Host ports a `docker ps`/`docker compose ps` entry publishes.
+ * Both output shapes are accepted rather than pinning a docker version:
+ * `Ports` as the human string (`0.0.0.0:4002->5432/tcp`) and `Publishers` as
+ * the structured array compose emits.
+ *
+ * @returns {Set<number>}
+ */
+function publishedPorts(entry) {
+  const ports = new Set();
+  for (const pub of Array.isArray(entry?.Publishers) ? entry.Publishers : []) {
+    const p = Number(pub?.PublishedPort);
+    if (Number.isInteger(p) && p > 0) ports.add(p);
+  }
+  const raw = String(entry?.Ports ?? '');
+  for (const m of raw.matchAll(/:(\d{1,5})->/g)) {
+    const p = Number(m[1]);
+    if (Number.isInteger(p) && p > 0) ports.add(p);
+  }
+  return ports;
+}
+
+/** The compose project a container belongs to, from its labels. `null` = unknown. */
+function composeProjectOf(entry) {
+  const labels = String(entry?.Labels ?? '');
+  for (const part of labels.split(',')) {
+    const idx = part.indexOf('=');
+    if (idx < 0) continue;
+    if (part.slice(0, idx).trim() === 'com.docker.compose.project') return part.slice(idx + 1).trim() || null;
+  }
+  return null;
+}
+
+/** Readable container name for a `docker ps` entry (Names may be a list). */
+function containerNameOf(entry) {
+  const names = String(entry?.Names ?? entry?.Name ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  return names[0] || String(entry?.ID ?? 'container desconhecido');
+}
+
+/**
+ * Parse a docker JSON listing that may be an array or NDJSON.
+ * `null` means the output could not be read — DISTINCT from `[]`, which means
+ * docker answered and there was nothing running. A caller that conflated the
+ * two would turn "could not ask" into "nothing to report", or worse, into a
+ * finding.
+ *
+ * @returns {Array<object>|null}
+ */
+function parseDockerJson(raw) {
+  const text = String(raw ?? '').trim();
+  if (!text) return [];
+  const parsed = parseComposePs(text);
+  if (parsed.length > 0) return parsed;
+  // parseComposePs (the ONE docker-JSON parser in this codebase) collapses two
+  // very different answers into `[]`: "docker listed nothing" and "this is not
+  // JSON". Only a literal empty array is the first one; everything else that
+  // parsed to nothing is garbage, and garbage must not read as "all clear".
+  return /^\[\s*\]$/.test(text) ? [] : null;
+}
+
+/**
+ * Audit the docker stacks around this repository.
+ *
+ * Returns `[]` — asking docker nothing at all — in three situations, and the
+ * silence is the point: this module is loaded by `doctor --worktrees` in every
+ * repo, including ones that never containerize anything.
+ *
+ *   1. no feature ever allocated a port block (no registry): there is no
+ *      isolation contract to compare a running stack against;
+ *   2. the docker CLI is not usable here;
+ *   3. any docker call exits non-zero or answers with something that is not
+ *      JSON — fail-open, the standing rule of this repo's diagnostics.
+ *
+ * `[]` here reads as "nothing to report", not as "unknown": with no docker or
+ * no blocks, nothing CAN be colliding. That is why this is not the `null`-is-
+ * UNKNOWN shape `pr-index.js` uses — there the question stays open, here the
+ * absence is itself the answer.
+ *
+ * @param {string} root - primary root of the repository
+ * @param {object} [opts]
+ * @param {(file: string, args: string[], o?: object) => {code: number, output: string}} [opts.exec]
+ *   injectable executor, exactly like `e2e-check.js` — the CI runners have no
+ *   guaranteed daemon, so every path here must be testable without docker
+ * @param {Iterable<string>} [opts.features] - feature names this tree knows.
+ *   Passed IN rather than re-derived: `auditWorktrees` already read
+ *   `.morph/features/` and `git worktree list`, and two scans of the same fact
+ *   are two chances to disagree about whether a stack is orphaned
+ * @param {string|null} [opts.gitCommonDir]
+ * @returns {Array<{type: string, severity: string, detail: string, fix: string, feature?: string}>}
+ */
+export function auditDockerStacks(root, { exec = defaultExec, features = [], gitCommonDir } = {}) {
+  const commonDir = gitCommonDir === undefined ? resolveGitCommonDir(root) : gitCommonDir;
+  if (!commonDir) return [];
+
+  // (1) No port block was ever allocated → no fleet isolation to protect.
+  const allocated = allocatedFeatures(commonDir);
+  if (allocated.length === 0) return [];
+
+  // (2) No docker → nothing can be holding anything.
+  if (!isDockerAvailable(root, exec)) return [];
+
+  const known = new Set(features);
+  const rootNorm = norm(root);
+  const issues = [];
+
+  // ---- docker-stack-orphan ----------------------------------------------
+  const lsResult = exec('docker', ['compose', 'ls', '--format', 'json'], { cwd: root });
+  if (lsResult.code !== 0) return []; // (3) fail-open
+  const projects = parseDockerJson(lsResult.output);
+  if (projects === null) return []; // (3) unreadable answer is not a finding
+
+  const knownProjects = new Set([...known].map((f) => composeProjectName(f)));
+  for (const entry of projects) {
+    const name = String(entry?.Name ?? '').trim();
+    if (!name.startsWith(MORPH_PROJECT_PREFIX)) continue;
+    if (knownProjects.has(name)) continue;
+    if (!belongsToRoot(entry, rootNorm)) continue;
+
+    const slug = name.slice(MORPH_PROJECT_PREFIX.length);
+    issues.push({
+      type: 'docker-stack-orphan',
+      severity: 'warn',
+      feature: slug || null,
+      detail: `stack docker "${name}" está de pé (${String(entry?.Status ?? 'estado desconhecido')}) e não corresponde a nenhuma feature desta árvore — sobra de outra sessão, segurando o bloco de portas e os volumes de "${slug}"`,
+      // NEVER `morph-spec e2e down {slug}`: that command resolves the feature's
+      // compose file, and this stack's feature no longer exists here. The
+      // project name is the only handle that still works.
+      fix: `docker compose -p ${name} down -v`,
+    });
+  }
+
+  // ---- docker-port-held --------------------------------------------------
+  const psResult = exec('docker', ['ps', '--format', 'json'], { cwd: root });
+  if (psResult.code !== 0) return []; // (3) fail-open
+  const containers = parseDockerJson(psResult.output);
+  if (containers === null) return [];
+
+  const { basePort, blockSize } = resolveFleetConfig(root);
+  for (const feature of allocated) {
+    // A block allocated by a feature this tree does not know belongs to another
+    // worktree of the repo; its collisions are that worktree's to report.
+    if (!known.has(feature)) continue;
+
+    let layout;
+    try {
+      // `allocateEnvBlock` for a feature that is ALREADY in the registry takes
+      // the early-return path and writes nothing. The expected ports are
+      // DERIVED from portLayout — the same function that writes worktree.env
+      // and the compose env — never recomputed here.
+      const block = allocateEnvBlock(feature, { gitCommonDir: commonDir, basePort, blockSize });
+      layout = portLayout(block, { feature });
+    } catch {
+      continue; // block out of range / corrupt entry — nothing to compare
+    }
+
+    const ownProject = layout.COMPOSE_PROJECT_NAME;
+    const expected = new Map();
+    for (const key of ['PORT', 'API_PORT', 'POSTGRES_PORT', 'REDIS_PORT']) {
+      const port = Number(layout[key]);
+      if (Number.isInteger(port)) expected.set(port, key);
+    }
+
+    for (const container of containers) {
+      const project = composeProjectOf(container);
+      if (project === ownProject) continue; // the feature's own stack, as intended
+      for (const port of publishedPorts(container)) {
+        const key = expected.get(port);
+        if (!key) continue;
+        issues.push({
+          type: 'docker-port-held',
+          severity: 'warn',
+          feature,
+          detail: `a porta ${port} (${key} do bloco de "${feature}") está publicada pelo container ${containerNameOf(container)}${project ? ` do projeto compose "${project}"` : ' (sem projeto compose)'}, não por "${ownProject}" — a stack de "${feature}" não sobe enquanto ela estiver presa`,
+          fix: project
+            ? `docker compose -p ${project} down  (ou pare o container ${containerNameOf(container)}) antes de subir a stack de "${feature}"`
+            : `docker stop ${containerNameOf(container)} antes de subir a stack de "${feature}"`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}

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

@@ -21,6 +21,8 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { join } from 'path';
+// src/ → hooks/shared/ is the allowed direction (hooks are installed standalone).
+import { composeProjectName } from '../../../framework/hooks/shared/e2e-check.js';
 
 const DEFAULT_BASE_PORT = 4000;
 const DEFAULT_BLOCK_SIZE = 10;
@@ -108,6 +110,30 @@ export function allocateEnvBlock(feature, { gitCommonDir, basePort = DEFAULT_BAS
   return { index, base, range: [base, base + blockSize - 1], created: true };
 }
 
+/**
+ * The features that ALREADY own a block — read-only, allocating nothing.
+ *
+ * `allocateEnvBlock` is the only sanctioned way to get a block, and it WRITES
+ * when the feature has none. A diagnostic that has to ask "who owns a block?"
+ * must not answer by handing one out: `doctor` is read-only, and an audit that
+ * mutates the registry it audits invents the very state it then reports. So
+ * this reader exists to bound the question, and the block itself still comes
+ * from `allocateEnvBlock` (which, for a feature listed here, takes the
+ * early-return path and writes nothing).
+ *
+ * An absent or corrupt registry yields `[]` — "nobody allocated anything",
+ * which for every caller is the same as "nothing to compare against".
+ *
+ * @param {string} gitCommonDir
+ * @returns {string[]} feature names with an allocated block
+ */
+export function allocatedFeatures(gitCommonDir) {
+  const registry = readRegistry(gitCommonDir);
+  return Object.entries(registry.allocations)
+    .filter(([, a]) => Number.isInteger(a?.index))
+    .map(([feature]) => feature);
+}
+
 /**
  * Release a feature's block. Returns false when nothing was allocated.
  *
@@ -124,9 +150,46 @@ export function releaseEnvBlock(feature, { gitCommonDir }) {
 }
 
 /**
- * Render the `.morph/worktree.env` contents for a block, stack-aware.
- * `PORT` covers next/vite/node dev servers; dotnet gets its own URL on base+1
- * so a full-stack worktree runs web and api side by side inside one block.
+ * Fixed offsets inside a block. The block has 10 ports; four are named, the
+ * rest (+4..+9) are the project's to use. A new offset added here MUST also be
+ * published by the compose template (`${VAR:-default}:container`), or it is a
+ * port nobody listens on.
+ */
+export const PORT_OFFSETS = Object.freeze({ web: 0, api: 1, postgres: 2, redis: 3 });
+
+/**
+ * The ONE port-layout contract. Two writers derive from it — the
+ * `.morph/worktree.env` manifest (`buildEnvFileContent`) and the env handed to
+ * `docker compose` (`src/lib/e2e/compose-env.js`) — so a worktree's file and
+ * its running stack can never describe different worlds.
+ *
+ * `COMPOSE_PROJECT_NAME` is part of the layout on purpose: a hand-run
+ * `docker compose up` inside the worktree must land in the isolated project,
+ * not in the root's. Every value is a string (env-safe); key order is stable.
+ *
+ * @param {{ base: number, range: [number, number] }} block
+ * @param {{ stack?: string, feature?: string }} [opts]
+ * @returns {Record<string,string>}
+ */
+export function portLayout(block, { stack = '', feature = '' } = {}) {
+  const env = {};
+  if (feature) env.COMPOSE_PROJECT_NAME = composeProjectName(feature);
+  env.MORPH_PORT_BASE = String(block.base);
+  env.MORPH_PORT_RANGE = `${block.range[0]}-${block.range[1]}`;
+  env.PORT = String(block.base + PORT_OFFSETS.web);
+  env.API_PORT = String(block.base + PORT_OFFSETS.api);
+  env.POSTGRES_PORT = String(block.base + PORT_OFFSETS.postgres);
+  env.REDIS_PORT = String(block.base + PORT_OFFSETS.redis);
+  if (/\bdotnet\b/i.test(String(stack))) {
+    env.ASPNETCORE_URLS = `http://localhost:${block.base + PORT_OFFSETS.api}`;
+  }
+  return env;
+}
+
+/**
+ * Render the `.morph/worktree.env` contents for a block: a header, the
+ * feature, and exactly the `portLayout()` pairs — nothing else, so the file
+ * cannot drift from what compose receives.
  *
  * @param {string} feature
  * @param {{ base: number, range: [number, number] }} block
@@ -135,15 +198,10 @@ export function releaseEnvBlock(feature, { gitCommonDir }) {
  */
 export function buildEnvFileContent(feature, block, stack = '') {
   const lines = [
-    `# Managed by morph-spec — fleet env desta worktree (feature: ${feature}).`,
-    '# Derivado e local: nunca commitar, nunca editar à mão (regenerado pelo worktree setup).',
+    `# Managed by morph-spec — ambiente dedicado desta worktree (feature: ${feature}).`,
+    '# Derivado, git-invisível, regenerado por `worktree setup|link`; nunca editar nem commitar.',
     `MORPH_FEATURE=${feature}`,
-    `MORPH_PORT_BASE=${block.base}`,
-    `MORPH_PORT_RANGE=${block.range[0]}-${block.range[1]}`,
-    `PORT=${block.base}`,
+    ...Object.entries(portLayout(block, { stack, feature })).map(([k, v]) => `${k}=${v}`),
   ];
-  if (/\bdotnet\b/i.test(String(stack))) {
-    lines.push(`ASPNETCORE_URLS=http://localhost:${block.base + 1}`);
-  }
   return `${lines.join('\n')}\n`;
 }

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

@@ -36,6 +36,7 @@ import {
 import { detectDefaultBranch } from '../git/default-branch.js';
 import { buildPrIndex } from '../git/pr-index.js';
 import { classifyBranch, commitsAhead, resolveBaseRef } from '../git/branch-classifier.js';
+import { auditDockerStacks } from './docker-audit.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
 
@@ -212,10 +213,24 @@ function dirsOnDisk(root) {
  *                                 directory that exists but git's own
  *                                 registry does not know as a worktree
  *
+ *   • docker-stack-orphan (warn) — a `morph-*` docker stack of this repository
+ *                                 still running for a feature this tree does
+ *                                 not know, and
+ *   • docker-port-held (warn)    — a port from a feature's block published by
+ *                                 another compose project. Both come from
+ *                                 `docker-audit.js`: the three sources above
+ *                                 cannot see a CONTAINER, and a stack outlives
+ *                                 every one of them
+ *
  * @param {string} [cwd]
+ * @param {object} [opts]
+ * @param {Function} [opts.exec] - injectable executor handed to the docker
+ *   audit, so the docker paths are testable with no daemon (the CI runners
+ *   have none). Absent, the real `docker` CLI is used — and answers `[]` when
+ *   it is not installed.
  * @returns {Array<{ type: string, detail: string, path?: string, feature?: string, fix: string }>}
  */
-export function auditWorktrees(cwd = process.cwd()) {
+export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   if (!isGitRepo(cwd)) return [];
   const root = resolvePrimaryRoot(cwd);
   const rootNorm = norm(root);
@@ -247,9 +262,47 @@ export function auditWorktrees(cwd = process.cwd()) {
 
     const feature = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1] || null;
     if (!feature) {
-      // Only worth reporting when it sits in morph's own worktree container —
-      // a worktree the user keeps elsewhere is none of morph's business.
       const inContainer = WORKTREE_DIR_NAMES.some((d) => path.startsWith(`${rootNorm}/${d}/`));
+      const task = entry.branch?.match(/^refs\/heads\/morph-task\/(.+)$/)?.[1] || null;
+
+      if (!inContainer) {
+        // A worktree OUTSIDE morph's container was created behind morph's back
+        // (a native Claude Code run before the WorktreeCreate hook, a raw
+        // `git worktree add ../x`, another skill). It has no junctions, no port
+        // block, and nothing morph runs there — the exact shape that let a
+        // root's `.claude/` be emptied. Reported as `warn` (never a failure,
+        // NEVER pruned): the work inside may be the only copy.
+        const work = unintegratedWork(root, entry.branch, prIndex);
+        issues.push({
+          type: 'out-of-container',
+          severity: 'warn',
+          path,
+          detail: `${path} é um worktree fora de worktrees/ (${entry.branch || 'HEAD destacado'}) — criado sem o morph: sem junctions, sem portas, invisível ao \`fleet\`${work.unintegrated ? `; carrega trabalho NÃO integrado (${work.evidence})` : ''}`,
+          fix: work.unintegrated
+            ? `integre a branch primeiro; depois \`morph-spec worktree remove --target "${path}"\`. Novos worktrees: \`morph-spec worktree setup <f>\` ou \`worktree provision <n>\``
+            : `morph-spec worktree remove --target "${path}"  — e crie os próximos por \`morph-spec worktree setup <f>\` / \`worktree provision <n>\``,
+        });
+        continue;
+      }
+
+      if (task) {
+        // `morph-task/*`: a task-isolation tree provisioned by the WorktreeCreate
+        // hook. Clean → nothing to say (the orchestrator removes it after the
+        // merge). With commits the default does not have → report, never
+        // suggest removal.
+        const work = unintegratedWork(root, entry.branch, prIndex);
+        if (work.unintegrated) {
+          issues.push({
+            type: 'unintegrated-work',
+            severity: 'info',
+            path,
+            detail: `${path} é um worktree de isolamento de task (${entry.branch}) com trabalho NÃO integrado (${work.evidence})`,
+            fix: `integre a branch (\`git merge --no-ff morph-task/${task}\` no orquestrador) e depois \`morph-spec worktree remove --target "${path}"\``,
+          });
+        }
+        continue;
+      }
+
       if (inContainer) {
         // Same hazard as `no-feature` below, and it needs the same guard:
         // "invisible to fleet" says nothing about whether the WORK is safe
@@ -356,6 +409,20 @@ export function auditWorktrees(cwd = process.cwd()) {
     }
   }
 
+  // The fourth source, and the only one that is not a file: the docker stacks.
+  // A container survives the removal of the worktree, of the branch and of the
+  // feature — none of the three reconciliations above can see it, and it keeps
+  // holding the feature's port block. The feature names come from HERE (the
+  // ones morph knows plus the ones the registered `morph/*` worktrees carry)
+  // rather than from a second scan inside docker-audit: two readings of the
+  // same fact are two chances to disagree about which stack is orphaned.
+  const treeFeatures = new Set(features);
+  for (const entry of registered) {
+    const f = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1];
+    if (f) treeFeatures.add(f);
+  }
+  issues.push(...auditDockerStacks(root, { exec, features: treeFeatures }));
+
   return issues;
 }
 

package/src/scripts/setup-infra.js

@@ -14,7 +14,7 @@
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
-import { readFileSync, readdirSync, copyFileSync, unlinkSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import {
   copyDirectory,
   copyFile,
@@ -33,6 +33,7 @@ import { installSkills } from '../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../utils/agents-installer.js';
 import { resolvePrimaryRoot } from '../commands/project/worktree.js';
 import { reconcileLegacyTemplatesCopy } from '../lib/installers/templates-reconcile.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const FRAMEWORK_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'framework');
 
@@ -61,7 +62,7 @@ async function installRequiredPlugins(log, exec) {
  * @param {string} rulesDest - Destination rules directory (.claude/rules/)
  * @param {string[]} projectTags - Stack tags from config (e.g., ['dotnet', 'blazor'])
  */
-export function installRulesForStack(rulesSrc, rulesDest, projectTags) {
+export function installRulesForStack(rulesSrc, rulesDest, projectTags, fx = realEffects()) {
   const sourceFiles = readdirSync(rulesSrc).filter(f => f.endsWith('.md'));
   const installed = new Set();
 
@@ -69,15 +70,19 @@ export function installRulesForStack(rulesSrc, rulesDest, projectTags) {
     const content = readFileSync(join(rulesSrc, file), 'utf-8');
     const stacks = parseStacks(content);
     if (shouldInstall(stacks, projectTags)) {
-      copyFileSync(join(rulesSrc, file), join(rulesDest, file));
+      fx.copyFile(join(rulesSrc, file), join(rulesDest, file));
       installed.add(file);
     }
   }
 
-  // Cleanup orphans
-  for (const file of readdirSync(rulesDest).filter(f => f.endsWith('.md'))) {
-    if (!installed.has(file)) {
-      unlinkSync(join(rulesDest, file));
+  // Cleanup orphans — calado em `dryRun` pelo mesmo motivo dos laços gêmeos em
+  // skills-installer.js e agents-installer.js (D6): `cleanFrameworkDirs()` já
+  // apagou `.claude/rules/` inteiro antes de este código rodar de verdade.
+  if (!fx.dryRun) {
+    for (const file of readdirSync(rulesDest).filter(f => f.endsWith('.md'))) {
+      if (!installed.has(file)) {
+        fx.remove(join(rulesDest, file));
+      }
     }
   }
 
@@ -134,12 +139,20 @@ async function installStackAwareAssets(targetPath, log) {
  *
  * @param {string} claudeMdPath - Absolute path to the installed .claude/CLAUDE.md
  * @param {Array<{ name: string, title: string, domains: string[] }>} agents
+ * @param {object} [options]
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ * @param {string} [options.readFrom] - De onde LER o conteúdo-base.
+ *   Num `--dry-run` o arquivo de destino ainda não recebeu a cópia que o passo
+ *   anterior previu, então ler o destino diria "sem marcadores" e o efeito de
+ *   escrita sumiria da previsão — divergindo da execução real. Lendo a MESMA
+ *   origem que seria copiada, previsão e execução decidem igual.
  */
-export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = []) {
-  if (!(await pathExists(claudeMdPath))) return;
+export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = [], options = {}) {
+  const { fx = realEffects(), readFrom = claudeMdPath } = options;
+  if (!(await pathExists(readFrom))) return;
   const START = '<!-- morph-agents:start -->';
   const END = '<!-- morph-agents:end -->';
-  const content = readFileSync(claudeMdPath, 'utf-8');
+  const content = readFileSync(readFrom, 'utf-8');
   if (!content.includes(START) || !content.includes(END)) return;
 
   const list = agents.length > 0
@@ -151,7 +164,7 @@ export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = []) {
     new RegExp(`${START}[\\s\\S]*?${END}`),
     block
   );
-  await writeFile(claudeMdPath, updated);
+  fx.writeFile(claudeMdPath, updated);
 }
 
 /**