@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/work-type-detector.js

@@ -1,20 +1,5 @@
-/**
- * Work Type Detector — deterministic keyword classifier for `text`/`declaredScope`.
- *
- * Mirrors risk-detector.js's style: pure, deterministic, no I/O. This module
- * is the TESTABLE MIRROR of the natural-language classification rules that
- * live in MORPH.md — behavior described here must stay in sync with those
- * rules, but this file is what `create`/`retype` call at runtime.
- *
- * Precedence: hotfix keywords win outright (a production incident never
- * ties down against a bug or chore signal). Otherwise bug vs. chore is
- * decided by keyword-match count, nudged by two weak signals:
- *   - estimatedFiles <= 2   -> +1 toward bug   (small, surgical diffs)
- *   - declaredScope <= 6 words -> +1 toward chore (a narrowly-scoped ask)
- * A genuine tie between bug and chore is surfaced to the caller (LLM/HCOP
- * router) rather than guessed at. Zero keyword matches -> no opinion; the
- * caller defaults to `feature`.
- */
+// Testable mirror of the classification rules in MORPH.md: the two must stay in sync.
+// Hotfix wins outright; a bug/chore tie is returned to the caller, never guessed.
 
 // Plural/inflected forms are listed EXPLICITLY: matching is whole-word, so
 // "incidentes" is not "incidente". Recall lives here, in a list that is visible
@@ -37,38 +22,8 @@ const CHORE_KEYWORDS = [
   'limpeza', 'docs', 'documentação', 'lint', 'formatação',
 ];
 
-/**
- * @returns {string[]} the subset of `keywords` present in `haystack` as WHOLE
- * words (or whole phrases), never as a fragment of a larger word.
- *
- * Substring matching routed real requests to the wrong pipeline: `p0` is two
- * characters with outright hotfix precedence, so "endpoint group0" matched it
- * and skipped Gates 1 and 2 by policy — no human, and not even the LLM router,
- * since a substring hit reports `confidence: 'high'`. Same shape for `fix`
- * inside "prefix"/"fixtures" and `bug` inside "debug".
- *
- * The failure directions are asymmetric, which is what settles the trade-off: a
- * false POSITIVE silently skips approval gates, while a false negative usually
- * only lowers confidence — and low confidence defers to the LLM router (exit 2).
- * Matching strictly is therefore the safe error, and provably so for the vector
- * that motivated it: whole-word matches are a strict SUBSET of substring matches
- * per keyword, so narrowing can never invent a hotfix hit that substring didn't
- * already have. No misroute INTO the only gate-skipping pipeline can be created
- * here, only removed.
- *
- * Being precise about the limit of that argument, since overclaiming in a
- * comment is what this file is fixing: the asymmetry holds per KEYWORD, not per
- * CLASSIFICATION. Dropping a match can still shift the bug-vs-chore balance —
- * losing a bug hit may promote a chore from `tie` to `high`, and chore also
- * skips Gates 1 and 2. Whole-word matching DID cost recall that substring had:
- * "bugs" contains "bug" but is not the word "bug". The answer is to list the
- * forms (below), not to match loosely — recall belongs in the vocabulary, where
- * it is explicit and testable, not in a matcher that fires on fragments.
- *
- * `\b` is not usable here: JS word boundaries are ASCII-only, so `\bnão\b`
- * would find a boundary between `n` and `ã` and misbehave on half of these
- * pt-BR keywords. Unicode letter/number lookarounds are the portable form.
- */
+// Whole words only: a false positive silently skips approval gates (`p0` in "group0", `fix` in
+// "prefix"). `\b` is ASCII-only in JS and breaks on pt-BR letters, hence the Unicode lookarounds.
 function matchKeywords(haystack, keywords) {
   return keywords.filter((kw) => {
     const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -81,18 +36,6 @@ function wordCount(str) {
   return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
 }
 
-/**
- * @param {object} input
- * @param {string} [input.text]
- * @param {string} [input.declaredScope]
- * @param {number} [input.estimatedFiles]
- * @returns {{
- *   workType: string|null,
- *   confidence: 'high'|'tie'|'none',
- *   matched: { hotfix: string[], bug: string[], chore: string[], feature: string[] },
- *   candidates: string[],
- * }}
- */
 export function detectWorkType({ text = '', declaredScope = '', estimatedFiles } = {}) {
   const haystack = `${text} ${declaredScope}`.toLowerCase();
 
@@ -107,7 +50,6 @@ export function detectWorkType({ text = '', declaredScope = '', estimatedFiles }
     feature: [], // no keywords of its own — the catch-all default
   };
 
-  // Hard precedence: any hotfix signal wins outright, never ties down.
   if (hotfixMatched.length > 0) {
     return { workType: 'hotfix', confidence: 'high', matched, candidates: ['hotfix'] };
   }
@@ -119,11 +61,7 @@ export function detectWorkType({ text = '', declaredScope = '', estimatedFiles }
   let bugScore = bugMatched.length;
   let choreScore = choreMatched.length;
 
-  // The weak nudges act ONLY as tie-breakers — apply them only when the raw
-  // keyword counts are already equal. Otherwise a clean single-keyword match
-  // on one type would be dragged into a tie by the other type's weak signal
-  // (e.g. a lone "bug" keyword + a short declaredScope), routing an
-  // unambiguous request to the LLM and risking a gate-skipping misroute.
+  // Weak nudges only break ties: applied otherwise, they drag a clean single-keyword match into a tie.
   if (bugMatched.length === choreMatched.length) {
     if (typeof estimatedFiles === 'number' && estimatedFiles <= 2) {
       bugScore += 1;

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

@@ -1,41 +1,8 @@
-/**
- * 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
- */
-
+// Stays out of `doctor --full`: a docker check in a repo with no compose file
+// could only be permanently yellow. Read-only; the `fix` strings are for a human.
 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,
@@ -44,19 +11,9 @@ import {
 } 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'], {
@@ -68,32 +25,12 @@ function resolveGitCommonDir(cwd) {
   }
 }
 
-/**
- * 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.
- *
- * Exported as the ONE copy of that rule: `doctor.js` compares a declared test
- * node `cwd` with a discovered `package.json` folder through it (#87 F5), and
- * `test-scope.js` takes only the CASE of a canonical path through it (#87 N3).
- */
+// On Windows git and docker report the drive letter in different case.
 export 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.
- */
+// The `morph-` prefix is host-global: two repos with the same feature name share
+// a project name, so ownership comes from the compose file path. No path = not ours.
 function belongsToRoot(entry, rootNorm) {
   const configFiles = String(entry?.ConfigFiles ?? '').split(',').map((s) => s.trim()).filter(Boolean);
   if (configFiles.length === 0) return false;
@@ -106,14 +43,6 @@ function belongsToRoot(entry, rootNorm) {
   });
 }
 
-/**
- * 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 : []) {
@@ -128,7 +57,6 @@ function publishedPorts(entry) {
   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(',')) {
@@ -139,83 +67,43 @@ function composeProjectOf(entry) {
   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}
- */
+// `null` = unreadable, distinct from `[]` = docker answered with nothing running.
 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".
+  // parseComposePs returns `[]` for non-JSON too; only a literal `[]` is "nothing".
   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}>}
+ * `[]` means "nothing to report", not unknown: with no port block allocated or
+ * no docker, nothing can collide. Docker errors are fail-open.
+ * `features` is passed in so the audit and `auditWorktrees` share one scan.
  */
 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
+  if (lsResult.code !== 0) return [];
   const projects = parseDockerJson(lsResult.output);
-  if (projects === null) return []; // (3) unreadable answer is not a finding
+  if (projects === null) return [];
 
   const knownProjects = new Set([...known].map((f) => composeProjectName(f)));
   for (const entry of projects) {
@@ -230,35 +118,27 @@ export function auditDockerStacks(root, { exec = defaultExec, features = [], git
       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.
+      // Not `e2e down {slug}`: the feature's compose file no longer resolves.
       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
+  if (psResult.code !== 0) return [];
   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.
+      // Feature is already in the registry, so allocateEnvBlock writes nothing.
       const block = allocateEnvBlock(feature, { gitCommonDir: commonDir, basePort, blockSize });
       layout = portLayout(block, { feature });
     } catch {
-      continue; // block out of range / corrupt entry — nothing to compare
+      continue;
     }
 
     const ownProject = layout.COMPOSE_PROJECT_NAME;
@@ -270,7 +150,7 @@ export function auditDockerStacks(root, { exec = defaultExec, features = [], git
 
     for (const container of containers) {
       const project = composeProjectOf(container);
-      if (project === ownProject) continue; // the feature's own stack, as intended
+      if (project === ownProject) continue;
       for (const port of publishedPorts(container)) {
         const key = expected.get(port);
         if (!key) continue;

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

@@ -1,34 +1,14 @@
-/**
- * env-allocator.js — deterministic per-worktree port-block allocation (fleet).
- *
- * Two parallel features that both start `next dev` (or `dotnet run`) collide on
- * the same default port, and the failure is invisible until one server kills
- * the other. Worktrees isolate files and branches, not runtime — this module
- * closes that gap by giving every feature worktree its own stable block of
- * ports.
- *
- * The registry lives at `<git-common-dir>/morph-spec/env-registry.json` — under
- * `.git/` on purpose, for the same reasons as `finish-backup/`: it can never
- * dirty the `git status` the worktree-finish gates read, it survives
- * `git clean -fdx`, and the COMMON dir is the one location every linked
- * worktree of the repo shares.
- *
- * Allocation is deterministic (first free index), idempotent per feature, and
- * 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).
- */
+// The registry lives under the COMMON git dir: shared by every linked worktree,
+// invisible to the `git status` the finish gates read, and survives `git clean -fdx`.
 
 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;
 const MAX_PORT = 65535;
 
-/** Registry file path for a repo's common git dir. */
 export function registryPath(gitCommonDir) {
   return join(gitCommonDir, 'morph-spec', 'env-registry.json');
 }
@@ -40,7 +20,7 @@ function readRegistry(gitCommonDir) {
     if (parsed && typeof parsed.allocations === 'object' && parsed.allocations !== null) {
       return parsed;
     }
-  } catch { /* fail-open: corrupt or absent registry restarts empty */ }
+  } catch { /* fail-open: a re-allocation, never a crash */ }
   return { version: 1, allocations: {} };
 }
 
@@ -52,13 +32,6 @@ function writeRegistry(gitCommonDir, registry) {
   renameSync(tmp, path);
 }
 
-/**
- * Read fleet overrides from the project's committed config.json.
- * Fail-open: missing/malformed config (or a Windows BOM) → defaults.
- *
- * @param {string} rootPath - primary root of the project
- * @returns {{ basePort: number, blockSize: number }}
- */
 export function resolveFleetConfig(rootPath) {
   const defaults = { basePort: DEFAULT_BASE_PORT, blockSize: DEFAULT_BLOCK_SIZE };
   try {
@@ -74,15 +47,7 @@ export function resolveFleetConfig(rootPath) {
   }
 }
 
-/**
- * Allocate (or return the existing) port block for a feature.
- * First-free-index policy: released slots are reused, so long-lived repos
- * don't creep toward the port ceiling.
- *
- * @param {string} feature
- * @param {{ gitCommonDir: string, basePort?: number, blockSize?: number }} opts
- * @returns {{ index: number, base: number, range: [number, number], created: boolean }}
- */
+/** First free index wins, so released slots are reused instead of creeping toward the port ceiling. */
 export function allocateEnvBlock(feature, { gitCommonDir, basePort = DEFAULT_BASE_PORT, blockSize = DEFAULT_BLOCK_SIZE }) {
   const registry = readRegistry(gitCommonDir);
 
@@ -110,23 +75,7 @@ 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
- */
+/** Read-only on purpose: `allocateEnvBlock` writes, and an audit that allocates invents the state it reports. */
 export function allocatedFeatures(gitCommonDir) {
   const registry = readRegistry(gitCommonDir);
   return Object.entries(registry.allocations)
@@ -134,13 +83,6 @@ export function allocatedFeatures(gitCommonDir) {
     .map(([feature]) => feature);
 }
 
-/**
- * Release a feature's block. Returns false when nothing was allocated.
- *
- * @param {string} feature
- * @param {{ gitCommonDir: string }} opts
- * @returns {boolean}
- */
 export function releaseEnvBlock(feature, { gitCommonDir }) {
   const registry = readRegistry(gitCommonDir);
   if (!registry.allocations[feature]) return false;
@@ -149,27 +91,12 @@ export function releaseEnvBlock(feature, { gitCommonDir }) {
   return true;
 }
 
-/**
- * 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.
- */
+// A new offset here must also be published by the compose template, 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, aliases?: Record<string, string> }} [opts] - aliases: resolvePortAliases()
- * @returns {Record<string,string>}
+ * The single layout both `worktree.env` and the compose env derive from. `COMPOSE_PROJECT_NAME`
+ * is in it so a hand-run `docker compose up` in the worktree lands in the isolated project.
  */
 export function portLayout(block, { stack = '', feature = '', aliases = {} } = {}) {
   const env = {};
@@ -194,9 +121,6 @@ const RESERVED_ENV_NAMES = new Set([
   'MORPH_FEATURE',
 ]);
 
-// e2e.portEnvNames: extra env names for the same four ports, so a compose file reading
-// ${PG_PORT} is fed by the block, not by its own default. An entry that cannot be
-// honoured is dropped and named in `problems`.
 export function resolvePortAliases(config) {
   const declared = config?.e2e?.portEnvNames;
   const aliases = {};
@@ -217,20 +141,8 @@ export function resolvePortAliases(config) {
 }
 
 /**
- * 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.
- *
- * `morphFeature` is for a task tree born from `morph/<f>`: `MORPH_FEATURE`
- * names the feature it works for, while the block and `COMPOSE_PROJECT_NAME`
- * stay keyed by `feature` (`task/<n>`) — keying them by `<f>` would hand the
- * sub-agent the feature's own ports and compose project.
- *
- * @param {string} feature - the env-registry key: `<feature>` or `task/<name>`
- * @param {{ base: number, range: [number, number] }} block
- * @param {string} [stack] - config.json `project.stack` (e.g. "nextjs+dotnet")
- * @param {{ morphFeature?: string|null, aliases?: Record<string, string> }} [opts]
- * @returns {string}
+ * `morphFeature` names the feature a `task/<n>` tree works for; the block and compose
+ * project stay keyed by `feature`, or the sub-agent would get the feature's own ports.
  */
 export function buildEnvFileContent(feature, block, stack = '', { morphFeature = null, aliases = {} } = {}) {
   const lines = [