@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/worktree/ignored-triage.js

@@ -1,77 +1,24 @@
-/**
- * ignored-triage.js — decide, per gitignored leftover, whether removing a
- * worktree would DESTROY something or merely delete a copy.
- *
- * WHY THIS EXISTS: `git worktree remove` deletes gitignored files outright and
- * the clean-check that gates it (`git status --porcelain`) omits them by
- * design, so a user's `.env` dies silently while the command reports success.
- * The first fix for that refused the removal whenever ANY unrecognised
- * gitignored path was present — correct, but blind: in the observed session a
- * worktree carried `.env` and `.env.e2e` that were BYTE-IDENTICAL to the
- * primary root's, alongside a `keys/key-*.xml` that existed nowhere else. The
- * refusal treated them alike, and the only escape it offered
- * (`--discard-ignored`) destroyed the unique one together with the replicas.
- *
- * The triage below replaces "recognised vs not" with the question that actually
- * decides whether bytes are lost:
- *
- *   REPLICABLE — the primary root has the same relative path with identical
- *                content. Deleting the worktree's copy loses nothing; the
- *                original stays where it always was.
- *   DISPOSABLE — a well-known build artifact or cache (`bin/`, `obj/`,
- *                `node_modules/`, `.next/`, `TestResults/`, `graphify-out/`…,
- *                see DISPOSABLE_DIR_NAMES). Reproducible from source, which is a
- *                STRONGER guarantee than backed up.
- *   EXCLUSIVE  — everything else: no counterpart in the root, or a counterpart
- *                whose content differs. These are the only bytes at stake, and
- *                the caller copies them to `finish-backup` before proceeding.
- *
- * Fail-CLOSED on every uncertainty: an unreadable file, a hash that cannot be
- * computed, a directory too large to compare, a counterpart that is a link
- * rather than a real file — all classify as EXCLUSIVE. Being wrong in that
- * direction costs a backup copy; being wrong the other way costs the file.
- */
+// `git worktree remove` deletes gitignored files and `git status` never shows them.
+// Every uncertainty classifies as EXCLUSIVE (backed up): being wrong that way costs a
+// copy, the other way costs the file.
 
 import { createHash } from 'crypto';
 import { existsSync, lstatSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 
-/**
- * Well-known, regenerable build artifacts and caches. Deliberately narrow — do
- * NOT add names a project might use for hand-written output (`dist/`,
- * `build/`, `coverage/`); anything unlisted still reaches the EXCLUSIVE bucket,
- * where it is backed up rather than assumed disposable. Each name here is a
- * directory its own tool rewrites from scratch: `.next/` (next build/dev),
- * `.turbo/`, `.pytest_cache/`, `TestResults/` (VSTest), `graphify-out/`
- * (`morph-spec graph build`). `.next/` is also the one that makes a backup
- * weigh hundreds of megabytes; `graphify-out/` is seeded into every worktree
- * and is past the replica size cap (18 MB in a real project), so without its
- * entry every `finish` would back it up.
- *
- * `.auth/` (Playwright storage state) belongs here for a reason worth stating:
- * it holds a captured session, so it LOOKS like precious local state — but it
- * is regenerated by the auth setup project on the next run, and it expires on
- * its own. Keeping it out of the backup avoids copying credentials around.
- */
+// Only dirs their own tool rewrites from scratch. Never add `dist/`, `build/` or `coverage/`:
+// projects hand-write those. `.auth/` (Playwright session) is regenerated by the auth setup,
+// and keeping it out of the backup avoids copying credentials around.
 const DISPOSABLE_DIR_NAMES = new Set([
   'bin', 'obj', 'node_modules', '__pycache__', 'test-results', '.auth',
   '.next', '.turbo', '.pytest_cache', 'TestResults', 'graphify-out',
 ]);
 const DISPOSABLE_FILE_RE = /\.tsbuildinfo$/;
 
-/**
- * Comparing a directory recursively is only worth doing while it stays small:
- * the point is to spare `.env`-sized replicas from a needless refusal, not to
- * checksum a data set. Past either cap the answer becomes EXCLUSIVE (the safe
- * direction), and the caller backs it up.
- */
 const REPLICABLE_MAX_FILES = 500;
 const REPLICABLE_MAX_BYTES = 8 * 1024 * 1024;
 
-/**
- * @param {string} p - forward-slash relative path
- * @returns {boolean}
- */
+/** @param {string} p - forward-slash relative path */
 export function isDisposableBuildArtifact(p) {
   if (DISPOSABLE_FILE_RE.test(p)) return true;
   return p.split('/').filter(Boolean).some((seg) => DISPOSABLE_DIR_NAMES.has(seg));
@@ -85,11 +32,7 @@ function sha256OfFile(path) {
   }
 }
 
-/**
- * Real file (not a link, not a directory)? A reparse point must never be read
- * THROUGH — following one is the exact failure mode the whole teardown path
- * exists to prevent — so a link on either side makes the pair incomparable.
- */
+// lstat, never stat: reading THROUGH a junction is the failure the teardown path exists to prevent.
 function isRealFile(path) {
   try {
     return lstatSync(path).isFile();
@@ -106,11 +49,7 @@ function isRealDir(path) {
   }
 }
 
-/**
- * Every real file under `dir`, relative to it. Returns null when the walk hits
- * a link, an unreadable entry, or either cap — "cannot enumerate" and "too big
- * to compare" both mean "do not claim this is replicable".
- */
+// null on a link, an unreadable entry or either cap: none of them may be claimed replicable.
 function walkFiles(dir, budget) {
   const out = [];
   const stack = [''];
@@ -125,9 +64,9 @@ function walkFiles(dir, budget) {
     for (const e of entries) {
       const childRel = rel ? `${rel}/${e.name}` : e.name;
       const childAbs = join(dir, childRel);
-      if (e.isSymbolicLink()) return null; // never compare through a link
+      if (e.isSymbolicLink()) return null;
       if (e.isDirectory()) { stack.push(childRel); continue; }
-      if (!e.isFile()) return null; // socket/fifo/unknown — incomparable
+      if (!e.isFile()) return null;
       let size;
       try { size = lstatSync(childAbs).size; } catch { return null; }
       budget.files += 1;
@@ -140,14 +79,8 @@ function walkFiles(dir, budget) {
 }
 
 /**
- * Does `root/rel` hold exactly the same content as `worktree/rel`?
- *
- * Files compare by SHA-256; directories compare by having the SAME set of
- * files, each with an identical hash — a root copy that is merely a SUPERSET
- * is not a replica of the worktree's, because the worktree's own extra files
- * would still be lost.
- *
- * @returns {boolean} false on ANY uncertainty
+ * False on any uncertainty. A directory needs the SAME file set: a root superset is
+ * not a replica, because the worktree's own extra files would still be lost.
  */
 export function isReplicatedInRoot(worktreePath, rootPath, rel) {
   const src = join(worktreePath, rel);
@@ -178,19 +111,10 @@ export function isReplicatedInRoot(worktreePath, rootPath, rel) {
     return true;
   }
 
-  return false; // a link, or something that is neither — incomparable
+  return false;
 }
 
-/**
- * Split gitignored worktree paths into the three buckets above.
- *
- * ORDER IS DELIBERATE: disposable is checked FIRST, so a `bin/` that happens to
- * be byte-identical to the root's is discarded rather than hashed, and a
- * `node_modules` never enters the comparison budget at all.
- *
- * @param {{ worktreePath: string, rootPath: string, paths: string[] }} args
- * @returns {{ replicable: string[], disposable: string[], exclusive: string[] }}
- */
+// Disposable is checked first so `node_modules` never enters the hashing budget.
 export function triageIgnoredPaths({ worktreePath, rootPath, paths }) {
   const replicable = [];
   const disposable = [];

package/src/lib/worktree/vscode-settings.js

@@ -63,9 +63,8 @@ function snippetFor(wanted, present) {
 }
 
 /**
- * Read-only: what `.vscode/settings.json` would need. `write` carries the full new text;
- * `suggest` carries the snippet to paste, because rewriting would drop comments, trailing
- * commas or a tracked file's cleanliness.
+ * Read-only. `write` carries the full new text; `suggest` carries the snippet to paste, because
+ * rewriting would drop comments, trailing commas or a tracked file's cleanliness.
  */
 export function planEditorSettings(root, { config = readProjectConfig(root), env = process.env } = {}) {
   const file = join(root, SETTINGS_REL);

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

@@ -1,28 +1,3 @@
-/**
- * worktree-audit.js — reconcile the three views of "which worktrees exist".
- *
- * Orphan worktrees accumulate silently. In the observed session,
- * `.worktrees/verify-tables-ui` and `.worktrees/tmp-cleanup` were registered in
- * `git worktree list` yet ABSENT from `morph-spec fleet` — fleet only reports
- * worktrees whose branch matches `refs/heads/morph/*`, so anything else is
- * invisible by construction and therefore never cleaned up (C2).
- *
- * Nothing compared the three sources that must agree:
- *
- *   1. git's registry   — `git worktree list --porcelain`
- *   2. the disk         — directories under `worktrees/` (and legacy `.worktrees/`)
- *   3. morph's features — `.morph/features/{f}/feature.json`
- *
- * Read-only and fail-open: anything unresolvable yields no issue rather than a
- * throw. A diagnostic that invents problems is worse than one that misses some.
- * The mutations all live in `pruneWorktrees`, and each is deliberately the
- * safest possible: `git worktree prune` drops ADMIN RECORDS for directories
- * that are already gone, and the empty-residue sweep removes only directories
- * with zero entries inside — nothing that can hold work. Deleting a directory
- * that still HOLDS something stays a human decision, the same PROVE-or-DECLINE
- * discipline `teardownWorktree` follows.
- */
-
 import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, rmdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
@@ -73,7 +48,6 @@ function agentLeftoverIssue(item) {
   };
 }
 
-/** Feature names morph knows about in the primary root. */
 function knownFeatures(root) {
   const names = new Set();
   try {
@@ -86,14 +60,7 @@ function knownFeatures(root) {
   return names;
 }
 
-/**
- * Is the feature's authoritative feature.json COMMITTED on its own branch?
- *
- * Not "does the branch exist": `git worktree add -b morph/{f}` creates the
- * branch as a side effect, so branch-existence is true for every registered
- * worktree and proves nothing. The blob is the real evidence — it is where the
- * per-feature state model says the truth lives.
- */
+// Branch existence proves nothing (`worktree add -b` creates it); the committed blob does.
 function featureCommittedOnBranch(root, feature) {
   try {
     execFileSync('git', ['cat-file', '-e', `morph/${feature}:.morph/features/${feature}/feature.json`], {
@@ -105,29 +72,8 @@ function featureCommittedOnBranch(root, feature) {
   }
 }
 
-/**
- * Does this worktree's branch still hold work that is NOT in the default
- * branch, or an OPEN PR?
- *
- * This is the predicate that separates "an orphan directory to clean up" from
- * "the only copy of somebody's work". Two independent pieces of evidence, and
- * ANY of them is enough to protect the worktree:
- *
- *   1. commits the default branch does not have (`git rev-list base..branch`)
- *   2. an OPEN pull request on that branch
- *
- * Fail-CLOSED, and that asymmetry is the whole design: whenever the answer
- * cannot be established — no default branch, no origin, git errored — the
- * worktree counts as UNINTEGRATED. The cost of being wrong that way is a
- * diagnostic that stays quiet; the cost of the opposite is a suggestion to
- * delete work that exists nowhere else.
- *
- * A squash-merged branch legitimately reports commits ahead, so the tree
- * comparison (`branch-classifier.js`) is consulted for the same reason
- * `branch prune` needs it — the two must not disagree about "is this in".
- *
- * @returns {{ unintegrated: boolean, evidence: string, pr: number|null }}
- */
+// Fail-CLOSED: when integration cannot be established the worktree counts as
+// unintegrated — a quiet diagnostic beats suggesting to delete the only copy.
 function unintegratedWork(root, branchRef, prIndex) {
   const branch = (branchRef || '').replace(/^refs\/heads\//, '');
   if (!branch) return { unintegrated: true, evidence: 'não foi possível resolver a branch do worktree', pr: null };
@@ -143,9 +89,7 @@ function unintegratedWork(root, branchRef, prIndex) {
   if (ahead === null) return { unintegrated: true, evidence: `não foi possível comparar com ${baseRef}`, pr: null };
   if (ahead === 0) return { unintegrated: false, evidence: `nenhum commit fora de ${baseRef}`, pr: pr?.number ?? null };
 
-  // Commits ahead, but the work may still be IN: a squash-merge leaves exactly
-  // that shape. Reuse the classifier so `doctor` and `branch prune` cannot
-  // reach opposite conclusions about the same branch.
+  // A squash-merge also leaves commits ahead; the classifier keeps `doctor` and `branch prune` agreeing.
   const verdict = classifyBranch({ name: branch, sha: '', current: false, worktreePath: null }, { baseRef, cwd: root, pr });
   if (verdict.kind === 'merged-ancestral' || verdict.kind === 'merged-squash') {
     return { unintegrated: false, evidence: verdict.reason, pr: pr?.number ?? null };
@@ -153,19 +97,6 @@ function unintegratedWork(root, branchRef, prIndex) {
   return { unintegrated: true, evidence: `${ahead} commit(s) fora de ${baseRef}`, pr: pr?.number ?? null };
 }
 
-/**
- * Every feature's `worktree` registration in the primary root — the OTHER
- * direction from `knownFeatures`/`dirsOnDisk`: not "does git/disk know about
- * this worktree", but "does the ROOT's feature.json still point somewhere
- * real". `create --worktree` writes this pointer once at birth
- * (`{path, branch, createdAt}`) and nothing updates it afterwards except
- * `finish`'s own teardown — so a directory removed any other way (by hand,
- * `git worktree prune` run directly, a failed teardown that still cleared the
- * field, an unrelated script) leaves it dangling with nothing to notice.
- *
- * @param {string} root
- * @returns {Array<{ feature: string, path: string, branch: string|null }>}
- */
 function featureRegistrations(root) {
   const out = [];
   try {
@@ -183,23 +114,15 @@ function featureRegistrations(root) {
   return out;
 }
 
-/**
- * Is this directory literally empty — zero entries, dotfiles included?
- *
- * The whole point of the distinction: an empty residue holds nothing that can
- * be lost, so it can be removed without a human looking at it. Anything else —
- * including a directory we cannot read — is reported as NON-empty, because the
- * safe answer to "might there be work in here?" is yes.
- */
+// Unreadable counts as occupied: emptiness is what licenses automatic removal.
 function isEmptyDir(path) {
   try {
     return readdirSync(path).length === 0;
   } catch {
-    return false; // unreadable → treat as occupied
+    return false;
   }
 }
 
-/** Directories physically present under either worktree root. */
 function dirsOnDisk(root) {
   const found = [];
   const rootNorm = norm(root);
@@ -221,53 +144,8 @@ function dirsOnDisk(root) {
 }
 
 /**
- * Reconcile git's registry, the disk and morph's features.
- *
- * Issue types:
- *   • registered-missing        — git has a worktree whose directory is gone
- *   • non-morph-branch          — a registered worktree under worktrees/ on a
- *                                 branch that is not `morph/*`, so `fleet`
- *                                 cannot see it
- *   • unregistered-dir          — a directory under worktrees/ git never
- *                                 registered
- *   • no-feature                — a `morph/{f}` worktree for a feature morph
- *                                 does not know AND whose branch carries
- *                                 nothing that is not already integrated
- *   • unintegrated-work (info)  — the same shape, except the branch still holds
- *                                 commits the default does not, or an OPEN PR.
- *                                 Reported so the reader knows why no removal
- *                                 is suggested — this worktree may be the ONLY
- *                                 copy of the work
- *   • dangling-registration     — a feature's ROOT feature.json still points
- *                                 at a `worktree.path` that no longer exists
- *                                 (the symmetric OTHER direction from
- *                                 `no-feature`: the worktree is gone, but the
- *                                 root's pointer to it survived)
- *   • unregistered-registration — a feature's `worktree.path` names a
- *                                 directory that exists but git's own
- *                                 registry does not know as a worktree
- *
- *   • agent-worktree-leftover (info) — a sub-agent's `agent-<hex>` tree or
- *                                 `morph-task/agent-<hex>` branch left behind:
- *                                 `reapable` when the agent stopped and nothing
- *                                 is lost, otherwise the reason it is kept
- *
- *   • 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 }>}
+ * Reconciles git's worktree registry, the disk, morph's features and docker.
+ * Read-only and fail-open; `exec` is the docker executor seam.
  */
 export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   if (!isGitRepo(cwd)) return [];
@@ -275,9 +153,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   const rootNorm = norm(root);
   const issues = [];
 
-  // ONE `gh pr list` for the whole audit — null means UNKNOWN (no gh, not
-  // GitHub, not authenticated), never "no PRs"; `unintegratedWork` treats the
-  // two differently on purpose.
+  // null = UNKNOWN (no gh / not GitHub / unauthenticated), never "no PRs".
   const prIndex = buildPrIndex(root);
 
   const containers = containerDirs(root);
@@ -288,7 +164,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   for (const entry of registered) {
     const path = norm(entry.path);
     registeredPaths.add(path);
-    if (path === rootNorm) continue; // the primary root is not a worktree orphan
+    if (path === rootNorm) continue;
 
     if (!existsSync(path)) {
       issues.push({
@@ -306,12 +182,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       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.
+        // Never pruned: the work inside a tree created outside morph may be the only copy.
         const work = unintegratedWork(root, entry.branch, prIndex);
         issues.push({
           type: 'out-of-container',
@@ -327,10 +198,6 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
 
       if (task) {
         if (AGENT_TASK.test(task)) continue; // reported once, by the agent plan below
-        // `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({
@@ -345,11 +212,6 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       }
 
       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
-        // elsewhere. A worktree on a `feat/*` branch with an open PR is the
-        // most normal thing in the world, and suggesting its removal is a
-        // suggestion to destroy the only copy.
         const work = unintegratedWork(root, entry.branch, prIndex);
         issues.push(work.unintegrated
           ? {
@@ -365,10 +227,8 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
             type: 'non-morph-branch',
             path,
             detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga (e não há trabalho pendente: ${work.evidence})`,
-            // 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.
+            // Never raw `git worktree remove`: it follows the infra junctions and
+            // empties the root's .claude/ and .morph/framework/.
             fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
           });
       }
@@ -376,13 +236,8 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
     }
 
     if (!features.has(feature) && !featureCommittedOnBranch(root, feature)) {
-      // "sem feature conhecida" is a bookkeeping fact, NOT a verdict on the
-      // work: a `finish` that archived the feature leaves exactly this shape,
-      // and so does a worktree whose PR is still open. In the observed session
-      // this branch recommended `worktree remove --target` for a worktree
-      // holding the ONLY copy of an open PR with 12 tasks and a 9.5 at Gate 3.
-      // So the diagnosis now depends on whether the WORK is integrated, and the
-      // suggestion to destroy appears only when it provably is.
+      // An archived feature or an open PR leaves this same shape: suggest removal
+      // only when the work is provably integrated.
       const work = unintegratedWork(root, entry.branch, prIndex);
       if (work.unintegrated) {
         issues.push({
@@ -420,19 +275,12 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       detail: d.empty
         ? `${d.container}/${d.name} existe no disco, está VAZIO e o git não o registra — resíduo de um finish anterior`
         : `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
-      // An empty folder has nothing to lose, so it gets the automatic repair.
-      // One with content keeps the manual chore: there may be work in there,
-      // and the whole PROVE-or-DECLINE discipline exists for exactly that.
       fix: d.empty
         ? `morph-spec doctor --worktrees --prune`
         : `apague o diretório à mão depois de conferir que nada importante ficou nele`,
     });
   }
 
-  // The other direction: does the ROOT's own bookkeeping still point at a
-  // live worktree? `git worktree list`/disk only see what's PHYSICALLY
-  // there; a registration surviving past its worktree's removal is invisible
-  // to every check above.
   for (const reg of featureRegistrations(root)) {
     const path = norm(reg.path);
     if (!existsSync(reg.path)) {
@@ -454,13 +302,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
     }
   }
 
-  // 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.
+  // Feature names are passed in so docker-audit never rescans and disagrees.
   const treeFeatures = new Set(features);
   for (const entry of registered) {
     const f = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1];
@@ -468,31 +310,13 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   }
   issues.push(...auditDockerStacks(root, { exec, features: treeFeatures }));
 
-  // What a worktree removal leaves behind in `.git/morph-spec/finish-backup/`
-  // past its retention — `warn`, pruned by `--prune` and by the next finish.
   issues.push(...auditFinishBackups(root));
 
   return issues;
 }
 
-/**
- * Remove the EMPTY directories under `worktrees/`/`.worktrees/` that git does
- * not register — the residue a finish leaves behind.
- *
- * "Empty" is the whole licence to act: a folder with zero entries cannot be
- * hiding uncommitted work, so asking a human about it is pure ceremony, and
- * the audit that only warns leaves it there forever. A directory with anything
- * in it keeps the manual path.
- *
- * Two guards beyond the emptiness check:
- *   • only directories directly inside morph's own worktree containers, never
- *     the containers themselves and never a path git registers;
- *   • `rmdirSync`, not `rm -rf` — it REFUSES a non-empty directory, so a file
- *     that appears between the check and the call is a failure, not a loss.
- *
- * @param {string} root
- * @returns {string[]} paths actually removed
- */
+// `rmdirSync`, never `rm -rf`: a file that appears after the emptiness check
+// makes it fail instead of being lost.
 function removeEmptyUnregisteredDirs(root) {
   const registeredPaths = new Set(parseWorktreeList(root).map((e) => norm(e.path)));
   const removed = [];
@@ -507,25 +331,9 @@ function removeEmptyUnregisteredDirs(root) {
 }
 
 /**
- * Drop git's admin records for worktrees whose directory is already gone,
- * remove the EMPTY unregistered residue directories, AND clear any feature's
- * `worktree` registration that names a directory that is now gone.
- *
- * These three are the ONLY prune offered, on purpose: none can destroy
- * anything, because everything they touch is either already absent from disk
- * or provably empty. Removing a directory that still HOLDS something is
- * exactly the operation that needs a human looking at it.
- *
- * Order is load-bearing: the empty directories go first, so a root pointer
- * naming one of them becomes dangling in time for the registration sweep below
- * to clear it — one command, not two runs.
- *
- * `clearDanglingWorktreeRegistration` re-checks the dangling predicate itself
- * (path unset, or still exists → no-op) rather than trusting a pre-computed
- * list, so this stays correct even called against a stale audit snapshot.
- *
- * @param {string} [cwd]
- * @returns {Promise<{ pruned: boolean, error?: string, removedEmptyDirs: string[], clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
+ * Touches only what is already gone from disk or provably empty. Order matters:
+ * empty dirs go first so a root pointer to one becomes dangling and is cleared
+ * in the same run.
  */
 export async function pruneWorktrees(cwd = process.cwd()) {
   if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', removedEmptyDirs: [], clearedRegistrations: [] };

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

@@ -9,11 +9,9 @@ const NESTED_GIT = /(^|\/)\.git(\/|$)/;
 const gitOut = (cwd, args, input) => execFileSync('git', args, { cwd, stdio: ['pipe', 'pipe', 'ignore'], encoding: 'utf8', input });
 
 /**
- * Claude Code's `.worktreeinclude` for a worktree morph-spec creates (a WorktreeCreate hook replaces
- * the native creation, so the native copy never runs): files matching a pattern AND gitignored in the
- * tree are copied when the tree lacks them. Real files only; build artifacts and `node_modules` never.
- *
- * @returns {string[]} relative paths copied
+ * `.worktreeinclude` parity: a WorktreeCreate hook replaces the native creation, so the native copy
+ * never runs. Copies files matching a pattern AND gitignored in the tree, when the tree lacks them;
+ * never build artifacts or `node_modules`. Returns the relative paths copied.
  */
 export function copyWorktreeIncludes(worktreePath, root) {
   const file = join(root, INCLUDE_FILE);

package/src/scripts/global-install.js

@@ -1,4 +1,3 @@
-// src/scripts/global-install.js
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir, platform } from 'os';
@@ -10,10 +9,7 @@ import { installGlobalStatusline } from '../utils/hooks-installer.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_DIR = join(__dirname, '..', '..', 'framework');
 
-/**
- * Ensure the npm global bin directory is in the user's PATH on Windows.
- * Adds it to the PowerShell $PROFILE so new terminals find `morph-spec`.
- */
+/** Windows only: adds the npm global bin to the PowerShell $PROFILE so new terminals find `morph-spec`. */
 export async function ensureNpmGlobalInPath() {
   if (platform() !== 'win32') return;
 
@@ -21,12 +17,11 @@ export async function ensureNpmGlobalInPath() {
   try {
     npmGlobalDir = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
   } catch {
-    return; // can't determine npm global dir
+    return;
   }
 
   if (!npmGlobalDir || !existsSync(npmGlobalDir)) return;
 
-  // --- PowerShell $PROFILE ---
   const psProfile = join(homedir(), 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
   const psProfileLegacy = join(homedir(), 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1');
 
@@ -44,7 +39,7 @@ export async function ensureNpmGlobalInPath() {
       let content = '';
       if (existsSync(profilePath)) {
         content = await readFile(profilePath, 'utf8');
-        if (content.includes(marker)) continue; // already patched
+        if (content.includes(marker)) continue;
       } else {
         await mkdir(dirname(profilePath), { recursive: true });
       }
@@ -56,7 +51,6 @@ export async function ensureNpmGlobalInPath() {
   }
 }
 
-// Run as postinstall script
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const HOOKS_SRC = join(FRAMEWORK_DIR, 'hooks', 'claude-code');
   const { readFileSync } = await import('fs');