@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/worktree/feature-truth.js

@@ -1,42 +1,12 @@
-/**
- * feature-truth.js — where a feature's authoritative `feature.json` actually
- * lives, and how to read it from a place that isn't the feature's own tree.
- *
- * `create --worktree` writes a COMPLETE feature.json into the primary root
- * (status, approvalGates, tasks, gateDecisions) and only then copies it into
- * the worktree. From that instant the branch-committed copy (`morph/{f}`) is
- * the truth and the root's copy never changes again — the root sees the
- * feature exactly as it was at birth, forever, unless someone reads through.
- *
- * `branchToReadFrom`/`branchView` are moved verbatim from fleet-scanner.js —
- * they already solved this (comments B3/B3b there), fleet just never shared
- * them. `resolveFeatureTree` is the missing piece for CONSUMERS OTHER than
- * fleet: "which tree/branch actually owns this feature's state", used by
- * `list`, `handoff`, and the mutator guard (assertOwnerTree).
- *
- * Fail-open throughout: no repo, no branch, no blob, unparseable JSON never
- * throws — callers get null/false and fall back to reading the disk.
- */
+// After `create --worktree`, the root keeps the feature.json frozen at birth; the
+// committed copy on `morph/{f}` is the truth. Fail-open: null means "read the disk".
 
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { isGitRepo, resolvePrimaryRoot, findWorktreeForFeature, buildBranchName } from '../../commands/project/worktree.js';
 
-/**
- * Which branch holds this feature's truth, when the working tree at `path` does
- * NOT — or `null` when the working tree IS the feature's own checkout.
- *
- * The ONE place this condition lives. `tasks` (B3) and `phase`/`pendingGates`
- * (B3b) are the same defect read through different files, so they must agree on
- * when to look at the branch; two drifting copies of this test would resurrect
- * the bug on one field while the other stayed fixed.
- *
- * A worktree entry is the feature's checkout by construction. A root entry is
- * only the feature's checkout when the root happens to be ON `morph/{f}`.
- *
- * @returns {string|null} branch name to read from, or null for "read the disk"
- */
+/** Branch holding the feature's truth, or `null` when this tree IS its checkout (read the disk). */
 export function branchToReadFrom(root, feature, location, branch) {
   if (location === 'worktree' || !root || !feature) return null;
   const featureBranch = branch || `morph/${feature}`;
@@ -45,24 +15,12 @@ export function branchToReadFrom(root, feature, location, branch) {
       .toString().trim();
     return current === featureBranch ? null : featureBranch;
   } catch {
-    return null; // no HEAD to compare against — trust the disk
+    return null;
   }
 }
 
-/**
- * The feature's committed state on its own branch: the feature.json blob plus
- * the set of files under its feature dir.
- *
- * `git ls-tree -z` is deliberate: without it git QUOTES paths containing
- * non-ASCII bytes (`"a\303\247/…"`), which would silently fail the prefix strip
- * and leave the artifact set empty — a predicate that is always false looks
- * exactly like "this feature has no artifacts".
- *
- * Fail-open in layers: no blob → null (caller reads the disk); no tree → the
- * gates alone still beat a stale working tree.
- *
- * @returns {{ fj: Object, files: Set<string> }|null}
- */
+// `ls-tree -z` is load-bearing: without it git quotes non-ASCII paths, the prefix
+// strip fails and the file set comes back silently empty.
 export function branchView(root, feature, featureBranch) {
   const prefix = `.morph/features/${feature}/`;
   let fj;
@@ -83,12 +41,11 @@ export function branchView(root, feature, featureBranch) {
       const p = raw.trim();
       if (p.startsWith(prefix)) files.add(p.slice(prefix.length));
     }
-  } catch { /* no tree — gates alone still beat the stale working tree */ }
+  } catch { /* the gates alone still beat a stale working tree */ }
 
   return { fj, files };
 }
 
-/** All local `morph/*` branches, as bare feature names — one spawn, a pre-filter. */
 export function morphBranches(root) {
   try {
     const out = execFileSync('git', ['for-each-ref', '--format=%(refname:short)', 'refs/heads/morph/'], {
@@ -105,7 +62,7 @@ export function morphBranches(root) {
   }
 }
 
-/** The tree's current branch, or null (detached HEAD / no repo / no commits yet). */
+/** null on detached HEAD, no repo or no commits yet. */
 export function currentBranch(cwd) {
   try {
     const out = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
@@ -115,7 +72,6 @@ export function currentBranch(cwd) {
   }
 }
 
-/** Read a feature's local feature.json from `dir`, or null if missing/corrupt. */
 function readLocalFeatureJson(dir, feature) {
   const p = join(dir, '.morph', 'features', feature, 'feature.json');
   if (!existsSync(p)) return null;
@@ -127,35 +83,9 @@ function readLocalFeatureJson(dir, feature) {
 }
 
 /**
- * Resolve which TREE (or, failing that, which BRANCH) actually owns a
- * feature's state — "follow the pointer" for any consumer, not just fleet.
- *
- * Six-step search, each step justified by what it's immune to:
- *
- *  1. cwd holds the feature AND cwd is that feature's registered worktree
- *     (git's own record, via findWorktreeForFeature) → running inside the
- *     owner never counts as a jump.
- *  2. `findWorktreeForFeature` finds a live worktree elsewhere → the tree the
- *     GIT REGISTRY says is the owner, not the feature.json pointer — immune
- *     to a dangling/stale `feature.worktree` field.
- *  3. the local feature.json's own `worktree.path` field, if it still exists
- *     on disk → covers a worktree living outside the conventional path or a
- *     registry `git worktree list` can't see for some reason.
- *  4. cwd holds the feature with no worktree registered anywhere → the common
- *     case (no `--worktree`, or the worktree was already torn down).
- *  5. no local copy, but `morph/{feature}` has the file committed → the truth
- *     exists, just not materialized into any tree right now.
- *  6. nothing anywhere.
- *
- * @param {string} feature
- * @param {string} [cwd]
- * @returns {{
- *   source: 'cwd'|'registry'|'pointer'|'branch-only'|'none',
- *   tree: string|null,
- *   branch: string|null,
- *   worktree: {path:string, branch:string}|null,
- *   pointerDangling: boolean,
- * }}
+ * Order: git's worktree registry, then the feature.json pointer, then cwd, then the branch.
+ * The registry comes first so a stale `feature.worktree` pointer never wins.
+ * @returns {{ source: 'cwd'|'registry'|'pointer'|'branch-only'|'none', tree: string|null, branch: string|null, worktree: {path:string, branch:string}|null, pointerDangling: boolean }}
  */
 export function resolveFeatureTree(feature, cwd = process.cwd()) {
   const localFj = readLocalFeatureJson(cwd, feature);
@@ -165,8 +95,6 @@ export function resolveFeatureTree(feature, cwd = process.cwd()) {
   const inGit = isGitRepo(cwd);
   const root = inGit ? resolvePrimaryRoot(cwd) : null;
 
-  // Step 1 + 2: git's own worktree registry is the source of truth for "is
-  // there a live worktree for this feature, and where".
   if (inGit && root) {
     const registered = findWorktreeForFeature(feature, root);
     if (registered && existsSync(registered.path)) {
@@ -178,19 +106,15 @@ export function resolveFeatureTree(feature, cwd = process.cwd()) {
     }
   }
 
-  // Step 3: the local pointer names a worktree the registry didn't surface
-  // (unconventional location, or registry unreadable) but that still exists.
   if (pointerPath && !pointerDangling) {
     const branch = localFj?.worktree?.branch || buildBranchName(feature);
     return { source: 'pointer', tree: pointerPath, branch, worktree: { path: pointerPath, branch }, pointerDangling };
   }
 
-  // Step 4: this tree holds the feature and nothing else claims to own it.
   if (localFj) {
     return { source: 'cwd', tree: cwd, branch: null, worktree: null, pointerDangling };
   }
 
-  // Step 5: no local copy anywhere in this tree, but the branch has one.
   if (inGit && root) {
     const branch = buildBranchName(feature);
     const view = branchView(root, feature, branch);
@@ -199,43 +123,16 @@ export function resolveFeatureTree(feature, cwd = process.cwd()) {
     }
   }
 
-  // Step 6.
   return { source: 'none', tree: null, branch: null, worktree: null, pointerDangling: false };
 }
 
-/**
- * Should a mutator (approve/advance/score/gate-decision/gate-check) refuse to
- * write this feature's `feature.json` from `cwd`?
- *
- * Blocked ONLY when a live worktree owns the feature and it is NOT cwd —
- * `resolveFeatureTree` sources `'registry'`/`'pointer'`. `'cwd'` (cwd IS the
- * owner, or no worktree exists at all) always passes. This is what stops
- * `morph-spec approve <f> plan` run from the root, with the worktree still
- * alive, from silently stamping the gate onto the root's birth-instant
- * skeleton — branch-drift CREATED by a command, not merely left behind by one.
- *
- * @param {string} feature
- * @param {string} [cwd]
- * @returns {{ blocked: boolean, tree: string|null, branch: string|null }}
- */
+/** Blocked only when a live worktree other than cwd owns the feature, so the root skeleton is never stamped. */
 export function assertOwnerTree(feature, cwd = process.cwd()) {
   const owner = resolveFeatureTree(feature, cwd);
   const blocked = owner.source === 'registry' || owner.source === 'pointer';
   return { blocked, tree: owner.tree, branch: owner.branch };
 }
 
-/**
- * The refusal text every mutator prints on an owner-tree block — one place so
- * `approve`/`advance`/`score`/`gate-decision`/`gate-check` can never drift
- * into five different wordings for the same defect. `commandLine` is the
- * exact command the caller should re-run inside the owner tree.
- *
- * @param {string} feature
- * @param {string} tree
- * @param {string|null} branch
- * @param {string} commandLine
- * @returns {Array<{tone: 'red'|'gray'|'cyan'|'yellow', text: string}>}
- */
 export function ownerTreeRefusalLines(feature, tree, branch, commandLine) {
   return [
     { tone: 'red', text: `\n❌ A feature "${feature}" não pode ser mutada A PARTIR DESTA ÁRVORE.` },