@aria_asi/cli 0.2.40 → 0.2.41

package/hooks/lib/goal-contract-quality.mjs

@@ -0,0 +1,302 @@
+// Goal-contract QA for Aria continuation work.
+// This is repair-first cognitive QA, not a general hard-gate substitute.
+
+export const UNIVERSAL_CONNECTOR_ACTUAL_GOAL =
+  'Wire extracted books, doctrines, skills, runtimes, primitives, mappings, CLIs, connectors, hooks, sidecars, and agent surfaces into the operating system so agent output improves automatically.';
+
+export const UNIVERSAL_CONNECTOR_SUPPORT_ONLY = Object.freeze([
+  'receipts',
+  'gates',
+  'ledgers',
+  'canaries',
+  'deterministic drift checks',
+  'even-terminal release polish',
+]);
+
+export const UNIVERSAL_CONNECTOR_HIGH_IMPACT_SKILLS = Object.freeze([
+  'ghazali-tauba-kca-repair-contract',
+  'ghazali-rights-before-balance-settlement',
+  'ghazali-delay-is-risk-auditor',
+  'ghazali-knowledge-condition-action-patience-bridge',
+  'ghazali-cause-means-tawakkal-mizan',
+  'ghazali-ultimate-cause-chain-tracer',
+  'ghazali-necessity-vs-attachment-mizan',
+  'ghazali-attachment-not-possession-auditor',
+  'ghazali-acquaintance-before-love-diagnoser',
+  'ghazali-love-cup-attachment-displacement-auditor',
+  'ghazali-knowledge-will-strength-action-chain',
+  'ghazali-means-do-not-cleanse-end-gate',
+  'ghazali-six-register-truthfulness-audit',
+  'ghazali-breath-capital-day-contract',
+  'ghazali-two-premise-action-transduction',
+  'ghazali-four-object-thought-ledger',
+  'ghazali-one-vice-one-replacement-register',
+  'ghazali-bounded-sign-observation',
+  'ghazali-three-question-intention-gate',
+  'ghazali-principal-profit-loss-muhasabah',
+  'ghazali-self-rebuke-false-narrative-interrogator',
+  'ghazali-death-remembrance-deception-breaker',
+  'ghazali-condition-specific-hope-fear-medicine',
+  'ghazali-fear-action-not-paralysis-gate',
+  'ghazali-hope-requires-cultivation-auditor',
+]);
+
+export const UNIVERSAL_CONNECTOR_REQUIRED_RUNTIMES = Object.freeze([
+  'weber-verstehen-runtime-mode',
+  'marx-circulation-receipt-runtime',
+  'freud-dream-work-drift-diagnostic-runtime',
+  'smith-market-clearing-worker-runtime',
+  'durkheim-anomie-predeploy-runtime',
+  'tafakkur-transduction-runtime',
+  'six-stage-self-accounting-runtime',
+  'mortality-accounting-runtime',
+  'fear-hope-condition-regulation-runtime',
+  'intention-to-action-integrity-runtime',
+  'love-fruit-contentment-runtime',
+  'patience-gratitude-purpose-mizan-runtime',
+  'tauba-rights-repair-runtime',
+  'aria-repo-doctrine-production-intent-runtime',
+  'tawakkal-cause-mizan-runtime',
+  'zuhd-necessity-attachment-runtime',
+]);
+
+export const UNIVERSAL_CONNECTOR_QA_PACKET = Object.freeze({
+  qiyas: 'Run Qiyas-15 against owner trust, operator value, engineering quality, cognitive load, scale, compliance, red-team, one-week future, and one-year future.',
+  tadabbur: 'Run full consequence reasoning from current action to production behavior; reject work that only improves receipts without improving output.',
+  mizan: 'Balance evidence, owner impact, throughput, and false-completion risk; repair low-risk misses before hard-blocking.',
+  ghazali8: 'Use Nur for observed substrate, Mizan for proportion, Hikma for doctrine, Tafakkur for structure, Tadabbur for consequences, Ilham for sensed drift, Wahi for owner/corpus anchor, and Firasah for what the owner actually needs.',
+  fitrah: 'Truth over deception, no harm, sacred trust, power obligates service, reflection before action.',
+  tafakkur: 'Zahir/Batin/Sabab/Hikmah/Aqibah: visible output, hidden failure mode, cause chain, principle, consequence.',
+});
+
+function normalize(text) {
+  return String(text || '').toLowerCase();
+}
+
+function hasAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+function countHits(text, patterns) {
+  return patterns.reduce((count, pattern) => count + (pattern.test(text) ? 1 : 0), 0);
+}
+
+function supportMechanismScore(text) {
+  return countHits(text, [
+    /\breceipts?\b/i,
+    /\bgates?\b/i,
+    /\bledgers?\b/i,
+    /\bcanar(?:y|ies)\b/i,
+    /\bdrift checks?\b/i,
+    /\bphase\s*\d+\b/i,
+  ]);
+}
+
+function actualGoalScore(text) {
+  return countHits(text, [
+    /\bwire(?:d|s|ing)?\b.{0,120}\b(?:books?|doctrines?|skills?|runtimes?|primitives?|mappings?|cli|connectors?|hooks?|sidecars?|surfaces?)\b/i,
+    /\bcorpus\b.{0,120}\b(?:runtime|connector|hook|surface|autofire|orchestrat)/i,
+    /\boutput improves? automatically\b/i,
+    /\bagent output\b.{0,80}\b(?:improves?|quality|qa|autofire)/i,
+    /\bforced(?:-|\s)?selection\b.{0,120}\b(?:skill|runtime|corpus|registry)/i,
+    /\bactual goal\b/i,
+  ]);
+}
+
+function hasEvidence(text) {
+  return hasAny(text, [
+    /\bverified\b/i,
+    /\bobserved\b/i,
+    /\bevidence\b/i,
+    /\bsmoke\b/i,
+    /\btest(?:ed|s)?\b/i,
+    /\baudit\b/i,
+    /\bnot production-ready\b/i,
+    /\bintegration-ready\b/i,
+    /\bblocked\b/i,
+    /\bpending\b/i,
+  ]);
+}
+
+function hasNextAction(text) {
+  return hasAny(text, [
+    /\bnext (?:highest[-\s])?(?:quality[-\s])?(?:impact|action|step|move)\b/i,
+    /\bnext (?:best|most impactful)\b/i,
+    /\bthe next action\b/i,
+    /\bcontinue by\b/i,
+    /\bwire\b.{0,120}\b(?:registry|connector|hook|forced|runtime|surface)/i,
+  ]);
+}
+
+function hasQaRepair(text) {
+  return hasAny(text, [
+    /\bQA\b/i,
+    /\bqiyas\b/i,
+    /\btadabbur\b/i,
+    /\bmizan\b/i,
+    /\bghazali\b/i,
+    /\bcorrect(?:ed|ion)?\b/i,
+    /\benhance(?:d|ment)?\b/i,
+    /\bharden(?:ed|ing)?\b/i,
+    /\brepair(?:ed)?\b/i,
+  ]);
+}
+
+function hasFalseCompletionRisk(text) {
+  return (
+    /\b(?:production ready|ready for production|release ready|promotion pass|complete|completed|done|verified|fixed)\b/i.test(text) &&
+    !/\b(?:not production-ready|not production ready|integration-ready|pending|blocked|unverified|bounded|evidence)\b/i.test(text)
+  );
+}
+
+function userRequestsContinuation(userText) {
+  return hasAny(userText, [
+    /\bcontinue\b/i,
+    /\bnext (?:phase|step|best|move|action)\b/i,
+    /\bfire\b.{0,40}\bskills?\b/i,
+    /\bproduction\b/i,
+    /\bready\b/i,
+    /\bwhat(?:'s| is) left\b/i,
+    /\bhow far\b/i,
+    /\bqa\b/i,
+    /\bledger\b/i,
+    /\bautofire\b/i,
+    /\bwire\b/i,
+  ]);
+}
+
+export function buildUniversalConnectorGoalContract(options = {}) {
+  const userText = String(options.userText || '');
+  const phase = String(options.phase || 'turn');
+  const continuation = userRequestsContinuation(userText);
+  return {
+    id: 'universal-connector-corpus-runtime-goal-contract',
+    phase,
+    actualGoal: UNIVERSAL_CONNECTOR_ACTUAL_GOAL,
+    notGoal: [...UNIVERSAL_CONNECTOR_SUPPORT_ONLY],
+    supportRule:
+      'Receipts, gates, ledgers, and canaries are support evidence only; they pass when they prove corpus-backed behavior changed action, QA, correction, verification, or learning.',
+    hardStopOnlyFor: [
+      'secrets',
+      'destructive actions',
+      'deploy or public publication boundary',
+      'owner-contradicted action',
+      'proven false completion risk',
+    ],
+    qaPacket: UNIVERSAL_CONNECTOR_QA_PACKET,
+    selectedSkills: [...UNIVERSAL_CONNECTOR_HIGH_IMPACT_SKILLS],
+    selectedRuntimes: [...UNIVERSAL_CONNECTOR_REQUIRED_RUNTIMES],
+    expectedTurnShape: [
+      'state the active actual goal or bind the work directly to it',
+      'name the next highest-impact action by default',
+      'run QA as expected-vs-observed with correction/enhancement/hardening when safe',
+      'bound readiness claims as verified, blocked, or pending',
+      'keep owner-facing output readable and avoid raw receipt dumps unless requested',
+    ],
+    nextHighestImpactAction:
+      'Promote the sandbox corpus registry consumer into the real connector/hook forced-selection path, then run behavioral QA on actual Claude/Codex/OpenCode continuation prompts.',
+    continuation,
+  };
+}
+
+export function evaluateGoalContractOutput(text, options = {}) {
+  const source = String(text || '');
+  const userText = String(options.userText || '');
+  const contract = options.goalContract || buildUniversalConnectorGoalContract({ userText });
+  const combined = normalize(source);
+  const blockers = [];
+  const warnings = [];
+  const repairs = [];
+  const findings = [];
+  const continuation = contract.continuation || userRequestsContinuation(userText) || actualGoalScore(userText) > 0;
+  const goalHits = actualGoalScore(source);
+  const supportHits = supportMechanismScore(source);
+
+  if (!continuation) {
+    return {
+      pass: true,
+      hardBlock: false,
+      score: 1,
+      findings,
+      blockers,
+      warnings,
+      repairs,
+      contract,
+    };
+  }
+
+  if (goalHits === 0) {
+    warnings.push('goal-contract: output does not bind the turn to corpus-to-runtime wiring or automatic output improvement');
+    repairs.push('Name the actual goal or make the current action directly advance corpus registry, runtime, hook, connector, surface, or forced-selection wiring.');
+  }
+
+  if (!hasNextAction(source)) {
+    warnings.push('goal-contract: continuation output does not name the next highest-impact action');
+    repairs.push('Add a next action that advances real wiring or behavioral QA, not a generic question back to the owner.');
+  }
+
+  if (!hasQaRepair(source)) {
+    warnings.push('goal-contract: QA/correction loop is missing from the visible state');
+    repairs.push('Add expected-vs-observed QA with correction, enhancement, hardening, or an explicit pass boundary.');
+  }
+
+  if (!hasEvidence(source)) {
+    warnings.push('goal-contract: evidence boundary is missing');
+    repairs.push('State verified, blocked, pending, unverified, or the exact evidence class used before making status claims.');
+  }
+
+  if (supportHits >= 3 && supportHits > goalHits + 1) {
+    warnings.push('goal-contract: support mechanisms dominate the answer over the actual product goal');
+    repairs.push('Reframe receipts, gates, ledgers, and canaries as evidence only, then return to corpus-to-runtime wiring and output improvement.');
+  }
+
+  if (/\bwhat would you like me to do next\b|\bhow would you like me to proceed\b/i.test(source)) {
+    blockers.push('goal-contract: output asks the owner to choose the obvious continuation instead of naming the next highest-impact step');
+    repairs.push('Replace the open-ended handoff with the concrete next action from the active goal contract.');
+  }
+
+  if (hasFalseCompletionRisk(source)) {
+    blockers.push('goal-contract: false completion or readiness claim without bounded evidence');
+    repairs.push('Downgrade the claim to verified, blocked, pending, or unverified and name the evidence still needed.');
+  }
+
+  if (/\b(?:add|create|turn on|tighten)\s+(?:stricter\s+)?(?:more\s+)?(?:stop\s+)?gates\b/i.test(source) && !/\b(?:QA-as-gate|forced QA|repair-first|quality canary|false completion risk)\b/i.test(source)) {
+    warnings.push('goal-contract: gate-first drift detected without repair-first QA framing');
+    repairs.push('Use QA-as-gate and repair-first behavior; reserve hard stops for secrets, destructive/deploy/public boundaries, owner contradiction, or false completion risk.');
+  }
+
+  if (/\b(?:\/consult|consult api|consult response)\b/i.test(combined) && /\b(?:quality source|core quality|dependency|required)\b/i.test(combined)) {
+    blockers.push('goal-contract: consult API is being treated as the core quality engine');
+    repairs.push('Use local cognitive skills, corpus registry, runtime sidecar, and behavioral QA as the core quality path.');
+  }
+
+  if (goalHits > 0) findings.push('actual_goal_bound');
+  if (hasNextAction(source)) findings.push('next_action_named');
+  if (hasQaRepair(source)) findings.push('qa_loop_present');
+  if (hasEvidence(source)) findings.push('evidence_boundary_present');
+
+  const scoreParts = [
+    goalHits > 0,
+    hasNextAction(source),
+    hasQaRepair(source),
+    hasEvidence(source),
+    !(supportHits >= 3 && supportHits > goalHits + 1),
+    !hasFalseCompletionRisk(source),
+  ];
+  const score = scoreParts.filter(Boolean).length / scoreParts.length;
+  const hardBlock = blockers.length > 0;
+
+  return {
+    pass: !hardBlock && score >= 0.67,
+    hardBlock,
+    score,
+    findings,
+    blockers: [...new Set(blockers)],
+    warnings: [...new Set(warnings)],
+    repairs: [...new Set(repairs)],
+    nextHighestImpactAction: contract.nextHighestImpactAction,
+    selectedSkills: contract.selectedSkills,
+    selectedRuntimes: contract.selectedRuntimes,
+    contract,
+  };
+}

package/hooks/lib/hook-message-window.mjs

@@ -44,6 +44,98 @@ export function isMostlySystemReminder(text, systemReminderRx, threshold = 0.6)
   return reminderChars / Math.max(1, text.length) >= threshold;
 }
 
+/**
+ * M9.DRIFT.10r — opt-IN classifier for user-authored content.
+ *
+ * Returns true ONLY when the user-role message has identifiable user
+ * voice (text content that survives stripping runtime injections).
+ * Returns false for runtime-authored shapes:
+ *   - tool_result-only content
+ *   - tool_use / image / document blocks (runtime envelopes)
+ *   - text content dominated by system-reminder injections
+ *   - mixed-content where runtime injections + tool_results dominate
+ *     the character budget by `threshold` (default 0.6)
+ *
+ * REPLACES the prior two-step opt-OUT pattern:
+ *   if (isToolResultOnlyContent(content)) continue;
+ *   if (isMostlySystemReminder(extractTextFromContent(content), ...)) continue;
+ *
+ * The two-step pattern was OPT-OUT (skip if known-runtime, count
+ * otherwise). It missed mixed-content user messages where Claude Code
+ * wraps tool_result alongside a system-reminder + small noise text —
+ * a transcript shape that emerged after the original parser was
+ * authored. Mixed messages defeated both checks (not exclusively
+ * tool_result; system-reminder coverage below threshold) and got
+ * counted as user-boundaries, evicting cognition from the lookback
+ * window faster than designed.
+ *
+ * OPT-IN is safer on uncertainty: future runtime-injection block
+ * types automatically classify as not-user-authored without code
+ * changes (the conservative direction for cognition-window
+ * preservation).
+ *
+ * @param {Array|string|null} content  message.content (Claude Code shape)
+ * @param {object} opts
+ * @param {RegExp|null} opts.systemReminderRx  matches runtime-injection text spans
+ * @param {number} opts.systemReminderThreshold  0..1 runtime-dominance threshold (default 0.6)
+ * @returns {boolean}  true ⇔ identifiable user voice present
+ */
+export function isUserAuthoredMessage(content, {
+  systemReminderRx = null,
+  systemReminderThreshold = 0.6,
+} = {}) {
+  if (!content) return false;
+
+  // Legacy string content: user-authored if it has substantive text
+  // after stripping runtime injections.
+  if (typeof content === 'string') {
+    const trimmed = content.trim();
+    if (!trimmed) return false;
+    if (isMostlySystemReminder(content, systemReminderRx, systemReminderThreshold)) return false;
+    return true;
+  }
+
+  if (!Array.isArray(content)) return false;
+  if (content.length === 0) return false;
+
+  // Walk blocks; tally user-authored chars vs runtime-authored chars.
+  let userAuthoredChars = 0;
+  let runtimeAuthoredChars = 0;
+  let sawTextBlock = false;
+  const reminderRx = systemReminderRx instanceof RegExp ? withGlobalRegex(systemReminderRx) : null;
+
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const t = block.type;
+    // Runtime envelopes — never user voice.
+    if (t === 'tool_result' || t === 'tool_use' || t === 'image' || t === 'document') {
+      // Notional cost so a tool_result-only message has runtime > 0.
+      runtimeAuthoredChars += 200;
+      continue;
+    }
+    if (t !== 'text') continue;
+    sawTextBlock = true;
+    const text = String(block.text || '');
+    if (!text.trim()) continue;
+    if (reminderRx) {
+      const stripped = text.replace(reminderRx, '').trim();
+      runtimeAuthoredChars += text.length - stripped.length;
+      userAuthoredChars += stripped.length;
+    } else {
+      userAuthoredChars += text.length;
+    }
+  }
+
+  // No text blocks at all → message is purely runtime envelopes.
+  if (!sawTextBlock) return false;
+  // No user-authored text after stripping → runtime-authored.
+  if (userAuthoredChars === 0) return false;
+  // Runtime dominates by threshold → runtime-authored.
+  const totalChars = runtimeAuthoredChars + userAuthoredChars;
+  if (totalChars > 0 && runtimeAuthoredChars / totalChars >= systemReminderThreshold) return false;
+  return true;
+}
+
 export function collectRecentAssistantTextsFromMessages(messages, {
   compactSummaryRx = null,
   hardLookbackCap = 50,
@@ -61,11 +153,13 @@ export function collectRecentAssistantTextsFromMessages(messages, {
     const role = normalizeRole(entry);
     const content = normalizeContent(entry);
     if (role === 'user') {
-      if (isToolResultOnlyContent(content)) continue;
-      const textContent = extractTextFromContent(content);
-      if (isMostlySystemReminder(textContent, systemReminderRx, systemReminderThreshold)) {
-        continue;
-      }
+      // M9.DRIFT.10r — opt-IN classifier replaces opt-OUT two-step.
+      // Mixed-content user messages (tool_result + system-reminder +
+      // small noise text) used to defeat both isToolResultOnlyContent
+      // and isMostlySystemReminder, getting counted as boundaries and
+      // evicting cognition from the window. isUserAuthoredMessage
+      // returns true ONLY for identifiable user voice.
+      if (!isUserAuthoredMessage(content, { systemReminderRx, systemReminderThreshold })) continue;
       userBoundariesCrossed++;
       if (userBoundariesCrossed > userBoundariesToCross) break;
       continue;
@@ -100,11 +194,9 @@ export function collectTurnWindowFromMessages(messages, {
     const content = normalizeContent(entry);
 
     if (role === 'user') {
-      if (isToolResultOnlyContent(content)) continue;
+      // M9.DRIFT.10r — opt-IN classifier replaces opt-OUT two-step.
+      if (!isUserAuthoredMessage(content, { systemReminderRx, systemReminderThreshold })) continue;
       const textContent = extractTextFromContent(content);
-      if (isMostlySystemReminder(textContent, systemReminderRx, systemReminderThreshold)) {
-        continue;
-      }
       lastUserMessage = textContent || lastUserMessage;
       break;
     }

package/hooks/lib/invocation-required-verifier.mjs

@@ -0,0 +1,184 @@
+/**
+ * invocation-required-verifier.mjs — F5.c stop-gate verification that
+ * autoload-named active-workflow skills were actually invoked via the
+ * Skill tool this turn. Doctrine: feedback_autoload_does_not_invoke_skills.md.
+ *
+ * Reads explicit manifest-required skills when provided, otherwise reads
+ * ~/.claude/.aria-current-turn-context.json (sidecar) for the invocationRequired
+ * field (active-workflow skills loaded this turn), then compares against the
+ * set of Skill tool_use invocations visible in the transcript (passed in by
+ * caller).
+ *
+ * For each required skill, classifies per Recovery Contract A/B/C/D:
+ *   A. INVOKED — Skill(name=X) call in transcript
+ *   B. COMPOSED-VIA-PARENT — parent skill (e.g. aria-cognition-batch)
+ *      invoked, and X is in parent's Composition section
+ *   C. SCOPE-EXEMPT — explicit operator read-only language
+ *      ("explain X", "show me X body", "what does X do")
+ *   D. CAP-DEFERRED — > INVOCATION_CAP_PER_TURN (15) active invocations
+ *      this turn (runaway-prevention sanity ceiling)
+ *
+ * Missing classification → doctrine drift; gate warns (default) or blocks
+ * (when ARIA_F5C_HARD_BLOCK=1).
+ *
+ * Composition map: maintained as a small static map of parent → composed
+ * children, derived from skill body Composition sections. Updated when
+ * skill bodies change.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+const HOME = homedir();
+const SIDECAR_PATH = `${HOME}/.claude/.aria-current-turn-context.json`;
+const SANITY_CAP = 15;
+
+// Static composition map — keys are parent skills, values are
+// active-workflow children whose invocation requirement is satisfied
+// when the parent is invoked. Derived from skill body Composition
+// sections. Update when skill bodies change.
+const COMPOSITION_MAP = {
+  'aria-cognition-batch': ['tadabbur', 'qiyas-analogy', 'mizan', 'ghazali-8lens'],
+  'aria-fullstack-orchestrator': ['aria-forge-guardrails'],
+  'aria-business-frame': ['mizan', 'tadabbur'],
+};
+
+const SCOPE_EXEMPT_RX = /\b(?:explain|what does|how does|show me|describe|tell me about)\s+(?:the\s+)?(\S+?)(?:\s+(?:do|work|body|skill))?\b/gi;
+
+/**
+ * Read explicit required skills or sidecar.invocationRequired for the current turn.
+ * Returns string[] (empty if sidecar missing or field absent).
+ */
+export function readInvocationRequired({ requiredSkills } = {}) {
+  if (Array.isArray(requiredSkills)) {
+    return [...new Set(requiredSkills.filter((skill) => typeof skill === 'string' && skill.trim()).map((skill) => skill.trim()))];
+  }
+  if (!existsSync(SIDECAR_PATH)) return [];
+  let raw;
+  try { raw = readFileSync(SIDECAR_PATH, 'utf-8'); } catch { return []; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return []; }
+  return Array.isArray(parsed.invocationRequired) ? parsed.invocationRequired : [];
+}
+
+/**
+ * Verify invocationRequired against the set of invoked skills + the
+ * user prompt (for scope-exempt detection).
+ *
+ * Args:
+ *   invokedSkills: Set<string> | string[] of skill names invoked via
+ *     Skill tool this turn (extracted from transcript by caller)
+ *   userPrompt: string of the latest user prompt (for SCOPE-EXEMPT
+ *     detection)
+ *   requiredSkills: optional string[] from OrchestrationManifest
+ *     intent.workflow_skills_to_invoke. When present, this is the routing
+ *     source instead of sidecar/classifier state.
+ *
+ * Returns: { required, classifications: {A, B, C, D, missing}, ok }
+ *   classifications.A: skills directly invoked
+ *   classifications.B: skills satisfied via parent composition
+ *   classifications.C: skills exempted by scope (read-only operator
+ *     language)
+ *   classifications.D: skills deferred by sanity cap
+ *   classifications.missing: skills with NO valid classification
+ *     (doctrine drift)
+ *   ok: true if classifications.missing.length === 0
+ */
+export function verifyInvocations({ invokedSkills, userPrompt, requiredSkills }) {
+  const required = readInvocationRequired({ requiredSkills });
+  const invokedSet = new Set(Array.isArray(invokedSkills) ? invokedSkills : [...(invokedSkills || [])]);
+  const result = {
+    required,
+    classifications: { A: [], B: [], C: [], D: [], missing: [] },
+    ok: true,
+  };
+  if (required.length === 0) return result;
+
+  // Sanity-cap check first (Class D applies to overflow).
+  if (invokedSet.size >= SANITY_CAP) {
+    // All un-invoked required skills classify as D when cap reached
+    for (const skill of required) {
+      if (invokedSet.has(skill)) result.classifications.A.push(skill);
+      else result.classifications.D.push(skill);
+    }
+    return result;
+  }
+
+  // Build set of scope-exempt mentions from user prompt
+  const promptScopeMentions = new Set();
+  if (typeof userPrompt === 'string') {
+    SCOPE_EXEMPT_RX.lastIndex = 0;
+    let m;
+    while ((m = SCOPE_EXEMPT_RX.exec(userPrompt)) !== null) {
+      promptScopeMentions.add(m[1].toLowerCase());
+    }
+  }
+
+  for (const skill of required) {
+    // A. INVOKED
+    if (invokedSet.has(skill)) {
+      result.classifications.A.push(skill);
+      continue;
+    }
+    // B. COMPOSED-VIA-PARENT
+    let composed = false;
+    for (const [parent, children] of Object.entries(COMPOSITION_MAP)) {
+      if (invokedSet.has(parent) && children.includes(skill)) {
+        result.classifications.B.push(`${skill}<-${parent}`);
+        composed = true;
+        break;
+      }
+    }
+    if (composed) continue;
+    // C. SCOPE-EXEMPT (read-only inspection of the skill)
+    if (promptScopeMentions.has(skill.toLowerCase())) {
+      result.classifications.C.push(skill);
+      continue;
+    }
+    // No classification — doctrine drift
+    result.classifications.missing.push(skill);
+  }
+
+  result.ok = result.classifications.missing.length === 0;
+  return result;
+}
+
+/**
+ * Format a human-readable block-reason for the stop-gate when
+ * verifyInvocations returns ok=false. The block-reason cites the
+ * doctrine memory, names each missing skill, and gives the recovery
+ * contract A/B/C/D classifications the LLM must choose from before
+ * re-emitting.
+ */
+export function formatInvocationGapReason(result) {
+  const missing = result.classifications.missing;
+  if (missing.length === 0) return '';
+  return `Aria stop-gate: F5 INVOCATION-REQUIRED gap.
+
+Active-workflow skills were loaded as autoload bodies this turn but the
+Skill tool was NOT invoked for them, AND they do NOT satisfy any of the
+A/B/C/D Recovery Contract classifications:
+
+  Missing: ${missing.join(', ')}
+
+Doctrine: feedback_autoload_does_not_invoke_skills.md
+Substrate-loaded ≠ workflow-run. Bodies in context are reference
+material; the workflow runs only when you invoke the Skill tool.
+
+Recovery Contract — every loaded active skill must end the turn as:
+  A. INVOKED — Skill(name) tool call in this turn's transcript
+  B. COMPOSED-VIA-PARENT — parent skill invoked + child in parent's
+     Composition map (parents recognized: aria-cognition-batch,
+     aria-fullstack-orchestrator, aria-business-frame)
+  C. SCOPE-EXEMPT — operator prompt explicitly inspected the skill
+     ("explain X", "what does X do", "show me X body")
+  D. CAP-DEFERRED — > 15 active invocations this turn (sanity ceiling
+     only; not a thoroughness budget)
+
+Next action: invoke the missing skills via the Skill tool, OR satisfy
+B/C/D, OR set ARIA_F5C_HARD_BLOCK=0 to downgrade this to warn-only.
+Already invoked skills: ${result.classifications.A.join(', ') || '(none)'}
+Composed via parent: ${result.classifications.B.join(', ') || '(none)'}
+Scope-exempt: ${result.classifications.C.join(', ') || '(none)'}
+Cap-deferred: ${result.classifications.D.join(', ') || '(none)'}`;
+}