@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/framework/hooks/shared/reparse-scan.js

@@ -1,63 +1,16 @@
-/**
- * reparse-scan.js — exhaustive, fail-closed reparse-point (symlink/junction)
- * scan of a directory tree.
- *
- * This lives in `framework/hooks/shared/` rather than `src/` because BOTH sides
- * need it and the dependency direction in this repo only runs one way: `src/`
- * imports from `framework/hooks/shared/` (see `finish.js`'s `claim-registry`
- * and `e2e-check` imports), never the reverse — a hook shipped into a target
- * project has the package, not this repo's `src/` layout.
- *
- * Two callers, one question:
- *   - `teardownWorktree` (src/commands/project/worktree.js) — may this worktree
- *     be handed to `git worktree remove`?
- *   - the `block-destructive-worktree-removal` PreToolUse hook — is the command
- *     about to run going to traverse a link out of the worktree?
- *
- * WHY IT MUST BE EXHAUSTIVE — both `git worktree remove` and its `--force`
- * fallback FOLLOW reparse points out of the worktree and delete the PRIMARY
- * ROOT's real files. The plain removal is not the safe one: it refuses only
- * when it sees modified/untracked *tracked-scope* content, so a GITIGNORED
- * junction (`node_modules`, `.claude`) leaves `git status` empty, the removal
- * proceeds, exits 0 — and the target is gone.
- *
- * So the check cannot live in the `catch` of the plain removal (unreachable on
- * exactly the destructive path), and it cannot be a fixed list of the links
- * `setup` creates: a nested link inside a real `node_modules` (npm link, npm
- * workspaces) is invisible to any top-level inventory. We scan the whole tree
- * and NEVER recurse INTO a reparse point — descending one would walk the target
- * we are trying to protect (and could not terminate on a cycle).
- *
- * FAIL-CLOSED, deliberately: an empty result is NOT the same as a safe one. A
- * directory we could not read or an entry we could not lstat might BE (or
- * contain) a reparse point. Those answer `unprovable`, and every caller must
- * treat that exactly like a found link — decline. "I saw nothing" and "I proved
- * there is nothing" are different claims, and only the second may authorize a
- * removal. This is the one module in the shared/ directory that must NOT be
- * fail-open; the whole point is that uncertainty blocks.
- *
- * `lstat` reports a POSIX symlink and a Windows junction alike as a symbolic
- * link, so the scan behaves identically on both platforms — as does the
- * destruction it prevents.
- */
+// `git worktree remove` (plain or --force) follows reparse points and deletes the
+// primary root's files, nested links included. FAIL-CLOSED: an entry that cannot
+// be read is `unprovable` and blocks exactly like a found link.
 
 import { readdirSync, lstatSync } from 'fs';
 import { join, relative } from 'path';
 
-/**
- * Every reparse point anywhere under `dir`, as relative paths.
- *
- * @param {string} dir
- * @param {string} [base] - root of the scan, for relative reporting
- * @param {{points: string[], unprovable: string[]}} [acc]
- * @returns {{points: string[], unprovable: string[]}} both empty = provably clean
- */
+/** @returns {{points: string[], unprovable: string[]}} both empty = provably clean */
 export function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }) {
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch {
-    // Unreadable (ACL, lock, EMFILE): we cannot prove what is in here.
     acc.unprovable.push((relative(base, dir) || '.').replace(/\\/g, '/'));
     return acc;
   }
@@ -71,28 +24,15 @@ export function findReparsePoints(dir, base = dir, acc = { points: [], unprovabl
       continue;
     }
     if (st.isSymbolicLink()) {
-      // Forward slashes: every other path this command reports is normalized,
-      // and these end up in JSON the caller may compare or display.
       acc.points.push(relative(base, p).replace(/\\/g, '/'));
-      continue; // do NOT descend — that is the target, not the worktree
+      continue; // descending would walk the target, not the worktree
     }
     if (st.isDirectory() && entry.name !== '.git') findReparsePoints(p, base, acc);
   }
   return acc;
 }
 
-/**
- * The single question both callers actually ask: may this tree be handed to a
- * command that follows links?
- *
- * Collapses `points` and `unprovable` into one list precisely because callers
- * must not weigh them differently — `teardownWorktree` already concatenated
- * them, and a hook that treated `unprovable` as "probably fine" would reopen
- * the hole this module exists to close.
- *
- * @param {string} dir
- * @returns {{ safe: boolean, blockers: string[] }}
- */
+// One list on purpose: callers must not weigh `unprovable` lighter than a link.
 export function scanForBlockers(dir) {
   const { points, unprovable } = findReparsePoints(dir);
   const blockers = [...points, ...unprovable];

package/framework/hooks/shared/slice-progress.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/** `PARCIAL` on the report's first non-blank line, tolerating heading/bold/quote typography. */
+export const PARTIAL_MARKER = /^[\s#>*_]*PARCIAL\b/;
+
+export const SLICE_STATUSES = ['pendente', 'parcial', 'feito'];
+
+export function checksPath(featureDir) {
+  return join(featureDir, '2-plan', 'checks.json');
+}
+
+export function sliceReportPath(featureDir, sliceId) {
+  return join(featureDir, '3-implement', 'reports', `${sliceId}.md`);
+}
+
+export function sliceStatusFromReport(text) {
+  if (text == null) return 'pendente';
+  const first = String(text).split(/\r?\n/).find((l) => l.trim() !== '') ?? '';
+  return PARTIAL_MARKER.test(first) ? 'parcial' : 'feito';
+}
+
+/** @returns {{ total, done, partial, pending, slices } | null} null when the checks text is unreadable */
+export function sliceProgressFrom(checksText, readReport) {
+  let slices;
+  try {
+    slices = JSON.parse(checksText ?? '').slices;
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(slices)) return null;
+  const out = slices
+    .filter((s) => s && typeof s.id === 'string')
+    .map((s) => ({
+      id: s.id,
+      title: s.title ?? '',
+      depends: Array.isArray(s.depends) ? s.depends : [],
+      covers: Array.isArray(s.covers) ? s.covers : [],
+      status: sliceStatusFromReport(readReport(s.id)),
+    }));
+  const count = (status) => out.filter((s) => s.status === status).length;
+  return { total: out.length, done: count('feito'), partial: count('parcial'), pending: count('pendente'), slices: out };
+}
+
+function readOrNull(path) {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+export function sliceProgress(featureDir) {
+  return sliceProgressFrom(readOrNull(checksPath(featureDir)), (id) => readOrNull(sliceReportPath(featureDir, id)));
+}
+
+export function readySlices(progress) {
+  if (!progress) return [];
+  const done = new Set(progress.slices.filter((s) => s.status === 'feito').map((s) => s.id));
+  return progress.slices.filter((s) => s.status !== 'feito' && s.depends.every((d) => done.has(d)));
+}
+
+// Loose on purpose: a false "complete" costs a read, a false "incomplete"
+// re-dispatches finished work.
+export const REPORT_MARKERS = [
+  { id: 'files', re: /^\s*(?:[-*]\s*)?(?:\*\*|#+\s*)?arquivos\s*:?\**\s*:?/mi },
+];
+
+const MIN_PROSE_CHARS = 80;
+
+const scenarioRe = (id) => new RegExp(`(?<![\\w-])${id}(?![\\w-])`);
+
+/** Every scenario in `covers` must be named in the report. */
+export function inspectReport(path, { covers = [] } = {}) {
+  const missingAll = ['what', 'files', ...covers];
+  if (!existsSync(path)) return { exists: false, complete: false, missing: missingAll };
+  let body = '';
+  try {
+    body = readFileSync(path, 'utf8');
+  } catch {
+    return { exists: true, complete: false, missing: missingAll, unreadable: true };
+  }
+
+  const missing = REPORT_MARKERS.filter((m) => !m.re.test(body)).map((m) => m.id);
+  missing.push(...covers.filter((id) => !scenarioRe(id).test(body)));
+  const prose = body
+    .split('\n')
+    .filter((l) => !/^\s*(#|[-*]\s|\*\*)/.test(l))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (prose.length < MIN_PROSE_CHARS) missing.unshift('what');
+
+  const firstLine = body.split('\n').find((l) => l.trim() !== '') ?? '';
+  const partial = PARTIAL_MARKER.test(firstLine);
+  if (partial) missing.push('partial');
+
+  return { exists: true, complete: missing.length === 0, missing, partial };
+}

package/framework/hooks/shared/source-files.js

@@ -1,34 +1,21 @@
-/**
- * Which files count as the project's hand-written source. One reading for the
- * `reuse` and `code-budget` validators and the `comment-guard` hook, so the
- * three never disagree about the same file.
- *
- * @module source-files
- */
+// One reading of "hand-written project source" for the `reuse` and
+// `code-budget` validators and the `comment-guard` hook.
 
 const SCANNABLE = /\.(cs|ts|tsx|js|jsx|mjs|cjs)$/i;
 
-// `.morph/` is real: an archived feature's `contracts.cs` entered ProspectPRO's
-// graph as a second `RoulettePriority`.
+// `.morph/` holds archived contracts that would duplicate real types.
 const NOT_SOURCE = /(^|\/)(?:\.morph|node_modules|dist|build|out|\.next|bin|obj|coverage)\//;
 
 const DECLARATION_FILE = /\.d\.ts$/i;
 
 const GENERATED = /(?:\.Designer|\.g|\.g\.i)\.cs$|ModelSnapshot\.cs$/i;
 
-/**
- * @param {string} sourceFile
- * @returns {boolean} project code in a scanned extension, tests included
- */
+/** Tests included. */
 export function isProjectSource(sourceFile) {
   const f = String(sourceFile || '').replace(/\\/g, '/');
   return SCANNABLE.test(f) && !DECLARATION_FILE.test(f) && !NOT_SOURCE.test(f);
 }
 
-/**
- * @param {string} sourceFile
- * @returns {boolean} generated C# nobody writes by hand
- */
 export function isGenerated(sourceFile) {
   return GENERATED.test(String(sourceFile || ''));
 }

package/framework/hooks/shared/spawn-command.js

@@ -0,0 +1,23 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const NEEDS_CMD_SHIM = /^(npm|npx|pnpm|yarn)$/;
+
+/**
+ * On win32 `npx`/`npm`/… are `.cmd` shims: ENOENT without a shell, EINVAL as `.cmd`
+ * with `shell: false`. Playwright runs from its own JS entry, so it needs no shell.
+ */
+export function resolveSpawn(file, args = [], {
+  cwd = process.cwd(),
+  platform = process.platform,
+  exists = existsSync,
+  execPath = process.execPath,
+} = {}) {
+  if (platform !== 'win32' || !NEEDS_CMD_SHIM.test(file)) return { file, args, shell: false };
+
+  if (file === 'npx' && args[0] === 'playwright') {
+    const cli = join(cwd, 'node_modules', '@playwright', 'test', 'cli.js');
+    if (exists(cli)) return { file: execPath, args: [cli, ...args.slice(1)], shell: false };
+  }
+  return { file: `${file}.cmd`, args, shell: true };
+}

package/framework/hooks/shared/state-reader.js

@@ -1,11 +1,4 @@
-/**
- * Shared read-only state accessor for Claude Code hooks.
- *
- * Wraps state.json reads with fail-open semantics:
- * - Returns null instead of throwing on missing/corrupt state
- * - Never writes to state.json (read-only)
- * - Uses synchronous reads for <100ms performance
- */
+// Fail-open: missing or corrupt state reads as null, never throws.
 
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
@@ -13,80 +6,15 @@ import { join } from 'path';
 const STATE_FILE = '.morph/state.json';
 const FEATURES_DIR = '.morph/features';
 
-/**
- * Module-level memoization of `loadState()`, keyed by `projectPath`.
- *
- * `loadState()` does a `readdirSync` of `.morph/features` plus a
- * `readFileSync` + `JSON.parse` of EVERY `feature.json` under it, on every
- * call. A single hook invocation calls it 1-3x (directly, or via
- * `getActiveFeature`/`derivePhaseForFeature`/`isGateApproved`/etc.) — re-doing
- * that full hydration each time is pure waste when nothing on disk changed
- * between those calls.
- *
- * SAFE because every hook process is short-lived and single-invocation: one
- * `node state-reader.js`-importing process handles exactly one tool call (or
- * one CLI command) and exits. There is no risk of the cache going stale
- * ACROSS invocations, because each invocation starts with an empty Map.
- * Within a SINGLE invocation, staleness would only matter if that same
- * process both reads and then writes a feature's `feature.json` and
- * expects a LATER read to see the write — verified (grep across every
- * consumer, 2026-08-11) that the one hook that writes feature.json
- * (`state-sync.js`) never re-reads through `loadState()` after writing in the
- * same invocation; its `AskUserQuestion` handler reads via
- * `readFeatureFile()` (a different, uncached module) as the PRIMARY path and
- * only falls back to `loadState()` for a feature that has NEVER had a
- * feature.json written — which, by construction, can't have just been
- * written to in this same invocation either.
- *
- * A directory-mtime-based invalidation was considered instead (so a
- * LONG-LIVED consumer could reuse this module safely too) but rejected on two
- * grounds: (1) verified — grep for every importer of this file — that none is
- * long-lived (they're all hooks, one process per tool call, or CLI commands,
- * one process per invocation; the dashboard is a separate Vite/React app and
- * the statusline is Python, neither imports this module); and (2) even if one
- * existed, `.morph/features`'s own mtime only changes when feature
- * DIRECTORIES are added/removed, not when an EXISTING feature.json's content
- * is overwritten in place — so mtime-of-the-dir can't actually detect the
- * mutation that matters here, and getting that right would mean stat'ing
- * every feature.json individually, which re-adds the very cost this cache
- * exists to remove. If a long-lived consumer is ever added, it should
- * re-derive state per request rather than lean on this cache.
- *
- * CAVEAT for any future consumer: the object returned by `loadState()` is the
- * SAME object on every cache hit, not a fresh copy — a caller that mutates it
- * (as `state-sync.js`'s `handleWriteEdit` does, in-place, before persisting)
- * is mutating the cached entry too. That's harmless today because nothing
- * currently reads the cache again after such a mutation within one process,
- * but treat the return value as read-only unless you've re-verified that.
- *
- * `clearStateCache()` is exported for tests that write/rewrite feature.json
- * and then call a `loadState()`-backed function again WITHIN THE SAME
- * process and need to see the fresh content — call it at the point of
- * mutation.
- */
+// Memoized per process: each hook/CLI process handles one call. The returned
+// object is shared, so treat it as read-only; writers call `clearStateCache()`.
 const stateCache = new Map();
 
-/** Drop all cached state — see `stateCache` above for when this is needed. */
 export function clearStateCache() {
   stateCache.clear();
 }
 
-/**
- * Load state from the project root, hydrating each feature from its
- * authoritative per-feature `feature.json`.
- *
- * The root `.morph/state.json` is a thin, gitignored index (status + updatedAt
- * per feature); the heavy feature data lives in `.morph/features/{name}/feature.json`
- * (committed). This reader merges them: it reads the thin index for project /
- * metadata and overlays each feature.json so callers see the full feature object.
- * A single corrupt feature.json is skipped, not fatal.
- *
- * Fail-open: returns null on any unexpected error or when there is no state at
- * all (no index and no feature files). Memoized per `projectPath` for the
- * lifetime of this process — see `stateCache` above.
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @returns {Object|null} State object or null
- */
+/** The thin `state.json` index overlaid with each authoritative `feature.json`; null when neither exists. */
 export function loadState(projectPath) {
   const base = projectPath || process.cwd();
   if (stateCache.has(base)) return stateCache.get(base);
@@ -119,7 +47,7 @@ export function loadState(projectPath) {
             state.features = state.features || {};
             state.features[name] = fj; // feature.json is authoritative
           } catch {
-            // skip a single corrupt feature.json — don't blind every hook
+            // one corrupt feature.json must not blind every hook
           }
         }
       }
@@ -134,17 +62,8 @@ export function loadState(projectPath) {
   return state;
 }
 
-/**
- * Check if there is state to read: either the thin `.morph/state.json` index
- * exists, or `.morph/features/` (committed, gitignore-exempt) already has at
- * least one feature with a `feature.json`. The latter case covers a freshly
- * checked-out worktree where state.json (gitignored) hasn't been materialized
- * yet, but `loadState()` can already self-heal from feature.json — so hooks
- * gating on `stateExists()` should be "on" there too, not dark.
- * Fail-open: any unexpected error (e.g. permission denied) returns false.
- * @param {string} [projectPath]
- * @returns {boolean}
- */
+// A fresh worktree has `feature.json` but no gitignored `state.json` yet; hooks
+// must stay on there.
 export function stateExists(projectPath) {
   try {
     const base = projectPath || process.cwd();
@@ -163,11 +82,6 @@ export function stateExists(projectPath) {
   }
 }
 
-/**
- * Get the active feature (most recently updated in_progress feature).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
 export function getActiveFeature(projectPath) {
   const state = loadState(projectPath);
   if (!state?.features) return null;
@@ -188,12 +102,6 @@ export function getActiveFeature(projectPath) {
   return active;
 }
 
-/**
- * Get the most recently updated feature (any status).
- * Useful as a fallback when getActiveFeature returns null (all features done).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
 export function getMostRecentFeature(projectPath) {
   const state = loadState(projectPath);
   if (!state?.features) return null;
@@ -212,155 +120,94 @@ export function getMostRecentFeature(projectPath) {
   return result;
 }
 
-/**
- * Get a specific feature by name.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null}
- */
 export function getFeature(featureName, projectPath) {
   const state = loadState(projectPath);
   return state?.features?.[featureName] || null;
 }
 
-/**
- * Derive phase from filesystem (phase deleted from state).
- *
- * Walks the phase map in descending order and returns the first phase whose
- * CANONICAL ARTIFACT exists. An empty folder is not enough — this avoids the
- * chicken-and-egg problem where `mkdir 2-plan/` (or any pre-created sibling)
- * advances the phase before plan content is written, then
- * `enforce-phase-writes` blocks writes back to `0-proposal/`.
- *
- * Canonical artifacts (one per phase) match MORPH.md §3:
- *   - 4-review  → review-report.md
- *   - 3-implement → recap.md
- *   - 2-plan    → spec.md  (the first plan-phase output produced)
- *   - 1-design  → design-system.md
- *   - 0-proposal → proposal.md
- *
- * If no canonical file is found, returns `'proposal'` (the starting phase).
- *
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string} Phase name
- */
-export const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review: 4 };
-
-/**
- * The canonical artifact of each phase, descending. Exported so a caller that
- * holds the file list from somewhere OTHER than the local filesystem (a git
- * tree, say) can answer the same question without re-encoding the map.
- */
+export const PHASE_INDEX = { plan: 0, uiux: 1, implement: 2, review: 3 };
+
+// Descending. An empty folder is not an artifact: a pre-created folder must
+// not advance the phase.
 export const PHASE_ARTIFACTS = [
-  ['4-review',    'review',    'review-report.md'],
-  ['3-implement', 'implement', 'recap.md'],
-  ['2-plan',      'plan',      'spec.md'],
+  ['4-review',    'review',    'verifier.md'],
+  ['3-implement', 'implement', 'reports/'],
   ['1-design',    'uiux',      'design-system.md'],
-  ['0-proposal',  'proposal',  'proposal.md'],
+  ['2-plan',      'plan',      'plan.md'],
 ];
 
+const DESIGN_DIR = '1-design';
+
 const gatesOf = (feature) => feature?.approvals || feature?.approvalGates;
 
-/**
- * Gate-implied phase from an ALREADY-LOADED feature object — no disk access.
- *
- * Split out of `gateImpliedPhase` so callers holding a feature.json that did
- * not come from the working tree (e.g. `git show morph/{f}:…`) can reuse the
- * rule instead of copying it. The path-based wrapper below is unchanged.
- *
- * @param {Object|null} feature
- * @returns {string} phase name
- */
-export function gateImpliedPhaseFrom(feature) {
+export function gateImpliedPhaseFrom(feature, designStarted = false) {
   const gates = gatesOf(feature);
   const ok = (g) => gates?.[g]?.approved === true;
   if (ok('review')) return 'review';
-  if (ok('plan')) return 'implement';
-  if (ok('uiux')) return 'plan';
-  return 'proposal';
+  if (ok('plan')) return designStarted && !ok('uiux') ? 'uiux' : 'implement';
+  return 'plan';
+}
+
+/** A path ending in `/` asks for any `.md` file directly under it. */
+export function diskArtifactProbe(featureDir) {
+  return (rel) => {
+    const abs = join(featureDir, ...rel.split('/').filter(Boolean));
+    if (!rel.endsWith('/')) return existsSync(abs);
+    try {
+      return readdirSync(abs, { withFileTypes: true }).some((e) => e.isFile() && e.name.endsWith('.md'));
+    } catch {
+      return false;
+    }
+  };
 }
 
-/**
- * Phase from an already-loaded feature plus an artifact predicate — no disk
- * access of its own, so the artifact universe can be a git tree.
- *
- * @param {Object|null} feature
- * @param {(relPath: string) => boolean} hasArtifact - receives POSIX-style
- *   paths relative to the feature dir, e.g. `2-plan/spec.md`
- * @returns {string} phase name
- */
+export function fileSetArtifactProbe(files) {
+  return (rel) => {
+    if (!rel.endsWith('/')) return files.has(rel);
+    for (const f of files) {
+      if (f.startsWith(rel) && f.endsWith('.md') && !f.slice(rel.length).includes('/')) return true;
+    }
+    return false;
+  };
+}
+
+/** @param {(relPath: string) => boolean} hasArtifact - {@link diskArtifactProbe} or {@link fileSetArtifactProbe} */
 export function derivePhaseFrom(feature, hasArtifact) {
-  let artifactPhase = 'proposal';
+  let artifactPhase = 'plan';
   for (const [folder, phase, canonical] of PHASE_ARTIFACTS) {
     if (hasArtifact(`${folder}/${canonical}`)) { artifactPhase = phase; break; }
   }
 
-  // Gate-aware: an approved gate advances the phase even before the next
-  // phase's first canonical artifact exists. This breaks the chicken-and-egg
-  // where that first artifact could never be written because the phase never
-  // advanced to permit it. Take whichever of (artifact, gate-implied) is later.
-  const implied = gateImpliedPhaseFrom(feature);
+  // An approved gate advances the phase before the next artifact exists, or
+  // that artifact could never be written.
+  const designStarted = hasArtifact(DESIGN_DIR) || hasArtifact(`${DESIGN_DIR}/design-system.md`);
+  const implied = gateImpliedPhaseFrom(feature, designStarted);
   return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
 }
 
-/**
- * The phase implied purely by approved gates, independent of which artifacts
- * exist on disk. An approved gate authorizes the NEXT phase, so:
- *   review approved  → review   (terminal)
- *   plan approved    → implement
- *   uiux approved    → plan
- *   otherwise        → proposal  (proposal-approval's fork between uiux/plan is
- *                                 resolved by enforce-phase-writes, not here)
- * @returns {string} phase name
- */
 export function gateImpliedPhase(featureName, projectPath) {
-  return gateImpliedPhaseFrom(getFeature(featureName, projectPath));
+  const designDir = join(projectPath || process.cwd(), '.morph/features', featureName, DESIGN_DIR);
+  return gateImpliedPhaseFrom(getFeature(featureName, projectPath), existsSync(designDir));
 }
 
 export function derivePhaseForFeature(featureName, projectPath) {
   const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
-  return derivePhaseFrom(
-    getFeature(featureName, projectPath),
-    (rel) => existsSync(join(basePath, rel)),
-  );
+  return derivePhaseFrom(getFeature(featureName, projectPath), diskArtifactProbe(basePath));
 }
 
-/**
- * Get the current phase of a feature.
- * Falls back to filesystem derivation when phase is not in state.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string|null}
- */
 export function getFeaturePhase(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
   if (!feature) return null;
   return feature.phase || derivePhaseForFeature(featureName, projectPath);
 }
 
-/**
- * Get approval status for a gate.
- * @param {string} featureName
- * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
- * @param {string} [projectPath]
- * @returns {boolean}
- */
 export function isGateApproved(featureName, gate, projectPath) {
   const feature = getFeature(featureName, projectPath);
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
   const gates = feature?.approvals || feature?.approvalGates;
   return gates?.[gate]?.approved === true;
 }
 
-/**
- * Get all pending approval gates for a feature.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string[]} List of gate names that are not yet approved
- */
 export function pendingGatesFrom(feature) {
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
   const gates = gatesOf(feature);
   if (!gates) return [];
 
@@ -373,54 +220,11 @@ export function getPendingGates(featureName, projectPath) {
   return pendingGatesFrom(getFeature(featureName, projectPath));
 }
 
-/**
- * Get feature outputs status.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null} outputs map or null
- */
 export function getOutputs(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
   return feature?.outputs || null;
 }
 
-/**
- * Get uncompleted required outputs for current phase.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Array<{type: string, path: string}>}
- */
-/**
- * Get task statistics directly from taskList (preferred over feature.tasks counters).
- * Excludes expanded tasks from counts, matching calculateProgress() behavior.
- *
- * @param {Object} feature - Feature state object
- * @returns {{ total: number, completed: number, inProgress: number, pending: number }}
- */
-export function getTaskStats(feature) {
-  const list = feature?.taskList || [];
-  if (list.length > 0) {
-    const active = list.filter(t => t.status !== 'expanded');
-    return {
-      total: active.length,
-      completed: active.filter(t => t.status === 'completed').length,
-      inProgress: active.filter(t => t.status === 'in_progress').length,
-      pending: active.filter(t => t.status === 'pending').length,
-    };
-  }
-  // Fallback: read from legacy counter object
-  const tasks = feature?.tasks;
-  if (tasks && typeof tasks === 'object' && !Array.isArray(tasks)) {
-    return {
-      total: tasks.total || 0,
-      completed: tasks.completed || 0,
-      inProgress: tasks.inProgress || 0,
-      pending: tasks.pending || 0,
-    };
-  }
-  return { total: 0, completed: 0, inProgress: 0, pending: 0 };
-}
-
 export function getMissingOutputs(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
   if (!feature?.outputs) return [];