wogiflow 2.30.4 → 2.31.1

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

@@ -0,0 +1,295 @@
+'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 '';
+  // wf-6e31850e (S-4): use 32-char (128-bit) instead of 16-char (64-bit).
+  // 64-bit was below NIST collision-resistance recommendation; 128-bit is
+  // standard. Birthday-bound collision moves from ~2^32 to ~2^64 questions.
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 32);
+}
+
+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
+};

package/scripts/hooks/core/session-start-orchestrator.js

@@ -0,0 +1,269 @@
+'use strict';
+
+/**
+ * Wogi Flow — SessionStart Orchestrator (wf-6e31850e A-3)
+ *
+ * Extracted from scripts/hooks/entry/claude-code/session-start.js to bring
+ * that entry file under the 120-LOC budget per
+ * .claude/rules/architecture/hook-three-layer.md.
+ *
+ * Same control flow as before. Entry session-start.js is now a thin
+ * pass-through that imports boot-instrumentation helpers + this orchestrator.
+ */
+
+const { gatherSessionContext } = require('./session-context');
+const { setCliSessionId, clearStaleCurrentTaskAsync, resetSessionTaskCounter } = require('../../flow-session-state');
+const { checkAndResetStalePhase } = require('./phase-gate');
+const { setRoutingPending } = require('./routing-gate');
+const { getConfig } = require('../../flow-utils');
+
+let autoSyncBridge = null;
+function getAutoSyncBridge() {
+  if (!autoSyncBridge) {
+    try {
+      autoSyncBridge = require('../../flow-bridge-state').autoSyncBridge;
+    } catch (_err) {
+      autoSyncBridge = async () => ({ synced: false, reason: 'unavailable' });
+    }
+  }
+  return autoSyncBridge;
+}
+
+async function orchestrateSessionStart({ parsedInput, bootMark, bootTime }) {
+  bootMark('SessionStart hook entered');
+
+  const bridgeSyncPromise = bootTime('bridge auto-sync', async () => {
+    try {
+      const syncFn = getAutoSyncBridge();
+      await syncFn('claude-code', { silent: true });
+    } catch (err) {
+      if (process.env.DEBUG) console.error(`[session-start] Bridge auto-sync failed: ${err.message}`);
+    }
+  });
+  await bridgeSyncPromise;
+  bootMark('after bridge sync');
+
+  // wf-b8839d99: Refresh standing no-defer pin from decisions.md policy.
+  try {
+    const { refreshFromPolicy } = require('./no-defer-policy');
+    const r = refreshFromPolicy();
+    if (r.refreshed && process.env.DEBUG) {
+      console.error(`[session-start] Refreshed no-defer pin from policy: ${r.header}`);
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] no-defer policy refresh failed: ${err.message}`);
+  }
+
+  // CLAUDE.md drift detection
+  let driftDetected = false;
+  let driftMarkerMissing = false;
+  try {
+    const { checkClaudeMdDrift } = require('../../flow-bridge-state');
+    const drift = checkClaudeMdDrift();
+    if (drift.drifted && drift.reason === 'content-changed') {
+      if (process.env.DEBUG) console.error('[session-start] CLAUDE.md drift detected — content changed since last sync');
+      driftDetected = true;
+    } else if (drift.drifted && drift.reason === 'marker-missing') {
+      if (process.env.DEBUG) console.error('[session-start] CLAUDE.md appears manually maintained (no generation marker)');
+      driftDetected = true;
+      driftMarkerMissing = true;
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Drift detection failed: ${err.message}`);
+  }
+
+  // Version compatibility checks (parallelized)
+  let versionWarning = null;
+  let updateWarning = null;
+  await bootTime('version checks', async () => {
+    try {
+      const { checkClaudeCodeVersionOnce, checkWogiFlowUpdateOnce } = require('../../flow-version-check');
+      const [vw, uw] = await Promise.all([
+        (async () => { try { return await checkClaudeCodeVersionOnce(); } catch (_err) { return null; } })(),
+        (async () => { try { return await checkWogiFlowUpdateOnce(); } catch (_err) { return null; } })()
+      ]);
+      versionWarning = vw;
+      updateWarning = uw;
+    } catch (err) {
+      if (process.env.DEBUG) console.error(`[session-start] Version check failed: ${err.message}`);
+    }
+  });
+  bootMark('after version checks');
+
+  // Batch 1: Independent pre-context operations
+  let scriptWarnings = [];
+  try {
+    const wasReset = checkAndResetStalePhase();
+    if (wasReset && process.env.DEBUG) console.error('[session-start] Reset stale workflow phase to idle');
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Failed to check stale phase: ${err.message}`);
+  }
+  try { resetSessionTaskCounter(); } catch (_err) { /* non-blocking */ }
+  try {
+    const routingResult = setRoutingPending();
+    if (process.env.DEBUG) console.error(`[session-start] Set routing-pending: ${routingResult.reason}`);
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Failed to set routing-pending: ${err.message}`);
+  }
+  try {
+    const { validateScripts } = require('../../flow-script-resolver');
+    scriptWarnings = validateScripts();
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Script validation failed: ${err.message}`);
+  }
+
+  // BUG-005: Create durable-session.json for active tasks on session start.
+  try {
+    const { getReadyData } = require('../../flow-utils');
+    const readyData = getReadyData();
+    if (Array.isArray(readyData.inProgress) && readyData.inProgress.length > 0) {
+      const task = readyData.inProgress[0];
+      const taskId = task && task.id;
+      if (taskId) {
+        const { loadDurableSession, createDurableSession } = require('../../flow-durable-session');
+        const existing = loadDurableSession();
+        if (!existing || existing.taskId !== taskId) {
+          const criteria = task.acceptanceCriteria || task.scenarios || [];
+          const steps = Array.isArray(criteria) ? criteria : [];
+          const sessionSteps = steps.length > 0 ? steps : [task.title || taskId];
+          createDurableSession(taskId, 'task', sessionSteps);
+          if (process.env.DEBUG) console.error(`[session-start] Created durable session for active task ${taskId}`);
+        }
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Durable session init failed: ${err.message}`);
+  }
+
+  // Async pre-ops batched with gatherSessionContext
+  const asyncPreOps = [];
+  if (parsedInput.sessionId) {
+    asyncPreOps.push(setCliSessionId(parsedInput.sessionId).catch(err => {
+      if (process.env.DEBUG) console.error(`[session-start] Failed to store session ID: ${err.message}`);
+    }));
+  }
+  asyncPreOps.push(clearStaleCurrentTaskAsync().catch(err => {
+    if (process.env.DEBUG) console.error(`[session-start] Failed to clear stale task: ${err.message}`);
+  }));
+
+  bootMark('before gatherSessionContext + asyncPreOps');
+  const [, coreResult] = await Promise.all([
+    Promise.all(asyncPreOps),
+    bootTime('gatherSessionContext', () => gatherSessionContext({
+      includeSuspended: true,
+      includeDecisions: true,
+      includeActivity: true
+    }))
+  ]);
+  bootMark('after gatherSessionContext + asyncPreOps');
+
+  // Batch 2: Post-context — plugin scan + community pull (parallel, non-blocking)
+  await bootTime('postContextOps (plugin-scan + community-pull)', () => Promise.all([
+    runPluginAutoScan(coreResult),
+    runCommunityPull(coreResult)
+  ]));
+  bootMark('after postContextOps');
+
+  // Inject warnings into context
+  if (scriptWarnings.length > 0 && coreResult?.context) {
+    coreResult.context.scriptWarnings = scriptWarnings.map(w => w.message);
+  }
+  if (versionWarning && coreResult?.context) coreResult.context.versionWarning = versionWarning;
+  if (updateWarning && coreResult?.context) coreResult.context.updateWarning = updateWarning;
+  if (driftDetected && coreResult?.context) {
+    coreResult.context.driftWarning = driftMarkerMissing
+      ? 'CLAUDE.md appears to have been manually edited (generation marker missing). Was this intentional? If yes, WogiFlow will respect your custom CLAUDE.md. If not, run `flow bridge sync` to regenerate from template.'
+      : 'CLAUDE.md content has changed since the last bridge sync. Was this intentional? If yes, WogiFlow will preserve your changes. If not, run `flow bridge sync` to regenerate from template.';
+  }
+
+  // State file drift detection
+  try {
+    const { detectDrift, saveSnapshot, formatDriftReport } = require('../../flow-state-drift-detector');
+    const driftResult = detectDrift();
+    if (driftResult.hasDrift && coreResult?.context) {
+      coreResult.context.stateDriftWarning = formatDriftReport(driftResult);
+    }
+    saveSnapshot();
+  } catch (_err) {
+    if (process.env.DEBUG) console.error(`[session-start] State drift detection failed: ${_err.message}`);
+  }
+
+  // Workspace worker restart-handoff
+  await bootTime('worker session-start handler', async () => {
+    try {
+      const { handleWorkerSessionStart } = require('./session-start-worker');
+      const workerResult = handleWorkerSessionStart();
+      if (workerResult.context && coreResult?.context) {
+        if (workerResult.branch === 'auto-resume') {
+          coreResult.context.workerAutoResume = workerResult.context;
+        } else if (workerResult.branch === 'announce-ready') {
+          coreResult.context.workerReadyAnnounce = workerResult.context;
+        }
+      }
+    } catch (err) {
+      if (process.env.DEBUG) console.error(`[session-start] Worker session-start handler failed: ${err.message}`);
+    }
+  });
+  bootMark('SessionStart hook returning');
+
+  return coreResult;
+}
+
+async function runPluginAutoScan(coreResult) {
+  try {
+    const config = getConfig();
+    if (!config.plugins?.enabled || !config.plugins?.autoScanOnSessionStart) return;
+    const { scanUnregisteredMcpServers, registerPlugin, deactivateStaleMcpPlugins, listPlugins } = require('../../flow-plugin-registry');
+
+    const unregistered = scanUnregisteredMcpServers();
+    for (const server of unregistered) {
+      registerPlugin({
+        name: server.serverName,
+        description: `Auto-discovered MCP server: ${server.serverName}`,
+        source: 'auto-scan',
+        triggers: [`use ${server.serverName}`, `send to ${server.serverName}`, server.serverName],
+        capabilities: [],
+        metadata: { mcpServer: server.serverName }
+      });
+      if (process.env.DEBUG) console.error(`[session-start] Auto-registered plugin: ${server.serverName}`);
+    }
+    const deactivated = deactivateStaleMcpPlugins();
+    if (deactivated.length > 0 && process.env.DEBUG) {
+      console.error(`[session-start] Deactivated ${deactivated.length} stale plugin(s): ${deactivated.join(', ')}`);
+    }
+    if (coreResult?.context) {
+      const activePlugins = listPlugins({ activeOnly: true });
+      if (unregistered.length > 0 || activePlugins.length > 0) {
+        coreResult.context.pluginScan = {
+          newlyRegistered: unregistered.map(s => s.serverName),
+          activePlugins: activePlugins.map(p => ({ name: p.name, capabilities: (p.capabilities || []).length }))
+        };
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Plugin auto-scan failed: ${err.message}`);
+  }
+}
+
+async function runCommunityPull(coreResult) {
+  try {
+    const communityConfig = getConfig();
+    if (!communityConfig.community?.enabled) return;
+    const community = require('../../flow-community');
+    community.retryPendingSuggestions(communityConfig).catch(() => {});
+    if (communityConfig.community?.pullOnSessionStart !== false) {
+      const knowledge = await community.pullFromServer(communityConfig);
+      if (knowledge && coreResult?.context) {
+        coreResult.context.communityKnowledge = knowledge;
+        try { community.mergeCommunityKnowledge(knowledge, communityConfig); }
+        catch (err) {
+          if (process.env.DEBUG) console.error(`[session-start] Community merge failed: ${err.message}`);
+        }
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[session-start] Community pull failed: ${err.message}`);
+  }
+}
+
+module.exports = { orchestrateSessionStart };

package/scripts/hooks/core/stop-orchestrator.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Wogi Flow — Stop-Hook Orchestrator (wf-6e31850e A-3)
+ *
+ * Extracted from scripts/hooks/entry/claude-code/stop.js to bring that entry
+ * file under the 120-LOC budget per .claude/rules/architecture/hook-three-layer.md.
+ *
+ * Same control flow as before; just moved here. Entry stop.js is now a thin
+ * pass-through that imports and delegates.
+ *
+ * Returns the Stop-hook result `{ __raw?, continue?, stopReason?, ... }`.
+ */
+
+const { isRoutingPending, incrementStopAttempts } = require('./routing-gate');
+const { checkLoopExit } = require('./loop-check');
+
+async function orchestrateStop({ parsedInput }) {
+  const activeGates = {};
+  try {
+    const { isLongInputPending } = require('./long-input-enforcement');
+    activeGates['long-input-pending'] = isLongInputPending();
+  } catch (_err) { /* fail-open */ }
+
+  let recoveryGraceActive = false;
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const { PATHS } = require('../../flow-utils');
+    const gracePath = path.join(PATHS.state, 'routing-recovery-grace.json');
+    if (fs.existsSync(gracePath)) {
+      const raw = fs.readFileSync(gracePath, 'utf-8');
+      const data = JSON.parse(raw);
+      if (data?.expiresAt && Date.parse(data.expiresAt) > Date.now()) {
+        recoveryGraceActive = true;
+      } else {
+        try { fs.unlinkSync(gracePath); } catch (_err) { /* fine */ }
+      }
+    }
+  } catch (_err) { /* fail-open */ }
+
+  let orchestratorTopGate = null;
+  try {
+    const { pickStopHookGate } = require('./gate-orchestrator');
+    const { topGateId } = pickStopHookGate({
+      'long-input-pending': activeGates['long-input-pending'] === true
+    });
+    orchestratorTopGate = topGateId;
+  } catch (_err) { /* fail-open */ }
+  const longInputActive = orchestratorTopGate === 'long-input-pending';
+
+  try {
+    if (isRoutingPending() && !longInputActive && !recoveryGraceActive) {
+      const { cleared, attempts } = incrementStopAttempts(10);
+      if (cleared) {
+        if (process.env.DEBUG) {
+          console.error(`[Stop] Max routing enforcement attempts reached (${attempts}), surfacing to user`);
+        }
+        return {
+          __raw: true,
+          continue: false,
+          stopReason: `ROUTING VIOLATION (unrecoverable): max ${attempts} attempts exceeded. The AI failed to call Skill(skill="wogi-start") after ${attempts} stop attempts. Manual review required — this may indicate a stuck routing flag or a session that bypassed /wogi-start through context compaction. To unstick: invoke /wogi-start manually, or check .workflow/state/routing-pending.json.`
+        };
+      } else {
+        return {
+          __raw: true,
+          continue: true,
+          stopReason: [
+            `ROUTING VIOLATION (attempt ${attempts}/10): You MUST call Skill(skill="wogi-start") before responding.`,
+            '',
+            'Call Skill(skill="wogi-start", args="<user\'s message>") NOW. No text. No explanation. Just the Skill tool call.'
+          ].join('\n')
+        };
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[Stop] Routing check error (fail-closed, forcing continue): ${err.message}`);
+    }
+    return {
+      __raw: true,
+      continue: true,
+      stopReason: 'Routing enforcement check encountered an error. Please invoke /wogi-start with your request.'
+    };
+  }
+
+  const workspaceNotify = require('./workspace-stop-notify');
+  await workspaceNotify.notifyWorkerStopped();
+
+  const restartCoordinator = require('./task-boundary-restart-coordinator');
+  const restartResult = await restartCoordinator.handleTaskBoundaryRestart({ parsedInput });
+  if (restartResult?.shouldReturn) return restartResult.result;
+
+  // Research-Required Stop-Hook Gate
+  try {
+    if (longInputActive) {
+      // skip — defer to long-input remediation
+    } else {
+      const { checkResearchRequiredGate } = require('./research-required-gate');
+      const { getConfig } = require('../../flow-utils');
+      const config = getConfig();
+      const result = checkResearchRequiredGate({
+        transcriptPath: parsedInput?.transcriptPath,
+        config
+      });
+      if (result.blocked) {
+        if (result.hardStop) return { __raw: true, continue: false, stopReason: result.message };
+        return { __raw: true, continue: true, stopReason: result.message };
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[Stop] Research-required gate error (fail-open): ${err.message}`);
+  }
+
+  // Workspace + worker gates
+  const workspaceGates = require('./workspace-stop-gates');
+  const wsResult = await workspaceGates.checkWorkspaceStopGates({ parsedInput });
+  if (wsResult?.shouldReturn) return wsResult.result;
+
+  return await checkLoopExit();
+}
+
+module.exports = { orchestrateStop };