@orchestrator-claude/definitions 3.43.1 → 3.44.1

package/hooks/gate-guardian.ts

@@ -13,10 +13,17 @@
  *   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)
+ *
+ * RFC-044 F3, S5 (ADR-031): every ALLOW except quick goes through ONE exit, allowAfterLedger(), which first runs the
+ * ledger step over the files on disk (lib/artifact-gate.ts): verify the sealed phases exhaustively (D-469), validate
+ * and register the files of the phase being left (with advancedBySession, without agentType: TD-390, D-485 (1)).
+ * A failure there is a DENY. No DENY registers or verifies. In PME REQ the adversarial verdict is read from
+ * workflows/<wf>/<P>/adversarial_review.md first, and from the content store only when there is no file (RF-020).
+ * quick mode never registers (Q-PL-4); what stays open on purpose is in TD-391.
  */
 
 import {
@@ -30,9 +37,21 @@ import {
   getGateCellMode,
   getAdversarialVerdict,
   outputPreToolUse,
+  type AdversarialVerdictResult,
   type PendingAction,
 } from './lib/api-client.js';
 import { classifyRisk, deriveGateStrategy, type GateContext } from './lib/gate-logic.js';
+import {
+  ADVERSARIAL_REVIEW_TYPE,
+  defaultArtifactGateDeps,
+  fileAdversarialVerdict,
+  observeWorkflow,
+  registerBeforeAllow,
+  sessionOf,
+  type ArtifactGateDeps,
+  type LedgerContext,
+  type Observation,
+} from './lib/artifact-gate.js';
 
 const HOOK = 'GATE-GUARDIAN';
 
@@ -40,7 +59,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,16 +86,15 @@ 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;
+  /** RFC-044 F3, S5: the disk + ledger step before every ALLOW (lib/artifact-gate.ts). */
+  artifacts: ArtifactGateDeps;
 }
 
-const defaultDeps: HookDeps = {
+export const defaultDeps: HookDeps = {
   readStdin,
   getWorkflowMode,
   getToken,
@@ -84,24 +104,180 @@ const defaultDeps: HookDeps = {
   getAdversarialVerdict,
   output: outputPreToolUse,
   log,
+  artifacts: defaultArtifactGateDeps(),
 };
 
+// ─────────────────────────────────────────────────────────────
+// PME Step 5.5: one decision per AdversarialVerdictResult kind
+// ─────────────────────────────────────────────────────────────
+
+type Output = HookDeps['output'];
+type Log = HookDeps['log'];
+type GateOutput = Parameters<Output>[0];
+
+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 and, under
+ * absentPolicy 'deny', an absent verdict.
+ * `absentPolicy` is the seam of Q-PL-3 (T-PM-09): 'allow' (the default) or 'deny', which the PME REQ call site
+ * passes since S6c — the reviewer can no longer write to the content store, so its file is the only channel.
+ * `expectedFile` names that file in the DENY reason (the actionable part: who did not write what).
+ */
+export function decideAdversarialResult(
+  raw: unknown,
+  workflowId: string,
+  targetPhase: string,
+  output: Output,
+  log: Log,
+  absentPolicy: 'allow' | 'deny' = 'allow',
+  expectedFile?: string
+): 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':
+      if (absentPolicy === 'deny') {
+        log(
+          HOOK,
+          `PME Step 5.5: no adversarial artifact found — DENY (absentPolicy=deny) wf=${workflowId}`
+        );
+        const file =
+          expectedFile ??
+          `project-guidelines/workflows/${workflowId}/<phase>/${ADVERSARIAL_REVIEW_TYPE}.md`;
+        output({
+          decision: 'deny',
+          reason: `Gate Guardian: adversarial_review required — the adversarial-reviewer did not write ${file} and the content store has no verdict, so '${targetPhase}' cannot be entered. Dispatch the adversarial-reviewer for this phase (it writes that file) and retry.`,
+        });
+        return;
+      }
+      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)
 // ─────────────────────────────────────────────────────────────
 
 export async function mainWithDeps(deps: HookDeps): Promise<void> {
-  const {
-    readStdin,
-    getWorkflowMode,
-    getToken,
-    getNextAction,
-    getWorkflowTypeAndVariant,
-    getGateCellMode,
-    getAdversarialVerdict,
-    output,
-    log,
-  } = deps;
+  const { readStdin, getWorkflowMode, getToken, output, log } = deps;
 
   const stdin = await readStdin();
   log(HOOK, 'PreToolUse advancePhase triggered');
@@ -111,7 +287,39 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
 
   log(HOOK, `workflow=${workflowId} targetPhase=${targetPhase}`);
 
-  // ── Step 2: Mode check — quick/interactive bypass gate entirely ──────────
+  // ── RFC-044 F3, S5: the ledger step, shared by every ALLOW (one exit point) ─────────
+  const session = sessionOf(stdin.session_id);
+  const ledgerCtx: LedgerContext = {
+    workflowId,
+    ...(session.kind === 'ok' && { advancedBySession: session.advancedBySession }),
+  };
+  let observation: Promise<Observation> | undefined;
+  const observe = (): Promise<Observation> =>
+    (observation ??= observeWorkflow(workflowId, deps.artifacts));
+
+  /** The ONE exit of every ALLOW (but quick): verify + register first; a failure there is a DENY. */
+  const allowAfterLedger = async (allow: GateOutput): Promise<boolean> => {
+    if (session.kind === 'omitted') {
+      log(HOOK, `advancedBySession omitted (session_id ${session.why}) wf=${workflowId}`);
+    }
+    const observed = await observe();
+    const outcome =
+      observed.kind === 'deny'
+        ? ({ ok: false, reason: observed.reason } as const)
+        : await registerBeforeAllow(observed, ledgerCtx, deps.artifacts, (m) => {
+            log(HOOK, m);
+          });
+    if (!outcome.ok) {
+      log(HOOK, `DENY (ledger step) wf=${workflowId}: ${outcome.reason}`);
+      output({ decision: 'deny', reason: outcome.reason });
+      return false;
+    }
+    log(HOOK, `${outcome.summary} wf=${workflowId}`);
+    output(allow);
+    return true;
+  };
+
+  // ── Step 2: Mode check — quick bypasses the gate; interactive skips its evaluation ──
   if (workflowId) {
     const mode = await getWorkflowMode(workflowId);
     log(HOOK, `workflow=${workflowId} mode=${mode ?? 'legacy'}`);
@@ -119,18 +327,18 @@ 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;
     }
 
     if (mode === 'interactive') {
-      output({
+      const allowed = await allowAfterLedger({
         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}`);
+      if (allowed) log(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
       return;
     }
   }
@@ -159,12 +367,49 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
     return;
   }
 
+  let decided: GateOutput | undefined;
+  const capture: Output = (o) => {
+    decided ??= o;
+  };
+  await evaluateGate(deps, { workflowId, targetPhase, token, observe, output: capture });
+  if (decided === undefined) {
+    output({ decision: 'deny', reason: 'Gate Guardian: no decision was produced (bug); denying.' });
+    return;
+  }
+  if (decided.decision === 'deny') {
+    output(decided);
+    return;
+  }
+  await allowAfterLedger(decided);
+}
+
+interface GateInput {
+  workflowId: string;
+  targetPhase: string;
+  token: string;
+  observe: () => Promise<Observation>;
+  /** Captures the decision; the caller routes an ALLOW through the ledger step. */
+  output: Output;
+}
+
+/** Steps 5.5, 5 and 6–8: the decision itself, written to `input.output` (a capture), never to stdout. */
+async function evaluateGate(deps: HookDeps, input: GateInput): Promise<void> {
+  const { getNextAction, getWorkflowTypeAndVariant, getGateCellMode, getAdversarialVerdict, log } =
+    deps;
+  const { workflowId, targetPhase, token, observe, output } = input;
+
   // ── Step 5.5: PME adversarial gate enforcement (RFC-031 §4.4) ───────────
   // Only enforced when:
   //   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.
+  // Malformed / unreadable artifacts are fail-open (ALLOW) so hooks never block
+  // on downtime; each is logged under its own label (TD-374). Exceptions: a
+  // non-PASS verdict whose `iteration` is not a canonical decimal integer is
+  // denied (TD-375), and since S6c (T-S6c-03, T-PM-09) an ABSENT verdict is
+  // denied too — the reviewer's vault file is its only channel, so no file and no
+  // content-store verdict means the reviewer did not write (R-12). PME non-REQ,
+  // quick and interactive never reach this branch.
   {
     const typeVariant = await getWorkflowTypeAndVariant(workflowId, token);
     if (typeVariant?.type === 'project_management_enterprise') {
@@ -175,49 +420,38 @@ 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.`,
-          });
+        // RF-020: the file of the phase being left comes first; the content store only when there is none.
+        const observed = await observe();
+        if (observed.kind === 'deny') {
+          output({ decision: 'deny', reason: observed.reason });
           return;
         }
-        if (verdict.verdict === 'PASS') {
-          // Adversarial review passed — ALLOW
-          log(HOOK, `PME Step 5.5: adversarial verdict=PASS — ALLOW wf=${workflowId}`);
+        const fromFile = fileAdversarialVerdict(observed);
+        if (fromFile.kind === 'invalid') {
+          log(HOOK, `PME Step 5.5: DENY adversarial_review file invalid wf=${workflowId}`);
           output({
-            decision: 'allow',
-            context: `[GATE] PME adversarial gate: verdict=PASS, proceeding to '${targetPhase}'.`,
+            decision: 'deny',
+            reason: `Gate Guardian: adversarial_review file invalid — ${fromFile.reason} Rewrite it with a string verdict and an integer iteration (ADR-031 D3).`,
           });
           return;
         }
-        // Verdict is NEEDS_REVISION (or unknown) and below hard cap — DENY
+        const result =
+          fromFile.kind === 'verdict'
+            ? fromFile.result
+            : await getAdversarialVerdict(workflowId, token);
         log(
           HOOK,
-          `PME Step 5.5: DENY verdict=${verdict.verdict} iteration=${String(verdict.iteration)} wf=${workflowId}`
+          `PME Step 5.5: verdict source=${fromFile.kind === 'verdict' ? 'file' : 'content-store'} wf=${workflowId}`
+        );
+        decideAdversarialResult(
+          result,
+          workflowId,
+          targetPhase,
+          output,
+          log,
+          'deny',
+          `project-guidelines/workflows/${workflowId}/${observed.phase}/${ADVERSARIAL_REVIEW_TYPE}.md`
         );
-        output({
-          decision: 'deny',
-          reason: `Gate Guardian: adversarial_review required — verdict=${verdict.verdict}, iteration=${String(verdict.iteration)}. Resolve adversarial review before advancing.`,
-        });
         return;
       }
       // gateMode is OPT, SKIP, or null — fall through to Step 5
@@ -236,7 +470,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 +537,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;