wogiflow 2.30.3 → 2.31.0

package/.claude/commands/wogi-self-adversary.md

@@ -0,0 +1,130 @@
+# /wogi-self-adversary — Self-adversary decision loop
+
+Iterate a generator and adversary on different models until you reach ≥95% confidence on an implementation-class decision. Only escalate to the user if confidence stays low after the loop.
+
+**Triggers**: invoked by the AI itself when blocked by the self-adversary PreToolUse gate (wf-e399bd8d), OR by the user directly.
+
+## Usage
+
+```bash
+/wogi-self-adversary "<question + brief context>"
+```
+
+The argument should be the question the AI was about to ask the user, optionally followed by relevant context (files, prior decisions, constraints). Both will be passed to the loop.
+
+## How it works
+
+For Claude inside this skill — read carefully, then execute.
+
+### Step 1: Parse the argument
+
+The ARGUMENTS string contains the question + context. Split on a sensible boundary (first newline, or `--context:` separator if present). If no clear split, treat the entire argument as the question and leave context empty.
+
+### Step 2: Run the loop
+
+```js
+const { runSelfAdversaryLoop } = require('wogiflow/scripts/flow-self-adversary-loop');
+const result = await runSelfAdversaryLoop({
+  question: questionText,
+  context: contextText,
+  maxIterations: 8,
+  targetConfidence: 95
+});
+```
+
+Or via Bash if a CLI wrapper exists; otherwise invoke through Node inline.
+
+### Step 3: Handle the result
+
+**Three possible outcomes:**
+
+**A. `escalate: false`** — confident decision reached.
+
+1. Display the decision + confidence + iteration count to the user as a summary.
+2. Write the completion marker so the next `AskUserQuestion` (if any) is allowed:
+   ```js
+   const gate = require('wogiflow/scripts/hooks/core/self-adversary-gate');
+   gate.writeCompletionMarker({
+     question: questionText,
+     decision: result.decision,
+     confidence: result.confidence,
+     iterationCount: result.iterationCount
+   });
+   ```
+3. ACT on the decision in your subsequent tool calls — no more asking, no hedging.
+
+**B. `escalate: true` (reason: `low-confidence` / `max-iterations-exhausted`)** — loop ran but couldn't converge.
+
+1. Write the escalation marker (allows the next `AskUserQuestion` to pass without re-blocking):
+   ```js
+   gate.writeEscalationMarker({
+     question: questionText,
+     decision: result.decision,
+     confidence: result.confidence,
+     iterationCount: result.iterationCount,
+     reason: result.reason
+   });
+   ```
+2. Surface to the user with: the question, what the loop concluded (best decision + confidence), why iteration couldn't push past the threshold, and what specific resolution you need from them.
+3. Call `AskUserQuestion` (which now passes the gate).
+
+**C. `escalate: true` (reason: `no-credentials` / `model-error` / etc.)** — loop couldn't run.
+
+1. Note the failure mode briefly to the user.
+2. Write the escalation marker and surface the original question.
+
+### Step 4: Audit trail
+
+Append a one-line summary to `.workflow/state/self-adversary-log.json` (append-only, ring-buffered at 100):
+
+```json
+{
+  "timestamp": "...",
+  "questionHash": "...",
+  "iterations": N,
+  "finalConfidence": X,
+  "outcome": "decided" | "escalated",
+  "reason": "..."
+}
+```
+
+This lets the user audit how often the loop converges vs escalates. Helps tune `targetConfidence` and `maxIterations` over time.
+
+## Configuration
+
+`.workflow/config.json`:
+
+```json
+{
+  "selfAdversaryGate": {
+    "enabled": true,
+    "targetConfidence": 95,
+    "maxIterations": 8,
+    "generatorModel": "anthropic:claude-sonnet-4-6",
+    "adversaryModel": "anthropic:claude-3-5-haiku-latest"
+  }
+}
+```
+
+- `enabled: false` — disables both the PreToolUse gate AND prevents the skill from running. Reverts to "always ask the user".
+- `targetConfidence` — clamped to [50, 99]; default 95.
+- `maxIterations` — clamped to [1, 12]; default 8.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `scripts/flow-self-adversary-loop.js` | Core loop (generator ↔ adversary, iteration memory in-process). |
+| `scripts/flow-impl-question-classifier.js` | Haiku classifier — implementation vs product/architecture/sensitive. |
+| `scripts/hooks/core/self-adversary-gate.js` | PreToolUse intercept + markers. |
+| `.workflow/state/self-adversary-complete.json` | Single-use marker, allows next AskUserQuestion. |
+| `.workflow/state/self-adversary-escalation.json` | Single-use marker, allows next AskUserQuestion after loop concluded "needs-user". |
+| `.workflow/state/self-adversary-log.json` | Append-only audit trail. |
+
+## Why this exists
+
+User directive 2026-05-11 (wf-e399bd8d):
+
+> "Always do highest standards, best approach, don't compromise on quality for token savings. Challenge yourself a few times and most of the times you get to a point where you already know what to do with very high confidence, 90 or 95+ percent. When you have doubt that you'll be able to challenge yourself, use adversary research. And do it in a few iterations until you're confident. And only if you're still not confident, then ask the user."
+
+The pattern maps to Self-Refine (Madaan et al. 2023) + Reflexion (Shinn et al. 2023) + Multi-Agent Reflexion (different-model adversary escapes local optima). WogiFlow already runs an Architect+Adversary loop at the PLAN level (IGR Step 1.55/1.57). This skill is the implementation-decision analogue, finer-grained, runs during coding rather than spec_review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wogiflow",
-  "version": "2.30.3",
+  "version": "2.31.0",
   "description": "AI-powered development workflow management system with multi-model support",
   "main": "lib/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "flow": "./scripts/flow",
-    "test": "NODE_ENV=test node --test tests/auto-compact-prompt.test.js tests/flow-paths.test.js tests/flow-io.test.js tests/flow-audit-gates.test.js tests/flow-standards-hook-three-layer.test.js tests/flow-correction-detector-reconcile.test.js tests/flow-correction-backfill.test.js tests/flow-audit-gates-feature-output-health.test.js tests/flow-config-loader.test.js tests/flow-damage-control.test.js tests/flow-output.test.js tests/flow-constants.test.js tests/flow-session-state.test.js tests/flow-hooks-integration.test.js tests/flow-utils.test.js tests/flow-security.test.js tests/flow-memory-db.test.js tests/flow-durable-session.test.js tests/flow-skill-matcher.test.js tests/flow-bridge.test.js tests/flow-proactive-compact.test.js tests/flow-cascade-completion.test.js tests/flow-capture-gate.test.js tests/flow-correction-detector-hybrid.test.js tests/flow-promote.test.js tests/flow-archive-runs.test.js tests/flow-memory.test.js tests/flow-hooks-pre-tool-helpers.test.js tests/flow-hooks-bugfix-scope-gate.test.js tests/flow-hooks-routing-gate.test.js tests/flow-hooks-phase-read-gate.test.js tests/flow-hooks-commit-log-gate.test.js tests/flow-hooks-deploy-gate.test.js tests/flow-hooks-todowrite-gate.test.js tests/flow-hooks-git-safety-gate.test.js tests/flow-hooks-scope-mutation-gate.test.js tests/flow-hooks-strike-gate.test.js tests/flow-hooks-component-check.test.js tests/flow-hooks-scope-gate.test.js tests/flow-hooks-implementation-gate.test.js tests/flow-hooks-research-gate.test.js tests/flow-hooks-loop-check.test.js tests/flow-hooks-manager-boundary-gate.test.js tests/flow-hooks-phase-gate.test.js tests/flow-hooks-pre-tool-orchestrator.test.js tests/flow-hooks-observation-capture.test.js tests/flow-hooks-task-gate.test.js tests/flow-durable-session-suspension.test.js tests/flow-health-mcp-scopes.test.js tests/flow-lean-config.test.js tests/flow-workspace-autopickup.test.js tests/flow-worker-boundary-gate.test.js tests/flow-worker-question-classifier.test.js tests/flow-completion-truth-gate-contradictions.test.js tests/flow-structure-sensor.test.js tests/flow-workspace-dispatch-tracking.test.js tests/workspace-ipc-sqlite.test.js tests/workspace-ipc-multi-worker.test.js tests/flow-story-gates.test.js tests/flow-workspace-restart-handoff.test.js tests/flow-wogi-claude-wrapper.test.js tests/flow-wave1-integrations.test.js tests/flow-wave2-integrations.test.js tests/flow-wave3-integrations.test.js tests/flow-commit-claims-gate.test.js tests/auto-review.test.js tests/gate-telemetry-surface.test.js tests/agents-md-alias.test.js tests/flow-skill-manage.test.js tests/fuzzy-patch.test.js tests/mode-schema.test.js tests/flow-feature-dossier.test.js tests/flow-autonomous-mode.test.js tests/flow-epic-cascade.test.js tests/flow-workspace-summary.test.js tests/flow-hooks-research-evidence-gate.test.js tests/flow-worker-mcp-strip.test.js tests/flow-orchestrate-corrections.test.js tests/flow-source-fidelity.test.js tests/flow-hooks-long-input-enforcement.test.js tests/workspace-channel-tracking.test.js tests/flow-hooks-deletion-log.test.js tests/flow-task-boundary-reset.test.js tests/flow-deferral-gate.test.js tests/flow-research-required-gate.test.js tests/flow-standards-forbidden-patterns.test.js tests/flow-hooks-architect-required-gate.test.js tests/flow-architect-runs.test.js && NODE_ENV=test node tests/run-quality-gates.test.js",
+    "test": "NODE_ENV=test node --test tests/auto-compact-prompt.test.js tests/flow-paths.test.js tests/flow-io.test.js tests/flow-audit-gates.test.js tests/flow-standards-hook-three-layer.test.js tests/flow-correction-detector-reconcile.test.js tests/flow-correction-backfill.test.js tests/flow-audit-gates-feature-output-health.test.js tests/flow-config-loader.test.js tests/flow-damage-control.test.js tests/flow-output.test.js tests/flow-constants.test.js tests/flow-session-state.test.js tests/flow-hooks-integration.test.js tests/flow-utils.test.js tests/flow-security.test.js tests/flow-memory-db.test.js tests/flow-durable-session.test.js tests/flow-skill-matcher.test.js tests/flow-bridge.test.js tests/flow-proactive-compact.test.js tests/flow-cascade-completion.test.js tests/flow-capture-gate.test.js tests/flow-correction-detector-hybrid.test.js tests/flow-promote.test.js tests/flow-archive-runs.test.js tests/flow-memory.test.js tests/flow-hooks-pre-tool-helpers.test.js tests/flow-hooks-bugfix-scope-gate.test.js tests/flow-hooks-routing-gate.test.js tests/flow-hooks-phase-read-gate.test.js tests/flow-hooks-commit-log-gate.test.js tests/flow-hooks-deploy-gate.test.js tests/flow-hooks-todowrite-gate.test.js tests/flow-hooks-git-safety-gate.test.js tests/flow-hooks-scope-mutation-gate.test.js tests/flow-hooks-strike-gate.test.js tests/flow-hooks-component-check.test.js tests/flow-hooks-scope-gate.test.js tests/flow-hooks-implementation-gate.test.js tests/flow-hooks-research-gate.test.js tests/flow-hooks-loop-check.test.js tests/flow-hooks-manager-boundary-gate.test.js tests/flow-hooks-phase-gate.test.js tests/flow-hooks-pre-tool-orchestrator.test.js tests/flow-hooks-observation-capture.test.js tests/flow-hooks-task-gate.test.js tests/flow-durable-session-suspension.test.js tests/flow-health-mcp-scopes.test.js tests/flow-lean-config.test.js tests/flow-workspace-autopickup.test.js tests/flow-worker-boundary-gate.test.js tests/flow-worker-question-classifier.test.js tests/flow-completion-truth-gate-contradictions.test.js tests/flow-structure-sensor.test.js tests/flow-workspace-dispatch-tracking.test.js tests/workspace-ipc-sqlite.test.js tests/workspace-ipc-multi-worker.test.js tests/flow-story-gates.test.js tests/flow-workspace-restart-handoff.test.js tests/flow-wogi-claude-wrapper.test.js tests/flow-wave1-integrations.test.js tests/flow-wave2-integrations.test.js tests/flow-wave3-integrations.test.js tests/flow-commit-claims-gate.test.js tests/auto-review.test.js tests/gate-telemetry-surface.test.js tests/agents-md-alias.test.js tests/flow-skill-manage.test.js tests/fuzzy-patch.test.js tests/mode-schema.test.js tests/flow-feature-dossier.test.js tests/flow-autonomous-mode.test.js tests/flow-epic-cascade.test.js tests/flow-workspace-summary.test.js tests/flow-hooks-research-evidence-gate.test.js tests/flow-worker-mcp-strip.test.js tests/flow-orchestrate-corrections.test.js tests/flow-source-fidelity.test.js tests/flow-hooks-long-input-enforcement.test.js tests/workspace-channel-tracking.test.js tests/flow-hooks-deletion-log.test.js tests/flow-task-boundary-reset.test.js tests/flow-deferral-gate.test.js tests/flow-research-required-gate.test.js tests/flow-standards-forbidden-patterns.test.js tests/flow-hooks-architect-required-gate.test.js tests/flow-architect-runs.test.js tests/flow-installer-forbidden-patterns.test.js tests/flow-deferral-classifier-ai.test.js tests/flow-no-defer-policy.test.js tests/flow-self-adversary-loop.test.js tests/flow-impl-question-classifier.test.js tests/flow-hooks-self-adversary-gate.test.js && NODE_ENV=test node tests/run-quality-gates.test.js",
     "test:syntax": "find scripts/ lib/ -name '*.js' -not -path '*/node_modules/*' -exec node --check {} +",
     "lint": "eslint scripts/ lib/ tests/",
     "lint:ci": "eslint scripts/ lib/ tests/ --max-warnings 0",

package/scripts/flow-impl-question-classifier.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * Wogi Flow — Implementation-Question Classifier (wf-e399bd8d)
+ *
+ * Classifies an "AI is about to ask the user" question to decide whether
+ * the self-adversary loop should run first or the question should reach
+ * the user directly.
+ *
+ * Four categories:
+ *   implementation — code structure, library/algorithm choice, naming,
+ *                    refactor mechanics, testing approach. The AI should
+ *                    self-adversary (likely high enough confidence).
+ *   product        — domain semantics, user-facing behavior, what to
+ *                    SHOW the user, what counts as "done" for the
+ *                    business. The AI cannot self-adversary; ask user.
+ *   architecture   — system-design tradeoffs (DB choice, deployment
+ *                    topology, public API shape). Tier-3: existing
+ *                    researchReasoningGate handles this with adversary;
+ *                    the new loop can also handle it but caller decides.
+ *   sensitive      — destructive operations (delete, force-push, drop),
+ *                    cross-boundary commitments (notify users, send
+ *                    emails). Always ask.
+ *
+ * The classifier is a small Haiku call. Fail-open: any error → ask
+ * (treat as if classification said "product"), preserving prior
+ * behavior. This avoids the failure shape from wf-b8839d99 (regex
+ * silently misclassifying).
+ *
+ * Note: this is interpretation of an AI-AUTHORED question (the question
+ * the AI is about to ask the user). It is NOT user-input parsing — so
+ * the "no regex on user answers" rule from wf-b8839d99 doesn't constrain
+ * us. We still use AI here because hedging vocabulary for implementation
+ * vs product is unbounded.
+ */
+
+const DEFAULT_MIN_CONFIDENCE = 75;
+const DEFAULT_MODEL = 'anthropic:claude-3-5-haiku-latest';
+const MAX_QUESTION_CHARS = 3000;
+const MAX_TOKENS = 300;
+const TEMPERATURE = 0.0;
+
+const { DANGEROUS_KEYS } = require('./flow-io');
+
+function hasDangerousKeys(value) {
+  if (!value || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return value.some(hasDangerousKeys);
+  for (const key of Object.keys(value)) {
+    if (DANGEROUS_KEYS.has(key)) return true;
+    if (hasDangerousKeys(value[key])) return true;
+  }
+  return false;
+}
+
+function buildClassifierPrompt(questionText) {
+  return `You classify the type of question an AI development assistant is about to ask the user. The user has instructed the AI to STOP asking implementation-class questions — instead, the AI should iterate generator↔adversary on a different model until ≥95% confidence. Product, architecture, or sensitive questions still reach the user normally.
+
+[QUESTION_START]
+${String(questionText || '').slice(0, MAX_QUESTION_CHARS)}
+[QUESTION_END]
+
+Four categories:
+
+  IMPLEMENTATION — code structure, library or algorithm choice, naming,
+    refactor mechanics, test framework picks, error-handling shape, code
+    organization, idiom selection. The AI can reason this out with research.
+
+  PRODUCT — domain semantics, user-facing behavior decisions, feature
+    scope, what counts as "done" for the business, copy/tone, UX flow
+    decisions. The AI cannot reason its way to these without the owner.
+
+  ARCHITECTURE — system-design tradeoffs (database choice, deployment
+    topology, public API shape, multi-tenant boundaries). High-stakes;
+    self-adversary alone may not be enough but more iteration helps.
+
+  SENSITIVE — destructive operations (delete data, force-push, drop
+    table), cross-boundary commitments (notify users, send emails),
+    legal/compliance gates. Always ask the user.
+
+CRITICAL RULES:
+  1. When ambiguous, return PRODUCT — the cost of mis-asking is low, the
+     cost of mis-acting is high.
+  2. Even if the question phrasing is technical, ask whether the ANSWER
+     depends on user-only knowledge. "Which date format do users
+     prefer?" — phrasing is technical, answer is product.
+  3. Confidence: only ≥80 if the category is unambiguous.
+
+Return JSON only, no prose, no markdown fences:
+{
+  "category": "implementation" | "product" | "architecture" | "sensitive",
+  "confidence": 0-100,
+  "reason": "one short sentence"
+}
+
+Examples:
+- "Should this be a map() or for-loop?" → {"category":"implementation","confidence":95,"reason":"pure code-style choice"}
+- "Which date format do users prefer?" → {"category":"product","confidence":90,"reason":"answer depends on user preference"}
+- "Should we use Postgres or MongoDB?" → {"category":"architecture","confidence":85,"reason":"system-design tradeoff"}
+- "OK to delete the migration table?" → {"category":"sensitive","confidence":95,"reason":"destructive operation"}
+- "Should I add error handling here?" → {"category":"implementation","confidence":85,"reason":"code-quality choice the AI can research"}`;
+}
+
+async function classifyImplementationQuestion(questionText, options = {}) {
+  const minConfidence = Number.isFinite(options.minConfidence) ? options.minConfidence : DEFAULT_MIN_CONFIDENCE;
+  const model = options.model || DEFAULT_MODEL;
+
+  if (typeof questionText !== 'string' || questionText.trim().length === 0) {
+    return { classified: false, reason: 'empty-question' };
+  }
+  if (!process.env.ANTHROPIC_API_KEY) {
+    return { classified: false, reason: 'no-credentials' };
+  }
+
+  let callModel;
+  try {
+    ({ callModel } = require('./flow-model-caller'));
+  } catch (_err) {
+    return { classified: false, reason: 'no-model-caller' };
+  }
+
+  let result;
+  try {
+    result = await callModel(model, buildClassifierPrompt(questionText), {
+      temperature: TEMPERATURE,
+      maxTokens: MAX_TOKENS
+    });
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[impl-question-classifier] model call failed: ${err.message}`);
+    }
+    return { classified: false, reason: 'model-error' };
+  }
+
+  const raw = String(result?.response ?? result?.content ?? '').trim();
+  if (!raw) return { classified: false, reason: 'empty-response' };
+
+  const jsonMatch = raw.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return { classified: false, reason: 'non-json-response' };
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch (_err) {
+    return { classified: false, reason: 'json-parse-error' };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { classified: false, reason: 'bad-shape' };
+  }
+  if (hasDangerousKeys(parsed)) {
+    return { classified: false, reason: 'dangerous-keys' };
+  }
+
+  const categoryRaw = String(parsed.category || '').toLowerCase();
+  const category = ['implementation', 'product', 'architecture', 'sensitive'].includes(categoryRaw)
+    ? categoryRaw
+    : 'product'; // fail-safe default
+  const confidence = Number.isFinite(parsed.confidence) ? Math.round(parsed.confidence) : 0;
+  const reason = typeof parsed.reason === 'string' ? parsed.reason.slice(0, 240) : '';
+
+  return {
+    classified: true,
+    category,
+    confidence,
+    reason,
+    shouldRunLoop: category === 'implementation' && confidence >= minConfidence,
+    minConfidence
+  };
+}
+
+module.exports = {
+  classifyImplementationQuestion,
+  buildClassifierPrompt,
+  hasDangerousKeys,
+  DEFAULT_MIN_CONFIDENCE,
+  DEFAULT_MODEL
+};

package/scripts/flow-self-adversary-loop.js

@@ -0,0 +1,360 @@
+'use strict';
+
+/**
+ * Wogi Flow — Self-Adversary Decision Loop (wf-e399bd8d)
+ *
+ * Implements the Self-Refine + Reflexion pattern for implementation-class
+ * decision-making. When the AI hits an "implementation/approach" question
+ * mid-task that it would otherwise ask the user about, it should instead
+ * iterate generator ↔ adversary on different models until confidence ≥ 95%
+ * (or max iterations). Only then, if still uncertain, escalate to user.
+ *
+ * User directive (2026-05-11, wf-e399bd8d original prompt):
+ *   "Always do highest standards, best approach, don't compromise on quality
+ *    for token savings. Challenge yourself a few times and most of the times
+ *    you get to a point where you already know what to do with very high
+ *    confidence, 90 or 95+ percent. When you have doubt that you'll be able
+ *    to challenge yourself, use adversary research. And do it in a few
+ *    iterations until you're confident. And only if you're still not
+ *    confident, then ask the user."
+ *
+ * Pattern references:
+ *   - Self-Refine (Madaan et al. 2023, arxiv 2303.17651): same LLM
+ *     generates → critiques → refines. ~20% absolute task gains.
+ *   - Reflexion (Shinn et al. 2023, arxiv 2303.11366): verbal self-
+ *     reflection stored in iteration memory, ~25-50% production gains.
+ *   - Socratic Self-Refine (SSR, 2025): step-level confidence with
+ *     sub-question decomposition.
+ *   - WogiFlow IGR Architect+Adversary (existing): different-model
+ *     adversary at the PLAN level. This module is the IMPLEMENTATION-
+ *     DECISION analogue.
+ *
+ * Architecture:
+ *   1. Generator (default: Sonnet) produces initial decision + confidence
+ *      + rationale + sub-confidences (which parts are weakest).
+ *   2. Adversary (default: Haiku, different model to escape local optima)
+ *      critiques: weakest claims, counterexamples, alternatives the
+ *      generator missed.
+ *   3. Generator refines, taking adversary feedback into account. Memory
+ *      of prior iterations is appended (Reflexion pattern) — in-process
+ *      only, NEVER persisted to disk (avoid memory-injection attacks per
+ *      International AI Safety Report 2026).
+ *   4. Loop terminates when: confidence ≥ threshold, OR max iterations
+ *      reached, OR adversary fails-open.
+ *   5. AskUserQuestion is structurally unavailable to sub-agents inside
+ *      this loop (prompts forbid it, models told). If the model insists
+ *      on asking, that signals genuine ambiguity → escalate.
+ *
+ * Failure modes — all fail SAFE (escalate to user):
+ *   - No API key: return { escalate: true, reason: 'no-credentials' }
+ *   - Model call error: return { escalate: true, reason: 'model-error' }
+ *   - Malformed JSON: skip that iteration, retry
+ *   - Max iterations + confidence < threshold: return { escalate: true,
+ *     reason: 'low-confidence', confidence, decision }
+ *
+ * Fail-safe direction: escalating to user is SAFER than acting on a
+ * low-confidence self-adversary decision. The user's instruction was
+ * "only if you're still not confident, then ask the user" — so escalation
+ * IS the contract when uncertainty remains.
+ */
+
+const DEFAULT_MAX_ITERATIONS = 8;
+const DEFAULT_TARGET_CONFIDENCE = 95;
+const DEFAULT_GENERATOR_MODEL = 'anthropic:claude-sonnet-4-6';
+const DEFAULT_ADVERSARY_MODEL = 'anthropic:claude-3-5-haiku-latest';
+const MAX_CONTEXT_CHARS = 8000;
+const MAX_TOKENS_GEN = 1200;
+const MAX_TOKENS_ADV = 800;
+const TEMPERATURE = 0.0;
+
+const { DANGEROUS_KEYS } = require('./flow-io');
+
+function hasDangerousKeys(value) {
+  if (!value || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return value.some(hasDangerousKeys);
+  for (const key of Object.keys(value)) {
+    if (DANGEROUS_KEYS.has(key)) return true;
+    if (hasDangerousKeys(value[key])) return true;
+  }
+  return false;
+}
+
+function buildGeneratorPrompt({ question, context, iterationMemory }) {
+  const memoryBlock = iterationMemory.length === 0
+    ? '(no prior iterations)'
+    : iterationMemory.map((it, i) =>
+        `## Iteration ${i + 1}\nDecision: ${it.decision}\nConfidence: ${it.confidence}%\nWeak points (per adversary): ${it.adversaryCritique || '(no critique yet)'}`
+      ).join('\n\n');
+
+  return `You are the GENERATOR in a Self-Refine + Reflexion loop for an implementation-class decision.
+
+The user has asked WogiFlow to handle implementation-approach decisions WITHOUT asking the user every time — instead, you iterate with an adversary on a DIFFERENT model until you reach ≥95% confidence, then act. Asking the user is reserved for product/domain questions and genuine ambiguity that survives the loop.
+
+## Decision question
+${String(question || '').slice(0, MAX_CONTEXT_CHARS / 2)}
+
+## Surrounding context
+${String(context || '').slice(0, MAX_CONTEXT_CHARS / 2)}
+
+## Iteration memory (prior rounds in THIS loop)
+${memoryBlock}
+
+## Your task
+
+1. State the decision you would make right now.
+2. Give brief rationale (≤4 sentences) — anchored to the context and any adversary critiques in the memory.
+3. Score your own confidence 0-100 — be calibrated, not optimistic. If a key sub-claim is shaky, the overall confidence cannot be higher than the weakest sub-claim.
+4. List your weakest sub-claims (what an adversary would attack).
+
+Return JSON only, no prose, no markdown fences:
+{
+  "decision": "one-sentence final answer",
+  "rationale": "≤4 sentences, in plain text",
+  "confidence": 0-100,
+  "weakSubClaims": ["...", "..."]
+}
+
+Calibration rules:
+  - If you have not considered ≥2 alternatives, confidence ≤ 70.
+  - If a domain-specific fact is uncertain, confidence ≤ 80.
+  - Confidence ≥ 95 means: you've reasoned through alternatives, the rationale withstands obvious counterarguments, and the implementation is well-defined.
+  - You CANNOT ask the user — that path is structurally unavailable inside this loop.`;
+}
+
+function buildAdversaryPrompt({ question, context, candidate }) {
+  return `You are the ADVERSARY in a Self-Refine + Reflexion loop. A GENERATOR (different model) just produced a candidate decision. Your job: find the weakest spots.
+
+## Decision question
+${String(question || '').slice(0, MAX_CONTEXT_CHARS / 2)}
+
+## Surrounding context
+${String(context || '').slice(0, MAX_CONTEXT_CHARS / 2)}
+
+## Candidate decision
+Decision: ${candidate.decision}
+Rationale: ${candidate.rationale}
+Self-confidence: ${candidate.confidence}%
+Weak sub-claims (self-reported): ${(candidate.weakSubClaims || []).join('; ') || '(none)'}
+
+## Your task
+
+Be a sharp, specific critic. Don't restate the candidate — attack it.
+  1. Strongest counterargument or missed alternative (≤2 sentences).
+  2. Any sub-claim that the generator over-confidenced (≤2 sentences).
+  3. Adjusted-confidence estimate — what would YOU score it at, after considering the above?
+
+Return JSON only, no prose, no markdown fences:
+{
+  "critique": "the counterargument / missed alternative",
+  "overconfidentClaims": "the sub-claim issue, or 'none' if calibration is fair",
+  "adjustedConfidence": 0-100,
+  "verdict": "accept" | "revise" | "needs-user"
+}
+
+Verdict rules:
+  - "accept" — candidate is sound, confidence is calibrated, no significant weak points.
+  - "revise" — candidate has fixable issues; generator should refine.
+  - "needs-user" — genuine ambiguity / domain question that no amount of iteration resolves. Use sparingly.`;
+}
+
+function extractJson(raw) {
+  if (typeof raw !== 'string') return null;
+  const match = raw.match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  try {
+    const parsed = JSON.parse(match[0]);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    if (hasDangerousKeys(parsed)) return null;
+    return parsed;
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Run the self-adversary loop.
+ *
+ * @param {Object} opts
+ * @param {string} opts.question - The implementation-class question
+ * @param {string} [opts.context] - Surrounding context (files, decisions, etc.)
+ * @param {number} [opts.maxIterations=8]
+ * @param {number} [opts.targetConfidence=95]
+ * @param {string} [opts.generatorModel]
+ * @param {string} [opts.adversaryModel]
+ * @returns {Promise<{
+ *   classified: boolean,
+ *   escalate: boolean,
+ *   reason?: string,
+ *   decision?: string,
+ *   rationale?: string,
+ *   confidence?: number,
+ *   iterations?: Array,
+ *   iterationCount?: number,
+ *   targetConfidence?: number
+ * }>}
+ */
+async function runSelfAdversaryLoop(opts = {}) {
+  const question = typeof opts.question === 'string' ? opts.question.trim() : '';
+  if (!question) {
+    return { classified: false, escalate: true, reason: 'empty-question' };
+  }
+
+  const context = typeof opts.context === 'string' ? opts.context : '';
+  const maxIterations = Number.isFinite(opts.maxIterations) && opts.maxIterations > 0
+    ? Math.min(opts.maxIterations, 12)
+    : DEFAULT_MAX_ITERATIONS;
+  const targetConfidence = Number.isFinite(opts.targetConfidence)
+    ? Math.max(50, Math.min(99, opts.targetConfidence))
+    : DEFAULT_TARGET_CONFIDENCE;
+  const generatorModel = opts.generatorModel || DEFAULT_GENERATOR_MODEL;
+  const adversaryModel = opts.adversaryModel || DEFAULT_ADVERSARY_MODEL;
+
+  if (!process.env.ANTHROPIC_API_KEY) {
+    return { classified: false, escalate: true, reason: 'no-credentials' };
+  }
+
+  let callModel;
+  try {
+    ({ callModel } = require('./flow-model-caller'));
+  } catch (_err) {
+    return { classified: false, escalate: true, reason: 'no-model-caller' };
+  }
+
+  // In-process iteration memory ONLY (NEVER persist to disk — prevents
+  // the memory-injection attack vector noted in International AI Safety
+  // Report 2026).
+  const iterationMemory = [];
+
+  for (let i = 0; i < maxIterations; i++) {
+    // Generator pass
+    let genRaw;
+    try {
+      const r = await callModel(generatorModel, buildGeneratorPrompt({ question, context, iterationMemory }), {
+        temperature: TEMPERATURE,
+        maxTokens: MAX_TOKENS_GEN
+      });
+      genRaw = String(r?.response ?? r?.content ?? '').trim();
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[self-adversary-loop] generator iter ${i + 1} model error: ${err.message}`);
+      }
+      return { classified: false, escalate: true, reason: 'generator-error' };
+    }
+
+    const candidate = extractJson(genRaw);
+    if (!candidate || typeof candidate.decision !== 'string' || !Number.isFinite(candidate.confidence)) {
+      // Bad iteration — record skip and retry
+      iterationMemory.push({
+        decision: '(malformed generator output)',
+        confidence: 0,
+        adversaryCritique: null,
+        skipped: true
+      });
+      continue;
+    }
+    candidate.confidence = Math.max(0, Math.min(100, Math.round(candidate.confidence)));
+
+    // Adversary pass — on a DIFFERENT model
+    let advRaw;
+    try {
+      const r = await callModel(adversaryModel, buildAdversaryPrompt({ question, context, candidate }), {
+        temperature: TEMPERATURE,
+        maxTokens: MAX_TOKENS_ADV
+      });
+      advRaw = String(r?.response ?? r?.content ?? '').trim();
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[self-adversary-loop] adversary iter ${i + 1} model error: ${err.message}`);
+      }
+      // Adversary error: accept candidate as final WITHOUT adversary boost.
+      // If generator already says ≥ targetConfidence, take it; else escalate.
+      iterationMemory.push({
+        decision: candidate.decision,
+        rationale: candidate.rationale,
+        confidence: candidate.confidence,
+        adversaryCritique: null,
+        adversaryError: true
+      });
+      if (candidate.confidence >= targetConfidence) {
+        return buildSuccess(candidate, iterationMemory, targetConfidence);
+      }
+      return buildEscalate(candidate, iterationMemory, targetConfidence, 'adversary-error');
+    }
+
+    const critique = extractJson(advRaw);
+    const adjustedConfidence = critique && Number.isFinite(critique.adjustedConfidence)
+      ? Math.max(0, Math.min(100, Math.round(critique.adjustedConfidence)))
+      : candidate.confidence;
+    const verdict = critique?.verdict || 'revise';
+
+    iterationMemory.push({
+      decision: candidate.decision,
+      rationale: candidate.rationale,
+      confidence: candidate.confidence,
+      adjustedConfidence,
+      adversaryCritique: critique?.critique || '(adversary returned malformed JSON)',
+      overconfidentClaims: critique?.overconfidentClaims || 'unknown',
+      verdict
+    });
+
+    // Termination checks
+    if (verdict === 'needs-user') {
+      return buildEscalate(candidate, iterationMemory, targetConfidence, 'adversary-says-needs-user');
+    }
+    if (verdict === 'accept' && adjustedConfidence >= targetConfidence) {
+      return buildSuccess({ ...candidate, confidence: adjustedConfidence }, iterationMemory, targetConfidence);
+    }
+    if (adjustedConfidence >= targetConfidence) {
+      return buildSuccess({ ...candidate, confidence: adjustedConfidence }, iterationMemory, targetConfidence);
+    }
+    // Otherwise loop again with the critique in memory
+  }
+
+  // Max iterations exhausted without reaching threshold
+  const last = iterationMemory[iterationMemory.length - 1] || {};
+  return buildEscalate(
+    { decision: last.decision, rationale: last.rationale, confidence: last.adjustedConfidence || last.confidence || 0 },
+    iterationMemory,
+    targetConfidence,
+    'max-iterations-exhausted'
+  );
+}
+
+function buildSuccess(candidate, iterationMemory, targetConfidence) {
+  return {
+    classified: true,
+    escalate: false,
+    decision: candidate.decision,
+    rationale: candidate.rationale,
+    confidence: candidate.confidence,
+    iterations: iterationMemory,
+    iterationCount: iterationMemory.length,
+    targetConfidence
+  };
+}
+
+function buildEscalate(candidate, iterationMemory, targetConfidence, reason) {
+  return {
+    classified: true,
+    escalate: true,
+    reason,
+    decision: candidate.decision || null,
+    rationale: candidate.rationale || null,
+    confidence: candidate.confidence || 0,
+    iterations: iterationMemory,
+    iterationCount: iterationMemory.length,
+    targetConfidence
+  };
+}
+
+module.exports = {
+  runSelfAdversaryLoop,
+  buildGeneratorPrompt,
+  buildAdversaryPrompt,
+  extractJson,
+  hasDangerousKeys,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_TARGET_CONFIDENCE,
+  DEFAULT_GENERATOR_MODEL,
+  DEFAULT_ADVERSARY_MODEL
+};

package/scripts/hooks/core/deferral-gate.js

@@ -315,33 +315,100 @@ function checkWriteGate(filePath, newContentRaw, config) {
 }
 
 /**
- * Validate a Bash command against the deferral gate. Two-stage:
- *   Stage 1: does the command mention any target file basename?
- *   Stage 2: does the command also mention `deferred` literal substring?
- * If both → fail SAFE (block) unless we can parse the content and prove auth.
+ * Strip quoted regions + heredoc bodies from a Bash command so the structural
+ * regex below only sees actual shell tokens. Released v2.30.3 over-triggered
+ * because the previous regex matched markdown blockquote `> "text"` inside
+ * heredoc bodies of `gh release create --notes "$(cat <<'EOF'...EOF)"`.
  *
- * For v1 we don't deep-parse the bash command; we conservatively block any
- * Bash that touches a target file AND contains a deferral status literal,
- * pointing the AI at the Write/Edit path (which can be properly inspected).
+ * Best-effort: handles single-quoted, double-quoted, backtick, and heredoc
+ * patterns. Doesn't attempt full shell parsing.
+ */
+function stripQuotedContent(cmd) {
+  if (typeof cmd !== 'string') return '';
+  let stripped = cmd;
+  // Heredocs first (multiline) — replace body with a sentinel
+  stripped = stripped.replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\1\s*$/gm, ' <<HEREDOC>> ');
+  stripped = stripped.replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, ' <<HEREDOC>> ');
+  // Single-quoted strings
+  stripped = stripped.replace(/'[^']*'/g, "''");
+  // Backtick command substitution
+  stripped = stripped.replace(/`[^`]*`/g, '``');
+  // Double-quoted strings (allow escaped quotes inside)
+  stripped = stripped.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+  return stripped;
+}
+
+/**
+ * Validate a Bash command against the deferral gate.
+ *
+ * wf-4a5b7a6f rewrite (2026-05-11): previously this used three independent
+ * regex checks AND'd together, which over-triggered on commands that merely
+ * REFERENCED the target file and the word "deferred" as text content
+ * (markdown blockquotes, commit messages, gh release notes). The
+ * `>\s*[^&|]` part of `mutates` matched markdown blockquote syntax inside
+ * heredocs. The bare-word `\bdeferred\b` part of `mentionsDeferral` matched
+ * any prose mention of "deferred".
+ *
+ * Fix:
+ *   1. Run the structural mutation check on a QUOTE-STRIPPED command —
+ *      a `>` inside `"..."` or `'...'` is not a shell redirect.
+ *   2. Tighten the mutation check to require the target file be the WRITE
+ *      DESTINATION, not merely mentioned anywhere.
+ *   3. Tighten deferral-content detection to the JSON-shape pattern only;
+ *      drop the bare-word match.
+ *
+ * If the AI tries to actually mutate the file via Bash with deferred
+ * content, the gate still catches it. Prose mentions pass through.
  */
 function checkBashGate(command, config) {
   try {
     if (!isGateEnabled(config)) return { blocked: false };
     if (typeof command !== 'string' || !command) return { blocked: false };
 
-    const mentionsTarget = /last-(review|audit)\.json/.test(command);
-    if (!mentionsTarget) return { blocked: false };
-
-    // Heuristic: only block when the command appears to MUTATE the file
-    // (writeFileSync, redirection >, sed -i, etc.). Pure reads (cat, jq, grep)
-    // are allowed.
-    const mutates = /(?:writeFileSync|>\s*[^&|]|>>\s*[^&|]|sed\s+-i|tee\s+|fs\.write|rename(?:Sync)?)/.test(command);
-    if (!mutates) return { blocked: false };
-
-    const mentionsDeferral = /\bdeferred[-_a-zA-Z0-9]*\b|"status"\s*:\s*"(deferred|wont-?fix|skipped|dismissed)/i.test(command);
+    // Step 1: strip quoted/heredoc content for the SHELL-LEVEL structural
+    // check (catches `>`, `tee` in actual shell positions, not inside markdown).
+    const stripped = stripQuotedContent(command);
+
+    // Step 2: detect a mutation operation targeting the review/audit file
+    // SPECIFICALLY. The patterns require the target file to be the WRITE
+    // DESTINATION — not merely mentioned. We test against BOTH the stripped
+    // command (catches shell-level redirects) AND the original command
+    // (catches in-language constructs like `node -e "fs.writeFileSync(...)"`
+    // where the JS payload is inside double-quotes and would be stripped).
+    // The patterns themselves are tight enough that running on the original
+    // doesn't re-introduce the prose-mention false positives — they require
+    // a write-verb token (writeFileSync, tee, etc.) IMMEDIATELY before the
+    // file path.
+    const writeToTargetPatterns = [
+      /(?:>>?|>\|)\s+['"]?[^\s'"`|&;]*last-(?:review|audit)\.json/,
+      /\btee\b(?:\s+-[a-zA-Z]+)*\s+['"]?[^\s'"`|&;]*last-(?:review|audit)\.json/,
+      /\b(?:fs\.)?writeFileSync\s*\(\s*[`'"][^`'"]*last-(?:review|audit)\.json/,
+      /\bfs\.write[A-Z][a-zA-Z]*\s*\(\s*[`'"][^`'"]*last-(?:review|audit)\.json/,
+      /\bsed\s+-i\b[^|;&]*\blast-(?:review|audit)\.json/,
+      /\b(?:mv|cp|rename(?:Sync)?)\s+\S+\s+['"]?[^\s'"`|&;]*last-(?:review|audit)\.json/
+    ];
+    const mutatesTarget = writeToTargetPatterns.some(re => re.test(stripped) || re.test(command));
+    if (!mutatesTarget) return { blocked: false };
+
+    // Step 3: check the ORIGINAL command for deferred-status content. We
+    // accept TWO signals:
+    //   - Quoted value: "deferred" / 'deferred' / `deferred` — JSON, JS,
+    //     template-literal styles.
+    //   - Bare word `\bdeferred\b` (or wont-?fix, skipped, dismissed) — fallback
+    //     for cases where escaping mangles the quote chars (e.g. shell-escaped
+    //     `\"deferred\"` inside a `node -e` payload where the quote becomes
+    //     non-adjacent to the word).
+    //
+    // The earlier false-positive case (prose mentions in release notes) is
+    // already closed by the tightened mutation check above — we only reach
+    // this step when the command demonstrably writes TO the target file.
+    // At that point, ANY mention of the deferral keyword is genuinely
+    // suspicious; the gate should err on the side of blocking.
+    const quotedDeferral = /['"`](deferred(?:[-_][a-zA-Z0-9]+)?|wont-?fix|won-?t-?fix|skipped|dismissed)['"`]/i;
+    const bareDeferral = /\b(deferred(?:[-_][a-zA-Z0-9]+)?|wont-?fix|won-?t-?fix|skipped|dismissed)\b/i;
+    const mentionsDeferral = quotedDeferral.test(command) || bareDeferral.test(command);
     if (!mentionsDeferral) return { blocked: false };
 
-    // We can't easily extract and validate the new content from arbitrary bash.
     // Check auth: if the user has authorized deferrals, allow. Otherwise block.
     const authResult = isAuthorized([{ id: 'unspecified' }]);
     if (authResult.authorized) return { blocked: false };
@@ -393,6 +460,7 @@ module.exports = {
   // Core checks
   checkWriteGate,
   checkBashGate,
+  stripQuotedContent,
 
   // Auth API (used by classifier + CLI helper)
   loadAuth,

package/scripts/hooks/core/pre-tool-deps.js

@@ -149,6 +149,16 @@ function loadGateDeps() {
     if (process.env.DEBUG) console.error(`[Hook] Long-input-pending gate not loaded: ${_err.message}`);
   }
 
+  // wf-e399bd8d — Self-adversary gate. Intercepts AskUserQuestion for
+  // implementation-class questions, requires the AI to run a self-adversary
+  // loop first. Fail-open via _noop if module fails to load.
+  let checkSelfAdversaryGate = _noop;
+  try {
+    checkSelfAdversaryGate = require('./self-adversary-gate').checkSelfAdversaryGate;
+  } catch (_err) {
+    if (process.env.DEBUG) console.error(`[Hook] Self-adversary gate not loaded: ${_err.message}`);
+  }
+
   // CLI-agnostic helpers (not gates per se but consumed by the orchestrator)
   const { markSkillPending } = require('../../flow-durable-session');
   const { getConfig } = require('../../flow-utils');
@@ -183,6 +193,7 @@ function loadGateDeps() {
     checkStrikeGate, checkBugfixScope, checkScopeMutation,
     checkGitSafety, checkManagerBoundary, checkWorkerBoundary, checkPathDiscipline,
     checkLongInputPendingGate,
+    checkSelfAdversaryGate,
     // Side-effect helpers
     markSkillPending,
     // Config + runtime

package/scripts/hooks/core/pre-tool-orchestrator.js

@@ -347,6 +347,27 @@ function runPreToolGates(ctx, deps) {
     }
   }
 
+  // wf-e399bd8d — Self-adversary gate. If the AI is about to invoke
+  // AskUserQuestion with an implementation-class question, block it
+  // and require the self-adversary loop to run first. Product /
+  // architecture / sensitive questions pass through. Fail-open: any
+  // error allows the call.
+  if (toolName === 'AskUserQuestion' && typeof deps.checkSelfAdversaryGate === 'function') {
+    try {
+      const saResult = deps.checkSelfAdversaryGate(toolName, toolInput, config);
+      if (saResult.blocked) {
+        return {
+          allowed: false,
+          blocked: true,
+          reason: saResult.reason,
+          message: saResult.message,
+        };
+      }
+    } catch (err) {
+      if (process.env.DEBUG) console.error(`[Hook] Self-adversary gate error (fail-open): ${err.message}`);
+    }
+  }
+
   // Long-input-pending gate (P11.6 mechanical layer): if the prior
   // UserPromptSubmit hook flagged this prompt as long-form-without-source-link
   // and wrote the pending marker, block any mutating tool until extract-review

package/scripts/hooks/core/self-adversary-gate.js

@@ -0,0 +1,292 @@
+'use strict';
+
+/**
+ * Wogi Flow — Self-Adversary PreToolUse Gate (wf-e399bd8d)
+ *
+ * Intercepts AskUserQuestion tool calls. If the question classifier
+ * returns IMPLEMENTATION with high confidence AND no recent self-
+ * adversary loop completion marker exists, BLOCK the call with
+ * instructions to run the loop first.
+ *
+ * State markers used:
+ *   .workflow/state/self-adversary-complete.json
+ *     Written by the loop when it produces a confident decision.
+ *     Single-use; cleared on consumption.
+ *     Shape:
+ *       {
+ *         completedAt: ISO timestamp,
+ *         questionHash: SHA-256-hex (first 16) of the original question,
+ *         decision, confidence, iterationCount,
+ *         expiresAt: ISO timestamp (5 min TTL)
+ *       }
+ *
+ *   .workflow/state/self-adversary-escalation.json
+ *     Written by the loop when iteration exhausts. Indicates the AI
+ *     DID iterate but still needs the user. Allows AskUserQuestion to
+ *     pass through without re-running the loop. Single-use, 5 min TTL.
+ *
+ * Note: the classifier is async (Haiku call). PreToolUse hooks must
+ * return promptly. Two options:
+ *   A) Block all AskUserQuestion calls if classifier hasn't pre-run,
+ *      requiring the AI to explicitly invoke the loop first.
+ *   B) Run classifier inline (async) and block based on result.
+ *
+ * Approach: (A) primary path, with a synchronous heuristic fallback
+ * that catches obvious implementation phrasings. The synchronous
+ * heuristic uses keyword presence (NOT user-input parsing — this is
+ * AI-authored question text, the "no regex on user answers" rule
+ * doesn't apply). The classifier itself is invoked from the user-
+ * prompt-submit hook (where async is fine) OR by the AI explicitly
+ * via the wogi-self-adversary skill.
+ *
+ * Fail-open: any error → allow the AskUserQuestion through.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { PATHS } = require('../../flow-utils');
+const { safeJsonParse } = require('../../flow-io');
+
+const COMPLETE_FILE = 'self-adversary-complete.json';
+const ESCALATION_FILE = 'self-adversary-escalation.json';
+const DEFAULT_TTL_SECONDS = 300; // 5 min
+
+function getCompletePath() { return path.join(PATHS.state, COMPLETE_FILE); }
+function getEscalationPath() { return path.join(PATHS.state, ESCALATION_FILE); }
+
+function hashQuestion(text) {
+  if (typeof text !== 'string') return '';
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+function isGateEnabled(config) {
+  const cfg = config?.selfAdversaryGate;
+  if (cfg === false) return false;
+  if (cfg && typeof cfg === 'object' && cfg.enabled === false) return false;
+  return true;
+}
+
+function loadMarker(filePath) {
+  const data = safeJsonParse(filePath, null);
+  if (!data || typeof data !== 'object') return null;
+  if (data.expiresAt) {
+    const exp = Date.parse(data.expiresAt);
+    if (Number.isFinite(exp) && exp < Date.now()) return null;
+  }
+  return data;
+}
+
+function consumeMarker(filePath) {
+  try { fs.unlinkSync(filePath); } catch (_err) { /* fine */ }
+}
+
+function writeCompletionMarker({ question, decision, confidence, iterationCount, ttlSec }) {
+  try {
+    const ttl = Number.isFinite(ttlSec) ? ttlSec : DEFAULT_TTL_SECONDS;
+    const now = Date.now();
+    const payload = {
+      version: 1,
+      completedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + ttl * 1000).toISOString(),
+      questionHash: hashQuestion(question),
+      decision: typeof decision === 'string' ? decision.slice(0, 500) : '',
+      confidence: Number.isFinite(confidence) ? Math.round(confidence) : 0,
+      iterationCount: Number.isFinite(iterationCount) ? iterationCount : 0
+    };
+    fs.mkdirSync(path.dirname(getCompletePath()), { recursive: true });
+    fs.writeFileSync(getCompletePath(), JSON.stringify(payload, null, 2));
+    return payload;
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[self-adversary-gate] writeCompletionMarker failed: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+function writeEscalationMarker({ question, decision, confidence, iterationCount, reason, ttlSec }) {
+  try {
+    const ttl = Number.isFinite(ttlSec) ? ttlSec : DEFAULT_TTL_SECONDS;
+    const now = Date.now();
+    const payload = {
+      version: 1,
+      escalatedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + ttl * 1000).toISOString(),
+      questionHash: hashQuestion(question),
+      reason: typeof reason === 'string' ? reason : 'unknown',
+      bestDecision: typeof decision === 'string' ? decision.slice(0, 500) : '',
+      finalConfidence: Number.isFinite(confidence) ? Math.round(confidence) : 0,
+      iterationCount: Number.isFinite(iterationCount) ? iterationCount : 0
+    };
+    fs.mkdirSync(path.dirname(getEscalationPath()), { recursive: true });
+    fs.writeFileSync(getEscalationPath(), JSON.stringify(payload, null, 2));
+    return payload;
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[self-adversary-gate] writeEscalationMarker failed: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Synchronous heuristic: does this question text LOOK implementation-class?
+ * Used as a fallback when the async classifier hasn't run. Conservative —
+ * defaults to NOT-implementation when ambiguous so AskUserQuestion passes.
+ * This is NOT user-input parsing (the text is AI-authored), so keyword
+ * matching is acceptable here. The async classifier provides the
+ * authoritative answer; this heuristic just catches the obvious cases.
+ */
+const IMPLEMENTATION_HEURISTIC_KEYWORDS = [
+  /\bmap\(\)\s+(?:or|vs)\s+for(?:-loop)?/i,
+  /\bwhich\s+(?:library|framework|algorithm|approach|pattern)\b/i,
+  /\bshould\s+(?:i|we)\s+use\s+\w+\s+or\s+\w+/i,
+  /\b(?:naming|name)\s+(?:convention|this|the\s+\w+)/i,
+  /\b(?:refactor|extract|inline)\s+(?:this|the)\b/i,
+  /\btest\s+(?:framework|library)\b/i,
+  /\berror\s+handling\s+(?:approach|pattern|style)/i,
+  /\bcode\s+(?:style|organization|structure)\b/i
+];
+
+const PRODUCT_HEURISTIC_KEYWORDS = [
+  /\bwhat\s+(?:should|do)\s+(?:users?|customers?)\b/i,
+  /\b(?:business|product)\s+(?:rule|decision|requirement)\b/i,
+  /\bcounts?\s+as\s+(?:done|complete|valid)\b/i,
+  /\bwhich\s+(?:behavior|outcome)\s+(?:do\s+you|should)\s+(?:want|prefer)\b/i,
+  /\b(?:delete|drop|truncate|remove|destroy)\b.*\b(?:data|table|migration|user)/i
+];
+
+function heuristicCategory(questionText) {
+  if (typeof questionText !== 'string') return 'unknown';
+  for (const re of PRODUCT_HEURISTIC_KEYWORDS) {
+    if (re.test(questionText)) return 'product';
+  }
+  for (const re of IMPLEMENTATION_HEURISTIC_KEYWORDS) {
+    if (re.test(questionText)) return 'implementation';
+  }
+  return 'unknown';
+}
+
+/**
+ * PreToolUse intercept on AskUserQuestion. Returns { blocked: bool, message? }.
+ *
+ * Decision tree:
+ *   1. Gate disabled → allow.
+ *   2. Tool is not AskUserQuestion → allow.
+ *   3. Escalation marker present for this question → allow (loop already ran).
+ *   4. Completion marker present for this question → allow (AI may follow up).
+ *   5. Sync heuristic → 'implementation' → block with loop-first instructions.
+ *   6. Otherwise → allow.
+ *
+ * The classifier itself (Haiku call) lives in flow-impl-question-classifier.js
+ * and is invoked by the `wogi-self-adversary` skill or by the user-prompt-
+ * submit hook for upstream classification — NOT from this synchronous gate.
+ */
+function checkSelfAdversaryGate(toolName, toolInput, config) {
+  try {
+    if (!isGateEnabled(config)) return { blocked: false };
+    if (toolName !== 'AskUserQuestion') return { blocked: false };
+
+    // Extract question text from the tool input shape (Claude Code's
+    // AskUserQuestion accepts a `questions` array).
+    let questionText = '';
+    if (toolInput && Array.isArray(toolInput.questions) && toolInput.questions.length > 0) {
+      const parts = [];
+      for (const q of toolInput.questions) {
+        if (q && typeof q.question === 'string') parts.push(q.question);
+      }
+      questionText = parts.join('\n');
+    } else if (toolInput && typeof toolInput.prompt === 'string') {
+      questionText = toolInput.prompt;
+    }
+    if (!questionText.trim()) return { blocked: false };
+
+    const qHash = hashQuestion(questionText);
+
+    // Check escalation marker
+    const escalation = loadMarker(getEscalationPath());
+    if (escalation && escalation.questionHash === qHash) {
+      // Consume and allow — the loop already ran and confirmed user is needed.
+      consumeMarker(getEscalationPath());
+      return { blocked: false, reason: 'escalation-marker-consumed' };
+    }
+
+    // Check completion marker — AI already decided via loop, this AskUserQuestion
+    // is a follow-up (e.g., "I decided X, but did you want Y instead?")
+    const complete = loadMarker(getCompletePath());
+    if (complete && complete.questionHash === qHash) {
+      consumeMarker(getCompletePath());
+      return { blocked: false, reason: 'completion-marker-consumed' };
+    }
+
+    // Sync heuristic
+    const heuristic = heuristicCategory(questionText);
+    if (heuristic !== 'implementation') {
+      return { blocked: false, reason: `heuristic-${heuristic}` };
+    }
+
+    // Heuristic says implementation — block and require loop.
+    return {
+      blocked: true,
+      reason: 'implementation-heuristic',
+      message: buildBlockMessage(questionText, qHash)
+    };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[self-adversary-gate] checkSelfAdversaryGate error (fail-open): ${err.message}`);
+    }
+    return { blocked: false };
+  }
+}
+
+function buildBlockMessage(questionText, qHash) {
+  const preview = questionText.slice(0, 240);
+  return [
+    'BLOCKED: AskUserQuestion looks like an implementation-class question.',
+    '',
+    'WogiFlow user directive (wf-e399bd8d): when you have doubt about an',
+    'implementation decision (code structure, library choice, naming,',
+    'refactor mechanics, etc.), self-adversary FIRST — iterate generator',
+    'and adversary on different models until ≥95% confidence. Only escalate',
+    'to the user if confidence stays low after the loop.',
+    '',
+    `Question intercepted: "${preview}${questionText.length > 240 ? '…' : ''}"`,
+    `Question hash: ${qHash}`,
+    '',
+    'How to proceed:',
+    '  1. RECOMMENDED — invoke the self-adversary skill:',
+    '       Skill(skill="wogi-self-adversary", args="<the question + brief context>")',
+    '     The skill runs the loop, writes a completion or escalation marker,',
+    '     then either acts on the high-confidence decision or re-issues the',
+    '     AskUserQuestion (which will now pass).',
+    '',
+    '  2. ESCAPE HATCH — if this is genuinely product / architecture /',
+    '     sensitive, the heuristic is wrong. Re-phrase the question to make',
+    '     the product-domain nature explicit (e.g., reference the user as',
+    '     decision-maker, name business constraints), and try again.',
+    '',
+    '  3. OVERRIDE — set the question metadata to bypass (advanced only).',
+    '',
+    'See: scripts/hooks/core/self-adversary-gate.js, wf-e399bd8d.'
+  ].join('\n');
+}
+
+module.exports = {
+  checkSelfAdversaryGate,
+  hashQuestion,
+  isGateEnabled,
+  loadMarker,
+  consumeMarker,
+  writeCompletionMarker,
+  writeEscalationMarker,
+  heuristicCategory,
+  getCompletePath,
+  getEscalationPath,
+  COMPLETE_FILE,
+  ESCALATION_FILE,
+  DEFAULT_TTL_SECONDS,
+  IMPLEMENTATION_HEURISTIC_KEYWORDS,
+  PRODUCT_HEURISTIC_KEYWORDS
+};