@orchestrator-claude/definitions 3.44.0 → 3.44.1

package/hooks/gate-guardian.ts

@@ -17,6 +17,13 @@
  *      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 {
@@ -34,6 +41,17 @@ import {
   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';
 
@@ -72,9 +90,11 @@ export interface HookDeps {
   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,6 +104,7 @@ const defaultDeps: HookDeps = {
   getAdversarialVerdict,
   output: outputPreToolUse,
   log,
+  artifacts: defaultArtifactGateDeps(),
 };
 
 // ─────────────────────────────────────────────────────────────
@@ -92,6 +113,7 @@ const defaultDeps: HookDeps = {
 
 type Output = HookDeps['output'];
 type Log = HookDeps['log'];
+type GateOutput = Parameters<Output>[0];
 
 const RESULT_KINDS: ReadonlySet<string> = new Set([
   'ok',
@@ -178,13 +200,21 @@ function decideRejectedIteration(
   });
 }
 
-/** Maps one classified adversarial result to ALLOW/DENY. Fail-open except a rejected iteration. */
-function decideAdversarialResult(
+/**
+ * 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
+  log: Log,
+  absentPolicy: 'allow' | 'deny' = 'allow',
+  expectedFile?: string
 ): void {
   const result = normalizeVerdictResult(raw);
   switch (result.kind) {
@@ -195,6 +225,20 @@ function decideAdversarialResult(
       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',
@@ -233,17 +277,7 @@ function decideAdversarialResult(
 // ─────────────────────────────────────────────────────────────
 
 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');
@@ -253,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'}`);
@@ -268,11 +334,11 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
     }
 
     if (mode === 'interactive') {
-      output({
+      const allowed = await allowAfterLedger({
         decision: 'allow',
         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;
     }
   }
@@ -301,15 +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
-  // 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).
+  // 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') {
@@ -320,8 +420,38 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
         token
       );
       if (gateMode === 'REQ') {
-        const result = await getAdversarialVerdict(workflowId, token);
-        decideAdversarialResult(result, workflowId, targetPhase, output, log);
+        // 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;
+        }
+        const fromFile = fileAdversarialVerdict(observed);
+        if (fromFile.kind === 'invalid') {
+          log(HOOK, `PME Step 5.5: DENY adversarial_review file invalid wf=${workflowId}`);
+          output({
+            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;
+        }
+        const result =
+          fromFile.kind === 'verdict'
+            ? fromFile.result
+            : await getAdversarialVerdict(workflowId, token);
+        log(
+          HOOK,
+          `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`
+        );
         return;
       }
       // gateMode is OPT, SKIP, or null — fall through to Step 5

package/hooks/lib/api-client.ts

@@ -123,12 +123,27 @@ const API_URL = process.env.ORCHESTRATOR_API_URL || 'http://localhost:3001';
 // `system` tier account (level 4, ABOVE admin) rather than admin — the
 // env-override chain is preserved verbatim so an explicit
 // ORCHESTRATOR_ADMIN_EMAIL/ORCHESTRATOR_AUTH_EMAIL still wins.
-const AUTH_EMAIL =
-  process.env.ORCHESTRATOR_ADMIN_EMAIL ||
-  process.env.ORCHESTRATOR_AUTH_EMAIL ||
-  'system@orchestrator.local';
-const AUTH_PASSWORD =
-  process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || 'system123';
+const DEFAULT_AUTH_EMAIL = 'system@orchestrator.local';
+// TD-267 A1 (S572): there is NO default password. The credential is read
+// lazily, at login time, and a password that is unset, empty or
+// whitespace-only counts as absent — in which case login() makes no network
+// call at all and getToken() returns null (each hook keeps the posture it
+// already has for "no token"). The client never invents a credential.
+const MISSING_CREDENTIAL_MESSAGE =
+  'no credential configured (ORCHESTRATOR_ADMIN_PASSWORD / ORCHESTRATOR_AUTH_PASSWORD unset or empty) - login not attempted';
+let missingCredentialLogged = false;
+
+function resolveAuthCredentials(): { email: string; password: string } | null {
+  const password =
+    (process.env.ORCHESTRATOR_ADMIN_PASSWORD ?? '').trim() ||
+    (process.env.ORCHESTRATOR_AUTH_PASSWORD ?? '').trim();
+  if (!password) return null;
+  const email =
+    process.env.ORCHESTRATOR_ADMIN_EMAIL ||
+    process.env.ORCHESTRATOR_AUTH_EMAIL ||
+    DEFAULT_AUTH_EMAIL;
+  return { email, password };
+}
 // Mutable (not const): RFC-040 Operator Multi-Project, Slice 5 (C5) lazily
 // resolves this once per process when the env var is absent — see
 // ensureProjectIdResolved() below.
@@ -338,6 +353,14 @@ async function login(): Promise<string | null> {
   // the server ignores X-Project-ID on this route entirely, so login can
   // always proceed and PROJECT_ID is resolved afterwards, once a Bearer
   // token is available (see ensureProjectIdResolved, called from getToken()).
+  const credentials = resolveAuthCredentials();
+  if (credentials === null) {
+    if (!missingCredentialLogged) {
+      missingCredentialLogged = true;
+      log('API-CLIENT', MISSING_CREDENTIAL_MESSAGE);
+    }
+    return null;
+  }
   try {
     const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
       method: 'POST',
@@ -345,7 +368,7 @@ async function login(): Promise<string | null> {
         'Content-Type': 'application/json',
         'X-Project-ID': PROJECT_ID,
       },
-      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      body: JSON.stringify({ email: credentials.email, password: credentials.password }),
       signal: AbortSignal.timeout(5000),
     });
     if (!resp.ok) return null;