@orchestrator-claude/definitions 3.37.0 → 3.37.2

package/hooks/pre-agent-dispatch.ts

@@ -1,7 +1,9 @@
 /**
  * pre-agent-dispatch.ts — PreToolUse hook for the Agent tool
  *
- * NON-BLOCKING (always exits 0; only injects advisory context). Two responsibilities:
+ * NON-BLOCKING (always exits 0; only injects advisory context). Four responsibilities
+ * (the count said "Two" while listing three, from S445 back to whenever the third was
+ * added — corrected here rather than left to drift a fourth time):
  *
  *  1. (RFC-027 Sprint 4) Warn when a known agent is dispatched WITHOUT subagent_type,
  *     so frontmatter (model/tools) loads correctly.
@@ -29,6 +31,15 @@
  *     Best-effort / fail-open in every dimension (missing deps, no active workflow,
  *     resolution timeout, filesystem error) — never blocks the dispatch.
  *
+ *  4. (S445, RFC-042) Boundary marker per ref. RFC-042 settled that a checkpoint is an
+ *     AUDIT MARK (D1) and is EXPLICIT (D2) — neither of which yields a coordinate for
+ *     "the state just before this agent started". This hook fires at the exact instant
+ *     of dispatch and already talks to git, so it records that coordinate: a ref under
+ *     `refs/orchestrator/` at HEAD's full 40-hex sha, for COMMITTING agents only.
+ *     It creates no commit, writes no file, and touches no database — a ref is git
+ *     metadata, so `git status` is unchanged. Rollback is deliberately NOT implemented:
+ *     it is plain `git reset --hard <ref>`. See lib/dispatch-marker.ts.
+ *
  * Design note (TD-171): the committing-agent set mirrors the `createCheckpoint` tool
  * holders in `.claude/agents/*.md`. Keep it in sync with that ground truth and with the
  * orchestrator SKILL §2c.1 Commit-Policy scope.
@@ -42,7 +53,13 @@ import {
   outputContext,
   getActiveWorkflow,
   writeDispatchIntent,
+  normalizeAgentName,
 } from './lib/api-client.js';
+import {
+  writeDispatchBoundaryMarker,
+  runGitDefault,
+  type DispatchMarkerOutcome,
+} from './lib/dispatch-marker.js';
 
 const HOOK = 'PRE-AGENT-DISPATCH';
 
@@ -80,20 +97,6 @@ const PROTECTED_BRANCHES: readonly string[] = ['main', 'master'];
 // Pure helpers (exported for testing)
 // ─────────────────────────────────────────────────────────────
 
-/**
- * Strip the plugin namespace from a dispatch name.
- *
- * Under plugin scope the harness namespaces every agent (`orchestrator:implementer`
- * — measured in the S398 sandbox, RFC-040 §18.14); in project scope the same agent
- * arrives bare (`implementer`). A guard that compares against the bare name only
- * answers `false` for the namespaced form — and since hooks fail open, it disables
- * itself in silence. Both forms MUST resolve to the same decision.
- */
-export function normalizeAgentName(subagentType: string): string {
-  const i = subagentType.lastIndexOf(':');
-  return i === -1 ? subagentType : subagentType.slice(i + 1);
-}
-
 export function isCommittingAgent(subagentType: string): boolean {
   if (!subagentType) return false;
   const t = normalizeAgentName(subagentType).toLowerCase();
@@ -176,6 +179,13 @@ export interface HookDeps {
   getActiveWorkflow?: () => Promise<{ id: string } | null>;
   /** TD-205: stamps the dispatch-intent marker for workflowId. See getActiveWorkflow doc. */
   writeDispatchIntent?: (workflowId: string) => boolean;
+  /**
+   * S445 (RFC-042): records the git BOUNDARY MARKER for a committing agent —
+   * a ref at HEAD's full sha, so there is a coordinate to `git reset --hard`
+   * back to. Optional for the same reason as the TD-205 deps above: pre-S445
+   * test doubles must keep working, and an absent dep simply skips the marker.
+   */
+  writeDispatchMarker?: (agentName: string, branch: string) => DispatchMarkerOutcome;
 }
 
 function readBranchFromGit(): string {
@@ -197,6 +207,8 @@ const defaultDeps: HookDeps = {
   readBranch: readBranchFromGit,
   getActiveWorkflow,
   writeDispatchIntent,
+  writeDispatchMarker: (agentName, branch) =>
+    writeDispatchBoundaryMarker(agentName, branch, { runGit: runGitDefault }),
 };
 
 /**
@@ -240,6 +252,57 @@ export async function stampDispatchIntent(
   }
 }
 
+/**
+ * S445 (RFC-042): writes the git boundary marker for a COMMITTING agent, and
+ * returns an advisory line if it failed (empty array otherwise).
+ *
+ * ONLY committing agents get a marker. An agent that cannot commit cannot move
+ * HEAD, so a marker for it records a boundary nothing can cross — pure noise
+ * consuming the retention cap. This condition is the load-bearing one and is
+ * covered by an explicit negative control in the test suite.
+ *
+ * FAIL-OPEN BUT NOT SILENT. A marker failure must never block or delay the
+ * dispatch, so everything here is caught. But "fail-open" is not "invisible":
+ * the failure mode this feature must avoid is a GREEN VACUUM — the ref silently
+ * never being written (e.g. an invalid ref name) while everything looks fine. So
+ * a failure is reported on BOTH existing channels: the debug log AND the in-band
+ * advisory context the TD-171 branch warning already uses, which is the one a
+ * human or orchestrator actually reads.
+ */
+export function markDispatchBoundary(
+  subagentType: string,
+  branch: string,
+  deps: Pick<HookDeps, 'writeDispatchMarker' | 'log'>
+): string[] {
+  if (!deps.writeDispatchMarker) return [];
+  if (!isCommittingAgent(subagentType)) return [];
+
+  try {
+    const outcome = deps.writeDispatchMarker(subagentType, branch);
+
+    if (outcome.status === 'written') {
+      deps.log(HOOK, `[S445] boundary marker ${outcome.ref} -> ${outcome.sha}`);
+      if (outcome.pruned.length > 0) {
+        deps.log(HOOK, `[S445] pruned ${outcome.pruned.length} marker(s) over retention cap`);
+      }
+      return [];
+    }
+
+    deps.log(HOOK, `[S445] boundary marker FAILED: ${outcome.reason}`);
+    return [
+      `[BOUNDARY-MARKER][S445] Could not record the pre-dispatch git coordinate for ` +
+        `'${subagentType}' on '${branch}': ${outcome.reason}. The dispatch proceeds (this never ` +
+        `blocks), but there will be NO ref to 'git reset --hard' back to for this agent's work.`,
+    ];
+  } catch (err) {
+    deps.log(HOOK, `[S445] boundary marker threw (fail-open): ${String(err)}`);
+    return [
+      `[BOUNDARY-MARKER][S445] Boundary-marker step threw for '${subagentType}': ${String(err)}. ` +
+        `Dispatch proceeds; no rollback coordinate was recorded.`,
+    ];
+  }
+}
+
 // ─────────────────────────────────────────────────────────────
 // Core logic (exported for testing)
 // ─────────────────────────────────────────────────────────────
@@ -259,6 +322,10 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
 
   const warnings = evaluateDispatch({ subagentType, prompt, branch });
 
+  // S445: record the pre-dispatch git coordinate BEFORE the sub-agent spawns.
+  // Committing agents only; never blocks; a failure is surfaced, not swallowed.
+  warnings.push(...markDispatchBoundary(subagentType, branch, deps));
+
   // TD-205: stamp the dispatch-intent marker regardless of whether a warning
   // fires — a dispatch is happening either way, and the marker exists purely
   // to cover the bg-dispatch race for dangling-guard's Stop hook.

package/hooks/security-gate-honest.mjs

@@ -0,0 +1,302 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/lib/api-client.ts
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
+import { join as join2 } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+
+// ../project-root-resolver/dist/index.js
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+function hasProjectRootMarker(candidate, sentinel) {
+  return existsSync(join(candidate, ".git")) || existsSync(join(candidate, "package.json")) || existsSync(join(candidate, sentinel, ".root"));
+}
+function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  const candidates = [];
+  let currentDir = cwd;
+  for (; ; ) {
+    if (existsSync(join(currentDir, sentinel))) {
+      candidates.push(currentDir);
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  const [innermost] = candidates;
+  if (innermost === void 0) {
+    return null;
+  }
+  for (const candidate of candidates) {
+    if (hasProjectRootMarker(candidate, sentinel)) {
+      return candidate;
+    }
+  }
+  return innermost;
+}
+
+// hooks/lib/api-client.ts
+function resolveFallbackStateDir(cwd) {
+  const cwdHash = createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+  return join2(tmpdir(), "orchestrator-hook-fallback", cwdHash);
+}
+var PROJECT_ROOT = (() => {
+  const resolved = resolveHookProjectRoot(process.cwd());
+  if (resolved !== null && hasProjectRootMarker(resolved, ".orchestrator")) {
+    return resolved;
+  }
+  return null;
+})();
+var STATE_DIR_OVERRIDE = process.env.ORCHESTRATOR_STATE_DIR;
+var STATE_DIR = STATE_DIR_OVERRIDE !== void 0 && STATE_DIR_OVERRIDE !== "" ? STATE_DIR_OVERRIDE : PROJECT_ROOT !== null ? join2(PROJECT_ROOT, ".orchestrator", ".state") : resolveFallbackStateDir(process.cwd());
+var JWT_CACHE = join2(STATE_DIR, "jwt-token");
+var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
+mkdirSync(STATE_DIR, { recursive: true });
+if ((STATE_DIR_OVERRIDE === void 0 || STATE_DIR_OVERRIDE === "") && PROJECT_ROOT === null) {
+  log(
+    "API-CLIENT",
+    `PROJECT_ROOT: no marker-verified ".orchestrator" project root found above ${process.cwd()} \u2014 falling back to isolated state dir ${STATE_DIR} (RF-003)`
+  );
+}
+var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
+var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";
+var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function resolveHookProjectRoot(cwd) {
+  return resolveProjectRoot(cwd);
+}
+function log(prefix, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}
+`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+  }
+}
+var LAST_COMPLETED_FILE = join2(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
+var INVOCATIONS_DIR = join2(STATE_DIR, "invocations");
+var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
+var DISPATCH_INTENT_DIR = join2(STATE_DIR, "dispatch-intent");
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function getField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = current[part];
+  }
+  return current != null ? String(current) : "";
+}
+
+// hooks/security-gate-honest.ts
+import { execFileSync } from "node:child_process";
+
+// hooks/lib/security-gate-core.ts
+var L2_LATENCY_FLOOR_MS = 400;
+var L1_COVERAGE = "literais de credencial no diff (chaves de provedor, tokens, blocos PEM, URLs com senha)";
+var SECRET_RULES = [
+  { 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 }
+];
+var PLACEHOLDER = /(?:x{6,}|\.{3,}|<[^>]{2,}>|\$\{|EXAMPLE|PLACEHOLDER|YOUR_|CHANGEME|REDACTED|FAKE|DUMMY|\bTODO\b)/i;
+function maskEvidence(s) {
+  const t = s.trim().slice(0, 80);
+  return t.length <= 12 ? "***" : `${t.slice(0, 6)}\u2026${t.slice(-4)} (${String(t.length)} ch)`;
+}
+function scanDiff(diff) {
+  const out = [];
+  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;
+}
+function isCommitCommand(command) {
+  return /git\s+(?:-\S+(?:\s+\S+)?\s+)*commit\b/.test(command) && !/--dry-run\b/.test(command);
+}
+function evaluate(deps) {
+  const verdicts = [];
+  let src;
+  try {
+    src = deps.getDiff();
+  } catch (e) {
+    const reason = `n\xE3o consegui ler o diff do commit (${e.message.slice(0, 80)})`;
+    return [
+      { state: "not-analyzed", layer: "L1", reason },
+      { state: "not-analyzed", layer: "L2", reason }
+    ];
+  }
+  const diff = src.text;
+  if (!diff.trim()) {
+    const reason = `o diff veio vazio via ${src.how} \u2014 nada para analisar. Isto N\xC3O \xE9 o mesmo que limpo`;
+    return [
+      { state: "not-analyzed", layer: "L1", reason },
+      { state: "not-analyzed", layer: "L2", reason }
+    ];
+  }
+  const hits = scanDiff(diff);
+  const cover = `${L1_COVERAGE} \xB7 via ${src.how}`;
+  verdicts.push(
+    hits.length ? { state: "findings", layer: "L1", detail: cover, hits } : { state: "clean", layer: "L1", detail: cover }
+  );
+  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) {
+    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 \u2014 tratado como fallback, n\xE3o como an\xE1lise`
+    });
+  } else {
+    verdicts.push(
+      sem.hits.length ? { state: "findings", layer: "L2", detail: "an\xE1lise sem\xE2ntica", hits: sem.hits } : { state: "clean", layer: "L2", detail: "an\xE1lise sem\xE2ntica" }
+    );
+  }
+  return verdicts;
+}
+function renderShort(verdicts) {
+  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} \u2014 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 \u2014 isto N\xC3O \xE9 "limpo", \xE9 aus\xEAncia de an\xE1lise';
+  }
+  if (skipped.length) {
+    return `SECURITY-GATE: cobertura PARCIAL \u2014 ${analyzed.join("+")} analisou, ${skipped.join("+")} n\xE3o`;
+  }
+  return `SECURITY-GATE: ${analyzed.join("+")} analisou, sem achados`;
+}
+function render(verdicts) {
+  const lines = ["[SECURITY-GATE] Revis\xE3o do commit \u2014 veredito por camada:"];
+  for (const v of verdicts) {
+    if (v.state === "clean") {
+      lines.push(`  ${v.layer} ANALISADO \u2014 LIMPO \xB7 cobertura: ${v.detail}`);
+    } else if (v.state === "findings") {
+      lines.push(
+        `  ${v.layer} ANALISADO \u2014 ${String(v.hits.length)} ACHADO(S) \xB7 cobertura: ${v.detail}`
+      );
+      for (const h of v.hits.slice(0, 10)) {
+        lines.push(`      ${h.rule} \xB7 ${h.file}:${String(h.line)} \xB7 ${h.evidence}`);
+      }
+      if (v.hits.length > 10) lines.push(`      \u2026 e mais ${String(v.hits.length - 10)}`);
+    } else {
+      lines.push(`  ${v.layer} N\xC3O ANALISEI \u2014 ${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(
+      '  \u26A0 NENHUMA camada analisou este commit. Isto N\xC3O \xE9 "limpo" \u2014 \xE9 aus\xEAncia de informa\xE7\xE3o.'
+    );
+  } else if (skipped.length) {
+    lines.push(
+      `  \u26A0 Cobertura PARCIAL: ${analyzed.join("+")} rodou, ${skipped.join("+")} n\xE3o. O que n\xE3o foi analisado n\xE3o est\xE1 limpo \u2014 est\xE1 por analisar.`
+    );
+  }
+  if (verdicts.some((v) => v.state === "findings")) {
+    lines.push("  \u2192 Confira antes de publicar. O commit local j\xE1 existe; nada foi bloqueado.");
+  }
+  return lines.join("\n");
+}
+
+// hooks/security-gate-honest.ts
+var HOOK = "SECURITY-GATE";
+var defaultDeps = {
+  getDiff: () => {
+    const git = (args2) => execFileSync("git", args2, { encoding: "utf8", maxBuffer: 8 * 1024 * 1024, timeout: 1e4 });
+    const parents = git(["rev-list", "--parents", "-n", "1", "HEAD"]).trim().split(/\s+/).length - 1;
+    const args = parents > 1 ? ["show", "--format=", "--unified=0", "-m", "--first-parent", "HEAD"] : ["show", "--format=", "--unified=0", "HEAD"];
+    const how = parents > 1 ? `git show -m --first-parent HEAD (merge de ${parents} pais)` : "git show HEAD";
+    return { text: git(args), how };
+  },
+  // Ficha 3 item (d): o gate é honesto ANTES de voltar a funcionar. Enquanto a
+  // credencial/SDK não forem decididos pelo PM, L2 declara ausência — nunca
+  // finge limpeza.
+  runSemantic: () => null,
+  l2UnavailableReason: () => "camada sem\xE2ntica sem credencial decidida (ficha 3 da S505, item d) \u2014 nenhuma chamada foi tentada, nada foi analisado nesta camada"
+};
+async function mainWithDeps(deps, stdinFn = readStdin) {
+  const stdin = await stdinFn();
+  const command = getField(stdin, "tool_input.command") || getField(stdin, "command") || "";
+  if (!isCommitCommand(command)) return;
+  const verdicts = evaluate(deps);
+  const text = render(verdicts);
+  log(HOOK, text.replace(/\n/g, " | "));
+  console.log(
+    JSON.stringify({
+      systemMessage: renderShort(verdicts),
+      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text }
+    })
+  );
+}
+async function main() {
+  await mainWithDeps(defaultDeps);
+}
+main().catch((e) => {
+  try {
+    log(HOOK, `N\xC3O ANALISEI \u2014 o pr\xF3prio gate falhou: ${e.message.slice(0, 120)}`);
+  } catch {
+  }
+  process.exit(0);
+});
+export {
+  L1_COVERAGE,
+  L2_LATENCY_FLOOR_MS,
+  SECRET_RULES,
+  evaluate,
+  isCommitCommand,
+  mainWithDeps,
+  maskEvidence,
+  render,
+  renderShort,
+  scanDiff
+};

package/hooks/security-gate-honest.ts

@@ -0,0 +1,148 @@
+/**
+ * security-gate-honest.ts — PostToolUse[Bash] hook
+ *
+ * Substituto honesto do `security-guidance@claude-plugins-official` para a
+ * revisão de commits (ficha 3 da S505; decisão do PM: trocar por algo que
+ * FALHE ALTO).
+ *
+ * ─── O DEFEITO QUE ESTE HOOK EXISTE PARA NÃO COMETER ──────────────────────
+ * Medido na S505, `security_reminder_hook.py:1418`: quando a chamada de API
+ * falha, o Commit review emite `no security issues found` e sai com 0 — três
+ * MILISSEGUNDOS depois do erro. A informação de que nada foi analisado está
+ * disponível ali (`llm._last_call_claude_http_error`) e é enviada para a
+ * telemetria como `api_error`, mas NÃO muda o veredito mostrado.
+ *
+ * O mesmo arquivo faz a coisa certa 667 linhas abaixo: o Stop hook (:2085)
+ * testa `_last_call_claude_http_error` ANTES do veredito e, quando há erro,
+ * chama `restore_unreviewed_stop_state` em vez de declarar limpo. Duas
+ * rotinas, a mesma variável, duas condutas — e só uma é honesta.
+ *
+ * ─── A REGRA, E É A ÚNICA QUE IMPORTA ─────────────────────────────────────
+ * AUSÊNCIA DE ANÁLISE NUNCA VIRA VEREDITO POSITIVO. Um gate que degrada para
+ * "limpo" é pior que gate nenhum: gate nenhum é uma ausência que se percebe;
+ * "no security issues found" é uma afirmação que se cita depois.
+ *
+ * Três estados, sempre explícitos, nunca implícitos:
+ *   ANALISADO — LIMPO ......... a camada rodou e não achou nada
+ *   ANALISADO — ACHADOS ....... a camada rodou e achou
+ *   NÃO ANALISEI — <motivo> ... a camada não rodou, e o motivo vai junto
+ *
+ * E a cobertura é declarada em toda saída: dizer "limpo" sem dizer "limpo
+ * DE QUÊ" é a mesma família de defeito, um degrau mais sutil.
+ *
+ * ─── CAMADAS ──────────────────────────────────────────────────────────────
+ *   L1 · varredura local de segredos (regex sobre o diff) — SEM API, sempre
+ *        disponível, cobertura estreita e declarada.
+ *   L2 · análise semântica por LLM — hoje NÃO DISPONÍVEL (sem credencial,
+ *        ver §credencial na ficha). O gancho e o piso de latência ficam
+ *        escritos para quando a credencial for decidida; enquanto isso L2
+ *        reporta NÃO ANALISEI, que é o comportamento correto.
+ *
+ * ─── PISO DE LATÊNCIA (segunda guarda, achado da S505) ────────────────────
+ * Análise semântica de um diff não fecha em milissegundos. Quando L2 existir
+ * e devolver veredito em menos de L2_LATENCY_FLOOR_MS, o resultado é tratado
+ * como fallback, não como análise — vira NÃO ANALISEI. É guarda secundária:
+ * a primária é testar o erro explicitamente, como o Stop hook do plugin faz.
+ *
+ * NUNCA BLOQUEIA. Emite contexto. O objetivo é informar com honestidade, não
+ * impedir o commit — bloquear seria decisão de outra ficha.
+ */
+
+import { log, readStdin, getField } from './lib/api-client.js';
+import { execFileSync } from 'node:child_process';
+import {
+  evaluate,
+  render,
+  renderShort,
+  isCommitCommand,
+  type GateDeps,
+} from './lib/security-gate-core.js';
+
+export {
+  L1_COVERAGE,
+  L2_LATENCY_FLOOR_MS,
+  SECRET_RULES,
+  maskEvidence,
+  scanDiff,
+  isCommitCommand,
+  evaluate,
+  render,
+  renderShort,
+  type Finding,
+  type Verdict,
+  type GateDeps,
+} from './lib/security-gate-core.js';
+
+const HOOK = 'SECURITY-GATE';
+
+// ─────────────────────────────────────────────────────────────
+// Produção
+// ─────────────────────────────────────────────────────────────
+
+const defaultDeps: GateDeps = {
+  getDiff: () => {
+    const git = (args: string[]) =>
+      execFileSync('git', args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, timeout: 10_000 });
+    // Um merge commit devolve diff VAZIO em `git show` sem `-m` (medido S505: o
+    // HEAD de merge dava 0 linhas e um commit normal, 159). Sem esta distinção o
+    // gate diria "não analisei" para todo merge, misturando-o com falha real.
+    const parents =
+      git(['rev-list', '--parents', '-n', '1', 'HEAD']).trim().split(/\s+/).length - 1;
+    const args =
+      parents > 1
+        ? ['show', '--format=', '--unified=0', '-m', '--first-parent', 'HEAD']
+        : ['show', '--format=', '--unified=0', 'HEAD'];
+    const how =
+      parents > 1 ? `git show -m --first-parent HEAD (merge de ${parents} pais)` : 'git show HEAD';
+    return { text: git(args), how };
+  },
+  // Ficha 3 item (d): o gate é honesto ANTES de voltar a funcionar. Enquanto a
+  // credencial/SDK não forem decididos pelo PM, L2 declara ausência — nunca
+  // finge limpeza.
+  runSemantic: () => null,
+  l2UnavailableReason: () =>
+    'camada semântica sem credencial decidida (ficha 3 da S505, item d) — ' +
+    'nenhuma chamada foi tentada, nada foi analisado nesta camada',
+};
+
+export async function mainWithDeps(deps: GateDeps, stdinFn = readStdin): Promise<void> {
+  const stdin = await stdinFn();
+  const command =
+    (getField(stdin, 'tool_input.command') as string | undefined) ||
+    (getField(stdin, 'command') as string | undefined) ||
+    '';
+
+  if (!isCommitCommand(command)) return;
+
+  const verdicts = evaluate(deps);
+  const text = render(verdicts);
+  log(HOOK, text.replace(/\n/g, ' | '));
+
+  // DOIS canais, e a distinção é a ficha inteira (achado do Manager, S505):
+  //   additionalContext → só o MODELO lê;
+  //   systemMessage     → a PESSOA vê, sem bloquear.
+  // Um gate que "falha alto" apenas para o modelo não falha alto para ninguém —
+  // é o mesmo efeito prático do plugin que este substitui. `outputContext` da
+  // casa não emite systemMessage, então o JSON sai montado aqui.
+  console.log(
+    JSON.stringify({
+      systemMessage: renderShort(verdicts),
+      hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text },
+    })
+  );
+}
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
+// Falha do próprio gate também não pode virar silêncio-que-parece-limpo:
+// o motivo vai para o log, e a saída 0 apenas não bloqueia o fluxo.
+main().catch((e: unknown) => {
+  try {
+    log(HOOK, `NÃO ANALISEI — o próprio gate falhou: ${(e as Error).message.slice(0, 120)}`);
+  } catch {
+    /* nada a fazer; nunca derrubar a sessão por causa do gate */
+  }
+  process.exit(0);
+});