@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/worktree/fleet-scanner.js

@@ -1,17 +1,4 @@
-/**
- * fleet-scanner.js — aggregate view of every active feature across the fleet.
- *
- * A fleet is N Claude Code instances, one per feature worktree, plus whatever
- * is active in the primary root. Each instance only sees its own cwd; the
- * operator loses track of "what is each session doing, what is waiting on me".
- * This scanner answers that from the primary root's vantage point: one entry
- * per active feature, worktree or root-resident, with the operational facts
- * (phase, pending gates, task counts, port block, handoff freshness, last
- * commit, dirtiness) resolved per entry.
- *
- * Read-only and fail-open per FIELD: a corrupt feature.json or a git hiccup
- * nulls that field, never the scan.
- */
+// Fail-open per FIELD: a corrupt feature.json or a git hiccup nulls that field, never the scan.
 
 import { execSync, execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync } from 'fs';
@@ -24,52 +11,31 @@ import {
   getFeature,
   derivePhaseForFeature,
   derivePhaseFrom,
+  fileSetArtifactProbe,
   getPendingGates,
   pendingGatesFrom,
 } from '../../../framework/hooks/shared/state-reader.js';
 import { listClaims } from '../../../framework/hooks/shared/claim-registry.js';
 import { buildPrIndex } from '../git/pr-index.js';
 import { pendingPrFeatures } from '../git/pending-prs.js';
+import { sliceProgress, sliceProgressFrom } from '../../../framework/hooks/shared/slice-progress.js';
 
-function countFrom(raw) {
-  const data = JSON.parse(raw);
-  if (!Array.isArray(data.tasks)) return null;
-  return { done: data.tasks.filter((t) => t.status === 'done').length, total: data.tasks.length };
-}
+const counts = (progress) => (progress ? { done: progress.done, total: progress.total } : null);
 
-/**
- * Task progress for one feature.
- *
- * DIVERGENCE from the bug report, which blamed "a cached state.json/feature.json
- * snapshot": this never read either — it always read `2-plan/tasks.json`
- * directly. The real mechanism is which COPY of that file is on disk. Since
- * v8.4 every feature is born on `morph/{f}` and its tasks.json is COMMITTED
- * there; the primary root's working tree only ever holds the copy of the
- * CHECKED-OUT branch. An operator sitting on the default therefore read the
- * pre-work copy — the reported `2/2` for a feature whose branch already had
- * T1..T3 all done.
- *
- * @param {string} featureDir - the feature dir inside `path`
- * @param {{ root: string, feature: string, featureBranch: string|null }} ctx
- */
-function taskCounts(featureDir, { root, feature, featureBranch } = {}) {
+// A root-resident feature's reports live on `morph/{f}`; the root tree only has the pre-work copy.
+function sliceCounts(featureDir, { root, feature, featureBranch } = {}) {
   if (featureBranch && root && feature) {
-    try {
-      const raw = execFileSync(
-        'git',
-        ['show', `${featureBranch}:.morph/features/${feature}/2-plan/tasks.json`],
-        { cwd: root, stdio: 'pipe' },
-      ).toString();
-      const counted = countFrom(raw);
-      if (counted) return counted;
-    } catch { /* no such branch/blob — fall through to the working tree */ }
-  }
-
-  try {
-    return countFrom(readFileSync(join(featureDir, '2-plan', 'tasks.json'), 'utf8'));
-  } catch {
-    return null;
+    const show = (rel) => {
+      try {
+        return execFileSync('git', ['show', `${featureBranch}:.morph/features/${feature}/${rel}`], { cwd: root, stdio: 'pipe' }).toString();
+      } catch {
+        return null;
+      }
+    };
+    const onBranch = sliceProgressFrom(show('2-plan/checks.json'), (id) => show(`3-implement/reports/${id}.md`));
+    if (onBranch) return counts(onBranch);
   }
+  return counts(sliceProgress(featureDir));
 }
 
 function handoffInfo(featureDir) {
@@ -101,20 +67,7 @@ function dirtyCount(worktreePath) {
   }
 }
 
-/**
- * One `git ls-remote --heads origin` for the WHOLE scan → Map<branch, sha>.
- *
- * The fleet used to read only local state, so a feature whose branch (and PR)
- * already lived on origin still showed up as "pending, nothing pushed" — that
- * reading is what made a second session redo finished work. Resolved once per
- * scan, never per entry.
- *
- * Returns `null` when there is no origin, or the probe fails/times out: the
- * entries then carry `remote: null` ("unknown"), never a false `pushed: false`.
- *
- * @param {string} root
- * @returns {Map<string,string>|null}
- */
+// null = unknown (no origin, or the probe failed): entries get `remote: null`, never a false `pushed: false`.
 function remoteHeads(root) {
   if (!hasOriginRemote(root)) return null;
   try {
@@ -132,28 +85,11 @@ function remoteHeads(root) {
   }
 }
 
-/**
- * One `gh pr list` for the whole scan → Map<headRefName, {number, state}>.
- *
- * Delegates to the shared `buildPrIndex` so `fleet`, `branch prune` and
- * `doctor --worktrees` cannot answer "does this branch have a PR" differently
- * — the destructive two read it to decide what NOT to delete.
- *
- * Fail-open: `null` (no `gh`, not authenticated, not GitHub, timeout) just
- * leaves the PR half of the column empty while `pushed` still works.
- *
- * @param {string} root
- * @returns {Map<string,{number:number,state:string}>|null}
- */
 function remotePrs(root) {
   return buildPrIndex(root, { limit: 100 });
 }
 
-/**
- * The remote fact for one feature. Worktree entries know their real branch
- * (which may carry a `--fresh` date suffix); root-resident features fall back
- * to the canonical `morph/{feature}` every feature is born on.
- */
+// A worktree's real branch may carry a `--fresh` date suffix; only root entries fall back to `morph/{f}`.
 function buildRemote(feature, branch, heads, prs) {
   if (!heads) return null;
   const remoteBranch = branch || `morph/${feature}`;
@@ -164,23 +100,17 @@ function buildRemote(feature, branch, heads, prs) {
 function buildEntry(feature, { location, path, branch, root, allocations, blockSize, heads, prs, claims }) {
   let workType = null;
   let status = 'unknown';
-  let phase = 'proposal';
+  let phase = 'plan';
   let pendingGates = [];
 
-  // Resolved once and shared with taskCounts — see branchToReadFrom.
   const featureBranch = branchToReadFrom(root, feature, location, branch);
 
   try {
-    // B3b: phase and gates suffered the same branch-staleness B3 fixed for
-    // tasks. They read `.morph/features/{f}/` through the working tree, so a
-    // root parked on the default reported the PRE-WORK phase for a feature
-    // whose branch was already at implement — and re-asked for a gate the
-    // feature branch had already approved.
     const view = featureBranch ? branchView(root, feature, featureBranch) : null;
     if (view) {
       workType = view.fj?.workType || null;
       status = view.fj?.status || 'unknown';
-      phase = derivePhaseFrom(view.fj, (rel) => view.files.has(rel));
+      phase = derivePhaseFrom(view.fj, fileSetArtifactProbe(view.files));
       pendingGates = pendingGatesFrom(view.fj);
     } else {
       const fj = getFeature(feature, path);
@@ -189,7 +119,7 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
       phase = derivePhaseForFeature(feature, path);
       pendingGates = getPendingGates(feature, path);
     }
-  } catch { /* field-level fail-open */ }
+  } catch { /* fail-open */ }
 
   const featureDir = join(path, '.morph', 'features', feature);
   const alloc = allocations[feature];
@@ -202,7 +132,7 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
     location,
     path,
     branch,
-    tasks: taskCounts(featureDir, { root, feature, featureBranch }),
+    slices: sliceCounts(featureDir, { root, feature, featureBranch }),
     env: alloc && Number.isInteger(alloc.base)
       ? { base: alloc.base, range: [alloc.base, alloc.base + blockSize - 1] }
       : null,
@@ -210,20 +140,11 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
     lastCommit: location === 'worktree' && branch ? lastCommitRelative(root, branch) : null,
     dirty: location === 'worktree' ? dirtyCount(path) : null,
     remote: buildRemote(feature, branch, heads, prs),
-    // Advisory ownership (B1): which session is on this feature right now.
-    // `live` is what matters for the operator — a stale claim is reported as
-    // stale rather than hidden, so "nobody is here" and "somebody died here"
-    // stay distinguishable.
+    // A stale claim is reported, not hidden: "nobody is here" ≠ "somebody died here".
     claim: claims?.[feature] || null,
   };
 }
 
-/**
- * Scan the fleet from anywhere inside the repo.
- *
- * @param {string} [cwd]
- * @returns {{ root: string, entries: object[] }}
- */
 export function scanFleet(cwd = process.cwd()) {
   if (!isGitRepo(cwd)) {
     return { root: resolve(cwd).replace(/\\/g, '/'), entries: [] };
@@ -239,13 +160,12 @@ export function scanFleet(cwd = process.cwd()) {
       try {
         const reg = JSON.parse(readFileSync(registryPath(gitCommonDir), 'utf8'));
         if (reg && typeof reg.allocations === 'object' && reg.allocations !== null) allocations = reg.allocations;
-      } catch { /* no env registry yet — env stays null per entry */ }
+      } catch { /* env stays null per entry */ }
       for (const c of listClaims(gitCommonDir)) claims[c.feature] = c;
     }
-  } catch { /* no common dir — env and claim both stay null per entry */ }
+  } catch { /* env and claim stay null per entry */ }
   const { blockSize } = resolveFleetConfig(root);
 
-  // Remote awareness, resolved ONCE for the whole scan (see remoteHeads/remotePrs).
   const heads = remoteHeads(root);
   const prs = heads ? remotePrs(root) : null;
 
@@ -254,7 +174,7 @@ export function scanFleet(cwd = process.cwd()) {
 
   for (const e of parseWorktreeList(root)) {
     const m = e.branch && e.branch.match(/^refs\/heads\/morph\/(.+)$/);
-    if (!m) continue; // primary root entry and non-morph worktrees
+    if (!m) continue;
     inWorktree.add(m[1]);
     entries.push(buildEntry(m[1], {
       location: 'worktree',
@@ -269,7 +189,6 @@ export function scanFleet(cwd = process.cwd()) {
     }));
   }
 
-  // Root-resident features (no live worktree): whatever has a feature.json.
   try {
     const featuresDir = join(root, '.morph', 'features');
     if (existsSync(featuresDir)) {
@@ -285,23 +204,9 @@ export function scanFleet(cwd = process.cwd()) {
     }
   } catch { /* fail-open */ }
 
-  // Features that exist ONLY as an open PR: no registered worktree, no
-  // `.morph/features/*` folder in this tree. This is exactly what
-  // `finish --pr` leaves behind — and without this pass `fleet` would say
-  // "nothing in flight" about work that is under review on GitHub.
-  //
-  // `prs` was attempted above whenever `heads` is truthy (`remotePrs` runs —
-  // see `const prs = heads ? remotePrs(root) : null;` — regardless of
-  // whether that `gh` call itself succeeded). Gate on the SAME condition
-  // `remotePrs` used, not on `prs !== null`: `remotePrs`/`buildPrIndex` can
-  // fail (timeout, not authenticated, malformed JSON) and legitimately
-  // return `null` even after really invoking `gh`. Passing that `null`
-  // through lets `pendingPrFeatures` short-circuit on its own documented
-  // contract (explicit `null` index = known unknown, never a fallback build)
-  // instead of retrying `gh` a second time in the same scan. Only when
-  // `remotePrs` was never attempted at all (`heads` falsy) does
-  // `pendingPrFeatures` get no index, so it makes the first (and only) `gh`
-  // call itself.
+  // Features that exist only as an open PR (what `finish --pr` leaves). Gate on `heads`, not
+  // `prs !== null`: a `gh` that already ran and failed passes an explicit `null` index, so
+  // `pendingPrFeatures` does not call `gh` a second time.
   try {
     const seen = new Set(entries.map((e) => e.feature));
     const pendOpts = heads ? { index: prs } : {};
@@ -316,7 +221,7 @@ export function scanFleet(cwd = process.cwd()) {
         location: 'pr-pending',
         path: null,
         branch: p.branch,
-        tasks: null,
+        slices: null,
         env: null,
         handoff: { exists: false, generatedAt: null },
         lastCommit: null,
@@ -325,7 +230,7 @@ export function scanFleet(cwd = process.cwd()) {
         claim: null,
       });
     }
-  } catch { /* fail-open — a pendency not listed must never take down the scan */ }
+  } catch { /* fail-open */ }
 
   return { root, entries };
 }

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