@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

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

@@ -9,52 +9,134 @@
  * the same split fleet-scanner uses. CLI-side; runs in the target project cwd.
  */
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, basename } from 'path';
 import { parseWorktreeList, resolvePrimaryRoot } from '../../commands/project/worktree.js';
+import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
+import { isFailedToolCall } from '../../../framework/hooks/shared/telemetry-logger.js';
 
-const EVENTS_FILE = join('.morph', 'logs', 'events.jsonl');
+const LOGS_DIR = join('.morph', 'logs');
+const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
+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']);
 
 /**
- * Read the raw event stream from a project root. A corrupt/truncated line is
- * skipped, not fatal. Returns [] when there is no log.
+ * 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.
+ */
+function dedupeKey(event) {
+  return event.eventId ? `id:${event.eventId}` : `raw:${JSON.stringify(event)}`;
+}
+
+function eventTime(event) {
+  const t = Date.parse(event.ts ?? '');
+  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 {string} [projectPath]
+ * @param {Object[]} events
  * @returns {Object[]}
  */
-export function loadTelemetry(projectPath) {
+export function dedupeEvents(events) {
+  const seen = new Set();
+  const out = [];
+  for (const e of events || []) {
+    if (!e || typeof e !== 'object') continue;
+    const key = dedupeKey(e);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(e);
+  }
+  return out.sort((a, b) => eventTime(a) - eventTime(b));
+}
+
+function readJsonlFile(path, out) {
   try {
-    const p = join(projectPath || process.cwd(), EVENTS_FILE);
-    if (!existsSync(p)) return [];
-    const events = [];
-    for (const line of readFileSync(p, 'utf-8').split('\n')) {
+    if (!existsSync(path)) return;
+    for (const line of readFileSync(path, 'utf-8').split('\n')) {
       const trimmed = line.trim();
       if (!trimmed) continue;
-      try { events.push(JSON.parse(trimmed)); } catch { /* skip corrupt line */ }
+      try { out.push(JSON.parse(trimmed)); } catch { /* skip corrupt line */ }
     }
-    return events;
+  } catch { /* unreadable file contributes nothing */ }
+}
+
+function archiveFiles(sessionsDir) {
+  try {
+    return readdirSync(sessionsDir)
+      .filter((name) => name.startsWith('events-') && EVENTS_LOG.test(name))
+      .sort()
+      .map((name) => join(sessionsDir, name));
   } catch {
     return [];
   }
 }
 
 /**
- * Enumerate every git worktree that has its OWN `.morph/logs/events.jsonl` —
- * the data source for `cost --all-trees` (Furo 3). Reuses the SAME worktree
- * enumeration `doctor --worktrees`/`fleet` already use (`parseWorktreeList` +
- * `resolvePrimaryRoot` from commands/project/worktree.js — see
- * src/lib/worktree/fleet-scanner.js and worktree-audit.js for the sibling
- * consumers) instead of re-walking `git worktree list` here.
+ * 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.
  *
- * `git worktree list --porcelain` always lists the PRIMARY worktree first —
- * that entry is labeled `'root'`; every other entry is labeled by its
- * directory basename (typically the feature slug, e.g. `worktrees/{f}` →
- * `f`). Only trees whose events.jsonl actually exists are returned — a
- * worktree that never ran the harness contributes nothing, silently.
+ * @param {string} [projectPath]
+ * @param {{ archives?: boolean }} [options]
+ * @returns {Object[]} deduplicated, in time order; [] when there is no log
+ */
+export function loadTelemetry(projectPath, { archives = true } = {}) {
+  const root = projectPath || process.cwd();
+  const events = [];
+  if (archives) for (const file of archiveFiles(join(root, LOGS_DIR, 'sessions'))) readJsonlFile(file, events);
+  readJsonlFile(join(root, EVENTS_FILE), events);
+  return dedupeEvents(events);
+}
+
+function collectBackupLogs(dir, depth, out) {
+  if (depth < 0) return;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!BACKUP_SKIP_DIRS.has(entry.name)) collectBackupLogs(full, depth - 1, out);
+    } else if (EVENTS_LOG.test(entry.name) && /[\\/]\.morph[\\/]logs([\\/]sessions)?$/.test(dir)) {
+      out.push(full);
+    }
+  }
+}
+
+/**
+ * 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}
+ */
+export function loadFinishBackupTelemetry(cwd = process.cwd()) {
+  const common = resolveGitCommonDir(cwd);
+  if (!common) return null;
+  const base = join(common, 'morph-spec', 'finish-backup');
+  const files = [];
+  collectBackupLogs(base, 6, files);
+  if (!files.length) return null;
+  const events = [];
+  for (const file of files.sort()) readJsonlFile(file, events);
+  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`.
  *
- * Fail-open, like `loadTelemetry`: outside a git repo (or on any git error)
- * `resolvePrimaryRoot`/`parseWorktreeList` degrade to a single root entry —
- * never throws.
+ * 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[] }>}
@@ -74,6 +156,8 @@ export function loadTelemetryAllTrees(cwd = process.cwd()) {
       events: loadTelemetry(t.path),
     });
   }
+  const backup = loadFinishBackupTelemetry(root);
+  if (backup) out.push({ tree: 'finish-backup', path: backup.path, events: backup.events });
   return out;
 }
 
@@ -247,9 +331,9 @@ function finalizeTask(state) {
  * with `open: true` and `durationSeconds: null`, rather than silently
  * dropped.
  *
- * Byte attribution keys off `typeof e.bytes === 'number'` alone (not a tool
- * check) — today only Read events carry `bytes`, but this stays correct if
- * that widens rather than reporting a silent 0.
+ * 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
@@ -259,17 +343,13 @@ function finalizeTask(state) {
  * `prompt.length`, unchanged from before — every existing byte count stays
  * exact against old logs.
  *
- * SessionUsage events (`{ event: 'SessionUsage', inputTokens, outputTokens,
- * cacheReadTokens, cacheCreationTokens }`) are a session-level rollup, not a
- * per-tool event — they don't touch toolCounts/bytesByKind/dispatches, only
- * sum into `sessionUsage` (real, hook-observed token counts — NOT the bytes
- * proxy). They participate in the `--feature` filter exactly like every
- * other event (via `scoped`, computed once at the top): a rollup with no
- * `feature` field is silently excluded by a feature-scoped call, same as any
- * other feature-less event would be — no special-casing. `sessionUsage` is
- * `null` when the stream carries none (nothing to show), never a zeroed
- * object, so a caller can tell "observed, all zero" apart from "never
- * observed" the same way `evalScore` does in gate-check's signals.
+ * 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
@@ -280,7 +360,9 @@ function finalizeTask(state) {
  *   bytesByKind: Object<string, number>,
  *   bytesTotal: number,
  *   dispatches: {count:number, promptChars:number},
- *   sessionUsage: {inputTokens:number, outputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, sessions:number}|null,
+ *   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}>,
  *   tasks: Array<Object>,
  *   phases: Array<{phase:string, bytesByKind:Object<string,number>, bytesTotal:number}>,
@@ -288,6 +370,14 @@ function finalizeTask(state) {
  */
 const SESSION_USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreationTokens'];
 
+/** Bytes a Read put in context: its window when known, else the file size. */
+export function ingestedBytes(e) {
+  if (isFailedToolCall(e)) return null;
+  if (Number.isFinite(e.bytesRead)) return e.bytesRead;
+  if (Number.isFinite(e.bytes)) return e.bytes;
+  return null;
+}
+
 export function aggregateCost(events, opts = {}) {
   const scoped = opts.feature
     ? (events || []).filter(e => e.feature === opts.feature)
@@ -300,8 +390,13 @@ export function aggregateCost(events, opts = {}) {
   const phaseBytes = new Map(); // phase -> Map(kind -> bytes)
   const activeByFeature = new Map(); // featureKey -> open task state
   const tasks = [];
-  const sessionUsageTotals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
-  let sessionUsageCount = 0;
+  const newUsageBucket = () => ({
+    totals: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
+    ids: new Set(),
+    samples: 0,
+    legacy: 0,
+  });
+  const usage = { session: newUsageBucket(), agent: newUsageBucket() };
 
   for (const e of scoped) {
     if (!e || typeof e !== 'object') continue;
@@ -325,10 +420,18 @@ export function aggregateCost(events, opts = {}) {
       continue;
     }
 
-    if (e.event === 'SessionUsage') {
-      sessionUsageCount += 1;
+    if (e.event === 'SessionUsage' || e.event === 'AgentUsage') {
+      const bucket = e.event === 'SessionUsage' ? usage.session : usage.agent;
+      // Only a delta can be summed: the top-level numbers are the transcript's
+      // running total, and v1 samples (no delta) repeat it on every Stop.
+      if (!e.delta || typeof e.delta !== 'object') {
+        bucket.legacy += 1;
+        continue;
+      }
+      bucket.samples += 1;
+      bucket.ids.add(e.event === 'SessionUsage' ? (e.sessionId ?? 'default') : e.agentId);
       for (const key of SESSION_USAGE_KEYS) {
-        if (typeof e[key] === 'number' && Number.isFinite(e[key])) sessionUsageTotals[key] += e[key];
+        if (Number.isFinite(e.delta[key])) bucket.totals[key] += e.delta[key];
       }
       continue;
     }
@@ -339,14 +442,15 @@ export function aggregateCost(events, opts = {}) {
       active.tools.set(e.tool, (active.tools.get(e.tool) || 0) + 1);
     }
 
-    if (typeof e.bytes === 'number' && Number.isFinite(e.bytes)) {
+    const read = ingestedBytes(e);
+    if (read !== null) {
       const kind = e.kind || 'unknown';
-      bytesByKindGlobal.set(kind, (bytesByKindGlobal.get(kind) || 0) + e.bytes);
-      if (active) active.bytesByKind.set(kind, (active.bytesByKind.get(kind) || 0) + e.bytes);
+      bytesByKindGlobal.set(kind, (bytesByKindGlobal.get(kind) || 0) + read);
+      if (active) active.bytesByKind.set(kind, (active.bytesByKind.get(kind) || 0) + read);
       if (e.phase) {
         if (!phaseBytes.has(e.phase)) phaseBytes.set(e.phase, new Map());
         const m = phaseBytes.get(e.phase);
-        m.set(kind, (m.get(kind) || 0) + e.bytes);
+        m.set(kind, (m.get(kind) || 0) + read);
       }
     }
 
@@ -384,7 +488,13 @@ export function aggregateCost(events, opts = {}) {
     bytesByKind: mapToObj(bytesByKindGlobal),
     bytesTotal: sumValues(bytesByKindGlobal),
     dispatches,
-    sessionUsage: sessionUsageCount > 0 ? { ...sessionUsageTotals, sessions: sessionUsageCount } : null,
+    sessionUsage: usage.session.samples > 0
+      ? { ...usage.session.totals, sessions: usage.session.ids.size, samples: usage.session.samples }
+      : null,
+    sessionUsageLegacySamples: usage.session.legacy,
+    agentUsage: usage.agent.samples > 0
+      ? { ...usage.agent.totals, agents: usage.agent.ids.size, samples: usage.agent.samples }
+      : null,
     tools: rank(toolCounts),
     tasks,
     phases,

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

@@ -0,0 +1,79 @@
+/**
+ * The `Verify` telemetry event: one line per `morph-spec verify` run with the
+ * scope, 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 }} context
+ * @returns {Object}
+ */
+export function buildVerifyEvent(result, { sha, tree, persisted, reason, fingerprint = null }) {
+  const nodes = {};
+  for (const name of NODE_NAMES) {
+    const node = result.nodes?.[name];
+    if (!node) continue;
+    nodes[name] = { status: node.status, durationMs: Number.isFinite(node.durationMs) ? node.durationMs : null };
+  }
+  if (nodes.validators) {
+    nodes.validators.ran = [...(result.nodes.validators.ran || [])];
+    nodes.validators.skipped = (result.nodes.validators.skipped || [])
+      .map(({ validator, reason: why, unavailable }) => ({ validator, reason: why, unavailable: unavailable === true }));
+  }
+  return {
+    event: 'Verify',
+    feature: result.feature,
+    task: result.task ?? null,
+    scope: result.scope,
+    status: result.status,
+    sha,
+    fingerprint,
+    tree,
+    persisted,
+    reason: persisted ? null : (reason ?? null),
+    nodes,
+  };
+}
+
+/**
+ * The last complete run of the same verify (feature, task, scope) 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, task: string|null, scope: string, fingerprint: string|null }} run
+ * @returns {{ ts: string, status: string, sha: string|null }|null}
+ */
+export function findRepeatedVerify(projectPath, { feature, task, scope, fingerprint }) {
+  if (!fingerprint) return null;
+  const events = readTelemetryEvents(projectPath);
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i];
+    if (e.event !== 'Verify' || e.feature !== feature || e.scope !== scope || (e.task ?? null) !== (task ?? null)) continue;
+    if (e.persisted === false) continue;
+    return e.fingerprint === fingerprint ? { ts: e.ts, status: e.status, sha: e.sha ?? null } : null;
+  }
+  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
+ */
+export function recordVerifyEvent(projectPath, event) {
+  if (!existsSync(join(projectPath, '.morph'))) return;
+  appendTelemetryEvent(event, projectPath);
+}

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

@@ -0,0 +1,172 @@
+/**
+ * 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).
+ *
+ * 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
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+import { addedLinesAgainst, detectDefaultBranch } from '../../git/default-branch.js';
+import { resolveBaseRef } from '../../git/branch-classifier.js';
+import { isProjectSource, isTestFile } from '../reuse/symbol-scanner.js';
+import { citesProcess, commentLines } from './comment-scanner.js';
+
+/** Razão teste ÷ produção acima da qual se avisa. */
+export const MAX_TEST_RATIO = 1.5;
+
+/** 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;
+
+/** Quantos locais citar no aviso de comentário antes de resumir com "(+N)". */
+const MAX_CITED = 4;
+
+/** Código gerado não é escrito por ninguém, então não entra em nenhum dos lados. */
+const GENERATED = /(?:\.Designer|\.g|\.g\.i)\.cs$|ModelSnapshot\.cs$/i;
+
+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}}
+ */
+export function measureCodeBudget(files) {
+  const measured = { commentLines: 0, processLines: [], testLines: 0, productionLines: 0 };
+
+  for (const { path, content, added } of files) {
+    if (!isProjectSource(path) || GENERATED.test(path)) continue;
+    const addedSet = added ? new Set(added) : null;
+    const isAdded = (n) => addedSet === null || addedSet.has(n);
+
+    const nonBlank = String(content).split('\n')
+      .filter((row, i) => isAdded(i + 1) && row.trim()).length;
+    if (isTestFile(path)) measured.testLines += nonBlank;
+    else measured.productionLines += nonBlank;
+
+    for (const [line, text] of commentLines(content, path)) {
+      if (!isAdded(line)) continue;
+      measured.commentLines++;
+      if (citesProcess(text)) measured.processLines.push({ file: path, line, text });
+    }
+  }
+
+  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 } = measured;
+
+  if (processLines.length > 0) {
+    const shown = processLines.slice(0, MAX_CITED).map((p) => `${p.file}:${p.line}`);
+    const more = processLines.length - shown.length;
+    issues.push({
+      level: 'warning',
+      message:
+        `${processLines.length} de ${comments} linhas de comentário adicionadas citam processo ` +
+        `(UC, ADR, T{n}, FR, Gate, spec.md, mockup): ${shown.join(', ')}${more > 0 ? ` (+${more})` : ''}`,
+      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 ' +
+        'ele não mostra (standard architecture-code-comments).',
+    });
+  }
+
+  if (testLines > MIN_TEST_LINES && testLines > MAX_TEST_RATIO * productionLines) {
+    const ratio = productionLines > 0 ? ` (${decimal(testLines / productionLines)}×)` : '';
+    issues.push({
+      level: 'warning',
+      message:
+        `linhas de teste adicionadas passam de ${decimal(MAX_TEST_RATIO)}× as de produção: ` +
+        `${testLines} de teste para ${productionLines} de produção${ratio}`,
+      solution:
+        'Orçamento por task: um teste por pós-condição + um de regressão por bug, cenários do mesmo ' +
+        'comportamento numa tabela, nenhum teste que só fixa texto. Excesso justificado fica escrito na task.',
+    });
+  }
+
+  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: [] };
+
+  try {
+    const added = options.addedLines
+      ?? addedLinesAgainst(resolveBaseRef(detectDefaultBranch(projectPath), projectPath), projectPath);
+    if (!added) {
+      result._skipReason = 'sem base git para medir o que a feature adicionou';
+      result._skipUnavailable = true;
+      return result;
+    }
+
+    const files = [];
+    // Todo path do diff existe no disco; um que não se lê é medida faltando, e isso se diz.
+    const unreadable = [];
+    for (const [path, lines] of added) {
+      if (!isProjectSource(path)) continue;
+      try {
+        files.push({ path, content: readFileSync(join(projectPath, path), 'utf8'), added: lines });
+      } catch {
+        unreadable.push(path);
+      }
+    }
+    const named = unreadable.slice(0, MAX_CITED).join(', ') +
+      (unreadable.length > MAX_CITED ? ` (+${unreadable.length - MAX_CITED})` : '');
+
+    const measured = measureCodeBudget(files);
+    if (measured.testLines + measured.productionLines === 0) {
+      result._skipReason = unreadable.length > 0
+        ? `nenhum arquivo adicionado pôde ser lido (${named})`
+        : 'nenhuma linha de código adicionada nesta árvore';
+      if (unreadable.length > 0) result._skipUnavailable = true;
+      return result;
+    }
+
+    result.issues = budgetIssues(measured);
+    if (unreadable.length > 0) {
+      result.issues.push({
+        level: 'warning',
+        message: `${unreadable.length} arquivo(s) adicionado(s) não puderam ser lidos, a medida é parcial: ${named}`,
+        solution: 'Confira se o verify roda na raiz do projeto e se os arquivos têm permissão de leitura.',
+      });
+    }
+    result.warnings = result.issues.length;
+  } catch (err) {
+    result.issues = [];
+    result.warnings = 0;
+    result._skipReason = `medição indisponível: ${err.message}`;
+    result._skipUnavailable = true;
+  }
+
+  return result;
+}

package/src/lib/validators/code-budget/comment-scanner.js

@@ -0,0 +1,75 @@
+/**
+ * Linhas de comentário de um arquivo e se elas contam história de processo.
+ *
+ * O comentário é o que `stripComments` apaga: o mesmo varredor que já separa
+ * comentário de string para o `doctor --ai`, com a sintaxe de TS/JS ligada
+ * fora do C#. Um regex por linha confundiria `https://` com comentário.
+ *
+ * @module code-budget-comment-scanner
+ */
+
+import { stripComments } from '../../ai/comment-stripper.js';
+
+/** Vocabulário de processo do morph-spec, fora o id de task (abaixo). */
+const PROCESS_CITATION = [
+  /\bUC[-\s]?\d+/,
+  /\bADR[-\s]?\d+/,
+  /\bFR[-\s]?\d+/,
+  /\bgate\s?[1-3]\b/i,
+  /\b(?:spec|mandate)\.md\b/i,
+  /\bmockups?\b/i,
+];
+
+/**
+ * `T{n}` também é nome de parâmetro genérico. Não casa depois de `template`/
+ * `typename`/`generic`, nem colado a letra ou dígito (a hora ISO `24T10`).
+ */
+const TASK_ID = /(?<!\b(?:[Tt]emplate|[Tt]ypename|[Gg]eneric)\s+)(?<![\w"])T\d{1,3}\b(?!")/;
+
+/** Lista de tipos `<…>` e `{…}` (`Func<T1, T2>`, `cref="Func{T1,T2}"`, XML doc), de dentro para fora. */
+const TYPE_LIST = /<[^<>]*>|\{[^{}]*\}/g;
+
+function withoutTypeLists(text) {
+  let previous;
+  let current = text;
+  do {
+    previous = current;
+    current = current.replace(TYPE_LIST, ' ');
+  } while (current !== previous);
+  return current;
+}
+
+/**
+ * @param {string} commentText
+ * @returns {boolean} o comentário usa o vocabulário de processo acima
+ */
+export function citesProcess(commentText) {
+  return PROCESS_CITATION.some((re) => re.test(commentText))
+    || TASK_ID.test(withoutTypeLists(commentText));
+}
+
+/**
+ * @param {string} content - conteúdo do arquivo
+ * @param {string} file - path, só para escolher a sintaxe
+ * @returns {Map<number, string>} nº da linha (1-based) → texto do comentário nela
+ */
+export function commentLines(content, file) {
+  const text = String(content || '');
+  const stripped = stripComments(text, { js: !/\.cs$/i.test(file) });
+  const out = new Map();
+  let start = 0;
+  text.split('\n').forEach((row, index) => {
+    let first = -1;
+    let last = -1;
+    for (let k = 0; k < row.length; k++) {
+      if (stripped[start + k] === row[k]) continue;
+      if (first < 0) first = k;
+      last = k;
+    }
+    // O espaço dentro do comentário não muda ao ser apagado; o trecho vai do
+    // primeiro ao último caractere apagado.
+    if (first >= 0) out.set(index + 1, row.slice(first, last + 1).trim());
+    start += row.length + 1;
+  });
+  return out;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 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 './comment-scanner.js';

package/src/lib/validators/reuse/reuse-validator.js

@@ -114,8 +114,8 @@ export function findDuplicateSymbols(declarations, existing, opts = {}) {
     const language = languageOf(decls[0].file);
 
     // Onde mais esse nome vive: no grafo (código que já existia) e nos OUTROS
-    // arquivos desta mesma leva (código novo que o grafo ainda não viu — o
-    // rebuild é assíncrono, e é exatamente o caso SimpleBuilding).
+    // arquivos desta mesma leva (código novo que o grafo ainda não viu — ele
+    // só é refeito depois do commit, e é exatamente o caso SimpleBuilding).
     const fromGraph = (existing.get(key) ?? []).filter(
       (e) => e.language === language && !declaredFiles.has(e.file),
     );
@@ -280,6 +280,8 @@ export async function validateReuse(projectPath, featureName = null, options = {
     // segue em frente. Um validador que reprovasse aqui transformaria uma
     // dependência opcional em pré-requisito.
     result._skipReason = 'sem grafo de codebase — `morph-spec graph build` habilita esta verificação';
+    // "Could not check", unlike "nothing to check": verify reports it aloud.
+    result._skipUnavailable = true;
     return result;
   }