@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/telemetry/metrics.js

@@ -1,18 +1,5 @@
-/**
- * Loop measurements over the harness event stream: turns, tool calls split by
- * orchestrator and sub-agent, time per command class, identical reruns, file
- * rereads, verify count per feature, git calls and whether the reuse
- * validator ran. Computed the same way on every window so a later
- * window compares with an earlier one.
- *
- * Every number degrades to null ("not measurable here") when the stream lacks
- * the field it needs — a v1 event never counts as a zero.
- *
- * A rerun is the same producer command (what runs before the output filter:
- * `dotnet test | tail -25` then `| tail -20` is one test run twice) in the same
- * feature within 10 minutes of its previous run. `rate` counts the repeats;
- * `burstRate` counts every run that belongs to a burst, the first included.
- */
+// Every number degrades to null when the stream lacks its field: a v1 event never counts as a zero.
+// A rerun is the same producer command (before the output filter) in the same feature within 10 minutes.
 
 import { ingestedBytes } from './telemetry-reader.js';
 import { producerOf } from '../../../framework/hooks/shared/command-tokens.js';
@@ -25,22 +12,13 @@ const READ_ONLY = new Set(['grep', 'rg', 'sed', 'ls', 'cat', 'find', 'head', 'ta
 const TOOL_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure']);
 const NO_FEATURE = '\u0000';
 
-/**
- * The command without quoted text and heredoc bodies: `morph-spec verify`
- * inside a commit message is not a verify run.
- */
+// `morph-spec verify` inside a commit message is not a verify run.
 function executedText(command) {
   const beforeHeredoc = command.split('<<', 1)[0];
   return beforeHeredoc.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, (q) => q[0] + ' '.repeat(q.length - 2) + q[0]);
 }
 
-/**
- * Kind (fine) and class (coarse) of a shell command. Searched anywhere in the
- * command, most specific first, so `cd x && dotnet test` is a test.
- *
- * @param {string} command
- * @returns {{ kind: string, klass: string }}
- */
+/** Searched anywhere in the command, most specific first, so `cd x && dotnet test` is a test. */
 export function classifyCommand(command) {
   const cmd = String(command || '');
   if (/\bmorph-spec(?:\.js)?\s+verify\s+[^\s;&|)]+/.test(executedText(cmd))) return { kind: 'verify', klass: 'verify' };
@@ -120,11 +98,8 @@ function finishCounters(c, turnsObserved) {
   };
 }
 
-/**
- * Why a command ran again within the window. Edits in between and a changed
- * output filter need no exit code; the pass/fail split does, so a masked or v1
- * exit code falls back to "after an edit or not".
- */
+// Edits in between and a changed output filter need no exit code; the pass/fail split does, so a masked
+// or v1 exit code falls back to "after an edit or not".
 function rerunClass(prev, current, editsBetween) {
   if (isV2(prev) && prev.outcome === 'timeout') return 'timeout';
   if (editsBetween === 0 && prev.command !== current.command) return 'refilter';
@@ -147,11 +122,7 @@ function reuseStateOf(e) {
   return { state: 'absent', reason: null };
 }
 
-/**
- * @param {Object[]} events - deduplicated, time-ordered (loadTelemetry)
- * @param {{ feature?: string, top?: number }} [opts]
- * @returns {Object} see framework/docs/CLI.md, "cost --metrics"
- */
+/** The returned shape is documented in framework/docs/CLI.md, "cost --metrics". */
 export function computeMetrics(events, opts = {}) {
   const top = Number.isInteger(opts.top) && opts.top > 0 ? opts.top : 10;
   const scoped = (events || []).filter((e) => e && typeof e === 'object' && (!opts.feature || e.feature === opts.feature));

package/src/lib/telemetry/telemetry-reader.js

@@ -1,14 +1,3 @@
-/**
- * Telemetry aggregation — reads the append-only harness event stream
- * (.morph/logs/events.jsonl, written by the telemetry-log hook) and summarizes
- * the whole execution path: which skills ran, which personas were dispatched,
- * which standards (knowledge base) were read, the tool mix, and the prompts.
- *
- * Pure aggregation (`aggregateTelemetry`) is separated from disk I/O
- * (`loadTelemetry`) so the summary logic is unit-testable without fixtures —
- * the same split fleet-scanner uses. CLI-side; runs in the target project cwd.
- */
-
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, basename } from 'path';
 import { parseWorktreeList, resolvePrimaryRoot } from '../../commands/project/worktree.js';
@@ -21,11 +10,8 @@ const EVENTS_LOG = /^events(-.+)?\.jsonl$/;
 // Caches a finish backup may hold; none of them contains a log.
 const BACKUP_SKIP_DIRS = new Set(['node_modules', '.next', 'bin', 'obj', 'TestResults', 'graphify-out', '.git']);
 
-/**
- * The same line reaches the reader through the live log, its rotated archives
- * and every finish backup that copied it. v2 events carry an `eventId`; a v1
- * event is identical only to a byte-identical copy of itself.
- */
+// The same line arrives through the live log, its rotated archives and every finish backup. v2 events
+// carry an `eventId`; a v1 event is identical only to a byte-identical copy of itself.
 function dedupeKey(event) {
   return event.eventId ? `id:${event.eventId}` : `raw:${JSON.stringify(event)}`;
 }
@@ -35,13 +21,7 @@ function eventTime(event) {
   return Number.isNaN(t) ? 0 : t;
 }
 
-/**
- * Collapse copies of the same event and restore time order across sources.
- * The sort is stable, so events sharing a timestamp keep their write order.
- *
- * @param {Object[]} events
- * @returns {Object[]}
- */
+/** Stable sort, so events sharing a timestamp keep their write order. */
 export function dedupeEvents(events) {
   const seen = new Set();
   const out = [];
@@ -61,9 +41,9 @@ function readJsonlFile(path, out) {
     for (const line of readFileSync(path, 'utf-8').split('\n')) {
       const trimmed = line.trim();
       if (!trimmed) continue;
-      try { out.push(JSON.parse(trimmed)); } catch { /* skip corrupt line */ }
+      try { out.push(JSON.parse(trimmed)); } catch {}
     }
-  } catch { /* unreadable file contributes nothing */ }
+  } catch {}
 }
 
 function archiveFiles(sessionsDir) {
@@ -77,15 +57,7 @@ function archiveFiles(sessionsDir) {
   }
 }
 
-/**
- * Read the event stream of a project root: the live log plus, by default, the
- * archives SessionStart rotated into `.morph/logs/sessions/` — reading only the
- * live file loses everything older than the last 5 MB.
- *
- * @param {string} [projectPath]
- * @param {{ archives?: boolean }} [options]
- * @returns {Object[]} deduplicated, in time order; [] when there is no log
- */
+/** Live log plus, by default, the rotated archives: the live file alone loses everything past 5 MB. */
 export function loadTelemetry(projectPath, { archives = true } = {}) {
   const root = projectPath || process.cwd();
   const events = [];
@@ -108,14 +80,7 @@ function collectBackupLogs(dir, depth, out) {
   }
 }
 
-/**
- * Event logs that `finish` saved under `<git-common-dir>/morph-spec/finish-backup/`
- * before tearing a worktree down — once the worktree is gone, a feature built
- * there leaves its telemetry nowhere else.
- *
- * @param {string} [cwd]
- * @returns {{ path: string, events: Object[] }|null}
- */
+/** Logs `finish` saved before tearing a worktree down: once it is gone, they are the feature's only telemetry. */
 export function loadFinishBackupTelemetry(cwd = process.cwd()) {
   const common = resolveGitCommonDir(cwd);
   if (!common) return null;
@@ -128,19 +93,7 @@ export function loadFinishBackupTelemetry(cwd = process.cwd()) {
   return { path: base, events: dedupeEvents(events) };
 }
 
-/**
- * Every git worktree that has its OWN `.morph/logs/events.jsonl` — the source
- * of `cost --all-trees` — plus a `finish-backup` entry for worktrees already
- * torn down. Reuses the worktree enumeration of `doctor --worktrees`/`fleet`.
- *
- * The PRIMARY worktree is labeled `'root'`; every other entry by its directory
- * basename (typically the feature slug). A tree that never ran the harness
- * contributes nothing. Outside a git repo this degrades to a single root
- * entry — never throws.
- *
- * @param {string} [cwd]
- * @returns {Array<{ tree: string, path: string, events: Object[] }>}
- */
+/** Labels the primary worktree `'root'`, the others by directory basename. Outside git, a single root entry. */
 export function loadTelemetryAllTrees(cwd = process.cwd()) {
   const root = resolvePrimaryRoot(cwd);
   const entries = parseWorktreeList(root);
@@ -167,21 +120,6 @@ function rank(map) {
     .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
 }
 
-/**
- * Summarize an event stream.
- *
- * @param {Object[]} events - raw events (from loadTelemetry)
- * @param {{ feature?: string }} [opts] - optional feature filter
- * @returns {{
- *   total: number,
- *   skills: Array<{name:string,count:number}>,
- *   personas: Array<{name:string,count:number}>,
- *   standards: Array<{path:string,count:number}>,
- *   tools: Array<{name:string,count:number}>,
- *   prompts: Array<{ts:string,source:'user'|'agent',feature:?string,phase:?string,text:string}>,
- *   features: string[]
- * }}
- */
 export function aggregateTelemetry(events, opts = {}) {
   const scoped = opts.feature
     ? (events || []).filter(e => e.feature === opts.feature)
@@ -226,21 +164,8 @@ export function aggregateTelemetry(events, opts = {}) {
   };
 }
 
-// ─────────────────────────────────────────────────────────────────────────
-// Cost aggregation — sibling to aggregateTelemetry (kept separate rather than
-// folded in: aggregateTelemetry's return shape is pinned by
-// test/commands/telemetry.test.js, which spreads it wholesale into --json
-// output — adding fields there would leak into that contract).
-//
-// Turns the same raw event stream into a cost-facing view: how many context
-// bytes were re-ingested (by kind, globally and per phase), and how many
-// sub-agent dispatches happened (and how many prompt chars they cost).
-//
-// "Bytes re-ingested" is a DETERMINISTIC PROXY for cost, not a token count —
-// hooks can only see what tools read off disk, never the model's actual
-// token usage. The `cost` command surfaces that caveat; this module only
-// computes the numbers.
-// ─────────────────────────────────────────────────────────────────────────
+// Kept apart from aggregateTelemetry: its return shape is spread into `telemetry --json`, so new fields
+// there would leak into that contract. Bytes re-ingested is a proxy for cost, never a token count.
 
 function mapToObj(map) {
   const out = {};
@@ -254,45 +179,8 @@ function sumValues(map) {
   return total;
 }
 
-/**
- * Summarize an event stream for cost purposes: bytes-re-ingested buckets by
- * `kind` (global and per phase) and sub-agent dispatch counts.
- *
- * Byte attribution prefers `bytesRead` (the line window a Read put in context)
- * and falls back to `bytes` (the file size — all v1 events have) — keyed off
- * the number alone, not the tool.
- *
- * Dispatch prompt size (Furo 3 — contract with the hooks-side telemetry-log
- * rewrite): a dispatch event's `prompt` field is now TRUNCATED to 2k chars on
- * write, with the original length carried separately as `promptChars`. When
- * `promptChars` (a number) is present it is preferred; a legacy stream that
- * only ever had the untruncated `prompt` string falls back to
- * `prompt.length`, unchanged from before — every existing byte count stays
- * exact against old logs.
- *
- * SessionUsage (main session) and AgentUsage (each sub-agent) are real token
- * counts, not the bytes proxy, and never touch toolCounts/bytesByKind/
- * dispatches. Only their `delta` is summed — the top-level numbers are a
- * running total repeated on every sample — so a v1 sample (no `delta`) is
- * counted in `sessionUsageLegacySamples` and never added in. Like any event
- * they obey the `--feature` filter. `sessionUsage`/`agentUsage` are `null`
- * when nothing summable was observed, never a zeroed object.
- *
- * @param {Object[]} events - raw events (from loadTelemetry)
- * @param {{ feature?: string }} [opts] - optional feature filter
- * @returns {{
- *   total: number,
- *   features: string[],
- *   bytesByKind: Object<string, number>,
- *   bytesTotal: number,
- *   dispatches: {count:number, promptChars:number},
- *   sessionUsage: {inputTokens:number, outputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, sessions:number, samples:number}|null,
- *   sessionUsageLegacySamples: number,
- *   agentUsage: {inputTokens:number, outputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, agents:number, samples:number}|null,
- *   tools: Array<{name:string,count:number}>,
- *   phases: Array<{phase:string, bytesByKind:Object<string,number>, bytesTotal:number}>,
- * }}
- */
+// Prefers `promptChars` over `prompt.length`: the prompt is truncated on write. Session and agent usage sum
+// only their `delta`, never the running total; they are `null` when nothing summable was seen.
 const SESSION_USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreationTokens'];
 
 /** Bytes a Read put in context: its window when known, else the file size. */
@@ -312,7 +200,7 @@ export function aggregateCost(events, opts = {}) {
   const toolCounts = new Map();
   const bytesByKindGlobal = new Map();
   const dispatches = { count: 0, promptChars: 0 };
-  const phaseBytes = new Map(); // phase -> Map(kind -> bytes)
+  const phaseBytes = new Map();
   const newUsageBucket = () => ({
     totals: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
     ids: new Set(),

package/src/lib/telemetry/verify-event.js

@@ -1,22 +1,9 @@
-/**
- * The `Verify` telemetry event: one line per `morph-spec verify` run with the
- * per-node status and duration, the commit it covered and whether the
- * reuse validator could run. The Bash event of the same command says who
- * called it and how long the whole command took; this one says what it did.
- */
-
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { appendTelemetryEvent, readTelemetryEvents } from '../../../framework/hooks/shared/telemetry-logger.js';
 
 const NODE_NAMES = ['build', 'tests', 'validators', 'e2e'];
 
-/**
- * @param {Object} result - runVerify() output
- * @param {{ sha: string|null, tree: 'root'|'worktree', persisted: boolean, reason: string|null,
- *   fingerprint?: string|null, source?: 'local'|'ci' }} context
- * @returns {Object}
- */
 export function buildVerifyEvent(result, { sha, tree, persisted, reason, fingerprint = null, source = 'local' }) {
   const nodes = {};
   for (const name of NODE_NAMES) {
@@ -43,16 +30,7 @@ export function buildVerifyEvent(result, { sha, tree, persisted, reason, fingerp
   };
 }
 
-/**
- * The last complete run of the same feature's verify over the
- * same tree, or null. A partial run (`--filter`, `--skip-*`, `--no-persist`)
- * is not the proof a complete one replaces, so it is passed over. Only the
- * live log is read: a repeat worth warning about is recent.
- *
- * @param {string} projectPath
- * @param {{ feature: string, fingerprint: string|null }} run
- * @returns {{ ts: string, status: string, sha: string|null }|null}
- */
+/** A partial run (`--filter`, `--skip-*`, `--no-persist`) is not the proof a complete one replaces. */
 export function findRepeatedVerify(projectPath, { feature, fingerprint }) {
   if (!fingerprint) return null;
   const events = readTelemetryEvents(projectPath);
@@ -65,13 +43,7 @@ export function findRepeatedVerify(projectPath, { feature, fingerprint }) {
   return null;
 }
 
-/**
- * Appends only where a morph project already exists: this command must never
- * be the one that creates `.morph/`.
- *
- * @param {string} projectPath
- * @param {Object} event
- */
+// Appends only where a morph project exists: this command must never be the one that creates `.morph/`.
 export function recordVerifyEvent(projectPath, event) {
   if (!existsSync(join(projectPath, '.morph'))) return;
   appendTelemetryEvent(event, projectPath);

package/src/lib/tests-audit/audit.js

@@ -0,0 +1,96 @@
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { basename, join } from 'path';
+import { isTestPath } from '../graph/sanitize.js';
+
+export const PROSE_MIN_HITS = 3;
+export const FAMILY_MIN_SIZE = 4;
+
+const TEST_FILE = /\.(cs|[cm]?[jt]sx?)$/i;
+const CS_CASE = /\[\s*\w*(Fact|Theory)\b/g;
+const JS_CASE = /^\s*(?:it|test)(?:\.each\s*\([\s\S]*?\))?\s*\(\s*['"`]/gm;
+const READS_DOC = /(ReadAll\w*|readFileSync)\s*\([^)]*\.(md|txt)\b/;
+const PROSE_ASSERT = /(?:Assert\.(?:Contains|DoesNotContain)\(\s*"|\.(?:toContain|toMatch)\(\s*['"`])([^"'`]{20,})/g;
+const CONSTANT_ASSERT = /Assert\.Equal\(\s*"[^"]*"\s*,\s*[A-Z]\w*(?:\.[A-Z]\w*)+\s*\)|expect\(\s*[A-Z][A-Z0-9_]+(?:\.[A-Z0-9_]+)*\s*\)\.toBe\(\s*['"`]/g;
+const CS_METHOD = /\[\s*\w*Fact\b[^\]]*\][\s\S]*?(?:void|Task)\s+(\w+)\s*\(/g;
+const LAYER = /^(\w+?)(Handler|Endpoints?|EndpointIntegration|Integration)Tests$/;
+
+function trackedTestFiles(root) {
+  try {
+    return execFileSync('git', ['ls-files', '-z'], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 256 * 1024 * 1024 })
+      .toString().split('\0').filter((f) => f && TEST_FILE.test(f) && isTestPath(f));
+  } catch {
+    return null;
+  }
+}
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+const countOf = (text, re) => (text.match(re) ?? []).length;
+
+function factFamilies(text) {
+  const byStem = new Map();
+  for (const m of text.matchAll(CS_METHOD)) {
+    const name = m[1];
+    const cut = name.lastIndexOf('_');
+    if (cut <= 0) continue;
+    const stem = name.slice(0, cut);
+    byStem.set(stem, [...(byStem.get(stem) ?? []), name]);
+  }
+  return [...byStem].filter(([, names]) => names.length >= FAMILY_MIN_SIZE).map(([stem, names]) => ({ stem, size: names.length }));
+}
+
+/** Read-only heuristics over the tracked test files: candidates to delete or merge, never verdicts. */
+export function auditTests(root) {
+  const files = trackedTestFiles(root);
+  if (files === null) return { ok: false, reason: 'git ls-files não respondeu — a auditoria lê só arquivos rastreados' };
+
+  const perFile = [];
+  const prose = [];
+  const constants = [];
+  const families = [];
+  const layers = new Map();
+  for (const file of files) {
+    let text;
+    try { text = readFileSync(join(root, file), 'utf8'); } catch { continue; }
+    const cases = /\.cs$/i.test(file) ? countOf(text, CS_CASE) : countOf(text, JS_CASE);
+    if (cases === 0) continue;
+    perFile.push({ file, cases });
+
+    const proseHits = [...text.matchAll(PROSE_ASSERT)].filter((m) => /\s/.test(m[1]));
+    if (READS_DOC.test(text) || proseHits.length >= PROSE_MIN_HITS) {
+      prose.push({ file, readsDoc: READS_DOC.test(text), literalAsserts: proseHits.length });
+    }
+    for (const m of text.matchAll(CONSTANT_ASSERT)) constants.push({ file, line: lineOf(text, m.index) });
+    for (const family of factFamilies(text)) families.push({ file, ...family });
+
+    const layer = LAYER.exec(basename(file).replace(/\.\w+$/, ''));
+    if (layer) layers.set(layer[1], [...(layers.get(layer[1]) ?? []), file]);
+  }
+
+  perFile.sort((a, b) => b.cases - a.cases);
+  return {
+    ok: true,
+    files: perFile.length,
+    cases: perFile.reduce((n, f) => n + f.cases, 0),
+    largest: perFile.slice(0, 10),
+    prose,
+    constants,
+    families,
+    layers: [...layers].filter(([, f]) => f.length > 1).map(([subject, f]) => ({ subject, files: f })),
+  };
+}
+
+export function renderTestsAudit(result) {
+  if (!result.ok) return `tests audit: ${result.reason}`;
+  const out = [`${result.cases} casos em ${result.files} arquivos de teste`, ''];
+  const section = (title, rows) => {
+    if (rows.length === 0) return;
+    out.push(`${title} (${rows.length})`, ...rows.map((r) => `  ${r}`), '');
+  };
+  section('Maiores arquivos', result.largest.map((f) => `${f.cases}  ${f.file}`));
+  section('Fixam texto ou leem doc — candidatos a apagar', result.prose.map((p) => `${p.file}${p.readsDoc ? ' (lê .md/.txt)' : ''}${p.literalAsserts ? ` — ${p.literalAsserts} asserts de frase` : ''}`));
+  section('Constante contra o próprio literal — candidatos a apagar', result.constants.map((c) => `${c.file}:${c.line}`));
+  section(`Famílias de [Fact] (≥ ${FAMILY_MIN_SIZE} com o mesmo prefixo) — candidatas a [Theory]`, result.families.map((f) => `${f.file} — ${f.stem}_* ×${f.size}`));
+  section('Mesmo assunto em mais de uma camada — mantenha a mais barata que morde', result.layers.map((l) => `${l.subject}: ${l.files.join(', ')}`));
+  return out.join('\n').trimEnd();
+}

package/src/lib/validators/code-budget/code-budget-validator.js

@@ -1,20 +1,4 @@
-/**
- * Code Budget Validator — o que a feature adicionou além do código.
- *
- * Mede, só nas linhas que esta árvore adicionou contra a branch default:
- *   (a) linhas de comentário que citam processo (task, UC, ADR, Gate...), que o
- *       standard `architecture-code-comments` manda para o commit;
- *   (b) linhas de teste ÷ linhas de produção, contra o orçamento por task do
- *       `morph-plan` (um teste por pós-condição + um de regressão por bug);
- *   (c) linhas de comentário ÷ linhas de código, porque o padrão do standard é
- *       nenhum comentário. Doc-comment (`///`, JSDoc) conta como qualquer outro.
- *
- * Sempre `warning`: é medida de volume, e o excesso pode estar justificado na
- * task. Um aviso por medida, não por linha, porque cada aviso custa 1 ponto no
- * score do validador. Qualquer falha de medição vira skip com razão.
- *
- * @module code-budget-validator
- */
+// Sempre `warning`: é medida de volume, e o excesso pode estar justificado no plano.
 
 import { readFileSync } from 'fs';
 import { join } from 'path';
@@ -25,31 +9,21 @@ import { isTestFile } from '../reuse/symbol-scanner.js';
 import { isGenerated, isProjectSource } from '../../../../framework/hooks/shared/source-files.js';
 import { citesProcess, commentLines } from '../../../../framework/hooks/shared/comment-scanner.js';
 
-/** Razão teste ÷ produção acima da qual se avisa. */
-export const MAX_TEST_RATIO = 1.5;
+export const MAX_TEST_RATIO = 1;
 
 /** Abaixo disto a razão não é julgada: a regressão de um bug de 2 linhas cabe aqui. */
 export const MIN_TEST_LINES = 40;
 
-/** Mais de uma linha de comentário a cada dez de código: os nomes não estão fazendo o trabalho. */
 export const MAX_COMMENT_RATIO = 0.1;
 
 /** Abaixo disto a densidade não é julgada: um comentário legítimo num arquivo pequeno já passaria da razão. */
 export const MIN_CODE_LINES = 40;
 
-/** Quantos locais citar no aviso de comentário antes de resumir com "(+N)". */
 const MAX_CITED = 4;
 
 const decimal = (n) => n.toFixed(1).replace('.', ',');
 
-/**
- * Puro, sem I/O.
- *
- * @param {Array<{path: string, content: string, added: number[]|null}>} files -
- *   `added` são as linhas adicionadas; `null` é o arquivo inteiro (novo)
- * @returns {{commentLines: number, processLines: Array<{file: string, line: number, text: string}>,
- *   testLines: number, productionLines: number, commentsByFile: Record<string, number>}}
- */
+/** `added` são as linhas adicionadas de cada arquivo; `null` é o arquivo inteiro (novo). */
 export function measureCodeBudget(files) {
   const measured = { commentLines: 0, processLines: [], testLines: 0, productionLines: 0, commentsByFile: {} };
 
@@ -74,10 +48,6 @@ export function measureCodeBudget(files) {
   return measured;
 }
 
-/**
- * @param {ReturnType<typeof measureCodeBudget>} measured
- * @returns {Array<object>} avisos no formato do validation-runner
- */
 export function budgetIssues(measured) {
   const issues = [];
   const { commentLines: comments, processLines, testLines, productionLines, commentsByFile = {} } = measured;
@@ -93,7 +63,7 @@ export function budgetIssues(measured) {
       file: processLines[0].file,
       line: processLines[0].line,
       solution:
-        'A história vai na mensagem de commit e no decisions.md; no código fica só o porquê que ' +
+        'A história vai na mensagem de commit e no plan.md; no código fica só o porquê que ' +
         'ele não mostra (standard architecture-code-comments).',
     });
   }
@@ -133,16 +103,6 @@ export function budgetIssues(measured) {
   return issues;
 }
 
-/**
- * Validador plugado no `validation-runner` (e por ele no nó `validators` do
- * `morph-spec verify`).
- *
- * @param {string} projectPath
- * @param {string|null} [featureName] - não usado: a medida é da árvore inteira contra a default
- * @param {object} [options]
- * @param {Map<string, number[]|null>} [options.addedLines] - override da coleta (testes)
- * @returns {Promise<{errors: number, warnings: number, issues: object[], _skipReason?: string}>}
- */
 export async function validateCodeBudget(projectPath, featureName = null, options = {}) {
   const result = { errors: 0, warnings: 0, issues: [] };
 

package/src/lib/validators/code-budget/index.js

@@ -1,9 +1,2 @@
-/**
- * Code Budget Validators
- *
- * Volume que a feature adicionou além do código: comentário que conta a
- * história do processo e teste acima do orçamento (ver code-budget-validator.js).
- */
-
 export * from './code-budget-validator.js';
 export * from '../../../../framework/hooks/shared/comment-scanner.js';

package/src/lib/validators/contracts/contract-compliance-validator.js

@@ -18,7 +18,6 @@ export async function validateContracts(projectPath, featureName, options = {})
     return skipped('plan.md declares no interfaces/records/enums — skipping');
   }
 
-  // Find all .cs files in the project (excluding .morph outputs, bin, obj)
   const csFiles = await glob('**/*.cs', {
     cwd: projectPath,
     ignore: ['.morph/**', '**/bin/**', '**/obj/**', '**/node_modules/**']
@@ -30,7 +29,6 @@ export async function validateContracts(projectPath, featureName, options = {})
     try {
       projectCode[file] = readFileSync(fullPath, 'utf-8');
     } catch {
-      // Skip unreadable files
     }
   }
 
@@ -39,7 +37,6 @@ export async function validateContracts(projectPath, featureName, options = {})
   let total = 0;
   const interfaceResults = [];
 
-  // Validate interfaces
   for (const iface of contracts.interfaces) {
     total++;
     const result = validateInterface(iface, projectCode, options);
@@ -58,7 +55,6 @@ export async function validateContracts(projectPath, featureName, options = {})
       });
     }
 
-    // Check for missing methods
     for (const method of result.missingMethods || []) {
       issues.push({
         level: 'error',
@@ -69,7 +65,6 @@ export async function validateContracts(projectPath, featureName, options = {})
     }
   }
 
-  // Validate records/DTOs
   for (const record of contracts.records) {
     total++;
     const found = Object.entries(projectCode).some(([, content]) =>
@@ -90,7 +85,6 @@ export async function validateContracts(projectPath, featureName, options = {})
     }
   }
 
-  // Validate enums
   for (const enumDef of contracts.enums) {
     total++;
     const found = Object.entries(projectCode).some(([, content]) =>
@@ -138,7 +132,6 @@ function parseContracts(content) {
   const records = [];
   const enums = [];
 
-  // Extract interfaces with their methods
   const interfaceRegex = /public\s+interface\s+(I\w+)(?:\s*:\s*[\w<>,\s]+)?\s*\{([^}]*)\}/gs;
   let match;
 
@@ -150,18 +143,15 @@ function parseContracts(content) {
     interfaces.push({ name, methods });
   }
 
-  // Extract records/classes (DTOs)
   const recordRegex = /public\s+(record|class|struct)\s+(\w+)/g;
   while ((match = recordRegex.exec(content)) !== null) {
     const type = match[1];
     const name = match[2];
-    // Skip interface names that were already captured
     if (!name.startsWith('I') || !interfaces.some(i => i.name === name)) {
       records.push({ type, name });
     }
   }
 
-  // Extract enums
   const enumRegex = /public\s+enum\s+(\w+)/g;
   while ((match = enumRegex.exec(content)) !== null) {
     enums.push({ name: match[1] });
@@ -170,9 +160,6 @@ function parseContracts(content) {
   return { interfaces, records, enums };
 }
 
-/**
- * Extract method signatures from an interface body
- */
 function extractMethods(body) {
   const methods = [];
 
@@ -182,7 +169,6 @@ function extractMethods(body) {
 
   while ((match = methodRegex.exec(body)) !== null) {
     const methodName = match[1];
-    // Skip property getters/setters
     if (!['get', 'set', 'init'].includes(methodName)) {
       methods.push(methodName);
     }
@@ -191,9 +177,6 @@ function extractMethods(body) {
   return methods;
 }
 
-/**
- * Validate that an interface is implemented in project code
- */
 function validateInterface(iface, projectCode, options) {
   const result = {
     name: iface.name,
@@ -205,7 +188,6 @@ function validateInterface(iface, projectCode, options) {
     missingMethods: []
   };
 
-  // Search for classes implementing this interface
   const implRegex = new RegExp(`class\\s+(\\w+)\\s*(?:<[^>]*>)?\\s*:\\s*[^{]*${escapeRegex(iface.name)}`, 'g');
 
   for (const [file, content] of Object.entries(projectCode)) {
@@ -215,7 +197,6 @@ function validateInterface(iface, projectCode, options) {
       result.implementingClass = match[1];
       result.implementingFile = file;
 
-      // Check which methods are implemented
       for (const method of iface.methods) {
         const methodExists = new RegExp(`(public|protected|private|internal)?\\s*(async\\s+)?\\S+\\s+${escapeRegex(method)}\\s*\\(`, 'g').test(content);
         if (methodExists) {
@@ -225,17 +206,14 @@ function validateInterface(iface, projectCode, options) {
         }
       }
 
-      break; // Found the implementation
+      break;
     }
-    implRegex.lastIndex = 0; // Reset for next file
+    implRegex.lastIndex = 0;
   }
 
   return result;
 }
 
-/**
- * Escape special regex characters in a string
- */
 function escapeRegex(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }