@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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

@@ -1,29 +1,5 @@
-/**
- * `morph-spec report-check <feature> [slice...] [--json]` — the deterministic
- * half of the missing-report protocol.
- *
- * The slice report file is the sub-agent's authoritative return value; the
- * final message is a courtesy. This command answers what the orchestrator
- * needs when it resumes control, from evidence rather than from the agent's
- * own word: **did the WORK land, independently of whether the REPORT did?**
- *
- *   verdict                          action
- *   ─────────────────────────────    ──────────────────
- *   ok                               proceed
- *   report-stale                     refresh-from-evidence
- *   report-incomplete                resume | complete-degraded
- *   work-landed-report-missing       accept-degraded
- *   no-work-no-report                redispatch
- *   report-missing-evidence-unknown  redispatch   (conservative default)
- *
- * The observed evidence is keyed by the dispatch: the agent whose `agentId`
- * wrote the report owns the window, and its writes after the report make the
- * report stale. A report written inline (no sub-agent) is judged by its
- * markers only.
- *
- * Exit 0 only for `ok`. The output also carries `tree` (see tree-state.js),
- * information only — it never changes the verdict.
- */
+// Judged from observed evidence, never the agent's word: did the WORK land, independently of
+// the REPORT? The `tree` block is information only and never changes the verdict.
 
 import chalk from 'chalk';
 import { existsSync, readFileSync, statSync } from 'fs';
@@ -54,7 +30,7 @@ export function inspectReviewReports(cwd, feature) {
   return out;
 }
 
-/** Who reviews and on which model: the verifier routes to opus on prompt/model or media; security is dispatched only when required. */
+// The verifier routes to opus on prompt/model or media; security is dispatched only when required.
 function reviewDispatch(cwd, feature, slices) {
   let changedFiles = [];
   try { changedFiles = changedPathsAgainst(detectDefaultBranch(cwd), cwd); } catch { changedFiles = []; }
@@ -74,20 +50,12 @@ function reviewDispatch(cwd, feature, slices) {
   };
 }
 
-/**
- * Two clocks: the report's mtime comes from the filesystem, the event's `ts`
- * from the telemetry hook. Two seconds absorb their skew and are far less
- * than any real work done after reporting.
- */
+// Two clocks: the report mtime comes from the filesystem, the event `ts` from the hook. Two
+// seconds absorb their skew and are far less than any real work done after reporting.
 export const STALE_TOLERANCE_MS = 2000;
 
 const slash = (p) => String(p || '').replace(/\\/g, '/');
 
-/**
- * The event target relative to the tree that logged it, the same shape as the
- * slice's `arquivos:`. `Write`/`Edit` targets are absolute; a target outside
- * that tree comes back as it was.
- */
 function toTreeRelative(target, treePath) {
   const norm = slash(target);
   const root = slash(treePath).replace(/\/+$/, '');
@@ -98,7 +66,6 @@ function toTreeRelative(target, treePath) {
 
 const reportSuffix = (feature, sliceId) => `.morph/features/${feature}/3-implement/reports/${sliceId}.md`.toLowerCase();
 
-/** Every successful Write/Edit of every tree of this repo, oldest first. */
 function loadWrites(cwd) {
   let trees = [];
   try { trees = loadTelemetryAllTrees(cwd); } catch { trees = []; }
@@ -115,14 +82,8 @@ function loadWrites(cwd) {
   return { available: trees.some((t) => t.events.length > 0), writes: dedupeEvents(events) };
 }
 
-/**
- * Evidence OBSERVED in the telemetry, never the agent's own word.
- *
- * The dispatch that owns the slice is the sub-agent that wrote its report —
- * the latest such write carrying an `agentId`; an orchestrator edit made
- * afterwards does not hide it. Without a report, any write to one of the
- * slice's files says the work landed.
- */
+// The owning dispatch is the latest sub-agent write of the report; a later orchestrator edit
+// does not hide it. Without a report, any write to one of the slice files says the work landed.
 function observedEvidence(telemetry, feature, slice) {
   if (!telemetry.available) return { available: false };
   const suffix = reportSuffix(feature, slice.id);
@@ -150,7 +111,6 @@ function observedEvidence(telemetry, feature, slice) {
   };
 }
 
-/** Is the report older than the last work its own dispatch observed? */
 function isReportStale(reportFsPath, observed) {
   if (!observed?.agentId || !observed.lastWriteAt) return false;
   try {
@@ -160,7 +120,6 @@ function isReportStale(reportFsPath, observed) {
   }
 }
 
-/** Combine report state + evidence into a verdict and the action it implies. */
 function decide(report, observed, stale) {
   if (report.exists && report.complete) {
     // Structural integrity answers "is the report complete?", never "is it
@@ -200,11 +159,7 @@ function snapshotPath(cwd, feature) {
   return join(cwd, '.morph', 'features', feature, '4-review', 'tree-before-eval.json');
 }
 
-/**
- * The tree block, compared with the snapshot taken before the review agents were
- * dispatched when there is one. `beforeEval` takes a new snapshot after the
- * comparison, so the output still shows what changed since the previous one.
- */
+// `beforeEval` snapshots after comparing, so the output still shows what changed since the last one.
 function treeFor(cwd, feature, beforeEval, slices = []) {
   const path = snapshotPath(cwd, feature);
   let snapshot = null;
@@ -218,11 +173,6 @@ function treeFor(cwd, feature, beforeEval, slices = []) {
   return { tree, beforeEval: { at: next.at, files: Object.keys(next.files).length }, reviewModels };
 }
 
-/**
- * @param {string} feature
- * @param {string[]|undefined} sliceIds - audits only these slices; none audits every slice
- * @param {{ json?: boolean, cwd?: string, beforeEval?: boolean }} [options]
- */
 export function reportCheckCommand(feature, sliceIds, options = {}) {
   const cwd = options.cwd || process.cwd();
   const emit = (obj, code) => {

package/src/commands/state/retype.js

@@ -5,28 +5,8 @@ import { getFeature, setApprovalGate, updateFeature } from '../../core/state/sta
 import { WORK_TYPES, isValidWorkType, POLICY_APPROVER_PREFIX } from '../../core/work-types.js';
 import { renderPlanSkeleton } from '../../lib/plan/plan-template.js';
 
-/**
- * `morph-spec retype <feature> <newType>` — mid-flight work-type change with
- * asymmetric gate rules that preserve GENUINE human/auto approvals and only
- * ever undo policy stamps:
- *
- *  - Blocked outright once Gate 3 (review) is approved — the feature already
- *    shipped its pipeline, retyping it retroactively would be revisionist.
- *  - Downgrade (fewer skipped gates → more skipped gates, e.g. feature/bug
- *    → chore/hotfix) is blocked once the plan gate carries a genuine
- *    (non-policy) approval — the plan was already accepted under the old
- *    type's scrutiny; retyping around it would erase that judgment call.
- *  - Upgrade (more skipped gates → fewer, e.g. chore/hotfix → feature/bug)
- *    is always allowed before review: it only ever ADDS scrutiny.
- *
- * Applying a retype resets exactly the gates that were stamped
- * `policy:{oldType}` and the NEW type no longer skips (so the human is asked
- * again), stamps `policy:{newType}` on any of the new type's skippedGates
- * that aren't already approved (a prior genuine approval is left standing —
- * that's the "preserves human approvals" half of the contract), scaffolds
- * any phase folders the new type needs that don't exist yet, and appends an
- * audit entry to `workTypeHistory`.
- */
+// Retype only ever undoes `policy:` stamps: blocked once review is approved; a downgrade
+// is blocked once the plan carries a genuine approval; an upgrade only adds scrutiny.
 export async function retypeCommand(featureName, newType, options = {}) {
   try {
     if (!isValidWorkType(newType)) {
@@ -69,8 +49,7 @@ export async function retypeCommand(featureName, newType, options = {}) {
 
     const now = new Date().toISOString();
 
-    // Reset gates that were stamped policy:{oldType} and the new type no
-    // longer skips — a genuine (non-policy) approval is never touched.
+    // A genuine (non-policy) approval is never reset.
     const resetGates = [];
     for (const [gate, data] of Object.entries(feature.approvalGates || {})) {
       const isPolicyStamped = String(data?.approvedBy || '').startsWith(POLICY_APPROVER_PREFIX);
@@ -80,8 +59,7 @@ export async function retypeCommand(featureName, newType, options = {}) {
       }
     }
 
-    // Stamp the new type's skipped gates — but only the ones not already
-    // approved (preserves a prior genuine approval untouched).
+    // A gate already approved keeps its genuine approval.
     const stampedGates = [];
     for (const gate of newWorkType.skippedGates) {
       if (!feature.approvalGates?.[gate]?.approved) {

package/src/commands/validation/index.js

@@ -1,5 +1,2 @@
-/**
- * Validation Commands
- */
 export { validateFeatureCommand } from './validate-feature.js';
 export { verifyCommand } from './verify.js';

package/src/commands/validation/mutate.js

@@ -23,11 +23,8 @@ const EXIT = { ok: 0, failed: 1, usage: 2, busy: 3, unsafe: 4 };
 const KEEP_RUNS = 2;
 const DEFAULT_JOBS = 2;
 
-/**
- * One heavy slot per worker: the first waits like any heavy node, the others
- * are taken only if free right now. The run uses as many workers as it got,
- * so a busy machine degrades to sequential instead of queueing.
- */
+// One heavy slot per worker: the first waits, the others are taken only if free now,
+// so a busy machine degrades to sequential instead of queueing.
 export function workerGate({ root, feature, jobs }) {
   const config = readHeavyConfig(root);
   const gates = [createHeavyGate({ projectPath: root, label: 'mutate', feature, config })];

package/src/commands/validation/validate-feature.js

@@ -1,34 +1,11 @@
-/**
- * MORPH-SPEC Feature Validation Command
- *
- * Content-aware validation of feature outputs at each phase.
- * Checks section presence, schema consistency, and contract correctness.
- *
- * Usage:
- *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
- *
- * Example:
- *   morph-spec validate user-portal --phase plan
- *   morph-spec validate user-portal --json
- */
-
 import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import { parsePlan } from '../../lib/plan/plan-parser.js';
 import { knownPersonas, planHash, validatePlan } from '../../lib/plan/checks.js';
 
-/**
- * Expected sections per markdown output — matched against *section markers*
- * (headings and line-start bold labels), not whole-file substrings; see
- * `extractSectionMarkers`. plan.md is judged by the plan parser instead.
- *
- *   required    → ERROR if absent.
- *   recommended → WARNING if absent.
- *   optional    → silent. Tracked when present, never penalized.
- *
- * Each entry is a string or an array of acceptable aliases (any-of).
- */
+// Matched against section markers (headings and line-start bold labels), never whole-file
+// substrings. required → ERROR, recommended → WARNING, optional → never penalized; an array is any-of.
 const OUTPUT_SECTIONS = {
   'verifier.md': {
     required: [
@@ -60,9 +37,6 @@ const OUTPUT_SECTIONS = {
   },
 };
 
-/**
- * Phase-to-output mapping (v5 NLH)
- */
 const PHASE_OUTPUTS = {
   plan: ['plan.md', 'checks.json'],
   uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
@@ -70,9 +44,6 @@ const PHASE_OUTPUTS = {
   review: ['verifier.md', 'reviewer.md'],
 };
 
-/**
- * Phase-to-folder mapping (v5 filesystem convention)
- */
 const PHASE_FOLDERS = {
   plan: '2-plan',
   uiux: '1-design',
@@ -80,20 +51,7 @@ const PHASE_FOLDERS = {
   review: '4-review',
 };
 
-/**
- * Extract section markers from markdown content.
- *
- * A marker is a line that structurally introduces a section:
- *   - a markdown heading           → `## Arquitetura da solução`
- *   - a line-start bold label      → `**Status:** Aceito`
- *
- * Bold labels are included on purpose (deviation from heading-only): reports
- * write `**Verdict:**` as a line-start bold label, not a heading. They are
- * structural, not prose, so this avoids the accidental-prose-match problem that
- * whole-file substring matching had.
- *
- * Returns lowercased marker texts.
- */
+// Line-start bold labels count: reports write `**Verdict:**` as a label, not a heading.
 function extractSectionMarkers(content) {
   const markers = [];
   for (const rawLine of content.split('\n')) {
@@ -111,9 +69,6 @@ function extractSectionMarkers(content) {
   return markers;
 }
 
-/**
- * Validate a single output file
- */
 function validateOutput(featurePath, outputFile) {
   const filePath = path.join(featurePath, outputFile);
   const result = {
@@ -143,7 +98,6 @@ function validateOutput(featurePath, outputFile) {
     return result;
   }
 
-  // Skip section checks for files without defined sections
   const sections = OUTPUT_SECTIONS[outputFile];
   if (!sections) {
     return result;
@@ -151,7 +105,6 @@ function validateOutput(featurePath, outputFile) {
 
   validateMarkdownSections(content, sections, result);
 
-  // Size warnings
   if (result.lineCount < 10) {
     result.warnings.push(`File is very short (${result.lineCount} lines) — may be incomplete`);
   }
@@ -159,10 +112,7 @@ function validateOutput(featurePath, outputFile) {
   return result;
 }
 
-/**
- * plan.md is judged by the same parser and rules as `morph-spec plan-check`.
- * `planDir` is `.morph/features/{f}/2-plan`, so the project is four levels up.
- */
+// `planDir` is `.morph/features/{f}/2-plan`, so the project is four levels up.
 function validatePlanOutput(content, planDir, result) {
   const plan = parsePlan(content);
   const { errors, warnings } = validatePlan(plan, { personas: knownPersonas(path.resolve(planDir, '..', '..', '..', '..')) });
@@ -171,7 +121,6 @@ function validatePlanOutput(content, planDir, result) {
   result.sections.found.push(...plan.sections.filter((x) => x.key).map((x) => x.name));
 }
 
-/** checks.json must parse and carry the hash of the plan.md beside it. */
 function validateChecksOutput(content, planDir, result) {
   let doc;
   try {
@@ -189,16 +138,6 @@ function validateChecksOutput(content, planDir, result) {
   result.sections.found.push(`${doc.checks?.length ?? 0} check(s), ${doc.slices?.length ?? 0} slice(s)`);
 }
 
-/**
- * Validate markdown sections against section markers (headings + bold labels).
- *
- * Each `entry` is a string or array of acceptable aliases (any-of). A section
- * is present when at least one alias is a substring of at least one marker.
- *
- *   required    → missing produces an ERROR
- *   recommended → missing produces a WARNING
- *   optional    → tracked when present, never penalized
- */
 function validateMarkdownSections(content, sections, result) {
   const markers = extractSectionMarkers(content);
   const match = (entry) => {
@@ -234,13 +173,6 @@ function validateMarkdownSections(content, sections, result) {
   }
 }
 
-/**
- * Resolve the list of `{ file, dir }` outputs to validate.
- *
- * @param {string} featurePath  Absolute path to the feature directory.
- * @param {string|null} phase   Phase key, or null to validate everything.
- * @returns {{ outputFiles?: Array<{file:string, dir:string}>, error?: string }}
- */
 function resolveOutputFiles(featurePath, phase) {
   if (phase) {
     const files = PHASE_OUTPUTS[phase];
@@ -250,7 +182,6 @@ function resolveOutputFiles(featurePath, phase) {
     return { outputFiles: files.map(file => ({ file, dir: searchPath })) };
   }
 
-  // Validate every existing output across the feature root + phase folders.
   const outputFiles = [];
   const isOutput = name => name.endsWith('.md') || name.endsWith('.cs') || name === 'checks.json';
   const entries = fs.readdirSync(featurePath, { withFileTypes: true });
@@ -267,17 +198,7 @@ function resolveOutputFiles(featurePath, phase) {
   return { outputFiles };
 }
 
-/**
- * Pure validation core — no console output, no process.exit.
- *
- * @param {string} featurePath  Absolute path to the feature directory.
- * @param {{ phase?: string }} [options]
- * @returns {{
- *   feature: string, phase: string, valid: boolean, error?: string,
- *   totalErrors: number, totalWarnings: number, totalFound: number,
- *   results: object[]
- * }}
- */
+/** Pure core: no console output, no process.exit. */
 export function runFeatureValidation(featurePath, options = {}) {
   const phase = options.phase || null;
   const feature = path.basename(featurePath);
@@ -312,9 +233,6 @@ export function runFeatureValidation(featurePath, options = {}) {
   };
 }
 
-/**
- * Main validate command (CLI wrapper around `runFeatureValidation`)
- */
 export async function validateFeatureCommand(featureName, options = {}) {
   if (!featureName) {
     console.error(chalk.red('Error: Feature name required'));
@@ -340,7 +258,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
   const { results, totalErrors, totalWarnings, totalFound } = validation;
   const schemaWarnings = [];
 
-  // JSON output mode
   if (options.json) {
     const output = {
       feature: featureName,
@@ -367,7 +284,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
     return;
   }
 
-  // Visual output
   console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
   console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
   console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
@@ -376,7 +292,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
   if (phase) console.log(chalk.gray(`Phase: ${phase}`));
   console.log('');
 
-  // File-by-file results
   for (const result of results) {
     const symbol = result.exists
       ? (result.errors.length === 0 ? '✅' : '❌')
@@ -387,25 +302,21 @@ export async function validateFeatureCommand(featureName, options = {}) {
 
     console.log(`${symbol} ${name}${result.exists ? chalk.gray(` (${result.lineCount} lines)`) : ''}`);
 
-    // Sections found
     if (result.sections.found.length > 0 && (options.verbose || result.errors.length > 0)) {
       result.sections.found.forEach(s => {
         console.log(chalk.green(`   ✓ ${s}`));
       });
     }
 
-    // Errors
     result.errors.forEach(err => {
       console.log(chalk.red(`   ✗ ${err}`));
     });
 
-    // Warnings
     result.warnings.forEach(warn => {
       console.log(chalk.yellow(`   ⚠ ${warn}`));
     });
   }
 
-  // Summary
   console.log('');
   console.log(chalk.gray('─'.repeat(60)));
 

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' };
 
@@ -106,17 +87,8 @@ function baselineStampBlock(baseline) {
   return `record-baseline: a contagem caiu em ${fell.map((u) => `${u.id} (${u.from} → ${u.to})`).join(', ')}`;
 }
 
-/**
- * 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 +99,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 +109,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 +133,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 +154,8 @@ 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.
- */
+// 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 {
@@ -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);
 }