@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/state/gate-check.js

@@ -11,35 +11,17 @@ import { readMorphConfig } from '../../lib/tasks/test-runner.js';
 import { readPlanChecks } from '../../lib/plan/checks.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
-/**
- * `--signals` on `gate-check` is NOT a general override like `gate-decision`'s
- * — everything else here is read straight off disk (workType, sliceCount, sha,
- * diffstat, verification), and letting a caller override those would let a
- * careless/hostile `--signals` silently defeat the policy this command exists
- * to make deterministic (e.g. overriding `workType` away from "hotfix" would
- * suppress risk-detector's forced Gate-3 pause). Only the signals that are
- * genuinely NOT derivable from disk today are accepted here:
- *   - standardsViolations / designSystemDivergence: still an LLM's
- *     natural-language read (see the R4 report — no deterministic detector
- *     exists in JS yet).
- */
+// Only signals NOT derivable from disk may be overridden: overriding a disk fact (e.g. `workType`
+// away from hotfix) would silently defeat the policy this command makes deterministic.
 const OVERRIDABLE_SIGNAL_KEYS = ['standardsViolations', 'designSystemDivergence'];
 
-/**
- * Os standards que fazem uma feature ser "de mídia", como os ids de
- * STANDARDS.json. Fato do plano congelado: ou uma fatia pinou o standard em
- * `standards:`, ou não pinou.
- */
 export const MEDIA_STANDARD_IDS = [
   'ai-agents-modalities-image-gen',
   'ai-agents-media-video',
   'ai-agents-media-pipeline',
 ];
 
-/**
- * O plano escreve o standard pelo id ou pelo caminho (`ai-agents/media-video.md`,
- * com ou sem `framework/` ou `standards/` na frente): as duas grafias viram o id.
- */
+// O plano escreve o standard pelo id ou pelo caminho (com ou sem `framework/`/`standards/`).
 export function standardIdOf(value) {
   return String(value ?? '').trim().replace(/\\/g, '/')
     .replace(/^(\.morph\/)?(framework\/)?(standards\/)?/, '')
@@ -47,41 +29,17 @@ export function standardIdOf(value) {
     .replace(/\//g, '-');
 }
 
-/**
- * Uma feature "gera mídia" quando alguma fatia extraída pinou um dos
- * standards de mídia. Predicado exportado porque decide se um guardrail arma:
- * um que sempre devolve `false` desarma a pausa de mídia da review e a rota opus em
- * silêncio.
- *
- * @param {{ standards?: string[] }[]|null|undefined} slices
- */
+// Decide se um guardrail arma: um predicado que sempre devolve `false` desarma em silêncio a
+// pausa de mídia da review e a rota opus.
 export function featureGeneratesMedia(slices) {
   if (!Array.isArray(slices)) return false;
   return slices.some((s) => Array.isArray(s?.standards)
     && s.standards.some((id) => MEDIA_STANDARD_IDS.includes(standardIdOf(id))));
 }
 
-/**
- * "Esta feature mexeu em prompt ou em modelo?" — em duas metades, porque uma só
- * não distingue as duas situações que pedem ações diferentes.
- *
- * `declared: false` é "o projeto não declara caminho algum de prompt/modelo" —
- * a regra é inerte por construção e a razão registrada diz isso. `declared:
- * true` com `touched: []` é "declara, e nada foi tocado" — a regra rodou e não
- * viu nada. Colapsar os dois num array vazio faria um projeto que nunca
- * configurou `watch[]` parecer um projeto que foi verificado.
- *
- * O predicado NÃO é invenção deste framework: o repositório de referência já
- * roda exatamente ele em produção, disparando publicação por `paths:` sobre os
- * mesmos globs e decidindo o escopo com `git diff --name-only`.
- *
- * COLETA, NUNCA DECIDE. Nada aqui julga se o que foi tocado deveria pausar um
- * gate — política escrita no coletor cria duas fontes para o mesmo fato.
- *
- * @param {string} cwd
- * @param {string|null} defaultBranch
- * @returns {{declared: boolean, watch: string[], touched: string[]}}
- */
+// `declared: false` (nenhum caminho declarado: regra inerte) e `touched: []` (declarou, nada
+// tocado) não podem colapsar num array vazio. COLETA, NUNCA DECIDE: política no coletor cria
+// duas fontes para o mesmo fato.
 function collectPromptModel(cwd, defaultBranch) {
   const watch = readMorphConfig(cwd)?.project?.evals?.watch;
   const globs = Array.isArray(watch) ? watch.filter((g) => typeof g === 'string' && g.trim()) : [];
@@ -96,12 +54,7 @@ function collectPromptModel(cwd, defaultBranch) {
   };
 }
 
-/**
- * Quais relatórios o ship exige: a regra única que gate-check, approve e
- * `report-check --before-eval` leem. Coleta do git, nunca decide.
- *
- * @returns {{ required: string[], security: { required: boolean, reasons: string[] } }}
- */
+/** A regra única de quais relatórios o ship exige, lida por gate-check, approve e report-check. */
 export function collectReviewRequirement(cwd, feature) {
   let changed = [];
   try { changed = changedPathsAgainst(detectDefaultBranch(cwd), cwd); } catch { changed = []; }
@@ -109,48 +62,21 @@ export function collectReviewRequirement(cwd, feature) {
   return { required: requiredReviewRoles({ workType: feature?.workType, securityRequired: security.required }), security };
 }
 
-/** O sinal `reviewReports` do ship, lido do disco. */
 export function collectReviewSignal(cwd, featureName, feature, planChecks = readPlanChecks(cwd, featureName)) {
   const { required } = collectReviewRequirement(cwd, feature);
   const checkIds = Array.isArray(planChecks.checks?.checks) ? planChecks.checks.checks.map((c) => c.id) : null;
   return reviewSignal(reviewReports(cwd, featureName), { required, checkIds });
 }
 
-/**
- * Why an automatic signature may not close the plan gate — the same rule that
- * makes gate-check pause it, read here by approve and advance.
- *
- * @returns {string|null}
- */
+/** Why an automatic signature may not close the plan gate: the rule that makes gate-check pause it. */
 export function planAutoApprovalBlock(cwd, featureName) {
   const reason = planChecksPause(readPlanChecks(cwd, featureName).status);
   return reason ? reason.replace('{feature}', featureName) : null;
 }
 
-/**
- * Collect every signal `shouldPauseGate()` (risk-detector.js) is documented
- * to consume, straight off disk — the deterministic call site risk-detector
- * never had (it shipped fully tested with zero callers; see the R4 report).
- *
- * `verificationStatus` feeds a real pause rule (verify vermelho pausa —
- * política adicionada em risk-detector.js no fecho do R4, qualquer gate).
- * `verificationStale` também alimenta uma regra própria, mas só no ship
- * (`gate === 'review'`) — sha do stamp divergindo do HEAD atual. `gate` em si
- * é o que permite risk-detector.js diferenciar as duas. `e2eStatus`/`e2eReason`
- * alimentam a regra da dispensa de e2e (também só no ship): um nó e2e que
- * PULOU não reprova o rollup, logo `verificationStatus` sai 'pass' e a razão
- * literal é o único fato que distingue dispensa legítima de ausência de prova.
- * `planChecks` (só no gate do plano) é o estado dos checks extraídos contra o
- * plano; `sliceCount` e as `standards` das fatias saem da mesma extração.
- * `verification` completo, `e2eSkipClass`, diffstat e sha seguem como contexto
- * de auditoria persistido, sem regra própria.
- *
- * @param {string} featureName
- * @param {object} feature
- * @param {string} cwd
- * @param {string} gateName
- * @returns {object}
- */
+// Collects only; risk-detector.js decides. `e2eStatus`/`e2eReason` exist because a skipped e2e
+// node does not fail the rollup: the literal reason is the only fact separating a legitimate
+// waiver from missing proof.
 export function collectSignals(featureName, feature, cwd, gateName) {
   const planChecks = readPlanChecks(cwd, featureName);
   const slices = planChecks.checks?.slices ?? null;
@@ -159,9 +85,7 @@ export function collectSignals(featureName, feature, cwd, gateName) {
   const verification = feature.verification || null;
 
   const signals = {
-    // Furo 2: disk-derived, never in OVERRIDABLE_SIGNAL_KEYS — a caller
-    // cannot spoof which gate risk-detector.js thinks it is deciding, same
-    // anti-spoof rationale as workType (hotfix's forced pause).
+    // Disk-derived, never overridable: a caller cannot spoof which gate is being decided.
     gate: gateName,
     workType: feature.workType || 'feature',
     sliceCount: slices ? slices.length : null,
@@ -171,8 +95,7 @@ export function collectSignals(featureName, feature, cwd, gateName) {
 
   if (gateName === 'plan') signals.planChecks = planChecks.status;
 
-  // Só onde o checklist decide algo: no fecho do design e no ship. Fato de
-  // disco, fora de OVERRIDABLE_SIGNAL_KEYS.
+  // Só onde o checklist decide algo: no fecho do design e no ship.
   if (gateName === 'uiux' || gateName === 'review') {
     signals.screenChecklist = collectScreenChecklist(cwd, featureName, gateName);
   }
@@ -185,37 +108,19 @@ export function collectSignals(featureName, feature, cwd, gateName) {
     };
   }
 
-  // verificationStatus alimenta a regra "verify vermelho pausa"; o resto do
-  // stamp é auditoria. verificationStale é fail-open na direção "not stale":
-  // stamp com sha null (checkout sem git) ou stamp ausente lê como NOT stale.
+  // verificationStale é fail-open: stamp sem sha (checkout sem git) ou ausente lê como NOT stale.
   signals.verification = verification;
   if (verification?.status) signals.verificationStatus = verification.status;
   signals.verificationStale = treeMovedSince(cwd, verification?.sha, sha);
 
-  // O nó e2e, separado do rollup de propósito: um `skip` NÃO reprova
-  // `verification.status`, então sem estas duas chaves o gate lê 'pass' tanto
-  // quando o e2e rodou e passou quanto quando ele nunca rodou. `null` aqui é
-  // DESCONHECIDO (stamp ausente, ou anterior ao nó e2e), nunca 'skip'.
-  // `e2eSkipClass` é DERIVADO pela fonte única (classifyE2eSkip, em
-  // risk-detector.js) e persistido só como auditoria — quem decide continua
-  // sendo shouldPauseGate, aqui não há política.
-  //
-  // Nenhuma das três entra em OVERRIDABLE_SIGNAL_KEYS: descrevem O QUE
-  // ACONTECEU no disco, como `gate`/`workType`, não uma opinião que o chamador
-  // possa afirmar. Um `--signals '{"e2eStatus":"pass"}'` compraria o Gate 3.
+  // Separado do rollup: um `skip` NÃO reprova `verification.status`. `null` é DESCONHECIDO, nunca
+  // 'skip'. Fora de OVERRIDABLE_SIGNAL_KEYS: um `--signals '{"e2eStatus":"pass"}'` compraria o ship.
   signals.e2eStatus = verification?.nodes?.e2e ?? null;
   signals.e2eReason = verification?.e2eReason ?? null;
   signals.e2eSkipClass = signals.e2eStatus === 'skip' ? classifyE2eSkip(signals.e2eReason) : null;
 
-  // O nó de eval, separado do rollup pela mesma razão que o e2e: um eval que
-  // PULOU não avermelha `verification.status`, então o gate
-  // leria 'pass' tanto para "o eval rodou e passou" quanto para "o eval nunca
-  // rodou". `null` aqui é "este projeto não declara nó de eval" — DISTINTO de
-  // 'skip', que é "declara, e esta corrida não o executou".
+  // Mesma razão do e2e. `null` = o projeto não declara nó de eval, DISTINTO de 'skip'.
   signals.evalsStatus = verification?.nodes?.evals ?? null;
-  // O que a feature TOCOU, contra os globs que o projeto declarou como
-  // prompt/modelo. Fato de disco: `declared` vem do config commitado, `touched`
-  // do git. Nenhuma política mora aqui — quem decide é shouldPauseGate.
   signals.promptModel = collectPromptModel(cwd, defaultBranch);
 
   signals.diffstat = getDiffStat(defaultBranch, cwd);
@@ -224,20 +129,8 @@ export function collectSignals(featureName, feature, cwd, gateName) {
   return signals;
 }
 
-/**
- * `morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>]
- * [--json]` — the deterministic, disk-derived counterpart to `gate-decision`:
- * collects the signals `shouldPauseGate()` (risk-detector.js) already knows
- * how to score, calls it, and persists the result through the SAME write path
- * as `gate-decision` ({@link persistGateDecision}) so the two commands can
- * never produce a differently-shaped `gateDecisions.{gate}` entry.
- *
- * Golden rule: this command does NOT change gate policy. It is a faithful
- * caller of risk-detector.js's existing, already-tested rules — nothing here
- * adds a new pause condition. Where the skills' natural-language risk tables
- * (morph-plan/morph-review/morph-apply) diverge from risk-detector.js,
- * risk-detector.js wins.
- */
+// Never changes gate policy: a faithful caller of risk-detector.js, which wins wherever the
+// skills' risk tables diverge. Persists through the same path as `gate-decision`.
 export async function gateCheckCommand(featureName, gateName, options = {}) {
   try {
     if (!VALID_GATES.includes(gateName)) {
@@ -252,10 +145,7 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Owner-tree guard: gate-check reads workType/checks/verdict/git off cwd
-    // AND writes the resulting decision through persistGateDecision — both
-    // halves are wrong from a tree that isn't this feature's own, so refuse
-    // rather than compute a decision from stale reads and then fail to save it.
+    // Both the reads and the persisted decision are wrong from a tree that doesn't own the feature.
     const owner = assertOwnerTree(featureName, process.cwd());
     if (owner.blocked) {
       for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec gate-check ${featureName} ${gateName}`)) {

package/src/commands/state/gate-decision.js

@@ -15,11 +15,7 @@ function parsePauseValue(raw) {
   process.exit(1);
 }
 
-/**
- * trust from the committed config (BOM-tolerant), defaulting to "auto".
- * Shared by `gate-decision` (recorded as metadata) and `gate-check`
- * (drives shouldPauseGate's decision directly).
- */
+/** `trust` from the committed config (BOM-tolerant), defaulting to "auto". */
 export function readTrustFromConfig() {
   try {
     const path = join(process.cwd(), '.morph', 'config', 'config.json');
@@ -32,22 +28,8 @@ export function readTrustFromConfig() {
 }
 
 /**
- * Write the canonical `gateDecisions.{gate}` entry to a feature's
- * authoritative feature.json — the ONE write path both `gate-decision` (a
- * caller-supplied pause/reason/signals, e.g. an LLM's natural-language risk
- * read, or a manual override) and `gate-check` (a `shouldPauseGate()`-derived
- * pause/reason/signals) feed into, so the two commands can never drift into
- * two different persisted shapes for the same field. Does NOT validate
- * `gateName` — callers that need a friendly CLI error check `VALID_GATES`
- * themselves before calling this.
- *
- * @param {string} featureName
- * @param {string} gateName
- * @param {{ pause: boolean, reason?: string, signals?: object, trust?: string, cwd?: string, source: 'manual'|'gate-check' }} decision
- * @returns {Promise<{ pause: boolean, reason: string, signals: object, trust: string, decidedAt: string, mockupsHash?: string|null }>}
- *   the exact entry written (decidedAt is server-side, generated here). A uiux
- *   decision also carries the hash of the mockup it saw: it answers that
- *   mockup's pause, not the next one's.
+ * The ONE write path of `gateDecisions.{gate}`, shared by `gate-decision` and `gate-check`.
+ * Does not validate `gateName`. A uiux decision records the `mockupsHash` it saw.
  */
 export async function persistGateDecision(featureName, gateName, { pause, reason, signals = {}, trust, cwd = process.cwd(), source } = {}) {
   const entry = {
@@ -64,24 +46,6 @@ export async function persistGateDecision(featureName, gateName, { pause, reason
   return entry;
 }
 
-/**
- * `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>]
- * [--signals <json>] [--trust <mode>]` — record the trust decision for a gate
- * under `gateDecisions` in the authoritative feature.json.
- *
- * The timestamp (`decidedAt`) is
- * stamped server-side and the write is atomic (state-manager). This replaces
- * the manual Edit of feature.json from the skills — which collided with the
- * state-sync hook rewriting the file between the agent's Read and Edit
- * ("file modified since read"). The canonical shape is documented in
- * framework/schemas/feature.schema.json and consumed by gate-guard.js.
- *
- * The manual escape hatch: `gate-check` (src/commands/state/gate-check.js) is
- * the default, disk-derived path via `shouldPauseGate()`; this command stays
- * for a caller that already knows the decision (an LLM's natural-language
- * risk read a script can't see, or a deliberate override) — both write
- * through {@link persistGateDecision}, so the persisted shape never diverges.
- */
 export async function gateDecisionCommand(featureName, gateName, options = {}) {
   try {
     if (!VALID_GATES.includes(gateName)) {

package/src/commands/state/handoff.js

@@ -1,34 +1,9 @@
-/**
- * `morph-spec handoff <feature>` — generate the compressed session-handoff
- * document (`.morph/features/{f}/handoff.md`).
- *
- * The fleet workflow hands a feature between Claude Code instances (a new
- * worktree session, a resumed session after a phase transition). The handoff
- * is the sanctioned way to carry context across: derived, regenerable, and
- * pointer-based (see handoff-generator.js). This command is also called
- * in-process by `worktree setup`, `create --worktree`, `advance` and
- * `approve` — the CLI surface exists for the LLM/user to refresh the
- * document on demand.
- *
- * WORKTREE-AWARE: `create --worktree` writes a COMPLETE feature.json into the
- * primary root and the branch-committed copy (`morph/{f}`) becomes the truth
- * from then on. Building the handoff from `process.cwd()` unconditionally
- * used to mean: run this from the root while the worktree is alive, and you
- * either got "Feature not found" (root's copy was already sheded) or a
- * document silently built from the stale birth skeleton, written INTO the
- * root (a second, always-defasada copy of a document that's supposed to be
- * regenerated, not duplicated). This resolves the owning tree first
- * (`resolveFeatureTree`) and writes THERE, unless `--here` forces the cwd.
- */
-
 import chalk from 'chalk';
 import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
-/**
- * @param {string} featureName
- * @param {{ json?: boolean, here?: boolean }} [options]
- */
+// With a live worktree the root copy is a stale birth skeleton: build and write in the
+// owning tree (`resolveFeatureTree`) unless `--here` forces the cwd.
 export function handoffCommand(featureName, options = {}) {
   const cwd = process.cwd();
 
@@ -44,9 +19,7 @@ export function handoffCommand(featureName, options = {}) {
   }
 
   if (owner.source === 'branch-only') {
-    // The truth exists, committed on morph/{feature}, but is not materialized
-    // into ANY tree right now. A handoff points at files on disk — pointing
-    // at files that exist nowhere is worse than recusing outright.
+    // The handoff points at files on disk; a truth materialized in no tree is refused.
     const hint = `morph-spec worktree setup ${featureName}  (ou: git checkout ${owner.branch})`;
     if (options.json) {
       console.log(JSON.stringify({ error: 'feature-not-in-tree', feature: featureName, branch: owner.branch, hint }));

package/src/commands/state/list.js

@@ -10,32 +10,8 @@ import { morphBranches, currentBranch, branchView } from '../../lib/worktree/fea
 import { buildPrIndex } from '../../lib/git/pr-index.js';
 import { pendingPrFeatures, prForFeature } from '../../lib/git/pending-prs.js';
 
-/**
- * `morph-spec list [--all] [--json] [--no-branch]` — the feature audit board.
- *
- * One row per feature: slug × workType × status × phase × gates (G1/Gd/G3) ×
- * description, plus a flags column for anomalies (missing description, gate
- * order, dangling worktree pointer). Complements `delete`: see what's dead
- * before removing it. Replaces the ad-hoc "loop over every feature.json in
- * python" audit.
- *
- * Read-only by construction — reads feature.json straight off disk (never
- * `loadState`, which mutates), so listing can never resurrect or prune state.
- * Always exits 0 (fail-open — an empty board is an answer).
- *
- * WORKTREE TRUTH: `create --worktree` writes a COMPLETE feature.json into the
- * primary root, then the branch-committed copy (`morph/{f}`) becomes the
- * truth and the root's copy never changes again. By default this command
- * reads that branch when it disagrees with the disk — same mechanism fleet
- * already uses (`branchToReadFrom`/`branchView`, moved to feature-truth.js so
- * both consumers share the one place this condition lives). `--no-branch`
- * turns that off for a faster, disk-only read.
- *
- * NOT AN OBJECTIVE: this command only enumerates what exists IN THIS TREE.
- * A feature that lives solely on a branch with no local `.morph/features/`
- * copy in any tree never appears here — aggregating across trees is
- * `morph-spec fleet`'s job, not this one's.
- */
+// Read-only: feature.json straight off disk, never `loadState` (which mutates). By default the
+// branch `morph/{f}` wins over a stale root copy; `--no-branch` reads only the disk.
 
 const G = ['plan', 'uiux', 'review'];
 
@@ -59,34 +35,23 @@ function readFeaturesIn(baseDir, subdir, location) {
   return rows;
 }
 
-/** The feature's `worktree` pointer, normalized with a computed `exists`. */
 function readWorktreePointer(fj) {
   const w = fj?.worktree;
   if (!w?.path) return null;
   return { path: w.path, branch: w.branch || null, exists: existsSync(w.path) };
 }
 
-/**
- * Build a row's flags/gates/identity shape from a `feature.json` object, given
- * an already-resolved phase and provenance. Shared by the disk read
- * (`buildRow`) and the branch read (`resolveBranchTruth`) so the two never
- * drift on what counts as an anomaly.
- */
+// Shared by the disk and branch reads so the two never drift on what counts as an anomaly.
 function shapeRow(name, fj, location, phase, { corruptDisk = false, worktree = null, source = 'disk', branch = null } = {}) {
   const gates = {};
   for (const g of G) gates[g] = fj.approvalGates?.[g]?.approved === true;
 
-  // Gate 3 approved WITHOUT the independent review reports (`approve --self-assessed`).
-  // A recorded degradation is only worth recording if it is visible — this is
-  // the surface that makes it so (D2).
+  // Review approved via `--self-assessed`: a recorded degradation is only worth it if visible.
   const selfAssessed = fj.approvalGates?.review?.selfAssessed === true;
 
   const flags = [];
   if (corruptDisk) flags.push('corrupt');
   if (selfAssessed) flags.push('self-assessed-g3');
-  // Identity + gate-order anomalies come from the shared rules
-  // (core/state/feature-identity.js, core/state/gate-order.js) — same source
-  // doctor reports from.
   for (const field of missingIdentity(fj)) flags.push(`missing-${field}`);
   for (const v of gateOrderViolations(fj.approvalGates)) flags.push(`gate-order:${v.gate}`);
   if (worktree && !worktree.exists) flags.push('worktree-missing');
@@ -104,10 +69,7 @@ function shapeRow(name, fj, location, phase, { corruptDisk = false, worktree = n
     location,
     createdAt: fj.createdAt || null,
     updatedAt: fj.updatedAt || null,
-    // Provenance — added for worktree-truth awareness. `worktree` is always
-    // read from the LOCAL disk copy (root-owned bookkeeping, stripped from
-    // branch-committed copies at birth) regardless of where `source` reads
-    // status/phase/gates from.
+    // `worktree` always comes from the local disk copy, whatever `source` reads the rest from.
     source,
     branch,
     worktree,
@@ -124,14 +86,7 @@ function buildRow(name, fj, fdir, location) {
   });
 }
 
-/**
- * Refresh active rows from the branch that owns their truth, when the disk
- * copy in THIS tree is not that owner. Never throws — a git hiccup or a
- * corrupt blob just leaves the disk-read row in place.
- *
- * @param {string} cwd
- * @param {object[]} rows - mutated in place (active rows only)
- */
+// Never throws: a git hiccup or a corrupt blob leaves the disk-read row in place.
 function resolveBranchTruth(cwd, rows) {
   if (!isGitRepo(cwd)) return;
   let head;
@@ -160,15 +115,8 @@ function resolveBranchTruth(cwd, rows) {
   }
 }
 
-/**
- * Flag an active row whose feature ALSO has an archived copy in this tree —
- * the signature left behind when a feature is merged and archived on its
- * branch (or via GitHub) without `morph-spec finish` ever running here:
- * the untracked root skeleton from `create` survives `git pull` (it was
- * never tracked, so pull has nothing to remove) while `.morph/archive/{f}`
- * arrives for real. Flagging beats suppressing the row — a read-only board
- * that resurrects or prunes nothing must not silently hide the anomaly either.
- */
+// The untracked root skeleton survives a `git pull` that brings `.morph/archive/{f}`. Flagged,
+// never hidden: a read-only board must not silently suppress the anomaly.
 function flagArchivedElsewhere(cwd, rows) {
   for (const row of rows) {
     if (row.location !== 'active') continue;
@@ -178,13 +126,8 @@ function flagArchivedElsewhere(cwd, rows) {
   }
 }
 
-/**
- * A linha de uma feature que existe SÓ como PR aberto — sem pasta ativa nem
- * arquivada nesta árvore. É o estado que o `finish --pr` deixa: o scaffold do
- * root foi apagado pelo shed e o archive viaja no diff do PR, chegando na
- * default apenas no merge. Sem esta linha o trabalho fica sem dono no quadro,
- * e uma branch sem dono é candidata a poda.
- */
+// O estado que o `finish --pr` deixa: sem esta linha o trabalho fica sem dono no quadro, e
+// uma branch sem dono é candidata a poda.
 function pendingRow(p) {
   return {
     feature: p.feature,
@@ -232,15 +175,8 @@ export function listCommand(options = {}) {
   // Commander's `--no-branch` sets options.branch = false; anything else (undefined/true) reads the branch.
   if (options.branch !== false) resolveBranchTruth(cwd, rows);
 
-  // Estado do PR — uma consulta ao `gh` por invocação, compartilhada pela
-  // coluna e pela síntese. `--no-branch` (o modo offline rápido) pula as duas.
-  //
-  // `prIndex` continua `null` quando a pergunta não pôde ser feita (sem `gh`,
-  // sem auth, remoto não-GitHub, ou `--no-branch`). É o mesmo sinal que
-  // `--json` já expõe como `pr: null` por linha — a tabela texto usa o mesmo
-  // fato para decidir se a coluna PR sequer aparece (achado #2): índice `null`
-  // degrada para o comportamento de antes, sem coluna e sem `-` que afirme
-  // ausência.
+  // Uma consulta ao `gh` por invocação. `prIndex` `null` = a pergunta não pôde ser feita: sem
+  // coluna PR, e sem `-` que afirme "sem PR" para o que é "não sabemos".
   let prIndex = null;
   if (options.branch !== false) {
     prIndex = buildPrIndex(cwd);
@@ -249,8 +185,7 @@ export function listCommand(options = {}) {
       row.pr = pr ? { number: pr.number, state: pr.state, url: pr.url, ageDays: null } : null;
     }
     const known = new Set(rows.map((r) => r.feature));
-    // `null` propaga desconhecido: nenhuma linha sintetizada, e nenhuma
-    // afirmação de que não há pendência.
+    // `null` propaga desconhecido: nenhuma linha sintetizada.
     for (const p of pendingPrFeatures(cwd, { index: prIndex }) || []) {
       if (!known.has(p.feature)) rows.push(pendingRow(p));
     }
@@ -271,13 +206,8 @@ export function listCommand(options = {}) {
   }
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
-  // A coluna PR só aparece quando o índice foi construído com sucesso (achado
-  // #2) — um índice `null` não vira uma coluna cheia de `-`, que afirmaria
-  // "sem PR" para algo que na verdade é "não sabemos".
   const showPr = Boolean(prIndex);
-  // `pr-pending` é estado normal de trabalho em voo, não inconsistência —
-  // não deve marcar `⚠` nem contar no rodapé (achado #6). Continua em
-  // `flags` no `--json`: é metadado real, só não é anomalia.
+  // `pr-pending` é trabalho em voo, não anomalia: segue em `flags` no `--json`, sem `⚠`.
   const warnFlags = (r) => r.flags.filter((f) => f !== 'pr-pending');
   console.log(chalk.white.bold(
     col('FEATURE', 22) + col('TYPE', 9) + col('STATUS', 13) + col('PHASE', 17) + col('WHERE', 22) + (showPr ? col('PR', 12) : '')