@orchestrator-claude/definitions 3.37.0 → 3.37.2

package/hooks/lib/dispatch-marker.ts

@@ -0,0 +1,214 @@
+/**
+ * dispatch-marker.ts — boundary marker per git ref (S445, RFC-042).
+ *
+ * WHAT THIS IS. At the instant a committing agent is dispatched, record WHERE
+ * HEAD WAS, as a git ref pointing at the full 40-hex sha. That is the whole
+ * feature: a COORDINATE for "the state before this agent started".
+ *
+ * WHAT THIS IS NOT, deliberately. It does not restore anything. RFC-042 settled
+ * that a checkpoint is an AUDIT MARK (D1) and is EXPLICIT (D2); asked whether a
+ * restore path was wanted, the answer was that rollback has been needed only a
+ * few times and plain git handled it. So rollback stays plain git:
+ *
+ *     git reset --hard <ref>
+ *
+ * No restore code lives here. An unused restore path is precisely how the
+ * existing checkpoint subsystem accumulated four independent breaks (see the
+ * checkpoint-protocol skill) — a coordinate that git can consume cannot rot the
+ * same way, because git is the thing that consumes it.
+ *
+ * IT DOES NOT CREATE A COMMIT AND DOES NOT TOUCH THE WORKING TREE. A ref is git
+ * metadata: writing one leaves `git status` byte-identical. That is what lets
+ * this coexist with the S445 rule that ordinary machine operation must never
+ * write a git-tracked file.
+ *
+ * THE COLON TRAP (the reason sanitization is a requirement, not a nicety).
+ * Under plugin scope agents are named `orchestrator:implementer`. A git ref name
+ * may not contain a colon (nor space, tilde, caret, question mark, asterisk,
+ * open bracket, backslash, or a double dot). Passing a raw agent name through
+ * would make `update-ref` fail — and since the calling hook is fail-open, it
+ * would fail SILENTLY, leaving the whole feature a green no-op for exactly the
+ * agents that can commit. Hence sanitizeRefComponent, and hence a test that
+ * validates the output with git's own `check-ref-format`.
+ *
+ * RETENTION. Refs are GC roots, so markers would accumulate forever and we would
+ * have traded collectable orphan objects for uncollectable refs. Hence a cap.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Namespace for dispatch boundary markers. Verified free before adoption:
+ * `git for-each-ref refs/orchestrator/` returned 0 refs. The 6 pre-existing
+ * `orchestrator/*` TAGS live under `refs/tags/orchestrator/`, which is a
+ * DIFFERENT namespace — these markers do not collide with them, and are not
+ * tags (a tag is a published, human-meaningful mark; this is machine bookkeeping
+ * with a retention cap).
+ */
+export const DISPATCH_MARKER_REF_PREFIX = 'refs/orchestrator/dispatch';
+
+/**
+ * Maximum markers retained PER KEY (per branch — see writeDispatchBoundaryMarker
+ * for why branch and not workflow). Oldest are pruned once the cap is exceeded.
+ *
+ * WHY A CAP EXISTS AT ALL: a git ref is a GC ROOT. Every marker pins the commit
+ * it points at, so without pruning these would accumulate without bound and
+ * would keep otherwise-unreachable objects alive forever — trading collectable
+ * orphans for uncollectable refs, which is a worse deal than the problem being
+ * solved. 20 is deliberately small: markers are a rollback coordinate for RECENT
+ * work, and a coordinate 20 dispatches old has been superseded by ordinary
+ * commits and branches. Raise it only against a measured need.
+ */
+export const MAX_DISPATCH_MARKERS_PER_KEY = 20;
+
+/** Fallback when an input sanitizes down to nothing. */
+const EMPTY_COMPONENT_PLACEHOLDER = 'unknown';
+
+/**
+ * Reduces arbitrary text to a single ref-name component that git accepts.
+ *
+ * The allowlist is deliberately narrower than git's own rules rather than a
+ * blocklist of forbidden characters. Permitting only [A-Za-z0-9_-] makes whole
+ * FAMILIES of git's restrictions unreachable instead of individually handled:
+ * dropping '.' rules out a leading dot, a trailing dot, a '..' sequence and a
+ * '.lock' suffix at once; dropping '@' and '{' rules out '@{' and the lone '@'.
+ * A blocklist would have to enumerate each rule correctly and stay correct as
+ * git evolves; this cannot fail open by omission.
+ */
+export function sanitizeRefComponent(raw: string): string {
+  const cleaned = (raw || '')
+    .replace(/[^A-Za-z0-9_-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  return cleaned || EMPTY_COMPONENT_PLACEHOLDER;
+}
+
+/**
+ * Compact UTC stamp, e.g. `20260804T142439123Z`. Colons are stripped because a
+ * plain ISO-8601 string (`2026-08-04T14:24:39.123Z`) is an INVALID ref name for
+ * the very same reason the agent name is. Fixed width and zero-padded, so
+ * lexicographic ref order equals chronological order — which is what makes
+ * "prune the oldest" a plain sort.
+ */
+export function formatMarkerStamp(d: Date): string {
+  return d.toISOString().replace(/[-:.]/g, '');
+}
+
+/** `refs/orchestrator/dispatch/<branch>/<stamp>-<agent>`. */
+export function buildMarkerRefName(branch: string, agent: string, stamp: string): string {
+  const branchPart = sanitizeRefComponent(branch);
+  const agentPart = sanitizeRefComponent(agent);
+  const stampPart = sanitizeRefComponent(stamp);
+
+  return `${DISPATCH_MARKER_REF_PREFIX}/${branchPart}/${stampPart}-${agentPart}`;
+}
+
+export type DispatchMarkerOutcome =
+  | { status: 'written'; ref: string; sha: string; pruned: string[] }
+  | { status: 'failed'; reason: string };
+
+export interface DispatchMarkerDeps {
+  /** Runs git and returns stdout. MUST throw on non-zero exit. */
+  runGit: (args: string[]) => string;
+  /** Injectable clock (tests need deterministic, ordered stamps). */
+  now?: () => Date;
+}
+
+/** Production git runner: fixed argv, no shell, so no interpolation surface. */
+export function runGitDefault(args: string[]): string {
+  return execFileSync('git', args, {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+/**
+ * Removes the oldest markers under `prefix` until at most `cap` remain.
+ * Lexicographic ref order is chronological (see formatMarkerStamp).
+ */
+function pruneOldestMarkers(prefix: string, cap: number, deps: DispatchMarkerDeps): string[] {
+  const listed = deps
+    .runGit(['for-each-ref', '--format=%(refname)', '--sort=refname', `${prefix}/`])
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+
+  const excess = listed.length - cap;
+  if (excess <= 0) return [];
+
+  const doomed = listed.slice(0, excess);
+  for (const ref of doomed) {
+    deps.runGit(['update-ref', '-d', ref]);
+  }
+  return doomed;
+}
+
+/**
+ * Writes the boundary marker for `agentName` on `branch`.
+ *
+ * RETENTION KEY IS THE BRANCH, NOT THE WORKFLOW — a deliberate substitution,
+ * reported as such. The workflow id is only obtainable here through an async API
+ * call, which would make the marker ABSENT precisely when the system is degraded
+ * (API down) — the opposite of what a rollback coordinate is for. The branch is
+ * already in hand locally and needs no network. It is also the better key on the
+ * merits: `git reset --hard` is a branch-scoped operation, so grouping markers by
+ * branch matches the unit they would be consumed at.
+ *
+ * FAIL-OPEN IN EVERY DIMENSION: git missing, no commits yet, a ref-name that
+ * somehow still fails validation, a broken prune — all return a `failed` outcome.
+ * This function NEVER throws, so it can never block or delay a dispatch. It is
+ * fail-open but NOT silent: it returns the reason, and the caller surfaces it.
+ */
+export function writeDispatchBoundaryMarker(
+  agentName: string,
+  branch: string,
+  deps: DispatchMarkerDeps
+): DispatchMarkerOutcome {
+  let ref = '';
+  try {
+    // An agent name that sanitizes to nothing yields a marker nobody can
+    // attribute — litter that consumes the retention cap rather than a usable
+    // coordinate. NOT a hypothetical guard: a `...-unknown` ref was written into
+    // the real repository during S445's negative-control run, because this hook's
+    // entry module executes on import (top-level `main().catch()`) and therefore
+    // ran with production deps and an empty stdin. The caller gates on
+    // isCommittingAgent, so this never fires in production — it is the backstop
+    // for the paths that bypass that gate.
+    if (sanitizeRefComponent(agentName) === EMPTY_COMPONENT_PLACEHOLDER) {
+      return {
+        status: 'failed',
+        reason: `refusing to write an unattributable marker (agent name "${agentName}")`,
+      };
+    }
+
+    const sha = deps.runGit(['rev-parse', 'HEAD']).trim();
+    if (!/^[0-9a-f]{40}$/.test(sha)) {
+      return { status: 'failed', reason: `HEAD did not resolve to a 40-hex sha (got "${sha}")` };
+    }
+
+    const stamp = formatMarkerStamp((deps.now ?? (() => new Date()))());
+    ref = buildMarkerRefName(branch, agentName, stamp);
+
+    deps.runGit(['update-ref', ref, sha]);
+
+    // The marker now exists. Pruning is best-effort bookkeeping ON TOP of a
+    // successful write — a prune failure must never downgrade the outcome, or a
+    // full namespace would start reporting failure for markers that were in fact
+    // written.
+    let pruned: string[] = [];
+    try {
+      pruned = pruneOldestMarkers(
+        `${DISPATCH_MARKER_REF_PREFIX}/${sanitizeRefComponent(branch)}`,
+        MAX_DISPATCH_MARKERS_PER_KEY,
+        deps
+      );
+    } catch {
+      pruned = [];
+    }
+
+    return { status: 'written', ref, sha, pruned };
+  } catch (err) {
+    return { status: 'failed', reason: `${ref ? `ref="${ref}" ` : ''}${String(err)}` };
+  }
+}

package/hooks/lib/git-checkpoint.ts

@@ -3,7 +3,6 @@
  * Replaces post-phase-checkpoint.sh git logic.
  */
 
-import { execSync } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -24,22 +23,33 @@ function getCompletedPhase(currentPhase: string): string | null {
   return idx > 0 ? (PHASE_ORDER[idx - 1] ?? null) : null;
 }
 
-function exec(cmd: string): string {
-  return execSync(cmd, { cwd: PROJECT_ROOT, encoding: 'utf-8' }).trim();
-}
-
 /**
- * Create a git checkpoint if the phase changed and there are staged changes.
- * Returns the commit hash or null.
+ * Register a checkpoint (PostgreSQL side only) if the phase changed since the
+ * last checkpointed phase.
+ *
+ * TD-257 (S444): this function used to also stage and commit the working
+ * tree (`git add -A` + `git commit --no-verify`, unattended, on every phase
+ * transition). That was DISARMED after measurement — the decision was made
+ * by the user from data, not opinion: 212 such commits by subject over 7
+ * months, 145/212 (68%) pure machine-noise, 42/212 (20%) MIXED (real work
+ * buried alongside noise), one of which (`01c28adf`) deleted 1627 lines
+ * including `EvaluatePhaseGateUseCase.ts` and 3 suites under the message
+ * "Auto-checkpoint after tasks phase" — with zero restores in that window,
+ * and no production caller for `CheckpointManager.restore()` at all. The
+ * separate, deliberate `createCheckpoint` MCP tool (`CheckpointManager.ts`,
+ * `GitOperations.ts`) is UNAFFECTED by this change — it is named, tagged,
+ * and stays. Returns `true` when a checkpoint was registered for a newly
+ * completed phase, `false` otherwise (no completed phase, already
+ * checkpointed, or the registration call failed).
  */
 export async function createCheckpointIfNeeded(
   workflowId: string,
   currentPhase: string
-): Promise<string | null> {
+): Promise<boolean> {
   const completedPhase = getCompletedPhase(currentPhase);
   if (!completedPhase) {
     log('CHECKPOINT', `No completed phase from: ${currentPhase}`);
-    return null;
+    return false;
   }
 
   // Check if already checkpointed
@@ -51,41 +61,28 @@ export async function createCheckpointIfNeeded(
   }
   if (lastPhase === completedPhase) {
     log('CHECKPOINT', `Already checkpointed: ${completedPhase}`);
-    return null;
+    return false;
   }
 
   try {
-    // Stage all changes
-    exec('git add -A');
-
-    // Check if there are staged changes
-    try {
-      exec('git diff --cached --quiet');
-      // No changes
-      log('CHECKPOINT', `No changes for phase: ${completedPhase}`);
-      writeFileSync(LAST_PHASE_FILE, completedPhase);
-      return null;
-    } catch {
-      // Has changes — good, proceed to commit
-    }
-
-    const commitMsg = `[orchestrator] ${completedPhase}: Auto-checkpoint after ${completedPhase} phase`;
-    exec(`git commit -m "${commitMsg}" --no-verify`);
-    const commitHash = exec('git rev-parse HEAD');
-
-    log('CHECKPOINT', `Created: phase=${completedPhase} commit=${commitHash}`);
+    log('CHECKPOINT', `Registering checkpoint for phase: ${completedPhase}`);
 
-    // Register via API
-    await registerCheckpoint(
-      workflowId,
-      `Auto-checkpoint after ${completedPhase} phase`,
-      commitHash
-    );
+    // TD-257: no commit is made anymore, so there is no real hash to report.
+    // registerCheckpoint's `commitHash` parameter is still required by its
+    // signature (out of this task's scope to change — see implementation
+    // report) — '' is the honest value ("no commit exists"), not an invented
+    // placeholder: it mirrors how the separate createCheckpoint MCP tool path
+    // already reports "no commit" as `gitCommit: undefined`
+    // (CreateCheckpointHandler.ts) when there is nothing to point to, and the
+    // field is unused server-side regardless — CreateCheckpointBodySchema
+    // (checkpoints.schemas.ts) has no commitHash field at all, and the route
+    // handler (checkpoints.routes.ts) never reads it off the request body.
+    await registerCheckpoint(workflowId, `Auto-checkpoint after ${completedPhase} phase`, '');
 
     writeFileSync(LAST_PHASE_FILE, completedPhase);
-    return commitHash;
+    return true;
   } catch (err) {
     log('CHECKPOINT', `Error: ${err}`);
-    return null;
+    return false;
   }
 }

package/hooks/lib/observations-helper.ts

@@ -4,11 +4,22 @@
  * Provides types and helper to write observations.yaml files.
  * Used by subagent-stop.ts to record what each sub-agent observed.
  * All functions are fail-open: errors logged to stderr, never thrown.
+ *
+ * TD-214/TD-239 TASK-003 (RF-004): `agent` is normalized via
+ * `normalizeAgentName` BEFORE it is used to build `agentDir`. Under plugin
+ * scope the harness namespaces dispatch names (`orchestrator:reviewer`); in
+ * project scope the same agent arrives bare (`reviewer`). Without this,
+ * the two scopes silently fork into two different observations.yaml
+ * directories for the SAME agent. `data.agent` (the field written INSIDE the
+ * YAML) intentionally keeps the raw, un-normalized input — only the
+ * directory-path use is normalized — so the file still records exactly what
+ * the harness sent, for audit purposes.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { normalizeAgentName } from './api-client.js';
 
 // ─── Types ───────────────────────────────────────────────
 
@@ -47,7 +58,9 @@ export function appendObservation(
   entry: Omit<ObservationEntry, 'promoted'>
 ): void {
   try {
-    const agentDir = join(memoryDir, agent);
+    // TD-214/TD-239 TASK-003: normalize BEFORE building the directory path —
+    // see module doc for why (plugin-scope vs project-scope namespacing).
+    const agentDir = join(memoryDir, normalizeAgentName(agent));
     const filePath = join(agentDir, 'observations.yaml');
 
     // Ensure directory exists

package/hooks/lib/security-gate-core.ts

@@ -0,0 +1,271 @@
+/**
+ * security-gate-core.ts — lógica PURA do gate honesto de commit (S505, ficha 3).
+ *
+ * Separado de `security-gate-honest.ts` de propósito: aquele arquivo tem um
+ * `main()` de topo que aguarda stdin, e importá-lo num teste trava o runner.
+ * A convenção anterior desta casa contornava isso RE-IMPLEMENTANDO a lógica
+ * dentro do teste (ver `tests/unit/hooks/post-implement.test.ts`), o que
+ * duplica a regra e deixa as duas cópias divergirem em silêncio — a família
+ * TD-232 que este repo persegue. Extrair o núcleo resolve os dois problemas:
+ * o teste importa o que RODA, e não uma cópia dele.
+ *
+ * Nada aqui faz IO. O `git show` e a saída do hook ficam no arquivo do hook.
+ */
+
+/** Abaixo disto, um veredito de L2 é fallback disfarçado, não análise. */
+export const L2_LATENCY_FLOOR_MS = 400;
+
+/** O que a L1 cobre — declarado, porque cobertura não-dita vira cobertura presumida. */
+export const L1_COVERAGE =
+  'literais de credencial no diff (chaves de provedor, tokens, blocos PEM, URLs com senha)';
+
+export type Verdict =
+  | { state: 'clean'; layer: string; detail: string }
+  | { state: 'findings'; layer: string; detail: string; hits: Finding[] }
+  | { state: 'not-analyzed'; layer: string; reason: string };
+
+export interface Finding {
+  rule: string;
+  file: string;
+  line: number;
+  evidence: string;
+}
+
+// ─────────────────────────────────────────────────────────────
+// L1 — padrões. Estreitos de propósito: cada regra que dispara
+// falso positivo em massa treina quem lê a ignorar, e um gate
+// ignorado é um gate desligado com aparência de ligado.
+// ─────────────────────────────────────────────────────────────
+export const SECRET_RULES: { rule: string; re: RegExp }[] = [
+  { rule: 'aws-access-key-id', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { rule: 'anthropic-api-key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
+  { rule: 'openai-api-key', re: /\bsk-(?:proj-)?[A-Za-z0-9]{32,}\b/ },
+  { rule: 'github-token', re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+  { rule: 'slack-token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/ },
+  { rule: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { rule: 'npm-token', re: /\bnpm_[A-Za-z0-9]{36}\b/ },
+  { rule: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { rule: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+  { rule: 'url-with-password', re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:[^\s:@/]{6,}@/i },
+];
+
+/**
+ * Marcas que indicam placeholder e não segredo real. Sem isto o gate grita em
+ * cima do `.env.example` e ensina o leitor a ignorá-lo.
+ */
+const PLACEHOLDER =
+  /(?:x{6,}|\.{3,}|<[^>]{2,}>|\$\{|EXAMPLE|PLACEHOLDER|YOUR_|CHANGEME|REDACTED|FAKE|DUMMY|\bTODO\b)/i;
+
+/** Mascara a evidência: o gate não pode ser o veículo que vaza o segredo que achou. */
+export function maskEvidence(s: string): string {
+  const t = s.trim().slice(0, 80);
+  return t.length <= 12 ? '***' : `${t.slice(0, 6)}…${t.slice(-4)} (${String(t.length)} ch)`;
+}
+
+/**
+ * Varre um diff unificado. Só linhas ADICIONADAS (`+`) — uma linha removida
+ * já está no histórico e culpar o commit que a REMOVE inverte o sinal.
+ */
+export function scanDiff(diff: string): Finding[] {
+  const out: Finding[] = [];
+  let file = '(desconhecido)';
+  let lineNo = 0;
+
+  for (const raw of diff.split('\n')) {
+    if (raw.startsWith('+++ b/')) {
+      file = raw.slice(6);
+      lineNo = 0;
+      continue;
+    }
+    if (raw.startsWith('@@')) {
+      const m = /\+(\d+)/.exec(raw);
+      lineNo = m ? parseInt(m[1], 10) - 1 : 0;
+      continue;
+    }
+    if (!raw.startsWith('+') || raw.startsWith('+++')) continue;
+    lineNo += 1;
+
+    const content = raw.slice(1);
+    if (PLACEHOLDER.test(content)) continue;
+
+    for (const { rule, re } of SECRET_RULES) {
+      const hit = re.exec(content);
+      if (hit) out.push({ rule, file, line: lineNo, evidence: maskEvidence(hit[0]) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Detecta `git commit` — e NÃO `git commit --dry-run`, que não cria commit.
+ *
+ * Aceita opções globais com valor separado (`git -c user.name=x commit`), que a
+ * primeira versão desta função deixava passar: o `-c` consome o traço, mas o
+ * `user.name=x` seguinte não, e o `commit` deixava de casar. Pego por teste.
+ *
+ * LIMITAÇÃO CONHECIDA, declarada em vez de escondida: isto é casamento de
+ * texto, não parsing de shell. Um comando que apenas CONTENHA a frase
+ * (`ls "git commit"`) dispara o gate, que então descreve o HEAD corrente — um
+ * commit que não é daquele comando. É ruído, não risco: toda saída nomeia o que
+ * analisou, então o leitor vê sobre o que o veredito fala. Parsear shell de
+ * verdade custa mais do que o defeito que evita.
+ */
+export function isCommitCommand(command: string): boolean {
+  return /git\s+(?:-\S+(?:\s+\S+)?\s+)*commit\b/.test(command) && !/--dry-run\b/.test(command);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Núcleo
+// ─────────────────────────────────────────────────────────────
+
+/** O diff mais a declaração de COMO foi obtido — cobertura não-dita vira cobertura presumida. */
+export interface DiffSource {
+  text: string;
+  /** Ex.: "git show HEAD" · "git show -m --first-parent HEAD (merge de 2 pais)". */
+  how: string;
+}
+
+export interface GateDeps {
+  getDiff: () => DiffSource;
+  /** L2 devolve null enquanto não houver credencial decidida (ficha 3, item d). */
+  runSemantic: (diff: string) => { hits: Finding[]; elapsedMs: number } | null;
+  l2UnavailableReason: () => string;
+}
+
+export function evaluate(deps: GateDeps): Verdict[] {
+  const verdicts: Verdict[] = [];
+
+  let src: DiffSource;
+  try {
+    src = deps.getDiff();
+  } catch (e) {
+    // A falha de leitura do diff é NÃO ANALISEI para TODAS as camadas.
+    // Este é o ponto exato em que o plugin medido diria "limpo".
+    const reason = `não consegui ler o diff do commit (${(e as Error).message.slice(0, 80)})`;
+    return [
+      { state: 'not-analyzed', layer: 'L1', reason },
+      { state: 'not-analyzed', layer: 'L2', reason },
+    ];
+  }
+
+  const diff = src.text;
+  if (!diff.trim()) {
+    // Distinguir POR QUE veio vazio: um merge sem conflito e um `git show` que
+    // falhou pedem leituras diferentes, e medida que não separa estados que
+    // pedem ações diferentes é medida errada (regra de desenho da S480).
+    const reason =
+      `o diff veio vazio via ${src.how} — nada para analisar. ` + 'Isto NÃO é o mesmo que limpo';
+    return [
+      { state: 'not-analyzed', layer: 'L1', reason },
+      { state: 'not-analyzed', layer: 'L2', reason },
+    ];
+  }
+
+  // ── L1 ──
+  const hits = scanDiff(diff);
+  const cover = `${L1_COVERAGE} · via ${src.how}`;
+  verdicts.push(
+    hits.length
+      ? { state: 'findings', layer: 'L1', detail: cover, hits }
+      : { state: 'clean', layer: 'L1', detail: cover }
+  );
+
+  // ── L2 ──
+  const sem = deps.runSemantic(diff);
+  if (sem === null) {
+    verdicts.push({ state: 'not-analyzed', layer: 'L2', reason: deps.l2UnavailableReason() });
+  } else if (sem.elapsedMs < L2_LATENCY_FLOOR_MS) {
+    // A guarda de latência. Não confia no veredito: análise semântica de um
+    // diff não fecha nesse tempo, então isto é fallback, não resultado.
+    verdicts.push({
+      state: 'not-analyzed',
+      layer: 'L2',
+      reason:
+        `devolveu veredito em ${String(sem.elapsedMs)} ms, abaixo do piso de ${String(L2_LATENCY_FLOOR_MS)} ms — ` +
+        'tratado como fallback, não como análise',
+    });
+  } else {
+    verdicts.push(
+      sem.hits.length
+        ? { state: 'findings', layer: 'L2', detail: 'análise semântica', hits: sem.hits }
+        : { state: 'clean', layer: 'L2', detail: 'análise semântica' }
+    );
+  }
+
+  return verdicts;
+}
+
+/**
+ * A linha ÚNICA que o humano vê (`systemMessage`), contra o texto por camada que
+ * só chega ao modelo (`additionalContext`).
+ *
+ * Achado do Manager na S505, e é o coração da ficha: **falhar alto significa a
+ * PESSOA ver.** Um gate cujo aviso só alcança o modelo tem o mesmo efeito
+ * prático do plugin que ele substitui — ninguém é avisado. Por isso a saída sai
+ * pelos dois canais.
+ *
+ * Reporta o PIOR estado, porque é o único que muda o que a pessoa faz agora:
+ * achados > nada analisado > cobertura parcial > tudo analisado e limpo.
+ */
+export function renderShort(verdicts: Verdict[]): string {
+  const findings = verdicts.filter((v) => v.state === 'findings');
+  if (findings.length) {
+    const n = findings.reduce((a, v) => a + (v.state === 'findings' ? v.hits.length : 0), 0);
+    const layers = findings.map((v) => v.layer).join('+');
+    return `SECURITY-GATE: ${String(n)} achado(s) em ${layers} — confira antes de publicar`;
+  }
+
+  const analyzed = verdicts.filter((v) => v.state !== 'not-analyzed').map((v) => v.layer);
+  const skipped = verdicts.filter((v) => v.state === 'not-analyzed').map((v) => v.layer);
+
+  if (!analyzed.length) {
+    return 'SECURITY-GATE: NENHUMA camada analisou o commit — isto NÃO é "limpo", é ausência de análise';
+  }
+  if (skipped.length) {
+    return `SECURITY-GATE: cobertura PARCIAL — ${analyzed.join('+')} analisou, ${skipped.join('+')} não`;
+  }
+  return `SECURITY-GATE: ${analyzed.join('+')} analisou, sem achados`;
+}
+
+/**
+ * Renderiza. Nunca produz a frase "no security issues found" nem equivalente
+ * global: o veredito é sempre por camada, sempre com a cobertura ao lado.
+ */
+export function render(verdicts: Verdict[]): string {
+  const lines = ['[SECURITY-GATE] Revisão do commit — veredito por camada:'];
+
+  for (const v of verdicts) {
+    if (v.state === 'clean') {
+      lines.push(`  ${v.layer} ANALISADO — LIMPO · cobertura: ${v.detail}`);
+    } else if (v.state === 'findings') {
+      lines.push(
+        `  ${v.layer} ANALISADO — ${String(v.hits.length)} ACHADO(S) · cobertura: ${v.detail}`
+      );
+      for (const h of v.hits.slice(0, 10)) {
+        lines.push(`      ${h.rule} · ${h.file}:${String(h.line)} · ${h.evidence}`);
+      }
+      if (v.hits.length > 10) lines.push(`      … e mais ${String(v.hits.length - 10)}`);
+    } else {
+      lines.push(`  ${v.layer} NÃO ANALISEI — ${v.reason}`);
+    }
+  }
+
+  const analyzed = verdicts.filter((v) => v.state !== 'not-analyzed').map((v) => v.layer);
+  const skipped = verdicts.filter((v) => v.state === 'not-analyzed').map((v) => v.layer);
+
+  if (!analyzed.length) {
+    lines.push(
+      '  ⚠ NENHUMA camada analisou este commit. Isto NÃO é "limpo" — é ausência de informação.'
+    );
+  } else if (skipped.length) {
+    lines.push(
+      `  ⚠ Cobertura PARCIAL: ${analyzed.join('+')} rodou, ${skipped.join('+')} não. ` +
+        'O que não foi analisado não está limpo — está por analisar.'
+    );
+  }
+
+  if (verdicts.some((v) => v.state === 'findings')) {
+    lines.push('  → Confira antes de publicar. O commit local já existe; nada foi bloqueado.');
+  }
+  return lines.join('\n');
+}