@orchestrator-claude/definitions 3.43.1 → 3.44.0

package/hooks/gate-guardian.mjs

@@ -213,18 +213,74 @@ async function getGateCellMode(typeId, variant, gateKey, token) {
     return null;
   }
 }
+async function apiGetWithStatus(path, token) {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID
+      },
+      signal: AbortSignal.timeout(5e3)
+    });
+    return { kind: "response", resp };
+  } catch (err) {
+    const name = typeof err === "object" && err !== null && "name" in err ? err.name : "";
+    const timedOut = name === "TimeoutError" || name === "AbortError";
+    return { kind: "error", reason: timedOut ? "timeout" : "network" };
+  }
+}
+function iterationDetail(raw) {
+  const json = JSON.stringify(raw);
+  return json === void 0 ? void 0 : json.slice(0, 40);
+}
+function parseIteration(raw) {
+  if (!/^[0-9]+$/.test(raw)) return null;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function classifyIteration(verdict, rawIteration) {
+  if (typeof rawIteration !== "string") {
+    const detail = iterationDetail(rawIteration);
+    return detail === void 0 ? { kind: "malformed", reason: "iteration_invalid" } : { kind: "malformed", reason: "iteration_invalid", detail };
+  }
+  const iteration = parseIteration(rawIteration);
+  if (iteration === null) {
+    return { kind: "iteration_rejected", verdict, detail: iterationDetail(rawIteration) ?? "" };
+  }
+  return { kind: "ok", verdict, iteration };
+}
+function classifyAdversarialBody(body) {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return { kind: "malformed", reason: "body_not_object" };
+  }
+  const metadata = "metadata" in body ? body.metadata : void 0;
+  const customMetadata = typeof metadata === "object" && metadata !== null && "customMetadata" in metadata ? metadata.customMetadata : void 0;
+  if (typeof customMetadata !== "object" || customMetadata === null) {
+    return { kind: "malformed", reason: "custom_metadata_missing" };
+  }
+  const verdict = "verdict" in customMetadata ? customMetadata.verdict : void 0;
+  if (typeof verdict !== "string") return { kind: "malformed", reason: "verdict_invalid" };
+  const rawIteration = "iteration" in customMetadata ? customMetadata.iteration : void 0;
+  return classifyIteration(verdict, rawIteration);
+}
 async function getAdversarialVerdict(workflowId, token) {
   try {
-    const resp = await apiGet(`/api/v1/artifact-content/${workflowId}/adversarial_review`, token);
-    if (!resp) return null;
-    const { verdict, iteration: rawIteration } = resp.metadata?.customMetadata ?? {};
-    if (typeof verdict !== "string" || typeof rawIteration !== "string") return null;
-    if (rawIteration.trim() === "") return null;
-    const iteration = Number(rawIteration);
-    if (!Number.isFinite(iteration)) return null;
-    return { verdict, iteration };
+    const got = await apiGetWithStatus(
+      `/api/v1/artifact-content/${workflowId}/adversarial_review`,
+      token
+    );
+    if (got.kind === "error") return got;
+    if (got.resp.status === 404) return { kind: "absent" };
+    if (!got.resp.ok) return { kind: "error", reason: "http", status: got.resp.status };
+    let body;
+    try {
+      body = await got.resp.json();
+    } catch {
+      return { kind: "malformed", reason: "body_not_json" };
+    }
+    return classifyAdversarialBody(body);
   } catch {
-    return null;
+    return { kind: "error", reason: "unexpected" };
   }
 }
 async function readStdin() {
@@ -276,8 +332,8 @@ function deriveGateStrategy(ctx) {
     };
   }
   return {
-    strategy: "AUTO_APPROVE",
-    reason: `Phase '${ctx.targetPhase}' is low-risk \u2014 auto-approved.`
+    strategy: "ALLOW_LOW_RISK",
+    reason: `Phase '${ctx.targetPhase}' is low-risk \u2014 allowed without an approval check; no approval observed by this hook.`
   };
 }
 
@@ -295,6 +351,107 @@ var defaultDeps = {
   output: outputPreToolUse,
   log
 };
+var RESULT_KINDS = /* @__PURE__ */ new Set([
+  "ok",
+  "absent",
+  "malformed",
+  "iteration_rejected",
+  "error"
+]);
+function normalizeVerdictResult(raw) {
+  const known = typeof raw === "object" && raw !== null && "kind" in raw && RESULT_KINDS.has(String(raw.kind));
+  return known ? raw : { kind: "error", reason: "unexpected" };
+}
+function decideOkVerdict(result, workflowId, targetPhase, output, log2) {
+  if (result.iteration >= PME_HARD_CAP) {
+    log2(
+      HOOK,
+      `PME Step 5.5: BLOCKED escalation at hard cap (iteration=${String(result.iteration)}) \u2014 ALLOW wf=${workflowId}`
+    );
+    output({
+      decision: "allow",
+      context: `[GATE] PME adversarial gate: hard cap reached (iteration=${String(result.iteration)}/${String(PME_HARD_CAP)}), escalating.`
+    });
+    return;
+  }
+  if (result.verdict === "PASS") {
+    log2(HOOK, `PME Step 5.5: adversarial verdict=PASS \u2014 ALLOW wf=${workflowId}`);
+    output({
+      decision: "allow",
+      context: `[GATE] PME adversarial gate: verdict=PASS, proceeding to '${targetPhase}'.`
+    });
+    return;
+  }
+  log2(
+    HOOK,
+    `PME Step 5.5: DENY verdict=${result.verdict} iteration=${String(result.iteration)} wf=${workflowId}`
+  );
+  output({
+    decision: "deny",
+    reason: `Gate Guardian: adversarial_review required \u2014 verdict=${result.verdict}, iteration=${String(result.iteration)}. Resolve adversarial review before advancing.`
+  });
+}
+function decideRejectedIteration(result, workflowId, targetPhase, output, log2) {
+  const { verdict, detail } = result;
+  if (verdict === "PASS") {
+    log2(
+      HOOK,
+      `PME Step 5.5: adversarial verdict=PASS with iteration_invalid (${detail}) \u2014 ALLOW wf=${workflowId}`
+    );
+    output({
+      decision: "allow",
+      context: `[GATE] PME adversarial gate: verdict=PASS, iteration_invalid (${detail}), hard cap not evaluated, proceeding to '${targetPhase}'.`
+    });
+    return;
+  }
+  log2(HOOK, `PME Step 5.5: DENY verdict=${verdict} iteration_invalid (${detail}) wf=${workflowId}`);
+  output({
+    decision: "deny",
+    reason: `Gate Guardian: adversarial_review iteration invalid (${detail}) with verdict=${verdict} \u2014 the hard cap cannot apply. Rewrite the adversarial_review artifact with customMetadata.iteration as a non-negative decimal integer (e.g. '1') and retry.`
+  });
+}
+function decideAdversarialResult(raw, workflowId, targetPhase, output, log2) {
+  const result = normalizeVerdictResult(raw);
+  switch (result.kind) {
+    case "ok":
+      decideOkVerdict(result, workflowId, targetPhase, output, log2);
+      return;
+    case "iteration_rejected":
+      decideRejectedIteration(result, workflowId, targetPhase, output, log2);
+      return;
+    case "absent":
+      log2(HOOK, `PME Step 5.5: no adversarial artifact found \u2014 fail-open ALLOW wf=${workflowId}`);
+      output({
+        decision: "allow",
+        context: `[GATE] PME adversarial gate: no artifact found, fail-open ALLOW for '${targetPhase}'.`
+      });
+      return;
+    case "malformed": {
+      const detail = result.detail === void 0 ? "" : ` detail=${result.detail}`;
+      log2(
+        HOOK,
+        `PME Step 5.5: adversarial artifact present but malformed (${result.reason}${detail}) \u2014 fail-open ALLOW wf=${workflowId}`
+      );
+      output({
+        decision: "allow",
+        context: `[GATE] PME adversarial gate: artifact malformed (${result.reason}), fail-open ALLOW for '${targetPhase}'.`
+      });
+      return;
+    }
+    case "error": {
+      const status = result.status === void 0 ? "" : ` status=${String(result.status)}`;
+      log2(
+        HOOK,
+        `PME Step 5.5: adversarial artifact unreadable (${result.reason}${status}) \u2014 fail-open ALLOW wf=${workflowId}`
+      );
+      output({
+        decision: "allow",
+        context: `[GATE] PME adversarial gate: artifact could not be read (${result.reason}), fail-open ALLOW for '${targetPhase}'.`
+      });
+      return;
+    }
+  }
+}
 async function mainWithDeps(deps) {
   const {
     readStdin: readStdin2,
@@ -318,7 +475,7 @@ async function mainWithDeps(deps) {
     if (mode === "quick") {
       output({
         decision: "allow",
-        context: `[GATE] AUTO_APPROVE: quick mode skips gate evaluation for '${targetPhase}'.`
+        context: `[GATE] ALLOW_QUICK_MODE: quick mode skips gate evaluation for '${targetPhase}'; no approval observed by this hook.`
       });
       log2(HOOK, `ALLOW quick mode phase=${targetPhase}`);
       return;
@@ -326,7 +483,7 @@ async function mainWithDeps(deps) {
     if (mode === "interactive") {
       output({
         decision: "allow",
-        context: `[GATE] AUTO_APPROVE: interactive mode skips artifact gate evaluation for '${targetPhase}'.`
+        context: `[GATE] ALLOW_INTERACTIVE_MODE: interactive mode skips artifact gate evaluation for '${targetPhase}'; no approval observed by this hook.`
       });
       log2(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
       return;
@@ -361,45 +518,8 @@ async function mainWithDeps(deps) {
         token
       );
       if (gateMode === "REQ") {
-        const verdict = await getAdversarialVerdict2(workflowId, token);
-        if (!verdict) {
-          log2(
-            HOOK,
-            `PME Step 5.5: no adversarial artifact found \u2014 fail-open ALLOW wf=${workflowId}`
-          );
-          output({
-            decision: "allow",
-            context: `[GATE] PME adversarial gate: no artifact found, fail-open ALLOW for '${targetPhase}'.`
-          });
-          return;
-        }
-        if (verdict.iteration >= PME_HARD_CAP) {
-          log2(
-            HOOK,
-            `PME Step 5.5: BLOCKED escalation at hard cap (iteration=${String(verdict.iteration)}) \u2014 ALLOW wf=${workflowId}`
-          );
-          output({
-            decision: "allow",
-            context: `[GATE] PME adversarial gate: hard cap reached (iteration=${String(verdict.iteration)}/${String(PME_HARD_CAP)}), escalating.`
-          });
-          return;
-        }
-        if (verdict.verdict === "PASS") {
-          log2(HOOK, `PME Step 5.5: adversarial verdict=PASS \u2014 ALLOW wf=${workflowId}`);
-          output({
-            decision: "allow",
-            context: `[GATE] PME adversarial gate: verdict=PASS, proceeding to '${targetPhase}'.`
-          });
-          return;
-        }
-        log2(
-          HOOK,
-          `PME Step 5.5: DENY verdict=${verdict.verdict} iteration=${String(verdict.iteration)} wf=${workflowId}`
-        );
-        output({
-          decision: "deny",
-          reason: `Gate Guardian: adversarial_review required \u2014 verdict=${verdict.verdict}, iteration=${String(verdict.iteration)}. Resolve adversarial review before advancing.`
-        });
+        const result = await getAdversarialVerdict2(workflowId, token);
+        decideAdversarialResult(result, workflowId, targetPhase, output, log2);
         return;
       }
       log2(
@@ -467,10 +587,10 @@ async function mainWithDeps(deps) {
     JSON.stringify({ strategy: decision.strategy, targetPhase, riskLevel, reason: decision.reason })
   );
   switch (decision.strategy) {
-    case "AUTO_APPROVE":
+    case "ALLOW_LOW_RISK":
       output({
         decision: "allow",
-        context: `[GATE] AUTO_APPROVE: ${decision.reason}`
+        context: `[GATE] ALLOW_LOW_RISK: ${decision.reason}`
       });
       break;
     case "ASK_HUMAN":

package/hooks/gate-guardian.ts

@@ -13,7 +13,7 @@
  *   6. classifyRisk(targetPhase) → riskLevel
  *   7. buildGateContext() + deriveGateStrategy() → GateDecision
  *   8. switch strategy:
- *      AUTO_APPROVE      → allow + telemetry context
+ *      ALLOW_LOW_RISK    → allow + context (no approval observed by this hook)
  *      ASK_HUMAN         → deny + approval instructions
  *      BLOCK_AND_REQUIRE → deny + requiredAction
  *   9. log(HOOK, JSON summary)
@@ -30,6 +30,7 @@ import {
   getGateCellMode,
   getAdversarialVerdict,
   outputPreToolUse,
+  type AdversarialVerdictResult,
   type PendingAction,
 } from './lib/api-client.js';
 import { classifyRisk, deriveGateStrategy, type GateContext } from './lib/gate-logic.js';
@@ -40,7 +41,9 @@ const HOOK = 'GATE-GUARDIAN';
  * Maximum adversarial review iterations before the hard cap triggers.
  * When iteration >= PME_HARD_CAP the gate ALLOWS (escalation path) and logs
  * a BLOCKED-escalation warning. This prevents infinite review loops.
- * RFC-031 §4.4 documents this mechanic.
+ * RFC-031 §4.4 documents this mechanic. The cap only applies to a well-formed
+ * `iteration` (kind 'ok'); an `iteration` the helper rejected has no count to
+ * compare, so a non-PASS verdict with it is denied instead (TD-375).
  */
 const PME_HARD_CAP = 3;
 
@@ -65,11 +68,8 @@ export interface HookDeps {
     gateKey: string,
     token: string
   ) => Promise<'REQ' | 'OPT' | 'SKIP' | null>;
-  /** PME Step 5.5: retrieve adversarial review verdict + iteration (fail-open: null) */
-  getAdversarialVerdict: (
-    workflowId: string,
-    token: string
-  ) => Promise<{ verdict: string; iteration: number } | null>;
+  /** PME Step 5.5: retrieve the classified adversarial review verdict (TD-374; never rejects) */
+  getAdversarialVerdict: (workflowId: string, token: string) => Promise<AdversarialVerdictResult>;
   output: (opts: { decision: 'allow' | 'deny'; reason?: string; context?: string }) => void;
   log: (prefix: string, msg: string) => void;
 }
@@ -86,6 +86,148 @@ const defaultDeps: HookDeps = {
   log,
 };
 
+// ─────────────────────────────────────────────────────────────
+// PME Step 5.5: one decision per AdversarialVerdictResult kind
+// ─────────────────────────────────────────────────────────────
+
+type Output = HookDeps['output'];
+type Log = HookDeps['log'];
+
+const RESULT_KINDS: ReadonlySet<string> = new Set([
+  'ok',
+  'absent',
+  'malformed',
+  'iteration_rejected',
+  'error',
+]);
+
+/** null / undefined / unknown kind (a stale dep or a bug) is an unexpected error, never a throw. */
+function normalizeVerdictResult(raw: unknown): AdversarialVerdictResult {
+  const known =
+    typeof raw === 'object' && raw !== null && 'kind' in raw && RESULT_KINDS.has(String(raw.kind));
+  return known ? (raw as AdversarialVerdictResult) : { kind: 'error', reason: 'unexpected' };
+}
+
+/** Applies the gate for an `ok` verdict: hard cap -> PASS -> DENY (unchanged texts). */
+function decideOkVerdict(
+  result: Extract<AdversarialVerdictResult, { kind: 'ok' }>,
+  workflowId: string,
+  targetPhase: string,
+  output: Output,
+  log: Log
+): void {
+  if (result.iteration >= PME_HARD_CAP) {
+    // Hard cap reached — ALLOW with escalation log (prevents infinite loops)
+    log(
+      HOOK,
+      `PME Step 5.5: BLOCKED escalation at hard cap (iteration=${String(result.iteration)}) — ALLOW wf=${workflowId}`
+    );
+    output({
+      decision: 'allow',
+      context: `[GATE] PME adversarial gate: hard cap reached (iteration=${String(result.iteration)}/${String(PME_HARD_CAP)}), escalating.`,
+    });
+    return;
+  }
+  if (result.verdict === 'PASS') {
+    log(HOOK, `PME Step 5.5: adversarial verdict=PASS — ALLOW wf=${workflowId}`);
+    output({
+      decision: 'allow',
+      context: `[GATE] PME adversarial gate: verdict=PASS, proceeding to '${targetPhase}'.`,
+    });
+    return;
+  }
+  // Verdict is NEEDS_REVISION (or unknown) and below hard cap — DENY
+  log(
+    HOOK,
+    `PME Step 5.5: DENY verdict=${result.verdict} iteration=${String(result.iteration)} wf=${workflowId}`
+  );
+  output({
+    decision: 'deny',
+    reason: `Gate Guardian: adversarial_review required — verdict=${result.verdict}, iteration=${String(result.iteration)}. Resolve adversarial review before advancing.`,
+  });
+}
+
+/**
+ * `iteration` was a string that is not a canonical decimal integer (TD-375).
+ * PASS needs no hard cap, so it proceeds; any other verdict is denied with the
+ * way out spelled in the reason (the writer must fix the artifact).
+ */
+function decideRejectedIteration(
+  result: Extract<AdversarialVerdictResult, { kind: 'iteration_rejected' }>,
+  workflowId: string,
+  targetPhase: string,
+  output: Output,
+  log: Log
+): void {
+  const { verdict, detail } = result;
+  if (verdict === 'PASS') {
+    log(
+      HOOK,
+      `PME Step 5.5: adversarial verdict=PASS with iteration_invalid (${detail}) — ALLOW wf=${workflowId}`
+    );
+    output({
+      decision: 'allow',
+      context: `[GATE] PME adversarial gate: verdict=PASS, iteration_invalid (${detail}), hard cap not evaluated, proceeding to '${targetPhase}'.`,
+    });
+    return;
+  }
+  log(HOOK, `PME Step 5.5: DENY verdict=${verdict} iteration_invalid (${detail}) wf=${workflowId}`);
+  output({
+    decision: 'deny',
+    reason: `Gate Guardian: adversarial_review iteration invalid (${detail}) with verdict=${verdict} — the hard cap cannot apply. Rewrite the adversarial_review artifact with customMetadata.iteration as a non-negative decimal integer (e.g. '1') and retry.`,
+  });
+}
+
+/** Maps one classified adversarial result to ALLOW/DENY. Fail-open except a rejected iteration. */
+function decideAdversarialResult(
+  raw: unknown,
+  workflowId: string,
+  targetPhase: string,
+  output: Output,
+  log: Log
+): void {
+  const result = normalizeVerdictResult(raw);
+  switch (result.kind) {
+    case 'ok':
+      decideOkVerdict(result, workflowId, targetPhase, output, log);
+      return;
+    case 'iteration_rejected':
+      decideRejectedIteration(result, workflowId, targetPhase, output, log);
+      return;
+    case 'absent':
+      log(HOOK, `PME Step 5.5: no adversarial artifact found — fail-open ALLOW wf=${workflowId}`);
+      output({
+        decision: 'allow',
+        context: `[GATE] PME adversarial gate: no artifact found, fail-open ALLOW for '${targetPhase}'.`,
+      });
+      return;
+    case 'malformed': {
+      const detail = result.detail === undefined ? '' : ` detail=${result.detail}`;
+      log(
+        HOOK,
+        `PME Step 5.5: adversarial artifact present but malformed (${result.reason}${detail}) — fail-open ALLOW wf=${workflowId}`
+      );
+      output({
+        decision: 'allow',
+        context: `[GATE] PME adversarial gate: artifact malformed (${result.reason}), fail-open ALLOW for '${targetPhase}'.`,
+      });
+      return;
+    }
+    case 'error': {
+      const status = result.status === undefined ? '' : ` status=${String(result.status)}`;
+      log(
+        HOOK,
+        `PME Step 5.5: adversarial artifact unreadable (${result.reason}${status}) — fail-open ALLOW wf=${workflowId}`
+      );
+      output({
+        decision: 'allow',
+        context: `[GATE] PME adversarial gate: artifact could not be read (${result.reason}), fail-open ALLOW for '${targetPhase}'.`,
+      });
+      return;
+    }
+  }
+}
+
 // ─────────────────────────────────────────────────────────────
 // Core logic (exported for testing)
 // ─────────────────────────────────────────────────────────────
@@ -119,7 +261,7 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
     if (mode === 'quick') {
       output({
         decision: 'allow',
-        context: `[GATE] AUTO_APPROVE: quick mode skips gate evaluation for '${targetPhase}'.`,
+        context: `[GATE] ALLOW_QUICK_MODE: quick mode skips gate evaluation for '${targetPhase}'; no approval observed by this hook.`,
       });
       log(HOOK, `ALLOW quick mode phase=${targetPhase}`);
       return;
@@ -128,7 +270,7 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
     if (mode === 'interactive') {
       output({
         decision: 'allow',
-        context: `[GATE] AUTO_APPROVE: interactive mode skips artifact gate evaluation for '${targetPhase}'.`,
+        context: `[GATE] ALLOW_INTERACTIVE_MODE: interactive mode skips artifact gate evaluation for '${targetPhase}'; no approval observed by this hook.`,
       });
       log(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
       return;
@@ -164,7 +306,10 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
   //   a) workflow type is 'project_management_enterprise'
   //   b) the variant's 'adversarial' gate cell is 'REQ'
   //   c) adversarial review artifact exists and verdict is not PASS
-  // All infra failures are fail-open (ALLOW) so hooks never block on downtime.
+  // Absent / malformed / unreadable artifacts are fail-open (ALLOW) so hooks never
+  // block on downtime; each is logged under its own label (TD-374). The one
+  // exception is a non-PASS verdict whose `iteration` is not a canonical decimal
+  // integer: the hard cap cannot be evaluated, so it is denied (TD-375).
   {
     const typeVariant = await getWorkflowTypeAndVariant(workflowId, token);
     if (typeVariant?.type === 'project_management_enterprise') {
@@ -175,49 +320,8 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
         token
       );
       if (gateMode === 'REQ') {
-        const verdict = await getAdversarialVerdict(workflowId, token);
-        if (!verdict) {
-          // No artifact yet — fail-open: ALLOW
-          log(
-            HOOK,
-            `PME Step 5.5: no adversarial artifact found — fail-open ALLOW wf=${workflowId}`
-          );
-          output({
-            decision: 'allow',
-            context: `[GATE] PME adversarial gate: no artifact found, fail-open ALLOW for '${targetPhase}'.`,
-          });
-          return;
-        }
-        if (verdict.iteration >= PME_HARD_CAP) {
-          // Hard cap reached — ALLOW with escalation log (prevents infinite loops)
-          log(
-            HOOK,
-            `PME Step 5.5: BLOCKED escalation at hard cap (iteration=${String(verdict.iteration)}) — ALLOW wf=${workflowId}`
-          );
-          output({
-            decision: 'allow',
-            context: `[GATE] PME adversarial gate: hard cap reached (iteration=${String(verdict.iteration)}/${String(PME_HARD_CAP)}), escalating.`,
-          });
-          return;
-        }
-        if (verdict.verdict === 'PASS') {
-          // Adversarial review passed — ALLOW
-          log(HOOK, `PME Step 5.5: adversarial verdict=PASS — ALLOW wf=${workflowId}`);
-          output({
-            decision: 'allow',
-            context: `[GATE] PME adversarial gate: verdict=PASS, proceeding to '${targetPhase}'.`,
-          });
-          return;
-        }
-        // Verdict is NEEDS_REVISION (or unknown) and below hard cap — DENY
-        log(
-          HOOK,
-          `PME Step 5.5: DENY verdict=${verdict.verdict} iteration=${String(verdict.iteration)} wf=${workflowId}`
-        );
-        output({
-          decision: 'deny',
-          reason: `Gate Guardian: adversarial_review required — verdict=${verdict.verdict}, iteration=${String(verdict.iteration)}. Resolve adversarial review before advancing.`,
-        });
+        const result = await getAdversarialVerdict(workflowId, token);
+        decideAdversarialResult(result, workflowId, targetPhase, output, log);
         return;
       }
       // gateMode is OPT, SKIP, or null — fall through to Step 5
@@ -236,7 +340,7 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
 
   // ── Step 5: IMPLEMENT short-circuit (RF-008) ─────────────────────────────
   // If targetPhase contains "implement", check pending-action BEFORE classifyRisk.
-  // This prevents AUTO_APPROVE from being applied to implement phases.
+  // This prevents the low-risk allow path from being applied to implement phases.
   //
   // Phase 4: Only 'implement' phases have the approval path (via pending-action).
   // Other HIGH-risk phases (deploy, migrate, delete) will always ASK_HUMAN → DENY.
@@ -303,10 +407,10 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
   );
 
   switch (decision.strategy) {
-    case 'AUTO_APPROVE':
+    case 'ALLOW_LOW_RISK':
       output({
         decision: 'allow',
-        context: `[GATE] AUTO_APPROVE: ${decision.reason}`,
+        context: `[GATE] ALLOW_LOW_RISK: ${decision.reason}`,
       });
       break;
 

package/hooks/lib/api-client.ts

@@ -1088,35 +1088,138 @@ export async function getGateCellMode(
   }
 }
 
+/**
+ * Outcome of `GET /api/v1/artifact-content/:wf/adversarial_review`, classified
+ * so the caller can tell WHY there is no usable verdict (TD-374) and decide.
+ *
+ * - `ok`: verdict string + `iteration` parsed from a canonical decimal string.
+ * - `absent`: HTTP 404 (no artifact yet).
+ * - `malformed`: HTTP 200 whose body carries no decidable verdict. `iteration_invalid`
+ *   here means `iteration` is absent or not a string.
+ * - `iteration_rejected`: verdict is a valid string but `iteration` is a string that
+ *   fails the grammar (TD-375). Distinct kind on purpose: the caller must decide, a
+ *   `malformed` branch handled as fail-open would reopen the hole in silence.
+ * - `error`: no usable response (HTTP != 200/404, timeout, network, unexpected).
+ */
+export type AdversarialVerdictResult =
+  | { kind: 'ok'; verdict: string; iteration: number }
+  | { kind: 'absent' }
+  | {
+      kind: 'malformed';
+      reason:
+        | 'body_not_json'
+        | 'body_not_object'
+        | 'custom_metadata_missing'
+        | 'verdict_invalid'
+        | 'iteration_invalid';
+      detail?: string;
+    }
+  | { kind: 'iteration_rejected'; verdict: string; detail: string }
+  | { kind: 'error'; reason: 'http' | 'timeout' | 'network' | 'unexpected'; status?: number };
+
+type StatusFetch =
+  | { readonly kind: 'response'; readonly resp: Response }
+  | { readonly kind: 'error'; readonly reason: 'timeout' | 'network' };
+
+/**
+ * Same request as `apiGet` (URL, headers, 5s timeout) but keeps the HTTP
+ * status and the failure cause that `apiGet` collapses into `null`.
+ * `apiGet` itself is intentionally left untouched.
+ */
+async function apiGetWithStatus(path: string, token: string): Promise<StatusFetch> {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'X-Project-ID': PROJECT_ID,
+      },
+      signal: AbortSignal.timeout(5000),
+    });
+    return { kind: 'response', resp };
+  } catch (err) {
+    const name: unknown = typeof err === 'object' && err !== null && 'name' in err ? err.name : '';
+    const timedOut = name === 'TimeoutError' || name === 'AbortError';
+    return { kind: 'error', reason: timedOut ? 'timeout' : 'network' };
+  }
+}
+
+/** `JSON.stringify(raw)` capped at 40 chars; undefined when raw has no JSON form. */
+function iterationDetail(raw: unknown): string | undefined {
+  // JSON.stringify yields undefined for undefined/functions/symbols despite its typing.
+  const json = JSON.stringify(raw) as string | undefined;
+  return json === undefined ? undefined : json.slice(0, 40);
+}
+
+/** Canonical decimal grammar for `iteration` (TD-375): ASCII digits, safe integer. */
+function parseIteration(raw: string): number | null {
+  if (!/^[0-9]+$/.test(raw)) return null;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) ? value : null;
+}
+
+function classifyIteration(verdict: string, rawIteration: unknown): AdversarialVerdictResult {
+  if (typeof rawIteration !== 'string') {
+    const detail = iterationDetail(rawIteration);
+    return detail === undefined
+      ? { kind: 'malformed', reason: 'iteration_invalid' }
+      : { kind: 'malformed', reason: 'iteration_invalid', detail };
+  }
+  const iteration = parseIteration(rawIteration);
+  if (iteration === null) {
+    return { kind: 'iteration_rejected', verdict, detail: iterationDetail(rawIteration) ?? '' };
+  }
+  return { kind: 'ok', verdict, iteration };
+}
+
+function classifyAdversarialBody(body: unknown): AdversarialVerdictResult {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    return { kind: 'malformed', reason: 'body_not_object' };
+  }
+  const metadata: unknown = 'metadata' in body ? body.metadata : undefined;
+  const customMetadata: unknown =
+    typeof metadata === 'object' && metadata !== null && 'customMetadata' in metadata
+      ? metadata.customMetadata
+      : undefined;
+  if (typeof customMetadata !== 'object' || customMetadata === null) {
+    return { kind: 'malformed', reason: 'custom_metadata_missing' };
+  }
+  const verdict: unknown = 'verdict' in customMetadata ? customMetadata.verdict : undefined;
+  if (typeof verdict !== 'string') return { kind: 'malformed', reason: 'verdict_invalid' };
+  const rawIteration: unknown =
+    'iteration' in customMetadata ? customMetadata.iteration : undefined;
+  return classifyIteration(verdict, rawIteration);
+}
+
 /**
  * Retrieves the adversarial review verdict and iteration for a workflow.
- * Calls GET /api/v1/artifact-content/:workflowId/adversarial_review.
- * The API serves the fields in metadata.customMetadata (strings — S3
- * x-amz-meta-* headers only carry strings), so `iteration` is coerced:
- * accepted only as a non-blank string whose Number() is finite (TD-331).
- * Returns null when artifact is absent (404), on 5xx, timeout, or missing /
- * malformed customMetadata fields (fail-open — gate is not enforced when
- * artifact is absent). The pre-TD-331 flat metadata.{verdict,iteration}
- * shape is NOT read (RF-003).
+ * Calls GET /api/v1/artifact-content/:workflowId/adversarial_review and
+ * classifies the outcome (see AdversarialVerdictResult); it never rejects and
+ * never returns null. The API serves the fields in metadata.customMetadata
+ * (strings: S3 x-amz-meta-* headers only carry strings), so `iteration` is
+ * accepted only as a canonical decimal string (/^[0-9]+$/, safe integer). The
+ * pre-TD-331 flat metadata.{verdict,iteration} shape is NOT read (RF-003).
  */
 export async function getAdversarialVerdict(
   workflowId: string,
   token: string
-): Promise<{ verdict: string; iteration: number } | null> {
+): Promise<AdversarialVerdictResult> {
   try {
-    const resp = await apiGet<{
-      content?: string;
-      metadata?: { customMetadata?: Record<string, unknown> };
-    }>(`/api/v1/artifact-content/${workflowId}/adversarial_review`, token);
-    if (!resp) return null;
-    const { verdict, iteration: rawIteration } = resp.metadata?.customMetadata ?? {};
-    if (typeof verdict !== 'string' || typeof rawIteration !== 'string') return null;
-    if (rawIteration.trim() === '') return null;
-    const iteration = Number(rawIteration);
-    if (!Number.isFinite(iteration)) return null;
-    return { verdict, iteration };
+    const got = await apiGetWithStatus(
+      `/api/v1/artifact-content/${workflowId}/adversarial_review`,
+      token
+    );
+    if (got.kind === 'error') return got;
+    if (got.resp.status === 404) return { kind: 'absent' };
+    if (!got.resp.ok) return { kind: 'error', reason: 'http', status: got.resp.status };
+    let body: unknown;
+    try {
+      body = await got.resp.json();
+    } catch {
+      return { kind: 'malformed', reason: 'body_not_json' };
+    }
+    return classifyAdversarialBody(body);
   } catch {
-    return null;
+    return { kind: 'error', reason: 'unexpected' };
   }
 }
 

package/hooks/lib/gate-logic.ts

@@ -5,7 +5,7 @@
  */
 
 export type RiskLevel = 'HIGH' | 'LOW';
-export type GateStrategy = 'AUTO_APPROVE' | 'ASK_HUMAN' | 'BLOCK_AND_REQUIRE';
+export type GateStrategy = 'ALLOW_LOW_RISK' | 'ASK_HUMAN' | 'BLOCK_AND_REQUIRE';
 
 export interface GateContext {
   workflowId: string;
@@ -38,7 +38,7 @@ export function classifyRisk(targetPhase: string): RiskLevel {
  * Derive the gate strategy based on context.
  * Rules (evaluated in order):
  *   1. HIGH risk → ASK_HUMAN
- *   2. default   → AUTO_APPROVE
+ *   2. default   → ALLOW_LOW_RISK (allowed without an approval check; the hook observes no approval)
  *
  * BLOCK_AND_REQUIRE exists as a type but has no trigger rule yet.
  */
@@ -50,9 +50,10 @@ export function deriveGateStrategy(ctx: GateContext): GateDecision {
     };
   }
 
-  // Default: AUTO_APPROVE
+  // Default: low-risk phases pass without any approval check (TD-373: the label
+  // must not claim an approval this hook never observed).
   return {
-    strategy: 'AUTO_APPROVE',
-    reason: `Phase '${ctx.targetPhase}' is low-risk — auto-approved.`,
+    strategy: 'ALLOW_LOW_RISK',
+    reason: `Phase '${ctx.targetPhase}' is low-risk — allowed without an approval check; no approval observed by this hook.`,
   };
 }

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "orchestrator-definitions/v1",
   "namespace": "orchestrator",
-  "version": "3.43.1",
-  "generatedAt": "2026-10-01T17:04:34.229Z",
+  "version": "3.44.0",
+  "generatedAt": "2026-10-01T23:00:12.417Z",
   "definitions": {
     "agents": [
       {
@@ -613,7 +613,7 @@
         "slug": "gate-guardian",
         "file": "hooks/gate-guardian.mjs",
         "version": "1.0.0",
-        "checksum": "sha256:2fe79ad9a8621c9708530e627aed839cf145637af47f76a9ddd45e20da5ff70a",
+        "checksum": "sha256:2186f91f00fe6ec0cd6b49336fb45d9041b5c1fa91d7874a06b58defe1ca04ff",
         "supersedes": null,
         "metadata": {}
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/definitions",
-  "version": "3.43.1",
+  "version": "3.44.0",
   "description": "Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem",
   "type": "module",
   "main": "dist/index.js",