@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/validation/verify.js

@@ -14,7 +14,6 @@ import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 import { runCiVerify, CiUsageError, reusableLocalStamp } from '../../lib/ci/ci-verify.js';
 
-/** ✓ pass · ✗ fail · – skip */
 function statusIcon(status) {
   if (status === 'pass') return chalk.green('✓');
   if (status === 'fail') return chalk.red('✗');
@@ -69,27 +68,9 @@ function formatVerifyResult(result) {
 
 const samePath = (a, b) => canonicalPath(a).replace(/\\/g, '/') === canonicalPath(b).replace(/\\/g, '/');
 
-/**
- * Persist only in the tree that OWNS the feature — the same predicate
- * `list`/`handoff`/the mutator guard read (`resolveFeatureTree`), asked from
- * the PRIMARY ROOT so every tree gets the same answer. Any other tree (a
- * sub-agent's `morph-task/*` tree branched from `morph/{f}`, a scratch
- * checkout) must never write feature.json: its copy is not the one the gates
- * read, and the write would merge-conflict with the owner's.
- *
- * The old rule read only the root's `worktree.path` pointer, which a feature
- * created INSIDE its worktree never has: a `worktrees/homolog-v2` on
- * `morph/chat-demo-simulacao` measured `unregistered-worktree` on 11/11 runs,
- * and `repeatOf` (computed only when persisting) never fired. Git's worktree
- * registry names that tree as the owner.
- *
- * The root is not special: with a live worktree owning the feature, the
- * root's copy is the birth-instant skeleton and a stamp there is drift —
- * `owner-tree-elsewhere`, the verify side of `assertOwnerTree`.
- *
- * @param {{ cwd: string, featureName: string, noPersist: boolean }} params
- * @returns {{ persist: boolean, reason: string|null }}
- */
+// Persists only in the tree that OWNS the feature (`resolveFeatureTree`, asked from the PRIMARY
+// ROOT so every tree agrees): another tree's copy is not what the gates read, and writing it
+// would merge-conflict with the owner's.
 function decidePersistence({ cwd, featureName, noPersist }) {
   if (noPersist) return { persist: false, reason: 'no-persist-flag' };
 
@@ -100,23 +81,12 @@ function decidePersistence({ cwd, featureName, noPersist }) {
 }
 
 function baselineStampBlock(baseline) {
-  if (!baseline?.recorded) return baseline?.reason ? `record-baseline: ${baseline.reason}` : 'record-baseline';
-  const fell = baseline.updates.filter((u) => u.from !== null && u.to < u.from);
-  if (fell.length === 0) return null;
-  return `record-baseline: a contagem caiu em ${fell.map((u) => `${u.id} (${u.from} → ${u.to})`).join(', ')}`;
+  if (baseline?.recorded) return null;
+  return baseline?.reason ? `record-baseline: ${baseline.reason}` : 'record-baseline';
 }
 
-/**
- * The per-node status map, in the shape `feature.schema.json` fixes for BOTH
- * writers of it — the history entry (`verifications.feature`) and the
- * singular gate stamp (`verification.nodes`). One function because they were
- * two literal copies twenty-five lines apart: a fifth node meant remembering
- * both, and a stamp missing a node the history has is precisely the kind of
- * half-truth the gate reads as fact.
- *
- * @param {{ nodes: Record<string, { status: string }> }} result - runVerify() output
- * @returns {{ build: string, tests: string, validators: string, e2e: string }}
- */
+// The single writer of both node maps the schema fixes (`verification.nodes` and the history
+// entry): a stamp missing a node the history has is a half-truth the gate reads as fact.
 function nodeStatuses(result) {
   return {
     build: result.nodes.build.status,
@@ -127,25 +97,8 @@ function nodeStatuses(result) {
   };
 }
 
-/**
- * The status of the eval suites, pulled OUT of the tests rollup.
- *
- * The rollup cannot answer the question Gate 3 asks. A red eval and a red unit
- * test both arrive as `tests: 'fail'`, and — worse — an eval node that was
- * SKIPPED (`--filter`) leaves the rollup green, so a gate reading `tests` alone
- * cannot tell "the eval ran and passed" from "the eval never ran".
- *
- * Four values, and the distinction between the last two is the whole point:
- *   - `'pass'` / `'fail'`: every declared eval node agreed, or at least one did
- *     not. Same pessimistic rollup rule the tests node already uses;
- *   - `'skip'`: eval nodes ARE declared, but this run did not execute them;
- *   - `null`: this project declares NO eval node. Not a skip — there is nothing
- *     to skip. `risk-detector.js` pauses on the two for different reasons,
- *     because they call for different actions.
- *
- * @param {{nodes: {tests: {runs?: Array}}}} result - runVerify() output
- * @returns {'pass'|'fail'|'skip'|null}
- */
+// `'skip'` = eval nodes declared but not run; `null` = no eval node declared. A skipped eval
+// leaves the tests rollup green, so the gate needs this split to tell them apart.
 function evalsStatusOf(result) {
   const runs = (result.nodes.tests?.runs || []).filter((run) => run.runner === EVAL_RUNNER);
   if (runs.length === 0) return null;
@@ -154,10 +107,7 @@ function evalsStatusOf(result) {
   return 'skip';
 }
 
-/**
- * The options that make a run partial, each with the `reason` it
- * reports when it keeps the stamp from being written — first match wins.
- */
+// First match wins; each keeps the stamp from being written, with its `reason`.
 const PARTIAL_RUN_FLAGS = [['filter', 'filtered'], ['skipTests', 'skip-tests'], ['skipBuild', 'skip-build']];
 
 const CI_EXCLUSIVE_FLAGS = [
@@ -181,9 +131,7 @@ async function runLocalVerify(featureName, options) {
       linuxImage: options.linuxImage,
     });
   } catch (err) {
-    // A wrong invocation is exit 2, like an unknown feature — never a
-    // verdict. `--filter` that selects nothing must not print green (or red):
-    // there is no verification to report, only a command to fix.
+    // Exit 2, never a verdict: a `--filter` that selects nothing must not print green or red.
     if (err instanceof VerifyUsageError) {
       console.error(chalk.red(`\n❌ ${err.message}\n`));
       process.exit(2);
@@ -204,25 +152,19 @@ async function runLocalVerify(featureName, options) {
   }
 }
 
-/**
- * `morph-spec verify <feature>` — the deterministic code-before-judge
- * gate: build + tests + validators, BEFORE the LLM eval. See verify-runner.js
- * for the node cadence; this command wraps it with CLI ergonomics
- * (human/JSON output, exit codes) and context-aware persistence.
- *
- * Exit codes: 0 = pass (including all-skip) · 1 = fail (>=1 red node, or a
- * `--record-baseline` the run refused to write) · 2 = usage error.
- *
- * Exit 2 is "the command cannot mean what you typed", and there are four
- * paths to it — never a verdict, because a verdict about nothing is worse
- * than a refusal:
- *   - unknown feature;
- *   - `--filter` that matches no declared node (a filtered-to-empty run is
- *     green and proves nothing);
- *   - `--record-baseline` with nowhere to write (no `config.json`);
- *   - `--linux` without Docker.
- * The last three arrive as `VerifyUsageError` from the runner.
- */
+function exitWithReusedStamp(featureName, reused, why, options) {
+  console.error(chalk.green(`\n↪ ${why} (sha ${reused.sha.slice(0, 8)}, ${reused.ts}): nada mudou fora de .morph/ desde aquela rodada verde.\n`));
+  if (options.json) {
+    console.log(JSON.stringify({
+      feature: featureName, status: reused.status, nodes: reused.nodes, e2eReason: reused.e2eReason ?? null,
+      reused: { sha: reused.sha, ts: reused.ts, source: reused.source ?? 'local' }, persisted: false, reason: 'stamp-reused',
+    }, null, 2));
+  }
+  process.exit(0);
+}
+
+// Exit 2 is "the command cannot mean what you typed" (unknown feature, `--filter` matching
+// nothing, `--record-baseline` without config.json, `--linux` without Docker): never a verdict.
 export async function verifyCommand(featureName, options = {}) {
   let feature;
   try {
@@ -245,6 +187,8 @@ export async function verifyCommand(featureName, options = {}) {
 
   let ci = null;
   if (options.ci) {
+    const fresh = reusableLocalStamp(process.cwd(), feature.verification);
+    if (fresh) exitWithReusedStamp(featureName, fresh, 'stamp verde e fresco — o CI não roda de novo', options);
     try {
       const outcome = await runCiVerify(process.cwd(), featureName, readMorphConfig(process.cwd()), {
         log: (line) => console.error(chalk.gray(`   ${line}`)),
@@ -256,17 +200,6 @@ export async function verifyCommand(featureName, options = {}) {
         console.error(chalk.yellow(`\n⏳ ${outcome.reason}. Não é vermelho e não há stamp: não repita em laço — siga e deixe o gate-check decidir.\n`));
         process.exit(3);
       } else {
-        const reused = reusableLocalStamp(process.cwd(), feature.verification);
-        if (reused) {
-          console.error(chalk.green(`\n↪ CI indisponível (${outcome.reason}) — stamp fresco reaproveitado (sha ${reused.sha.slice(0, 8)}, ${reused.ts}): nada mudou fora de .morph/ desde aquela rodada verde.\n`));
-          if (options.json) {
-            console.log(JSON.stringify({
-              feature: featureName, status: reused.status, nodes: reused.nodes, e2eReason: reused.e2eReason ?? null,
-              reused: { sha: reused.sha, ts: reused.ts, source: reused.source ?? 'local' }, persisted: false, reason: 'stamp-reused',
-            }, null, 2));
-          }
-          process.exit(0);
-        }
         console.error(chalk.yellow(`\n↪ CI indisponível (${outcome.reason}) — verify local.\n`));
       }
     } catch (err) {
@@ -311,22 +244,9 @@ export async function verifyCommand(featureName, options = {}) {
     };
     await updateFeature(featureName, historyKey, compact);
 
-    // Singular "latest stamp" — distinct from the `verifications.feature`
-    // history above. `sha` is what lets a
-    // consumer (morph-spec gate-check) correlate this pass/fail with the
-    // EXACT commit it covers, the same way a review report's
-    // `**Reviewed-SHA:**` token lets approve.js detect a stale review. null
-    // in a non-git checkout (or before the first commit) — fail-open, never
-    // blocks persistence.
-    //
-    // `nodes` + `e2eReason` são acréscimo de campo, não mudança de forma: o
-    // rollup `status` continua onde estava. Existem porque um nó e2e que PULA
-    // não reprova o rollup — sem o status do nó e a razão LITERAL do skip, o
-    // gate-check lê 'pass' tanto quando o e2e rodou e passou quanto quando ele
-    // nunca rodou, e não tem como separar dispensa legítima ("o projeto não
-    // containeriza") de ausência de prova ("docker indisponível"). `e2eReason`
-    // é null quando o nó não pulou — e um null NUM SKIP é lido como dispensa
-    // sem motivo, que risk-detector.js recusa.
+    // `sha` ties the stamp to the exact commit (null without git: fail-open). `nodes` and `e2eReason`
+    // exist because a skipped e2e does not fail the rollup; a null reason ON A SKIP reads as a
+    // waiver without motive, which risk-detector.js refuses.
     const stamp = {
       status: result.status,
       nodes: nodeStatuses(result),
@@ -391,10 +311,7 @@ export async function verifyCommand(featureName, options = {}) {
     }
   }
 
-  // A recording the user asked for and did not get is a failure of the
-  // invocation even when the run itself was green (a filtered run is green and
-  // unrecordable): exiting 0 there would report success for something that did
-  // not happen.
+  // A recording asked for and not made fails the invocation, even when the run was green.
   const baselineRefused = Boolean(result.baseline && !result.baseline.recorded);
   process.exit(result.status === 'pass' && !baselineRefused ? 0 : 1);
 }

package/src/core/paths/output-schema.js

@@ -1,84 +1,27 @@
-/**
- * Output Schema — Single Source of Truth (v5)
- *
- * ALL output type definitions live here. Edit ONLY this file to add, rename,
- * or relocate output types.
- */
-
 import { join } from 'path';
 
-// ============================================================================
-// Schema Definition
-// ============================================================================
-
-/**
- * Schema for output types produced by morph-spec NLH phases.
- *
- * Fields:
- *   filename     - The file's basename (e.g. 'plan.md'). Single-file types only.
- *   phaseDir     - Subdirectory within .morph/features/{feature}/
- *   phase        - The morph-spec phase that produces this output
- *   protected    - Whether the file requires an approval gate before editing
- *   approvalGate - (optional) Which gate protects this file
- *
- * Multi-file types (`multi: true`) hold N files in a directory instead of one
- * fixed basename. They carry `dirname` + `filenamePattern` + `displayFilename`
- * INSTEAD of `filename`, and every derivation keyed by basename
- * (FILENAME_TO_OUTPUT, PROTECTED_SPEC_FILES) skips them —
- * there is no single basename to key on. `getOutputPath` returns the DIRECTORY
- * for these types.
- */
 export const OUTPUT_SCHEMA = {
-  // 2-plan/ — the plan gate freezes both: plan.md accepts only an append in
-  // `## Errata`, checks.json only a rewrite by `morph-spec plan-check`.
   plan:           { filename: 'plan.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   checks:         { filename: 'checks.json',           phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
 
-  // 1-design/ (optional)
   uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiMockups:      { filename: 'mockups.md',            phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiComponents:   { filename: 'components.md',         phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiFlows:        { filename: 'flows.md',              phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
 
-  // 3-implement/ — the slice reports (`reports/F{n}.md`, see getTaskReportPath) are the record.
-  // N files, one per scenario whose proof judges what a MODEL answers
-  // (`prova: eval` in the plan). Runtime evidence: input, model, output, verdict — pointing
-  // at the `runner: "evals"` node when the stack declares one. CONDITIONAL by
-  // construction: never in phases.json requiredOutputs. Readers: morph-review
-  // dispatch prompt.
   evidencias:     { dirname: 'evidencias', filenamePattern: '^C\\d+\\.md$', displayFilename: '{Cn}.md',
                     phaseDir: '3-implement', phase: 'implement', protected: false, multi: true },
 
-  // 4-review/
-  // Um relatório por papel; o canônico da fase é o do verificador.
   verifierReport: { filename: 'verifier.md',           phaseDir: '4-review',    phase: 'review',    protected: false },
   reviewerReport: { filename: 'reviewer.md',           phaseDir: '4-review',    phase: 'review',    protected: false },
   securityReport: { filename: 'security.md',           phaseDir: '4-review',    phase: 'review',    protected: false },
 };
 
-// ============================================================================
-// Builder Functions (Windows-safe via path.join)
-// ============================================================================
-
-/**
- * Leaf segment of a schema entry: the basename for single-file types, the
- * directory name for multi-file ones. Keeps every path builder from having to
- * know about `multi` on its own.
- */
 function leafSegment(entry) {
   return entry.multi ? entry.dirname : entry.filename;
 }
 
-/**
- * Get the morph-relative path for a specific output type of a feature.
- *
- * For `multi` types this is the DIRECTORY holding the N files
- * (".morph/features/my-feature/3-implement/evidencias"), not a single file.
- *
- * @param {string} featureName
- * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
- * @returns {string} e.g. ".morph/features/my-feature/2-plan/plan.md"
- */
+/** For `multi` types this is the directory holding the N files. */
 export function getOutputPath(featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];
   if (!entry) {
@@ -88,10 +31,6 @@ export function getOutputPath(featureName, outputType) {
     .replace(/\\/g, '/');
 }
 
-/**
- * Get the absolute filesystem path for a specific output type.
- * For `multi` types this is the directory — see {@link getOutputPath}.
- */
 export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];
   if (!entry) {
@@ -100,42 +39,20 @@ export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, leafSegment(entry));
 }
 
-/**
- * Get the feature base directory (morph-relative, forward slashes).
- */
 export function getFeatureDir(featureName) {
   return join('.morph', 'features', featureName).replace(/\\/g, '/');
 }
 
-/**
- * Per-task sub-agent report — the durable "return value" channel for a
- * dispatched implementation task (MORPH.md §6). A sub-agent's final text
- * message may never reach the orchestrator (idle_notification with no text
- * is an observed failure mode); the file it writes here always does. Doesn't
- * fit OUTPUT_SCHEMA's one-fixed-filename-per-type model since the filename
- * is parameterized by taskId, so it's a sibling helper instead of a schema
- * entry.
- *
- * @param {string} featureName
- * @param {string} taskId - e.g. "T7"
- * @returns {string} morph-relative, forward-slash path
- */
 export function getTaskReportPath(featureName, taskId) {
   return join('.morph', 'features', featureName, '3-implement', 'reports', `${taskId}.md`)
     .replace(/\\/g, '/');
 }
 
-/** Absolute filesystem variant of {@link getTaskReportPath}. */
 export function getAbsoluteTaskReportPath(projectRoot, featureName, taskId) {
   return join(projectRoot, '.morph', 'features', featureName, '3-implement', 'reports', `${taskId}.md`);
 }
 
-/**
- * Get all output paths for a feature, ready for state.json `outputs` block.
- *
- * Multi-file types contribute their DIRECTORY, so `created` for them means
- * "the folder exists" — the state index tracks presence, not file count.
- */
+/** `multi` types contribute their directory, so `created` means "the folder exists". */
 export function getAllOutputPaths(featureName) {
   const outputs = {};
   for (const [key] of Object.entries(OUTPUT_SCHEMA)) {
@@ -147,14 +64,6 @@ export function getAllOutputPaths(featureName) {
   return outputs;
 }
 
-// ============================================================================
-// Derived Constants
-// ============================================================================
-
-/**
- * filename → output type. Multi-file types are absent by construction: they
- * have N basenames, so there is nothing to key on.
- */
 export const FILENAME_TO_OUTPUT = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
     .filter(([, entry]) => !entry.multi)
@@ -165,20 +74,12 @@ export const OUTPUT_PHASE_MAP = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [key, entry.phase])
 );
 
-/**
- * Protected spec files and the approval gate that locks them.
- */
 export const PROTECTED_SPEC_FILES = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
     .filter(([, entry]) => entry.protected && entry.approvalGate && !entry.multi)
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
-// ============================================================================
-// Contracts
-// ============================================================================
-
-/** The output type whose code blocks declare the contracts the code must honour. */
 export function resolveContractsOutputType() {
   return 'plan';
 }

package/src/core/state/feature-identity.js

@@ -1,32 +1,8 @@
-/**
- * Feature identity — the fields that keep a feature.json from being an
- * anonymous shell (the {status, updatedAt}-only scaffolds nobody could later
- * identify). name/createdAt/workType are auto-stamped at birth (explicit
- * `morph-spec create` or the state-sync hook's implicit registration);
- * `description` is the one field a human must supply.
- *
- * `missingIdentity` powers the audit surfaces (`list`, `doctor`) that flag
- * pre-existing anonymous features LENIENTLY (warn, never invalidate old
- * feature.json). `create` enforces `description` HARD at birth — the two-tier
- * split the schema's `required` array can't express (adding fields there would
- * invalidate every feature.json that predates this).
- *
- * Pure module — no filesystem/CLI side effects.
- */
-
 export const IDENTITY_FIELDS = ['name', 'description', 'workType', 'createdAt'];
 
 const blank = (v) => v === undefined || v === null || String(v).trim() === '';
 
-/**
- * Identity fields absent from a feature.json (empty array = fully identified).
- * `description` leads because its absence is the real anonymity signal.
- * `workType` is intentionally excluded — absent workType defaults to 'feature',
- * so it is never a marker of an anonymous shell.
- *
- * @param {object} feature - feature.json contents
- * @returns {string[]} missing identity field names
- */
+// `workType` is excluded on purpose: absent, it defaults to `feature`.
 export function missingIdentity(feature) {
   const missing = [];
   if (blank(feature?.description)) missing.push('description');

package/src/core/state/gate-order.js

@@ -1,19 +1,3 @@
-/**
- * Gate monotonicity — single source of truth.
- *
- * A gate may only be approved once its predecessors are approved. The strict
- * chain is plan → review. uiux is optional: it requires plan but gates nothing
- * downstream, so a feature that skips UI/UX is never blocked.
- *
- * Policy-stamped gates (approvedBy: "policy:{type}", written at birth by
- * `morph-spec create` for a work type's skippedGates) count as approved, so
- * chore/hotfix (plan pre-stamped) satisfy prereqs naturally.
- *
- * Pure module — no filesystem/CLI side effects. Consumed by
- * `approve`/`advance` (refuse), the state-sync hook (warn), and `list`/`doctor`
- * (report).
- */
-
 export const GATE_PREREQ = {
   plan: [],
   uiux: ['plan'],
@@ -22,22 +6,11 @@ export const GATE_PREREQ = {
 
 const isApproved = (gates, name) => gates?.[name]?.approved === true;
 
-/**
- * Prerequisite gates NOT yet approved that block approving `gate`.
- * @param {string} gate - gate about to be approved
- * @param {object} gates - feature.approvalGates
- * @returns {string[]} unmet prerequisite gate names (empty = clear to approve)
- */
 export function unmetPrereqs(gate, gates) {
   const prereqs = GATE_PREREQ[gate] || [];
   return prereqs.filter((p) => !isApproved(gates, p));
 }
 
-/**
- * All monotonicity violations currently present in a feature's gates.
- * @param {object} gates - feature.approvalGates
- * @returns {Array<{gate: string, missing: string[]}>} empty when in order
- */
 export function gateOrderViolations(gates) {
   if (!gates || typeof gates !== 'object') return [];
   const out = [];

package/src/core/state/lifecycle-audit.js

@@ -1,23 +1,3 @@
-/**
- * Feature-lifecycle audit — the consolidated inconsistency scanner behind
- * `morph-spec doctor`. Read-only, non-throwing: scans `.morph/features/*` and
- * the thin root index and reports what's already wrong in the repo, without
- * touching state (never calls loadState — a diagnostic must not mutate).
- *
- * Issue types:
- *   • gate-order    — a gate approved with a predecessor pending (item 4)
- *   • identity      — a feature missing description/name/createdAt (item 3)
- *   • orphan-folder — a feature folder with no feature.json
- *   • stale-index   — a root-index entry with no feature folder (auto-heals on
- *                     the next loadState, but surfaced so it's not a mystery)
- *   • branch-drift  — the root's copy of a feature.json disagrees with the copy
- *                     committed on `morph/{f}` (B5 — the root's view lags)
- *   • abandoned-scaffold — an `in_progress` feature that never produced
- *                     anything: no artifacts, no approved gate, and a branch
- *                     with no commit of its own (see abandonedScaffold)
- *   • corrupt       — a feature.json that won't parse
- */
-
 import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
@@ -26,40 +6,19 @@ import { missingIdentity } from './feature-identity.js';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { commitsAhead, resolveBaseRef } from '../../lib/git/branch-classifier.js';
 
-/** The operational truth of a feature.json: its status and which gates are approved. */
 function operationalShape(fj) {
   const gates = {};
   for (const [g, v] of Object.entries(fj?.approvalGates || {})) gates[g] = v?.approved === true;
   return JSON.stringify({ status: fj?.status ?? null, gates });
 }
 
-/**
- * Does the root's working-tree copy of a feature.json disagree with the copy
- * COMMITTED on that feature's own branch?
- *
- * `.morph/state.json` is gitignored and derived, and every worktree keeps its
- * own — so "the index diverges between worktrees" is by design, not a defect to
- * fix by making the index authoritative (that would undo the whole per-feature
- * state model). The defect is that the divergence was INVISIBLE: since v8.4 the
- * authoritative feature.json travels committed on `morph/{f}`, so a primary root
- * parked on the default holds a copy that silently lags, and everything derived
- * from it (status, gates, and the index rebuilt from it) lags with it.
- *
- * Comparison is on the OPERATIONAL fields only — status and approved-gate flags
- * — not on bytes: reformatting or a timestamp bump is not a divergence anyone
- * needs to hear about.
- *
- * Fail-open at every step: no repo, no branch, no blob, unparseable JSON → no
- * issue. A diagnostic that invents problems is worse than one that misses some.
- *
- * @returns {string|null} the issue detail, or null when the copies agree
- */
+// Compares only status and approved gates (bytes and timestamps are not drift).
+// Fail-open: no repo, branch, blob or parseable JSON means no issue.
 function branchDrift(baseDir, feature, rootFj) {
   const branch = `morph/${feature}`;
   try {
     const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: baseDir, stdio: 'pipe' })
       .toString().trim();
-    // On the feature's own branch the working tree IS the branch — nothing to compare.
     if (current === branch) return null;
 
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
@@ -77,18 +36,9 @@ function branchDrift(baseDir, feature, rootFj) {
   }
 }
 
-/**
- * How long a scaffold has to sit untouched before it counts as abandoned.
- *
- * A dead scaffold and a feature born five minutes ago have the SAME shape:
- * `create` forks `morph/{f}` off the default branch without committing, so at
- * birth the branch has no commit of its own and the folder holds nothing but
- * `feature.json`. Only elapsed time separates the two — and a check that fires
- * on every fresh `create` is one people learn to scroll past.
- */
+// A dead scaffold and a feature born minutes ago have the same shape; only age tells them apart.
 const ABANDONED_SCAFFOLD_MIN_AGE_MS = 24 * 60 * 60 * 1000;
 
-/** Newest timestamp the feature carries, in ms; falls back to the folder's mtime. */
 function lastTouched(fdir, fj) {
   let newest = 0;
   for (const ts of [fj?.updatedAt, fj?.createdAt]) {
@@ -99,12 +49,7 @@ function lastTouched(fdir, fj) {
   try { return statSync(fdir).mtimeMs; } catch { return 0; }
 }
 
-/**
- * Does the feature dir hold any FILE other than its own `feature.json`?
- *
- * Files, not entries: `create` scaffolds the phase folders empty, so an empty
- * `2-plan/` is the absence of work, not evidence of it.
- */
+// Files, not entries: `create` scaffolds the phase folders empty.
 function hasArtifacts(fdir) {
   let entries;
   try { entries = readdirSync(fdir, { withFileTypes: true }); } catch { return false; }
@@ -119,22 +64,7 @@ function hasArtifacts(fdir) {
   return false;
 }
 
-/**
- * Commits on the feature's branch that the base does not already contain, or
- * `null` when git cannot answer (no repo, no resolvable base, no branch, no
- * rev-list). "Cannot prove" must never read as "proved zero" — the predicate
- * below hinges on this number, so an unanswerable repo has to stay silent.
- *
- * The counting itself is `branch-classifier.js`'s `commitsAhead` against its
- * `resolveBaseRef`, NOT a second copy: `origin/{default}` is the authority on
- * what actually landed, and two drifting answers to "does this branch carry
- * anything of its own?" is exactly what the `doctor`/`branch prune` split was
- * unified to avoid.
- *
- * Note the field evidence this exists for: the branch pointed at the merge
- * commit of somebody else's PR. That is the base's own tip — reachable from
- * the base, and therefore zero commits of its own.
- */
+// `null` when git cannot answer: "cannot prove" must never read as "proved zero".
 function ownCommitCount(baseDir, branch) {
   try {
     execFileSync('git', ['rev-parse', '--git-dir'], { cwd: baseDir, stdio: 'pipe' });
@@ -146,31 +76,15 @@ function ownCommitCount(baseDir, branch) {
   try {
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
   } catch {
-    return 0; // the branch never existed — nothing was ever committed for it
+    return 0; // the branch never existed: nothing was committed on it
   }
   return commitsAhead(baseRef, branch, baseDir);
 }
 
-/**
- * The orphan skeleton `create --worktree` can leave behind: a feature.json on
- * its own, `status: in_progress`, no tasks, no gates, and a branch parked on
- * somebody else's commit. Every one of those alone is normal at some point in
- * a feature's life; together, and only after the feature has gone stale, they
- * mean nobody ever came back to it.
- *
- * The artifact test is deliberately broader than the "0 tasks" the report
- * named: a plan drafted and waiting on its gate also has zero tasks and is
- * very much alive. What a dead scaffold has is NOTHING — checked in the root
- * and, if the feature registered one, in its worktree, where uncommitted work
- * would otherwise be invisible to both the disk scan and `rev-list`.
- *
- * @returns {string|null} the issue detail, or null when the feature is alive
- */
 function abandonedScaffold(baseDir, feature, fdir, fj) {
   if (fj?.status !== 'in_progress') return null;
 
-  // "0 gates": a gate stamped `policy:{workType}` at birth (chore/hotfix) was
-  // never a decision anyone took, so it must not read as progress.
+  // A gate stamped `policy:{workType}` at birth was never a decision, so it is not progress.
   const decided = Object.values(fj.approvalGates || {}).some(
     (g) => g?.approved === true && !String(g?.approvedBy ?? '').startsWith('policy:'),
   );
@@ -185,8 +99,6 @@ function abandonedScaffold(baseDir, feature, fdir, fj) {
   const age = Date.now() - lastTouched(fdir, fj);
   if (age < ABANDONED_SCAFFOLD_MIN_AGE_MS) return null;
 
-  // The registered branch when the feature has one, `morph/{f}` otherwise —
-  // same name `branchDrift` above assumes.
   const branch = fj.worktree?.branch || `morph/${feature}`;
   if (ownCommitCount(baseDir, branch) !== 0) return null;
 
@@ -196,10 +108,6 @@ function abandonedScaffold(baseDir, feature, fdir, fj) {
     + 'ou retome a feature';
 }
 
-/**
- * @param {string} [baseDir] - project root (defaults to cwd)
- * @returns {Array<{ feature: string, type: string, detail: string }>} issues
- */
 export function auditFeatureLifecycle(baseDir = process.cwd()) {
   const issues = [];
   const featuresDir = join(baseDir, '.morph', 'features');
@@ -256,7 +164,7 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
           issues.push({ feature: name, type: 'stale-index', detail: 'in state.json index but no feature folder' });
         }
       }
-    } catch { /* index is derivable — non-fatal */ }
+    } catch { }
   }
 
   return issues;