@orchestrator-claude/definitions 3.31.0 → 3.31.2

package/agents/adversarial-reviewer.md

@@ -54,7 +54,7 @@ MUST follow these steps in order. Do not skip steps.
 
 7. **Store critique artifact** — call `artifactStore` with:
    - `artifact_kind: adversarial_review`
-   - `phase`: same phase as the artifact under review
+   - `phase: "adversarial_review"` — **always use this literal string, regardless of the phase of the artifact under review** (S188 fix: OQ-1 Option B; S185 artifacts stored at `phase='research'` are NOT migrated — applies from S186 onward)
    - `content`: the full structured critique (see Output Format)
    - `metadata.persona_id`: the persona used
    - `metadata.iteration`: iteration number

package/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Agente Revisor que valida artefatos e codigo produzidos por outros agentes. Use para code review, validacao de specs/plans/tasks, e aprovacao de gates.
-tools: Read, Grep, Glob, Bash, Write, Edit, mcp__orchestrator-extended__artifactRetrieve
+tools: Read, Grep, Glob, Bash, Write, Edit, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-extended__artifactStore
 model: sonnet
 color: yellow
 permissionMode: default
@@ -29,6 +29,8 @@ Sua funcao e revisar e validar artefatos e codigo produzidos por outros agentes.
 ## Ferramentas Disponiveis
 
 ### MCP Tools
+- `artifactRetrieve(artifactId)`: Retrieve artifact under review from MinIO
+- `artifactStore(workflowId, phase, content, ...)`: **Store review artifact directly** — your own review output (review.md, findings, verdict). Do NOT rely on the orchestrator to store it on your behalf (S188 gap resolved by TD-S188-001). Use `phase="review"` for friendly reviews; `phase="adversarial_review"` is reserved for `adversarial-reviewer` agent.
 - `validateArtifact(path, type)`: Validacao automatizada
 - `lookupKnowledgeBase(topic)`: Busca padroes e convencoes
 

package/hooks/dangling-guard.ts

@@ -10,25 +10,163 @@ import {
   getField,
   getActiveWorkflow,
   getWorkflowStatus,
+  getLastCompletedWorkflow,
+  consumeLastCompletedWorkflow,
   outputBlock,
-} from "./lib/api-client.js";
+  postTelemetry,
+  type TelemetryPayload,
+} from './lib/api-client.js';
+import {
+  parseJsonlSession,
+  findJsonlPath,
+  estimateCost,
+  formatFinopsOutput,
+  type SessionMetrics,
+} from './lib/finops-parser.js';
+
+const HOOK = 'DANGLING-GUARD';
+
+/**
+ * Returns true only when both workflowId and metrics are present.
+ * Fail-open guard: missing either means we skip the POST.
+ */
+export function shouldPostTelemetry(
+  workflowId: string | null | undefined,
+  metrics: SessionMetrics | null | undefined
+): boolean {
+  return workflowId != null && workflowId !== '' && metrics != null;
+}
+
+/**
+ * Builds a TelemetryPayload from session metrics and estimated cost (USD).
+ */
+export function buildTelemetryPayload(
+  sessionId: string | undefined,
+  metrics: SessionMetrics,
+  estimatedCostUsd: number,
+  model?: string,
+  variant?: string
+): TelemetryPayload {
+  const totalTokens = metrics.inputTokens + metrics.outputTokens + metrics.cacheReadTokens;
+  const cacheHitRate = totalTokens > 0 ? metrics.cacheReadTokens / totalTokens : 0;
+  return {
+    ...(sessionId ? { session_id: sessionId } : {}),
+    input_tokens: metrics.inputTokens,
+    output_tokens: metrics.outputTokens,
+    cache_read_tokens: metrics.cacheReadTokens,
+    total_tokens: totalTokens,
+    total_turns: metrics.toolCalls,
+    cache_hit_rate: Math.round(cacheHitRate * 10000) / 10000,
+    estimated_cost_usd: Math.round(estimatedCostUsd * 1000000) / 1000000,
+    ...(model ? { model_used: model } : {}),
+    ...(variant ? { variant } : {}),
+  };
+}
+
+/**
+ * FinOpsAI telemetry block — fail-open, 5s timeout.
+ * Parses session JSONL, emits cost/token metrics, and POSTs to API if workflow active.
+ */
+async function emitFinopsTelemetry(
+  stdin: Record<string, unknown>,
+  workflowId?: string,
+  variant?: string
+): Promise<void> {
+  const sessionId = getField(stdin, 'session_id');
+  if (!sessionId) {
+    log(HOOK, '[FINOPS] No session_id in stdin, skipping telemetry');
+    return;
+  }
+
+  const jsonlPath = await findJsonlPath(sessionId);
+  if (!jsonlPath) {
+    log(HOOK, `[FINOPS] JSONL not found for session ${sessionId}, skipping`);
+    return;
+  }
+
+  const metrics = await parseJsonlSession(jsonlPath);
+  if (!metrics) {
+    log(HOOK, '[FINOPS] Failed to parse JSONL, skipping telemetry');
+    return;
+  }
+
+  const cost = estimateCost(metrics);
+  const output = formatFinopsOutput(metrics, cost);
+  console.error(output);
 
-const HOOK = "DANGLING-GUARD";
+  // POST to API only when both workflowId and metrics are available — fail-open
+  if (shouldPostTelemetry(workflowId, metrics)) {
+    try {
+      const payload = buildTelemetryPayload(
+        sessionId || undefined,
+        metrics,
+        cost,
+        undefined,
+        variant
+      );
+      const ok = await postTelemetry(workflowId!, payload);
+      if (ok) {
+        log(HOOK, `[FINOPS] Telemetry posted to workflow ${workflowId}`);
+      } else {
+        log(HOOK, `[FINOPS] postTelemetry returned false for workflow ${workflowId}`);
+      }
+    } catch (err) {
+      log(HOOK, `[FINOPS] postTelemetry threw: ${String(err)}`);
+    }
+  }
+}
 
 async function main(): Promise<void> {
   const stdin = await readStdin();
-  log(HOOK, "Stop hook triggered");
+  log(HOOK, `Stop hook triggered — stdin keys: [${Object.keys(stdin).join(', ')}]`);
 
   // Prevent infinite loops
-  const stopActive = getField(stdin, "stop_hook_active");
-  if (stopActive === "true") {
-    log(HOOK, "stop_hook_active=true, allowing stop to prevent loop");
+  const stopActive = getField(stdin, 'stop_hook_active');
+  if (stopActive === 'true') {
+    log(HOOK, 'stop_hook_active=true, allowing stop to prevent loop');
     return;
   }
 
   const workflow = await getActiveWorkflow();
+
+  // B4 FinOps timing race fix: when getActiveWorkflow() returns null (workflow
+  // already completed before Stop hook fires), fall back to last-completed-workflow.json
+  // written by the completeWorkflow MCP handler.
+  let finopsWorkflowId: string | undefined = workflow?.id;
+  let usedFallback = false;
+  if (!workflow) {
+    const lastCompleted = getLastCompletedWorkflow();
+    if (lastCompleted) {
+      finopsWorkflowId = lastCompleted.workflowId;
+      usedFallback = true;
+      log(
+        HOOK,
+        `[FINOPS] Active workflow null — using last-completed fallback: ${finopsWorkflowId}`
+      );
+    }
+  }
+
+  // FinOpsAI telemetry — fail-open with 5s timeout
+  // Pass workflowId so telemetry is POSTed to the API when a workflow is active or recently completed
+  try {
+    await Promise.race([
+      emitFinopsTelemetry(stdin, finopsWorkflowId, workflow?.variant ?? undefined),
+      new Promise<void>((resolve) => setTimeout(resolve, 5000)),
+    ]);
+  } catch {
+    log(HOOK, '[FINOPS] Error in telemetry block, continuing');
+  }
+
+  // Idempotency guard: consume the state file after use (regardless of POST success)
+  // to prevent double-posting on subsequent Stop invocations (abnormal exits, retries).
+  // Fail-open: even if the POST failed, we consume to avoid infinite retry loops.
+  if (usedFallback) {
+    consumeLastCompletedWorkflow();
+    log(HOOK, '[FINOPS] Consumed last-completed state file (idempotency guard)');
+  }
+
   if (!workflow) {
-    log(HOOK, "No active workflow, clean exit");
+    log(HOOK, 'No active workflow, clean exit');
     return;
   }
 
@@ -38,16 +176,16 @@ async function main(): Promise<void> {
 
   log(HOOK, `workflow=${workflow.id} status=${wfStatus} phase=${phase}`);
 
-  const activeStatuses = ["in_progress", "awaiting_agent", "awaiting_approval"];
+  const activeStatuses = ['in_progress', 'awaiting_agent', 'awaiting_approval'];
   if (activeStatuses.includes(wfStatus)) {
-    log(HOOK, "BLOCK stop (workflow still active)");
+    log(HOOK, 'BLOCK stop (workflow still active)');
     outputBlock(
       `[DANGLING-GUARD] Workflow ${workflow.id} is still ${wfStatus} (phase: ${phase}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`
     );
     return;
   }
 
-  log(HOOK, "Workflow completed or not active, allowing stop");
+  log(HOOK, 'Workflow completed or not active, allowing stop');
 }
 
 main().catch(() => process.exit(0));

package/hooks/gate-guardian.ts

@@ -26,12 +26,23 @@ import {
   getToken,
   getWorkflowMode,
   getNextAction,
+  getWorkflowTypeAndVariant,
+  getGateCellMode,
+  getAdversarialVerdict,
   outputPreToolUse,
   type PendingAction,
-} from "./lib/api-client.js";
-import { classifyRisk, deriveGateStrategy, type GateContext } from "./lib/gate-logic.js";
+} from './lib/api-client.js';
+import { classifyRisk, deriveGateStrategy, type GateContext } from './lib/gate-logic.js';
 
-const HOOK = "GATE-GUARDIAN";
+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.
+ */
+const PME_HARD_CAP = 3;
 
 // ─────────────────────────────────────────────────────────────
 // Dependency injection interface (enables testing without IO)
@@ -42,7 +53,24 @@ export interface HookDeps {
   getWorkflowMode: (id: string) => Promise<string | null>;
   getToken: () => Promise<string | null>;
   getNextAction: (id: string) => Promise<PendingAction | null>;
-  output: (opts: { decision: "allow" | "deny"; reason?: string; context?: string }) => void;
+  /** PME Step 5.5: retrieve workflow type + variant (fail-open: null) */
+  getWorkflowTypeAndVariant: (
+    workflowId: string,
+    token: string
+  ) => Promise<{ type: string; variant: string } | null>;
+  /** PME Step 5.5: retrieve gate cell mode for a type/variant/key combo (fail-open: null) */
+  getGateCellMode: (
+    typeId: string,
+    variant: string,
+    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>;
+  output: (opts: { decision: 'allow' | 'deny'; reason?: string; context?: string }) => void;
   log: (prefix: string, msg: string) => void;
 }
 
@@ -51,6 +79,9 @@ const defaultDeps: HookDeps = {
   getWorkflowMode,
   getToken,
   getNextAction,
+  getWorkflowTypeAndVariant,
+  getGateCellMode,
+  getAdversarialVerdict,
   output: outputPreToolUse,
   log,
 };
@@ -60,33 +91,43 @@ const defaultDeps: HookDeps = {
 // ─────────────────────────────────────────────────────────────
 
 export async function mainWithDeps(deps: HookDeps): Promise<void> {
-  const { readStdin, getWorkflowMode, getToken, getNextAction, output, log } = deps;
+  const {
+    readStdin,
+    getWorkflowMode,
+    getToken,
+    getNextAction,
+    getWorkflowTypeAndVariant,
+    getGateCellMode,
+    getAdversarialVerdict,
+    output,
+    log,
+  } = deps;
 
   const stdin = await readStdin();
-  log(HOOK, "PreToolUse advancePhase triggered");
+  log(HOOK, 'PreToolUse advancePhase triggered');
 
-  const workflowId = getField(stdin, "tool_input.workflowId") || getField(stdin, "workflowId");
-  const targetPhase = getField(stdin, "tool_input.targetPhase") || getField(stdin, "targetPhase");
+  const workflowId = getField(stdin, 'tool_input.workflowId') || getField(stdin, 'workflowId');
+  const targetPhase = getField(stdin, 'tool_input.targetPhase') || getField(stdin, 'targetPhase');
 
   log(HOOK, `workflow=${workflowId} targetPhase=${targetPhase}`);
 
   // ── Step 2: Mode check — quick/interactive bypass gate entirely ──────────
   if (workflowId) {
     const mode = await getWorkflowMode(workflowId);
-    log(HOOK, `workflow=${workflowId} mode=${mode ?? "legacy"}`);
+    log(HOOK, `workflow=${workflowId} mode=${mode ?? 'legacy'}`);
 
-    if (mode === "quick") {
+    if (mode === 'quick') {
       output({
-        decision: "allow",
+        decision: 'allow',
         context: `[GATE] AUTO_APPROVE: quick mode skips gate evaluation for '${targetPhase}'.`,
       });
       log(HOOK, `ALLOW quick mode phase=${targetPhase}`);
       return;
     }
 
-    if (mode === "interactive") {
+    if (mode === 'interactive') {
       output({
-        decision: "allow",
+        decision: 'allow',
         context: `[GATE] AUTO_APPROVE: interactive mode skips artifact gate evaluation for '${targetPhase}'.`,
       });
       log(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
@@ -96,27 +137,103 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
 
   // ── Step 3: Parse validation — FAIL-CLOSED ───────────────────────────────
   if (!workflowId || !targetPhase) {
-    log(HOOK, "DENY (could not parse input)");
+    log(HOOK, 'DENY (could not parse input)');
     output({
-      decision: "deny",
-      reason: "Gate Guardian: Could not parse workflowId or targetPhase.",
-      context: "Ensure you pass both workflowId and targetPhase to advancePhase.",
+      decision: 'deny',
+      reason: 'Gate Guardian: Could not parse workflowId or targetPhase.',
+      context: 'Ensure you pass both workflowId and targetPhase to advancePhase.',
     });
     return;
   }
 
   // ── Step 4: Auth check — FAIL-CLOSED ────────────────────────────────────
   const token = await getToken();
-  if (!token) {
-    log(HOOK, "DENY (auth failed)");
+  if (token === null || token === '') {
+    log(HOOK, 'DENY (auth failed)');
     output({
-      decision: "deny",
-      reason: "Gate Guardian: Authentication failed.",
-      context: "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.",
+      decision: 'deny',
+      reason: 'Gate Guardian: Authentication failed.',
+      context:
+        'Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.',
     });
     return;
   }
 
+  // ── 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.
+  {
+    const typeVariant = await getWorkflowTypeAndVariant(workflowId, token);
+    if (typeVariant?.type === 'project_management_enterprise') {
+      const gateMode = await getGateCellMode(
+        typeVariant.type,
+        typeVariant.variant,
+        'adversarial',
+        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.`,
+        });
+        return;
+      }
+      // gateMode is OPT, SKIP, or null — fall through to Step 5
+      log(
+        HOOK,
+        `PME Step 5.5: gateMode=${gateMode ?? 'null'} — ALLOW (non-REQ gate) wf=${workflowId}`
+      );
+      output({
+        decision: 'allow',
+        context: `[GATE] PME adversarial gate: mode=${gateMode ?? 'none'} (non-REQ), proceeding to '${targetPhase}'.`,
+      });
+      return;
+    }
+    // typeVariant null or non-PME type — fail-open or bypass, fall through
+  }
+
   // ── 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.
@@ -125,25 +242,42 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
   // Other HIGH-risk phases (deploy, migrate, delete) will always ASK_HUMAN → DENY.
   // An approval path for these will be added in Phase 5 (Adaptive Gate V2).
   if (/implement/i.test(targetPhase)) {
-    log(HOOK, "Checking approval for IMPLEMENT-type phase");
+    log(HOOK, 'Checking approval for IMPLEMENT-type phase');
     const action = await getNextAction(workflowId);
-    const status = action?.pendingAction?.status ?? "";
+    const status = action?.pendingAction?.status ?? '';
 
-    if (status === "approved" || status === "awaiting_agent") {
+    if (status === 'approved' || status === 'awaiting_agent') {
       output({
-        decision: "allow",
+        decision: 'allow',
         context: `[GATE] IMPLEMENT approved (status=${status}): proceeding to phase '${targetPhase}'.`,
       });
-      log(HOOK, JSON.stringify({ hook: "gate-guardian", strategy: "IMPLEMENT_APPROVED", targetPhase, workflowId }));
+      log(
+        HOOK,
+        JSON.stringify({
+          hook: 'gate-guardian',
+          strategy: 'IMPLEMENT_APPROVED',
+          targetPhase,
+          workflowId,
+        })
+      );
       return;
     }
 
     output({
-      decision: "deny",
-      reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status || "not-set"}.`,
-      context: "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.",
+      decision: 'deny',
+      reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status || 'not-set'}.`,
+      context: 'Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.',
     });
-    log(HOOK, JSON.stringify({ hook: "gate-guardian", strategy: "IMPLEMENT_DENIED", targetPhase, workflowId, reason: "pending-action not approved" }));
+    log(
+      HOOK,
+      JSON.stringify({
+        hook: 'gate-guardian',
+        strategy: 'IMPLEMENT_DENIED',
+        targetPhase,
+        workflowId,
+        reason: 'pending-action not approved',
+      })
+    );
     return;
   }
 
@@ -155,7 +289,7 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
     targetPhase,
     // Reserved for Phase 5+6 — will be populated when OLAP integration provides
     // workflow context. Currently unused by deriveGateStrategy().
-    currentPhase: "",
+    currentPhase: '',
     executionMode: null,
     workflowMode: null,
     riskLevel,
@@ -163,27 +297,30 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
 
   const decision = deriveGateStrategy(ctx);
 
-  log(HOOK, JSON.stringify({ strategy: decision.strategy, targetPhase, riskLevel, reason: decision.reason }));
+  log(
+    HOOK,
+    JSON.stringify({ strategy: decision.strategy, targetPhase, riskLevel, reason: decision.reason })
+  );
 
   switch (decision.strategy) {
-    case "AUTO_APPROVE":
+    case 'AUTO_APPROVE':
       output({
-        decision: "allow",
+        decision: 'allow',
         context: `[GATE] AUTO_APPROVE: ${decision.reason}`,
       });
       break;
 
-    case "ASK_HUMAN":
+    case 'ASK_HUMAN':
       output({
-        decision: "deny",
+        decision: 'deny',
         reason: `Gate Guardian: ${decision.reason} Ask user for approval.`,
       });
       break;
 
-    case "BLOCK_AND_REQUIRE":
+    case 'BLOCK_AND_REQUIRE':
       output({
-        decision: "deny",
-        reason: `Gate Guardian BLOCKED: ${decision.reason}. Required: ${decision.requiredAction ?? "unspecified"}.`,
+        decision: 'deny',
+        reason: `Gate Guardian BLOCKED: ${decision.reason}. Required: ${decision.requiredAction ?? 'unspecified'}.`,
       });
       break;
   }