@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/standards/verified-against.js

@@ -1,106 +1,29 @@
-/**
- * src/lib/standards/verified-against.js
- *
- * THE parser for a standard's verification header and for its age against the
- * AI package pin. Single source of truth, on purpose.
- *
- * A standard declares what it was checked against, and when:
- *
- *     **Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08);
- *     provado por `templates/dotnet/ai-kit/.../AgentFactory.cs`. Last-verified: 2026-09-08.
- *
- * Three places need to read that same fact — `scripts/check-freshness.js`
- * (the freshness gate), `test/framework/standard-header.test.js` (the header
- * contract) and the "ai-agents vs ai-pin" report. Three copies of the regex
- * would drift apart, which is exactly the failure mode CLAUDE.md's Dependency
- * Matrix exists to catalogue. So the regex lives here, once.
- *
- * The age is measured against `framework/ai-pin.json`'s `pinnedAt`, never
- * against "today": `pinnedAt` is the date a human checked the packages, so the
- * obligation is tied to a human act. Measuring against today would make a
- * parked repository change colour on its own.
- *
- * NOTE on the 90-day window: this module EXPOSES the age and the threshold; it
- * enforces nothing — enforcement lives in its consumers. Issue #93 re-verified
- * the `ai-agents` standards and turned the window into a HARD FAIL in
- * scripts/check-freshness.js, so the number below is no longer only a warning.
- * The name kept the `WARN` in it because renaming an export is a change to the
- * module's surface, not to its documentation; scripts/check-freshness.js aliases
- * it to `AI_PIN_STALE_DAYS` rather than re-declaring `90` — see that file's
- * docblock and CONTRIBUTING.md's "two rulers" table.
- */
+// Age is measured against `pinnedAt` of framework/ai-pin.json, never "today":
+// a parked repository must not change colour on its own.
 
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
-/** Repository root, resolved from this file: src/lib/standards → ../../.. */
 const DEFAULT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
-/** Path of the pin relative to a root. */
 const AI_PIN_RELATIVE = join('framework', 'ai-pin.json');
 
-/**
- * The verification header, on ONE line.
- *
- * Group 1 is the subject (what the standard was checked against), group 2 the
- * ISO date. `[^\n]*?` keeps the match inside a single line: a `Last-verified:`
- * two paragraphs below belongs to another claim, and stitching the two would
- * date a header that never carried a date.
- *
- * @type {RegExp}
- */
+// Group 1 = subject, group 2 = ISO date. `[^\n]*?` keeps it on one line: a
+// `Last-verified:` further down belongs to another claim.
 export const LAST_VERIFIED_RE = /\*\*Verified against:\*\*([^\n]*?)Last-verified:\s*(\d{4}-\d{2}-\d{2})/;
 
-/**
- * An unresolved `// VERIFY` marker: a code detail the author could not confirm
- * against the installed package.
- *
- * Deliberately broader than the regex it replaces (`/^\s*\/\/\s*VERIFY:/`),
- * which demanded line-start AND a colon. Every real marker in
- * `framework/standards/ai-agents/` is an end-of-line comment without a colon —
- *
- *     using OpenAI.Batch;   // VERIFY namespace — confirme contra o pacote OpenAI 2.*
- *
- * — so the old counter reported 0 while two standards openly declared
- * unconfirmed C# API. `\b` keeps `// VERIFYING` out; the fence requirement is
- * NOT in the regex (a regex cannot see a fence) — it lives in
- * {@link countVerifyMarkers}, so prose quoting `// VERIFY:` never counts.
- *
- * @type {RegExp}
- */
+// Real markers are end-of-line and often lack a colon (`x; // VERIFY namespace`),
+// so no line-start/colon anchor. The fence rule lives in countVerifyMarkers.
 export const VERIFY_MARKER_RE = /(^|\s)\/\/\s*VERIFY\b/;
 
-/**
- * Age, in days against `pinnedAt`, above which an `ai-agents/**` standard is
- * due for re-verification.
- *
- * READ UNDER TWO NAMES, ONE VALUE. `scripts/check-freshness.js` imports it as
- * `AI_PIN_STALE_DAYS` and **hard-fails** the run above it (issue #93), for
- * standards under `framework/standards/ai-agents/` measured against `pinnedAt`.
- * The alias exists so the number is declared once: a second literal `90` is the
- * same drift that once blinded the `// VERIFY` counter.
- *
- * The `WARN` in the name is now historical — it shipped in issue #92, when the
- * window was a measurement. Kept because renaming an export changes the module's
- * surface; this comment changes only what the reader is told.
- *
- * @type {number}
- */
+// scripts/check-freshness.js hard-fails above this (aliased as AI_PIN_STALE_DAYS):
+// declare the number only here.
 export const AI_AGENTS_WARN_DAYS = 90;
 
-/** ISO calendar date, the only date shape this module accepts. */
 const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 
-/**
- * Parse a standard's verification header.
- *
- * @param {string} text - Full markdown text of the standard.
- * @returns {{ verifiedAgainst: string, lastVerified: string }|null}
- *   `null` when the standard carries no parseable header — the caller decides
- *   whether that is a warning (the backfill backlog) or a failure
- *   (`ai-agents/**`, where a new standard must be born dated).
- */
+/** `null` when no parseable header: the caller decides if that is a warning or a failure. */
 export function parseVerifiedAgainst(text) {
   if (typeof text !== 'string' || text.length === 0) return null;
   const m = LAST_VERIFIED_RE.exec(text);
@@ -108,80 +31,18 @@ export function parseVerifiedAgainst(text) {
   return { verifiedAgainst: m[1].trim(), lastVerified: m[2] };
 }
 
-/**
- * The `provado por` clause, and the path token that may follow it.
- *
- * THREE TYPESETTINGS EXIST IN THE ACERVO, and all three are real claims.
- * Counted by re-deriving every one of the 78 standards on disk and summing the
- * resulting paths — 27 paths across 16 entries:
- *
- *     A  ; provado por `templates/…/AgentFactory.cs` e `.../ConversationStore.cs`
- *     B  ; `provado por templates/…/AgentFactory.cs` para a **ordem do pipeline**
- *     C  . O timeout é **provado por** `.../AgentSpecOptions.cs` e `.../AgentFactory.cs`
- *
- * B opens the code span BEFORE the clause; C wraps the clause in bold and can
- * appear MID-SENTENCE, after an earlier clause already closed. Each one was
- * found by measuring, and each was missing from the rule that preceded it:
- *
- *   - ignoring B dropped 4 of 16 claims (`middleware-patterns`,
- *     `observability-patterns`, `rag-custom-pgvector`, `structured-output`);
- *   - ignoring C dropped 2 paths from `llm-runtime-defaults` — 25 instead of 27.
- *
- * READ THE SHAPE OF THAT SECOND MISS, because it is why counting entries is not
- * enough: `llm-runtime-defaults` had two OTHER paths from a clause of form A, so
- * it stayed in the "16 entries with proof" bucket either way. No counter moved,
- * `--check` stayed green, exit 0. The only ruler that saw it is the SUM of
- * paths. A canary that pins entry counts would have gone green over it — which
- * is why `standards-registry.test.js` pins the paths themselves, written out by
- * hand, and not a total produced by this function.
- *
- * The DENIALS must stay empty, and they are the majority (61 of the 77 headers
- * derive to `[]`; 16 say some variant of "sem cláusula `provado por`" or
- * "NÃO carimba `provado por`"). Three properties keep them out without a
- * blacklist of prose:
- *
- *   1. a path must contain a `/` — so "`provado por`. Os nomes" and
- *      "`provado por`: o ai-kit" match nothing;
- *   2. a path must be CLOSED BY A BACKTICK — so prose that merely follows the
- *      clause ("para a **ordem do pipeline**") cannot be mistaken for a path;
- *   3. the clause must not be the tail of a LONGER word — `aprovado por` and
- *      `comprovado por` are different claims. The corpus already contains
- *      "aprovado por lucas@…" inside a code sample, so this is a live shape,
- *      not a hypothetical.
- *
- * @type {RegExp}
- */
+// Three real typesettings: backtick before the clause, after it, or the clause in
+// bold mid-sentence. The non-letter prefix keeps `aprovado por` out.
 export const PROVED_BY_TRIGGER_RE = /(?:^|[^a-zA-Z])provado por/gi;
 
-/**
- * One path token after the clause, plus the separator that may precede it:
- * whitespace, backtick, `,`, `;`, the word `e`, and the markdown emphasis
- * characters `*` and `_`. The emphasis characters are in the class because of
- * typesetting C — without them, `**provado por**` armed the trigger and then
- * matched no path at all, losing both of its files in silence.
- *
- * Anchored: it only ever reads from the cursor, so prose ends the scan instead
- * of being searched through.
- *
- * @type {RegExp}
- */
+// A path needs a `/` and a closing backtick, so denials ("sem cláusula `provado por`")
+// derive nothing. `*`/`_` are separators for the bold form. Anchored: prose ends the scan.
 export const PROVED_BY_PATH_RE =
   /^[\s`,;*_]*(?:\be\b[\s`,;*_]*)?([A-Za-z0-9_.][A-Za-z0-9_.\-]*(?:\/[A-Za-z0-9_.\-]*)+)`/;
 
 /**
- * Derive the list of files a standard claims to be *proved by*.
- *
- * Reads the SAME header {@link parseVerifiedAgainst} reads — deliberately, and
- * from this module, because a second regex over the same sentence in
- * `scripts/generate-standards-registry.js` is precisely the drift the module
- * docblock opens with.
- *
- * @param {string} verifiedAgainst - The subject captured by
- *   {@link parseVerifiedAgainst} (group 1), not the whole markdown file.
- * @returns {string[]} Paths in declaration order, de-duplicated. `[]` means
- *   "the header was read and declares no proof" — a documental verification —
- *   never "not asked". The caller distinguishes the two by whether the header
- *   parsed at all.
+ * Takes the subject from parseVerifiedAgainst, not the whole file. `[]` means the
+ * header declares no proof, never "not asked".
  */
 export function deriveProvedBy(verifiedAgainst) {
   if (typeof verifiedAgainst !== 'string' || verifiedAgainst.length === 0) return [];
@@ -199,16 +60,7 @@ export function deriveProvedBy(verifiedAgainst) {
   return paths;
 }
 
-/**
- * Count unresolved `// VERIFY` markers that sit INSIDE a fenced code block.
- *
- * The fence rule is what separates a real marker from prose that merely quotes
- * one (`marcados \`// VERIFY:\` no código`). It lives here, next to the regex,
- * so every consumer counts the same thing.
- *
- * @param {string} text - Full markdown text of the standard.
- * @returns {number}
- */
+/** Only markers inside a fenced code block count: prose quoting one is not a marker. */
 export function countVerifyMarkers(text) {
   if (typeof text !== 'string' || text.length === 0) return 0;
   let inFence = false;
@@ -220,20 +72,7 @@ export function countVerifyMarkers(text) {
   return count;
 }
 
-/**
- * Read and parse `framework/ai-pin.json`.
- *
- * Throws — never falls back to a default — when the pin is missing or invalid:
- * without a pin there is no ruler, and pretending there is one is the original
- * defect this feature removes. The message names the file so the failure is
- * diagnosable from a CI log alone.
- *
- * @param {string} [root=DEFAULT_ROOT] - Repository root that contains `framework/`.
- * @returns {{ pinnedAt: string, source: string, targetFramework: string, sdk: string,
- *             packages: Record<string, {version: string, published: string, role: string}>,
- *             toolchain: Record<string, {version: string}> }}
- * @throws {Error} When the file is absent or is not valid JSON.
- */
+/** Throws, never defaults, when the pin is missing or invalid: without a pin there is no ruler. */
 export function readAiPin(root = DEFAULT_ROOT) {
   const pinPath = join(root, AI_PIN_RELATIVE);
   if (!existsSync(pinPath)) {
@@ -246,7 +85,6 @@ export function readAiPin(root = DEFAULT_ROOT) {
   }
 }
 
-/** Parse an ISO calendar date into a UTC epoch, timezone-independent. */
 function isoToUtc(value, label) {
   const m = typeof value === 'string' ? ISO_DATE_RE.exec(value) : null;
   if (!m) {
@@ -256,18 +94,8 @@ function isoToUtc(value, label) {
 }
 
 /**
- * Age of a standard's verification, in whole days, measured against the pin.
- *
- * Both dates are read as UTC calendar days, so the result does not depend on
- * the runner's timezone. The value is NEGATIVE when the standard is newer than
- * the pin — the caller must treat that as a PIN error (a `pinnedAt` in the
- * future), never as a fresh standard: otherwise every standard could be
- * "renewed" by editing one date.
- *
- * @param {string} lastVerified - ISO date from the standard's header.
- * @param {string} pinnedAt - ISO date from `framework/ai-pin.json`.
- * @returns {number} Whole days between the two, possibly negative.
- * @throws {TypeError} When either argument is not an ISO date.
+ * Negative when the standard is newer than the pin: the caller must treat that as a
+ * pin error, never as fresh, or any standard could be "renewed" by editing one date.
  */
 export function ageInDaysAgainstPin(lastVerified, pinnedAt) {
   const verified = isoToUtc(lastVerified, 'lastVerified');

package/src/lib/tasks/eval-node.js

@@ -1,36 +1,3 @@
-/**
- * Eval Node — the `runner: "evals"` kind of `project.tests[]`.
- *
- * WHY THIS IS A RUNNER KIND AND NOT A SIXTH VERIFY NODE
- *
- * An eval IS `dotnet test` with a category filter: one command, one cwd, one
- * clock, one exit code. Modelling it as something other than a test suite would
- * mean a second copy of the executor, a second decision for `--filter`, a second
- * decision for `--linux`, a second place for `expectedCount` — and a new line in
- * a residency-capped charter that has zero slack. As a runner kind it inherits
- * all of that for free, and the ONE thing the rollup cannot express (eval red vs
- * unit-test red) is recovered by the verify stamp, which records `nodes.evals`
- * separately.
- *
- * WHAT THIS MODULE OWNS
- *
- *   - the STATES of a cache tree, judged BEFORE `dotnet test` is invoked. Paying
- *     for a whole suite to discover at the end that the cache did not serve is
- *     the worst possible ordering;
- *   - the `MORPH_EVAL_*` variables the CLI DICTATES, so the same xunit suite is
- *     runnable by `verify` without a second configuration path;
- *   - reading the summary the fixture writes — where **null is UNKNOWN, never
- *     zero**.
- *
- * WHAT IT DELIBERATELY DOES NOT OWN
- *
- * The pin. `readAiPin()` (src/lib/standards/verified-against.js) is the single
- * reader of `framework/ai-pin.json`; a second parser here is how two truths
- * about "which version is pinned" begin.
- *
- * @module eval-node
- */
-
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, resolve, sep } from 'path';
 import { tmpdir } from 'os';
@@ -38,28 +5,19 @@ import { tmpdir } from 'os';
 import { isInside } from './test-runner.js';
 import { resolveAiPin } from '../ai/pin-drift.js';
 
-/** The runner kind. One spelling, imported by every reader. */
 export const EVAL_RUNNER = 'evals';
 
-/** Stamp file at the root of a cache tree — the SAME name the .NET fixture writes. */
+/** The SAME name the .NET fixture writes. */
 export const EVAL_STAMP_FILE = '.morph-eval-cache.json';
 
-/** Default dataset root, relative to the cache root's parent. */
+/** Relative to the cache root's parent. */
 export const DEFAULT_DATASET_DIR = 'eval-datasets';
 
-/** Default credential file. Gitignored, like `e2e.auth.envFile`; never in the committed config. */
 export const DEFAULT_ENV_FILE = '.env.evals';
 
 /**
- * The pin entries that decide the FORMAT of a response cache.
- *
- * Only the `Microsoft.Extensions.AI` family: the cache key is computed by that
- * library, and its own docs say the hash is not guaranteed stable across
- * releases. Bumping an unrelated provider package (OpenAI, Google.GenAI) cannot
- * invalidate a cache tree, and a stamp that reacted to it would fail for
- * nothing — a guardrail that cries wolf gets switched off.
- *
- * @param {Record<string, {version: string}>} packages
+ * Only the `Microsoft.Extensions.AI` family decides the cache format: that library
+ * computes the cache key. Reacting to unrelated provider bumps would fail for nothing.
  * @returns {Record<string, string>} name → exact version
  */
 export function cacheRelevantPackages(packages) {
@@ -72,13 +30,6 @@ export function cacheRelevantPackages(packages) {
   return out;
 }
 
-/**
- * Resolve every path an eval node names, against the project root.
- *
- * @param {import('./test-nodes.js').TestNode & {evals?: object}} node
- * @param {string} projectPath
- * @returns {{cacheRoot: string, datasetRoot: string, resultsRoot: string, envFile: string}}
- */
 export function resolveEvalPaths(node, projectPath) {
   const root = resolve(projectPath);
   const evals = node?.evals ?? {};
@@ -88,25 +39,14 @@ export function resolveEvalPaths(node, projectPath) {
   return {
     cacheRoot,
     datasetRoot: evals.datasetPath ? resolve(root, evals.datasetPath) : join(beside, DEFAULT_DATASET_DIR),
-    // Results live OUTSIDE the committed cache tree by construction — they carry
-    // stopwatch latency, token usage and the cache-hit flag, so committing them
-    // is a guaranteed diff on every run with no signal in it.
+    // Outside the committed cache tree: results carry latency and token usage,
+    // so committing them is a diff on every run with no signal in it.
     resultsRoot: join(beside, 'eval-results'),
     envFile: resolve(root, evals.envFile ?? DEFAULT_ENV_FILE),
   };
 }
 
-/**
- * First problem with a node's `evals` block, or null when it is well formed.
- *
- * Fail-CLOSED, like the rest of `validateTestNodes`: a typo here would make the
- * eval silently disappear, which is the exact defect this feature exists to
- * prevent.
- *
- * @param {*} raw - the raw `tests[]` entry
- * @param {string|null} projectPath
- * @returns {string|null}
- */
+/** Fail-CLOSED: a typo must never make the eval silently disappear. */
 export function evalBlockProblem(raw, projectPath) {
   const evals = raw?.evals;
 
@@ -129,7 +69,6 @@ export function evalBlockProblem(raw, projectPath) {
   for (const key of ['cachePath', 'datasetPath']) {
     const value = evals[key];
     if (typeof value !== 'string' || !value.trim()) continue;
-    // Same rule as `cwd`: a path that leaves the root addresses ANOTHER tree.
     if (!isInside(resolve(root, value.trim()), root)) {
       return `evals.${key} "${value}" resolves outside the project root`;
     }
@@ -138,7 +77,6 @@ export function evalBlockProblem(raw, projectPath) {
   return null;
 }
 
-/** Does this cache tree hold at least one entry, beyond the stamp? */
 function cacheHasEntries(cacheRoot) {
   const walk = (dir) => {
     let entries;
@@ -160,7 +98,7 @@ function cacheHasEntries(cacheRoot) {
   return walk(cacheRoot);
 }
 
-/** Read the stamp the .NET fixture wrote. null for absent OR unreadable — Check tells them apart. */
+/** null for absent OR unreadable. */
 export function readEvalStamp(cacheRoot) {
   const path = join(cacheRoot, EVAL_STAMP_FILE);
   if (!existsSync(path)) return null;
@@ -173,40 +111,18 @@ export function readEvalStamp(cacheRoot) {
 }
 
 /**
- * Decide, BEFORE spending a single second of suite clock, whether this eval node
- * can run.
- *
- * The order is the order of the spec, and it is not arbitrary: the three cache
- * states are judged before the command is invoked, because discovering at the
- * END of a suite that the cache did not serve costs the whole clock and tells
- * the reader nothing they could not have been told first.
- *
- * **There is no `skip` for a bad cache.** A skip here would recreate the hole
- * this harness closed twice: a green gate over a verification that never
- * happened. The only skip is scope — an eval suite does not belong in the
- * per-task loop.
- *
- * @param {string} projectPath
- * @param {object} node - a resolved test node with `runner === 'evals'`
- * @param {{taskId?: string|null, refresh?: boolean}} [options]
- * @returns {{status: 'skip'|'fail'|null, reason: string|null}} status null means RUN
+ * Judged BEFORE `dotnet test`: finding a bad cache at the end costs the whole clock.
+ * A bad cache is `fail`, never `skip` — a skip is a green gate over nothing.
+ * @returns {{status: 'fail'|null, reason: string|null}} status null means RUN
  */
 export function evalPreflight(projectPath, node, options = {}) {
-  const { taskId = null, refresh = false } = options;
+  const { refresh = false } = options;
 
   if (node?.runner !== EVAL_RUNNER) return { status: null, reason: null };
 
-  // Scope first: an eval suite does not pay for itself in a per-task loop, and
-  // the result Gate 3 reads is the feature-scoped one. Same treatment `e2e: true`
-  // already gets.
-  if (taskId) {
-    return { status: 'skip', reason: 'eval node runs at feature scope only' };
-  }
-
   const { cacheRoot, envFile } = resolveEvalPaths(node, projectPath);
 
-  // In refresh the tree is being (re)written; demanding a populated, stamped
-  // cache would make the FIRST cache impossible to create.
+  // Demanding a populated, stamped cache in refresh would make the FIRST cache impossible.
   if (refresh) {
     if (!existsSync(envFile)) {
       return {
@@ -222,15 +138,12 @@ export function evalPreflight(projectPath, node, options = {}) {
   }
 
   if (!cacheHasEntries(cacheRoot)) {
-    // Distinct from `missing` on purpose: an empty COMMITTED directory is far
-    // more likely a `.gitignore` mistake than a deliberate absence, and the two
-    // ask for different fixes.
+    // Distinct from `missing`: an empty committed directory is usually a `.gitignore` mistake.
     return { status: 'fail', reason: `eval-cache-empty: ${cacheRoot} não contém nenhuma entrada de cache` };
   }
 
   const pin = resolveAiPin(projectPath);
   if (!pin) {
-    // No pin in the project or in the CLI package: nothing to stamp against.
     return { status: null, reason: null };
   }
 
@@ -260,15 +173,7 @@ export function evalPreflight(projectPath, node, options = {}) {
 }
 
 /**
- * The `MORPH_EVAL_*` variables the CLI dictates for one eval node.
- *
- * The summary path is chosen HERE, by the CLI, and not by the fixture: two eval
- * nodes in the same `verify` must not collide, and the process that reads the
- * file is the one that should decide where it lives.
- *
- * @param {object} node
- * @param {string} projectPath
- * @param {{refresh?: boolean}} [options]
+ * The CLI picks the summary path, not the fixture: two eval nodes in one verify must not collide.
  * @returns {{env: Record<string,string>, summaryPath: string}}
  */
 export function evalNodeEnv(node, projectPath, options = {}) {
@@ -287,31 +192,19 @@ export function evalNodeEnv(node, projectPath, options = {}) {
 
   const pin = resolveAiPin(projectPath);
   if (pin) {
-    // Compact, and only the packages that decide the cache format. The fixture
-    // stamps from THIS, so it never has to read (or parse) the pin itself.
     env.MORPH_EVAL_PIN = JSON.stringify({
       pinnedAt: pin.pinnedAt,
       packages: cacheRelevantPackages(pin.packages),
     });
   }
 
-  // The credential file goes on top, same pattern as `e2e.auth.envFile`. Absent
-  // is NOT an error offline: that is the whole point of a warm cache.
+  // Absent credential file is NOT an error offline: that is the point of a warm cache.
   Object.assign(env, readEnvFile(envFile));
 
   return { env, summaryPath };
 }
 
-/**
- * Parse a `KEY=value` file. Blank lines and `#` comments ignored; surrounding
- * quotes stripped; the first `=` splits.
- *
- * Fail-open to `{}`: an unreadable credential file must not take down a run that
- * did not need a credential in the first place.
- *
- * @param {string} path
- * @returns {Record<string,string>}
- */
+/** Fail-open to `{}`: an unreadable credential file must not take down a run that needed none. */
 export function readEnvFile(path) {
   if (!path || !existsSync(path)) return {};
   let text;
@@ -337,14 +230,7 @@ export function readEnvFile(path) {
   return out;
 }
 
-/**
- * Read the summary the fixture wrote.
- *
- * @param {string} path
- * @returns {object|null} **null is UNKNOWN, never zero.** A summary nobody could
- *   read is not a suite that evaluated zero scenarios: collapsing the two would
- *   manufacture a count drop against `expectedCount` out of a missing file.
- */
+/** @returns {object|null} null is UNKNOWN, never zero: a missing file must not fabricate a count drop. */
 export function readEvalSummary(path) {
   if (!path || !existsSync(path)) return null;
   try {
@@ -357,37 +243,15 @@ export function readEvalSummary(path) {
 }
 
 /**
- * How many scenarios an eval run evaluated.
- *
- * The ONLY source of an eval node's count. The `dotnet` extractor reads the same
- * run but counts xunit cases — another unit (#110) — so an unreadable summary
- * yields null: UNKNOWN, never 0, and never the extractor's number.
- *
- * @param {object|null} summary
- * @returns {number|null}
+ * The ONLY source of an eval node's count. The `dotnet` extractor counts xunit cases,
+ * another unit, so an unreadable summary is null — never 0, never the extractor's number.
  */
 export function evalScenarioCount(summary) {
   const n = summary?.scenarios;
   return Number.isInteger(n) ? n : null;
 }
 
-/**
- * The NAMED failures of an eval run, one readable line each.
- *
- * The summary publishes `failures[]` (scenario, assertion, kind, reason) and
- * without this reader the field would be written and never surfaced — a
- * published field with no consumer, the same shape #91 closed on `superseded`.
- * Worse here than usual: the whole point of `failures[]` is that a red eval
- * names what broke, and a name nobody prints is not a name.
- *
- * Defensive by construction, because this parses a file produced by ANOTHER
- * process: a summary that is absent, unreadable, or carries a malformed entry
- * yields fewer lines, never a throw. A crash here would turn "the eval failed"
- * into "the verify crashed", which reports the wrong defect.
- *
- * @param {object|null} summary
- * @returns {string[]} readable lines; empty when there is nothing to name
- */
+/** Never throws on a malformed summary: a crash would report "verify crashed" instead of "eval failed". */
 export function evalFailureLines(summary) {
   const failures = summary?.failures;
   if (!Array.isArray(failures)) return [];
@@ -403,16 +267,7 @@ export function evalFailureLines(summary) {
     });
 }
 
-/**
- * Why an otherwise-green eval run must still be red, or null when it is fine.
- *
- * One case, and it is the guardrail-inert shape this repository has already paid
- * to learn: a suite that evaluated ZERO scenarios and exited 0. The exit code
- * alone cannot see it, because nothing failed — nothing ran.
- *
- * @param {object|null} summary
- * @returns {string|null}
- */
+/** Zero scenarios with exit 0 is red: the exit code cannot see a suite where nothing ran. */
 export function evalEmptyRunProblem(summary) {
   if (summary && summary.scenarios === 0) {
     return 'eval-empty-run: a suíte de eval avaliou 0 cenários e saiu verde';
@@ -420,16 +275,7 @@ export function evalEmptyRunProblem(summary) {
   return null;
 }
 
-/**
- * Warning for a run whose cache went cold — the tree changed and must be committed.
- *
- * A warning and not a failure, deliberately: spending money nobody asked for is
- * bad, but lying about the result is worse. Without the warning, a freshly
- * written cache stays on the disk of whoever ran it and CI misses tomorrow.
- *
- * @param {object|null} summary
- * @returns {string|null}
- */
+/** A warning, not a failure: without it the fresh cache stays on one disk and CI misses tomorrow. */
 export function evalColdCacheWarning(summary) {
   if (summary?.cache === 'cold') {
     const misses = Number.isInteger(summary.misses) ? summary.misses : '?';
@@ -438,14 +284,12 @@ export function evalColdCacheWarning(summary) {
   return null;
 }
 
-/** Relative form of a path, for messages that should not shout an absolute path. */
 export function relativeToProject(projectPath, target) {
   const root = resolve(projectPath) + sep;
   const full = resolve(target);
   return full.startsWith(root) ? full.slice(root.length).replace(/\\/g, '/') : full;
 }
 
-/** Is `path` a directory? Fail-open to false. */
 export function isDirectory(path) {
   try {
     return statSync(path).isDirectory();