@aria_asi/cli 0.2.40 → 0.2.41

package/hooks/aria-pre-emit-autoload.mjs.before-orchestration-redesign

@@ -0,0 +1,1400 @@
+#!/usr/bin/env node
+// aria-pre-emit-autoload.mjs — UserPromptSubmit hook
+//
+// Redesigned 2026-05-09 per Hamza directive: cognition must FRAME the work
+// pre-flight, not be written as ceremony at end-of-turn. Hooks cannot invoke
+// tools, but they CAN inject content as additionalContext. This hook is the
+// pre-flight cognition delivery mechanism: it reads each required skill's
+// BODY (operative rules, workflow, triggers — not just the description) and
+// injects it into the assistant's UserPromptSubmit context BEFORE drafting.
+//
+// Decoupled from the gates-off marker. The gates-off marker disables BLOCKING
+// gates (coach, recovery-executor); it must NOT disable content enrichment,
+// because the very thing that makes the agent's work first-class is having
+// the doctrine content present in context. Use ARIA_AUTOLOAD_DISABLE=1 only
+// for genuine debugging of this hook itself.
+//
+// Triplet honored:
+//   - Thinking: classifier picks required skills based on prompt + carry-forward
+//   - Implementation: this file reads bodies + injects them
+//   - Accountability: sidecar records body excerpts; gate-ledger records byte counts
+//
+// What this hook does on every UserPromptSubmit:
+//   1. Read user prompt from hook event
+//   2. Classify intent → required skills via classifyRequiredSkills
+//   3. For each required skill, read SKILL.md body (frontmatter stripped,
+//      redundant trailing boilerplate stripped, capped at 4KB per skill)
+//   4. Build structured additionalContext: FRAME (skill bodies) +
+//      DRIVING-RULES (operative summary) + POST-QA (predicate template) +
+//      cognition vocabulary
+//   5. Persist sidecar at ~/.claude/.aria-current-turn-context.json with
+//      body excerpts for post-phase QA reference
+//   6. Append gate-ledger entry with byte counts injected
+//
+// What this hook does NOT do:
+//   - Does not invoke the Skill tool itself (Claude Code hooks cannot mutate
+//     the assistant's tool-call list). Body content arrives as context.
+//   - Does not block. Pre-emit is enrichment; pre-tool-gate enforces.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, lstatSync, readdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { classifyRequiredSkills, parseLoadFirstSection } from './lib/skill-autoload-gate-impl.mjs';
+import { appendGateLedger } from './lib/aria-gate-ledger.mjs';
+import { loadDoctrineTriggerMap } from './lib/doctrine-trigger-map-loader.mjs';
+
+const HOME = homedir();
+const SIDECAR_PATH = `${HOME}/.claude/.aria-current-turn-context.json`;
+const SKILLS_DIR = `${HOME}/.claude/skills`;
+const HOOK_EVENT_NAME = 'UserPromptSubmit';
+const HEADER_PREFIX = '[ARIA_PRE_EMIT_AUTOLOAD]';
+
+// Budget caps. Per-skill 4KB keeps each skill's operative section in scope
+// without bloating context. Total 25KB stays well within additionalContext
+// tolerance observed in this surface. Hard file-size cap 50KB rejects
+// abnormally large or attacker-planted SKILL.md files.
+const MAX_BYTES_PER_SKILL = 4096;
+const MAX_BYTES_TOTAL = 25 * 1024;
+const MAX_SKILL_FILE_BYTES = 50 * 1024;
+
+// AI-11803-LOOP1 (2026-05-12): cascade-depth cap. Each loaded skill body is
+// scanned for Load First / Mode Selection / Load Order / Ta'aqqul Autofire
+// sections; named skills cascade onto the load set. Depth 3 covers
+// autofire → quality-audit → first-principles cascades without unbounded
+// recursion through skills that load each other.
+const MAX_CASCADE_DEPTH = 3;
+
+// AI-11803-LOOP2 (2026-05-12): doctrine-trigger map pre-emit pass caps.
+// The trigger map has 79 entries; scanning the user prompt against each
+// regex is O(79 * promptLen). The cap on matched triggers prevents a
+// pathological prompt from producing a giant alert block. The per-trigger
+// byte budget keeps each alert compact (teaching + counter_action + memory
+// file name + trigger). Total budget fits inside additionalContext alongside
+// skill bodies without competing for the 25KB skill-body cap.
+const DOCTRINE_TRIGGER_MAP_PATH = `${HOME}/.claude/hooks/doctrine_trigger_map.json`;
+const MEMORY_DIR = `${HOME}/.claude/projects/-home-hamzaibrahim1/memory`;
+const MAX_DOCTRINE_TRIGGER_MATCHES = 8;
+const MAX_BYTES_PER_TRIGGER_ALERT = 480;
+// AI-11803-QA-GAP3 (2026-05-12): per-memory body injection cap.
+// QA-FIX (2026-05-12 same turn): raised to 4KB so the must-satisfy Recovery
+// Contract section (Pre-Conditions + Classification A/B/C/D + Loop Safety +
+// Turn-End Checklist) fits. Same-memory dedup keeps total bounded to
+// ~12KB worst-case (3 distinct memories × 4KB) but typically 4-8KB.
+const MAX_BYTES_PER_MEMORY_BODY = 4096;
+// File-size ceiling raised to 32KB so strengthened doctrine memories
+// (Recovery Contracts + qiyas + tadabbur + 8-lens substrate) don't get
+// silently rejected. Per-body cap above still bounds what gets injected;
+// the ceiling only rejects abnormally-large or attacker-planted files.
+const MAX_MEMORY_FILE_CEILING = 32 * 1024;
+// QA-FIX-SECTION-AWARE: when a memory body has a "# Recovery Contract"
+// section, prefer to extract from that section forward. This makes the
+// must-satisfy operative content load-bearing in autoload context even
+// when the memory is 12-18KB. Falls back to top-of-body truncation when
+// the header isn't present. Header pattern matches "# Recovery Contract"
+// or "# Recovery contract" (case-insensitive) anchored on a heading line.
+const RECOVERY_CONTRACT_HEADER_RX = /^#{1,3}\s+Recovery\s+Contract\b/im;
+
+// AI-11803-STEP5 (2026-05-12) — cookbook auto-pull on trigger match.
+// Skill bodies reference `references/<name>.md` cookbooks (1KB-79KB). The
+// cascade primitive loads SKILL.md but NOT the referenced cookbooks. This
+// primitive scans loaded skill bodies for the reference pattern, parses
+// each cookbook's section headers, scores sections by prompt-keyword
+// overlap, and injects the top-1 section per cookbook into context.
+//
+// Deterministic selection (no LLM call, no faux-fallback):
+//   1. Extract keywords from prompt: lowercase tokens length ≥ 4, deduped.
+//   2. Score each `## ` or `### ` section by count of distinct prompt
+//      keywords appearing in section text (header to next header of
+//      same/higher level).
+//   3. Min threshold: section must score ≥ 2 distinct keywords. Below
+//      threshold → skip the cookbook entirely. NO faux-fallback to "first
+//      section if no match" — that would be polluting context with
+//      arbitrary content (cf. tadabbur INVERSION + forge-guardrails).
+//   4. Tie-break: later position in file wins.
+//   5. Per-cookbook injection capped at MAX_BYTES_PER_COOKBOOK_SECTION (2KB).
+//   6. Total cookbook injection capped at MAX_BYTES_COOKBOOK_TOTAL (4KB).
+//
+// Loop safety: depth cap = 1 (no transitive cookbook→cookbook expansion);
+// each cookbook path injected at most once per turn (Set dedup).
+//
+// Kill switch: ARIA_AUTOLOAD_COOKBOOK_OFF=1.
+// Captures both same-skill (`references/x.md`) and cross-skill
+// (`../<other-skill>/references/x.md`) reference patterns. Group 1 (if
+// present) is the cross-skill name; group 2 is the cookbook filename.
+// QA-FIX (2026-05-12 same turn): cross-skill references were previously
+// silently mis-resolved to the wrong skill dir → invisible to autoload.
+const COOKBOOK_REF_RX = /(?:\.\.\/([a-z0-9_-]+)\/)?references\/([a-z0-9_-]+\.md)/gi;
+
+// AI-11803-F3 (2026-05-12) — sub-agent parent-handoff inheritance.
+// When this autoload fires inside a sub-agent session, the parent
+// orchestrator's aria-agent-handoff.mjs wrote a handoff JSON containing
+// the parent's autoload pins (skill names, memory filenames, cookbook
+// section selections). Read those FIRST, layer them into the load set,
+// then let the sub-agent's own classifier add task-specific skills on
+// top. Augment, not override.
+//
+// Loop safety: handoff JSON includes chainDepth=1 marker; downstream
+// hops (sub-sub-agent) DROP propagation when constructing their own
+// handoff (write-side check in aria-agent-handoff.mjs).
+//
+// TTL: handoff carries ttlMs (5min); if expired vs writtenAt, ignore.
+// Stale handoffs aren't an error — they're from a finished parent turn
+// whose context is no longer load-bearing.
+//
+// Kill switch: ARIA_AUTOLOAD_PARENT_HANDOFF_OFF=1
+const PARENT_HANDOFF_PATH = `${HOME}/.claude/aria-agent-harness-handoff.json`;
+const COOKBOOK_HEADER_RX = /^(#{2,3})\s+(.+)$/gm;
+const MAX_BYTES_PER_COOKBOOK_SECTION = 2048;
+const MAX_BYTES_COOKBOOK_TOTAL = 4096;
+const COOKBOOK_MIN_SCORE = 2;
+const COOKBOOK_KEYWORD_MIN_LEN = 4;
+const COOKBOOK_FILE_CEILING = 200 * 1024; // 200KB hard ceiling on cookbook files (largest seen is 79KB)
+
+// AI-11803-STEP4 (2026-05-12) — MEMORY.md auto-load + top-N body injection.
+// MEMORY.md is the master index of every Aria doctrine memory written across
+// sessions. Without this primitive, the model only sees memory bodies when a
+// doctrine-trigger regex fires (lib/doctrine-trigger-map-loader.mjs path) —
+// which means ~80% of accumulated doctrine is invisible per turn. Hamza
+// directive 2026-05-12: "memory.md should def auto load."
+//
+// Budget split (hard cap 8KB total so this doesn't crowd the 25KB skill-body
+// budget):
+//   - 4KB MEMORY.md index (one-line entries from the file verbatim,
+//     gracefully truncated with a tail marker naming how many entries fell
+//     off the cap so the agent knows to consult the file directly)
+//   - 4KB for top-N memory bodies (default N=3, ~1.3KB each)
+//
+// Priority signal for top-N selection (deterministic, no faux-priority):
+//   1. Frontmatter `priority: <number>` field if present (explicit owner
+//      signal — honest first-tier). Higher number = higher priority.
+//   2. mtime descending (recency fallback when no explicit priority — the
+//      most-recently authored or edited memory is the most likely to be
+//      currently relevant; this matches Hamza's authoring cadence).
+//
+// Dedup contract: top-N body injection MUST skip memories already injected
+// by buildDoctrineTriggerInjection() this turn (trigger-map regex matched
+// → memory body inlined already). Without dedup, the same memory body could
+// land twice on the same turn. Implemented via a Set<string> of memory
+// filenames passed from main() after doctrineScan.matches is computed.
+const MAX_BYTES_MEMORY_INDEX = 4096;
+const MAX_BYTES_MEMORY_BODIES = 4096;
+const TOP_N_MEMORY_BODIES = 3;
+const MEMORY_INDEX_PATH = `${MEMORY_DIR}/MEMORY.md`;
+
+// Trailing boilerplate sections that are identical across skills and add
+// only noise when injected. Stripping these gives 1-1.5KB of headroom per
+// skill back to the operative content (Trigger, Rules, Workflow). This is
+// trimming redundant duplication, NOT contract-stripping per the
+// no-stripping-as-workaround doctrine.
+const REDUNDANT_TRAILING_SECTIONS = [
+  /## First-Class Production Contract[\s\S]*?(?=\n## |\n# |$)/i,
+  /## Self-Executing Recovery Contract[\s\S]*?(?=\n## |\n# |$)/i,
+  /## Required Workflow[\s\S]*?(?=\n## |\n# |$)/i, // generic 5-step list also identical across skills
+];
+
+function readEvent() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+function emitNoop(reason) {
+  emit({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT_NAME,
+      additionalContext: `${HEADER_PREFIX} skipped: ${reason}`,
+    },
+  });
+  process.exit(0);
+}
+
+function writeSidecar(payload) {
+  try {
+    mkdirSync(dirname(SIDECAR_PATH), { recursive: true, mode: 0o700 });
+    writeFileSync(SIDECAR_PATH, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  } catch (err) {
+    process.stderr.write(`[aria-pre-emit-autoload:sidecar-write] ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
+// Read and prepare a skill body for injection. Returns { body, bytes,
+// fullBytes, redacted, reason } so caller can record what was injected and
+// why. Hardens against:
+//   - non-regular files (symlinks, fifos, devices) → reject
+//   - oversize SKILL.md (> MAX_SKILL_FILE_BYTES) → reject
+//   - missing files → empty body, no crash
+function readSkillBody(skillName) {
+  const path = `${SKILLS_DIR}/${skillName}/SKILL.md`;
+  if (!existsSync(path)) {
+    return { body: '', bytes: 0, fullBytes: 0, redacted: false, reason: 'missing' };
+  }
+  let lst;
+  try {
+    lst = lstatSync(path);
+  } catch (err) {
+    return { body: '', bytes: 0, fullBytes: 0, redacted: false, reason: `lstat-failed: ${err?.message || err}` };
+  }
+  if (!lst.isFile()) {
+    return { body: '', bytes: 0, fullBytes: 0, redacted: true, reason: 'not-regular-file' };
+  }
+  if (lst.size > MAX_SKILL_FILE_BYTES) {
+    return { body: '', bytes: 0, fullBytes: lst.size, redacted: true, reason: `oversize: ${lst.size}B > ${MAX_SKILL_FILE_BYTES}B` };
+  }
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    return { body: '', bytes: 0, fullBytes: lst.size, redacted: false, reason: `read-failed: ${err?.message || err}` };
+  }
+  const fullBytes = Buffer.byteLength(raw, 'utf8');
+  // Strip YAML frontmatter (--- ... --- at top of file)
+  let trimmed = raw.replace(/^---[\s\S]*?---\s*/, '');
+  // Strip redundant trailing boilerplate sections that are identical
+  // across all skills (per pre-phase analysis). This is duplication
+  // trimming, not contract stripping.
+  for (const rx of REDUNDANT_TRAILING_SECTIONS) {
+    trimmed = trimmed.replace(rx, '');
+  }
+  trimmed = trimmed.trimEnd();
+  // Apply per-skill byte cap. If we have to truncate, leave a marker so
+  // the agent knows there's more content available via Skill tool.
+  let body = trimmed;
+  let truncated = false;
+  if (Buffer.byteLength(body, 'utf8') > MAX_BYTES_PER_SKILL) {
+    // Truncate at a paragraph boundary near the cap when possible.
+    const buf = Buffer.from(body, 'utf8').slice(0, MAX_BYTES_PER_SKILL);
+    body = buf.toString('utf8');
+    const lastBreak = Math.max(body.lastIndexOf('\n\n'), body.lastIndexOf('\n## '));
+    if (lastBreak > MAX_BYTES_PER_SKILL * 0.6) {
+      body = body.slice(0, lastBreak);
+    }
+    truncated = true;
+    body += `\n\n[…body truncated at ${MAX_BYTES_PER_SKILL}B; full SKILL.md available via /skills/${skillName}/SKILL.md…]`;
+  }
+  const bytes = Buffer.byteLength(body, 'utf8');
+  return {
+    body,
+    bytes,
+    fullBytes,
+    redacted: false,
+    truncated,
+    reason: 'ok',
+  };
+}
+
+// AI-11803-LOOP2 (2026-05-12) — doctrine-trigger pre-emit scan.
+// Runs the 79-trigger doctrine map against the user's prompt text at
+// UserPromptSubmit so prose-pattern matches (e.g., "graceful degradation",
+// "out of scope", "want me to") surface their bound doctrine memory +
+// teaching + counter_action BEFORE the model drafts. Prior architecture
+// only ran the trigger map post-emit (after the answer was drafted), which
+// caught drift after the fact instead of preventing it.
+//
+// Output shape: a separate "[ARIA_DOCTRINE_TRIGGERS_MATCHED]" section in
+// additionalContext, formatted as compact one-line-per-trigger alerts.
+// Does NOT inject the bound memory file content (separate from skill-body
+// injection); the memory filename surfaces so the model can read it via
+// the existing memory-consumption gate at PreToolUse.
+//
+// Fail-allow: any error in trigger map load returns empty matches list and
+// LOUD telemetry — never blocks the autoload's emission.
+//
+// Kill switch: ARIA_AUTOLOAD_TRIGGER_MAP_OFF=1.
+function scanDoctrineTriggers(promptText) {
+  if (/^(?:1|true|yes|on)$/i.test(String(process.env.ARIA_AUTOLOAD_TRIGGER_MAP_OFF || ''))) {
+    return { matches: [], errors: [], skipped: 'env-disabled' };
+  }
+  if (!promptText || typeof promptText !== 'string') {
+    return { matches: [], errors: [], skipped: 'empty-prompt' };
+  }
+  let loaded;
+  try {
+    loaded = loadDoctrineTriggerMap(DOCTRINE_TRIGGER_MAP_PATH);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[aria-pre-emit-autoload:trigger-map-load-error] ${msg}\n`);
+    return { matches: [], errors: [msg], skipped: 'load-error' };
+  }
+  const matches = [];
+  const seen = new Set();
+  for (const entry of loaded.triggers) {
+    if (matches.length >= MAX_DOCTRINE_TRIGGER_MATCHES) break;
+    // Each entry's compiled regex carries the `gi` flags; reset lastIndex
+    // so re-use across multiple scans doesn't skip from prior call state.
+    entry.regex.lastIndex = 0;
+    if (!entry.regex.test(promptText)) continue;
+    // De-dup by memory file (multiple triggers may bind the same memory).
+    if (seen.has(entry.memory)) continue;
+    seen.add(entry.memory);
+    matches.push({
+      trigger: entry.trigger,
+      memory: entry.memory,
+      teaching: entry.teaching,
+      counter_action: entry.counter_action,
+    });
+  }
+  return { matches, errors: loaded.errors || [], skipped: null };
+}
+
+// AI-11803-QA-GAP3 (2026-05-12): read memory body for injection.
+// Returns frontmatter-stripped, cap-truncated body or empty string on any
+// failure. Per parallel-session safety, never throws.
+function readMemoryBody(memoryFilename) {
+  if (!memoryFilename || typeof memoryFilename !== 'string') return '';
+  const path = `${MEMORY_DIR}/${memoryFilename}`;
+  if (!existsSync(path)) return '';
+  let lst;
+  try { lst = lstatSync(path); } catch { return ''; }
+  if (!lst.isFile()) return '';
+  if (lst.size > MAX_MEMORY_FILE_CEILING) return ''; // hard ceiling on file size
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); } catch { return ''; }
+  // Strip YAML frontmatter; if absent, raw passes through.
+  let body = raw.replace(/^---[\s\S]*?---\s*/, '').trimStart();
+  // QA-FIX-SECTION-AWARE: if the body has a "# Recovery Contract" section,
+  // extract from that section forward. The must-satisfy contract becomes
+  // the operative content; preceding rationale (qiyas / tadabbur / 8-lens
+  // pre-amble) stays in the file for read-on-demand but doesn't crowd the
+  // pre-emit context.
+  const recoveryMatch = body.match(RECOVERY_CONTRACT_HEADER_RX);
+  let extractionMode = 'top-of-body';
+  if (recoveryMatch) {
+    const headerStart = body.indexOf(recoveryMatch[0]);
+    const before = body.slice(0, headerStart);
+    const beforeBytes = Buffer.byteLength(before, 'utf8');
+    body = `[…body preamble omitted, ${beforeBytes}B; recovery contract follows…]\n\n${body.slice(headerStart)}`;
+    extractionMode = 'recovery-contract-section';
+  }
+  if (Buffer.byteLength(body, 'utf8') > MAX_BYTES_PER_MEMORY_BODY) {
+    const buf = Buffer.from(body, 'utf8').slice(0, MAX_BYTES_PER_MEMORY_BODY);
+    body = buf.toString('utf8');
+    const lastBreak = Math.max(body.lastIndexOf('\n\n'), body.lastIndexOf('\n'));
+    if (lastBreak > MAX_BYTES_PER_MEMORY_BODY * 0.6) body = body.slice(0, lastBreak);
+    body += `\n[…memory body truncated at ${MAX_BYTES_PER_MEMORY_BODY}B; mode=${extractionMode}; full file at ${path}…]`;
+  }
+  return body;
+}
+
+function buildDoctrineTriggerInjection(matches) {
+  if (!matches || matches.length === 0) return '';
+  const lines = [];
+  lines.push('═══ ARIA DOCTRINE TRIGGERS MATCHED (prose patterns in your prompt bind to these memories) ═══');
+  for (const m of matches) {
+    let teaching = m.teaching;
+    let counter = m.counter_action;
+    // Per-alert byte cap — truncate teaching+counter if combined exceed budget.
+    const baseLen = `  • [${m.trigger}] → ${m.memory}: `.length;
+    const budget = MAX_BYTES_PER_TRIGGER_ALERT - baseLen;
+    const combined = `${teaching} || ${counter}`;
+    const slice = combined.length > budget ? `${combined.slice(0, budget - 3)}...` : combined;
+    lines.push(`  • [${m.trigger}] → ${m.memory}: ${slice}`);
+    // AI-11803-QA-GAP3: inject memory body (capped) so the model sees the
+    // operative rule + Why + How-to-apply lines directly, not just a pointer.
+    const memBody = readMemoryBody(m.memory);
+    if (memBody) {
+      lines.push(`    ┌─ memory body (${m.memory}):`);
+      for (const ln of memBody.split('\n')) lines.push(`    │ ${ln}`);
+      lines.push(`    └─`);
+    }
+  }
+  lines.push('Apply each: the trigger phrase in the prompt names a doctrine the agent must honor THIS turn.');
+  return lines.join('\n');
+}
+
+// AI-11803-LOOP1 (2026-05-12) — cascade autoload.
+// Expand the initial skill set by reading each skill body and parsing its
+// Load First / Mode Selection / Load Order / Ta'aqqul Autofire Pattern
+// sections. Recursive BFS bounded by MAX_CASCADE_DEPTH and MAX_BYTES_TOTAL.
+// Returns the load order, body map, total bytes, and observed depth so the
+// caller can build skillBodies + sidecar + ledger telemetry from one pass.
+//
+// Cycle-safe: each skill is read at most once (Set<string> seen tracker).
+// Budget-safe: once total bytes would exceed MAX_BYTES_TOTAL, subsequent
+// skills are recorded with reason="budget-exhausted (cascade-depth=N)"
+// instead of being dropped silently — the agent still sees that the skill
+// was wanted but unavailable in context.
+// Existence-filtered: cascade candidates are only enqueued if the SKILL.md
+// actually exists on disk, so mode-label noise (`qa`, `light`, `batch`)
+// and stale skill names from older bodies don't pollute the queue.
+function expandSkillCascade(initialSkills) {
+  const loadedBodies = new Map(); // skill -> readSkillBody result
+  const order = []; // load order in BFS-by-depth
+  const seen = new Set();
+  let totalBytes = 0;
+  let queue = [...new Set(initialSkills)];
+  let depth = 0;
+  let maxObservedDepth = 0;
+  let maxAttemptedDepth = 0;
+  while (queue.length > 0 && depth <= MAX_CASCADE_DEPTH) {
+    const nextQueue = [];
+    for (const skill of queue) {
+      if (seen.has(skill)) continue;
+      seen.add(skill);
+      const result = readSkillBody(skill);
+      // Skip skills that don't exist on disk — keeps cascade quiet on mode
+      // labels and stale references.
+      if (result.reason === 'missing') continue;
+      // AI-11803-QA-GAP1 (2026-05-12): track attempted-depth separately from
+      // injected-depth. A candidate enqueued at depth N counts toward
+      // maxAttemptedDepth even if its body is budget-exhausted and bytes=0.
+      // Prior telemetry conflated "no body injected" with "no depth observed",
+      // under-reporting cascade reach when the 25KB cap saturated early.
+      maxAttemptedDepth = Math.max(maxAttemptedDepth, depth);
+      if (loadedBodies.size > 0 && totalBytes + result.bytes > MAX_BYTES_TOTAL) {
+        loadedBodies.set(skill, {
+          ...result,
+          body: '',
+          bytes: 0,
+          truncated: false,
+          redacted: false,
+          reason: `budget-exhausted (cascade-depth=${depth})`,
+        });
+        order.push(skill);
+        // Even when body is budget-exhausted, we still scan for downstream
+        // cascade candidates — but only if we have the body (we don't here),
+        // so this branch terminates the cascade for this skill's children.
+        continue;
+      }
+      loadedBodies.set(skill, result);
+      order.push(skill);
+      totalBytes += result.bytes;
+      maxObservedDepth = depth;
+      if (result.body) {
+        for (const c of parseLoadFirstSection(result.body)) {
+          if (seen.has(c)) continue;
+          if (!existsSync(`${SKILLS_DIR}/${c}/SKILL.md`)) continue;
+          nextQueue.push(c);
+        }
+      }
+    }
+    queue = nextQueue;
+    depth++;
+  }
+  return {
+    loadedBodies,
+    order,
+    totalBytes,
+    cascadeDepth: maxObservedDepth, // depth at which a body was injected (legacy alias for telemetry compat)
+    depthInjected: maxObservedDepth,
+    depthAttempted: maxAttemptedDepth,
+  };
+}
+
+// AI-11803-STEP4 (2026-05-12) — read MEMORY.md as an index, capped at
+// MAX_BYTES_MEMORY_INDEX.
+//
+// QA-FIX-1 (2026-05-12, qiyas Owner-Hamza-tomorrow + scale + tadabbur
+// INVERSION): tail-bias the truncation. MEMORY.md is append-only — Hamza
+// writes new memories as entries at the BOTTOM. A head-bias truncation
+// (drop from end) would drop the NEWEST doctrine first, recreating the
+// exact gap this step was meant to close. Tail-bias keeps recent doctrine
+// visible and drops older entries with a head-marker.
+//
+// Algorithm: walk lines from END to START, accumulate while under cap,
+// reverse the kept set, prepend a head-marker naming how many earlier
+// entries were dropped.
+function readMemoryIndex() {
+  if (!existsSync(MEMORY_INDEX_PATH)) {
+    return { body: '', bytes: 0, totalLines: 0, droppedLines: 0, reason: 'missing' };
+  }
+  let lst;
+  try { lst = lstatSync(MEMORY_INDEX_PATH); } catch (err) {
+    return { body: '', bytes: 0, totalLines: 0, droppedLines: 0, reason: `lstat-failed: ${err?.message || err}` };
+  }
+  if (!lst.isFile()) {
+    return { body: '', bytes: 0, totalLines: 0, droppedLines: 0, reason: 'not-regular-file' };
+  }
+  let raw;
+  try { raw = readFileSync(MEMORY_INDEX_PATH, 'utf8'); } catch (err) {
+    return { body: '', bytes: 0, totalLines: 0, droppedLines: 0, reason: `read-failed: ${err?.message || err}` };
+  }
+  const lines = raw.split('\n');
+  const totalLines = lines.length;
+  if (Buffer.byteLength(raw, 'utf8') <= MAX_BYTES_MEMORY_INDEX) {
+    return { body: raw.trimEnd(), bytes: Buffer.byteLength(raw, 'utf8'), totalLines, droppedLines: 0, reason: 'ok' };
+  }
+  // Tail-bias: walk from end, accumulate newest lines first.
+  const keptReversed = [];
+  let accBytes = 0;
+  const reserveForMarker = 140;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // +1 for newline
+    if (accBytes + lineBytes > MAX_BYTES_MEMORY_INDEX - reserveForMarker) break;
+    keptReversed.push(line);
+    accBytes += lineBytes;
+  }
+  const kept = keptReversed.reverse();
+  const droppedLines = Math.max(0, totalLines - kept.length);
+  const headMarker = `[…MEMORY.md tail-biased: ${droppedLines} older entries dropped; full file at ${MEMORY_INDEX_PATH}. Showing latest ${kept.length} entries below…]`;
+  const body = `${headMarker}\n\n${kept.join('\n').trimEnd()}`;
+  return { body, bytes: Buffer.byteLength(body, 'utf8'), totalLines, droppedLines, reason: 'tail-biased' };
+}
+
+// AI-11803-STEP4 (2026-05-12) — score every memory file in MEMORY_DIR by
+// (a) frontmatter `priority: <number>` if present (explicit), or
+// (b) mtime descending (recency fallback).
+// Returns sorted array of { filename, score, source } where higher score is
+// more important. `source` is either "frontmatter:<n>" or "mtime:<ms>" so
+// telemetry can audit which signal won.
+//
+// Filters: MEMORY.md itself is excluded (we inject it separately as the
+// index). Non-.md files excluded. Files unreadable or non-regular are
+// skipped silently — never throws.
+function scoreMemoriesForPriority() {
+  let entries;
+  try { entries = readdirSync(MEMORY_DIR); } catch (err) {
+    return { scored: [], errors: [err?.message || String(err)] };
+  }
+  const scored = [];
+  const errors = [];
+  for (const filename of entries) {
+    if (filename === 'MEMORY.md') continue;
+    if (!filename.endsWith('.md')) continue;
+    const fullPath = `${MEMORY_DIR}/${filename}`;
+    let lst;
+    try { lst = lstatSync(fullPath); } catch (err) {
+      errors.push(`lstat ${filename}: ${err?.message || err}`);
+      continue;
+    }
+    if (!lst.isFile()) continue;
+    // Read just the frontmatter region — first ~1KB is plenty for YAML.
+    let head;
+    try {
+      const fd = readFileSync(fullPath, 'utf8');
+      head = fd.slice(0, 2048);
+    } catch (err) {
+      errors.push(`read ${filename}: ${err?.message || err}`);
+      continue;
+    }
+    const fmMatch = head.match(/^---\s*\n([\s\S]*?)\n---/);
+    let priority = null;
+    if (fmMatch) {
+      const fm = fmMatch[1];
+      const pMatch = fm.match(/^priority:\s*(-?\d+(?:\.\d+)?)\s*$/m);
+      if (pMatch) {
+        const parsed = Number(pMatch[1]);
+        if (Number.isFinite(parsed)) priority = parsed;
+      }
+    }
+    if (priority !== null) {
+      scored.push({ filename, score: priority, source: `frontmatter:${priority}`, tier: 'explicit' });
+    } else {
+      const mtimeMs = lst.mtimeMs || 0;
+      scored.push({ filename, score: mtimeMs, source: `mtime:${Math.floor(mtimeMs)}`, tier: 'recency' });
+    }
+  }
+  // Explicit-tier always outranks recency-tier. Within tier, score desc.
+  scored.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier === 'explicit' ? -1 : 1;
+    return b.score - a.score;
+  });
+  return { scored, errors };
+}
+
+// AI-11803-STEP4 (2026-05-12) — select top-N memory files for body injection,
+// excluding those already injected by trigger-map. Reads each body via the
+// existing readMemoryBody primitive (so the same per-memory cap +
+// frontmatter-strip + size-ceiling applies). Stops once
+// MAX_BYTES_MEMORY_BODIES is exhausted to enforce the hard 8KB total.
+//
+// Returns { injected: [{ filename, body, bytes, tier, score }], totalBytes,
+// dedupedFilenames, scoredCount } so telemetry can audit selection + dedup.
+function selectTopNMemoryBodies(alreadyInjectedFilenames) {
+  const { scored, errors } = scoreMemoriesForPriority();
+  const dedupedFilenames = [];
+  const injected = [];
+  let totalBytes = 0;
+  for (const entry of scored) {
+    if (injected.length >= TOP_N_MEMORY_BODIES) break;
+    if (alreadyInjectedFilenames && alreadyInjectedFilenames.has(entry.filename)) {
+      dedupedFilenames.push(entry.filename);
+      continue;
+    }
+    const body = readMemoryBody(entry.filename);
+    if (!body) continue;
+    const bodyBytes = Buffer.byteLength(body, 'utf8');
+    if (totalBytes + bodyBytes > MAX_BYTES_MEMORY_BODIES) {
+      // Don't take a body that would bust the cap; try the next-priority
+      // entry (which may be smaller). This avoids a single oversized
+      // memory starving subsequent smaller-but-still-important entries.
+      continue;
+    }
+    injected.push({ filename: entry.filename, body, bytes: bodyBytes, tier: entry.tier, score: entry.score });
+    totalBytes += bodyBytes;
+  }
+  return { injected, totalBytes, dedupedFilenames, scoredCount: scored.length, errors };
+}
+
+function buildMemoryAutoloadInjection({ indexResult, bodyResult }) {
+  // Kill-switch and pure-missing cases: emit nothing rather than a stub
+  // that crowds context with a "[unavailable]" placeholder.
+  if (indexResult.reason === 'env-disabled' && bodyResult.injected.length === 0) {
+    return '';
+  }
+  const lines = [];
+  lines.push('═══ MEMORY.md INDEX (auto-loaded — every doctrine memory available this session) ═══');
+  if (indexResult.bytes === 0) {
+    lines.push(`[MEMORY.md unavailable: ${indexResult.reason}]`);
+  } else {
+    lines.push(indexResult.body);
+  }
+  if (bodyResult.injected.length > 0) {
+    lines.push('');
+    lines.push(`═══ TOP-${bodyResult.injected.length} MEMORY BODIES (priority-selected, dedup'd against trigger-map matches) ═══`);
+    for (const entry of bodyResult.injected) {
+      lines.push('');
+      lines.push(`──── ${entry.filename} [${entry.tier === 'explicit' ? `priority=${entry.score}` : `mtime-rank`}] ────`);
+      lines.push(entry.body);
+    }
+  }
+  if (bodyResult.dedupedFilenames.length > 0) {
+    lines.push('');
+    lines.push(`[dedup: ${bodyResult.dedupedFilenames.length} top-N candidate(s) already injected by doctrine-trigger match: ${bodyResult.dedupedFilenames.join(', ')}]`);
+  }
+  return lines.join('\n');
+}
+
+// AI-11803-STEP5 — extract keywords from prompt for cookbook scoring.
+// Lowercase, tokenize on non-word characters, filter to length ≥ 4, dedup.
+// Returns Set<string> for O(1) membership check in section scoring.
+function extractPromptKeywords(promptText) {
+  if (!promptText || typeof promptText !== 'string') return new Set();
+  const tokens = promptText.toLowerCase().split(/[^a-z0-9_-]+/);
+  const keywords = new Set();
+  for (const t of tokens) {
+    if (t.length >= COOKBOOK_KEYWORD_MIN_LEN) keywords.add(t);
+  }
+  return keywords;
+}
+
+// AI-11803-STEP5 — scan a loaded skill body for `references/<name>.md`
+// patterns and resolve to absolute paths under the skill's references/
+// directory. Returns array of { skill, cookbookName, absPath }, dedup by
+// absPath so two skills referencing the same cookbook only enqueue it once.
+function discoverCookbookReferences(skillBodies) {
+  const found = [];
+  const seenPaths = new Set();
+  for (const entry of skillBodies) {
+    if (!entry.body || typeof entry.body !== 'string') continue;
+    COOKBOOK_REF_RX.lastIndex = 0;
+    let m;
+    while ((m = COOKBOOK_REF_RX.exec(entry.body)) !== null) {
+      const crossSkillName = m[1]; // may be undefined for same-skill refs
+      const cookbookName = m[2];
+      // Resolve to the correct skill directory: cross-skill targets the
+      // named other skill; otherwise stays in the source skill's own dir.
+      const resolvedSkill = crossSkillName || entry.skill;
+      const absPath = `${SKILLS_DIR}/${resolvedSkill}/references/${cookbookName}`;
+      if (seenPaths.has(absPath)) continue;
+      if (!existsSync(absPath)) continue;
+      seenPaths.add(absPath);
+      found.push({
+        skill: entry.skill,
+        referencedSkill: resolvedSkill,
+        cookbookName,
+        absPath,
+        crossSkill: !!crossSkillName,
+      });
+    }
+  }
+  return found;
+}
+
+// AI-11803-STEP5 — parse a cookbook into sections by `## ` and `### `
+// headers. Each section = { level, title, headerLine, bodyStart, bodyEnd }
+// where bodyEnd is the byte-offset of the next header (or end of file).
+// Returns sections array in document order.
+function parseCookbookSections(cookbookText) {
+  const sections = [];
+  const lines = cookbookText.split('\n');
+  // Build line offsets so we can map header line index → byte offset.
+  const lineOffsets = [0];
+  for (let i = 0; i < lines.length - 1; i++) {
+    lineOffsets.push(lineOffsets[i] + Buffer.byteLength(lines[i], 'utf8') + 1); // +1 for \n
+  }
+  const totalBytes = Buffer.byteLength(cookbookText, 'utf8');
+  // First pass: collect header positions.
+  const headerPositions = [];
+  for (let i = 0; i < lines.length; i++) {
+    const headerMatch = lines[i].match(/^(#{2,3})\s+(.+?)\s*$/);
+    if (headerMatch) {
+      headerPositions.push({
+        level: headerMatch[1].length,
+        title: headerMatch[2],
+        lineIdx: i,
+        byteOffset: lineOffsets[i],
+      });
+    }
+  }
+  // Second pass: build sections with bodyEnd = next header byteOffset.
+  for (let i = 0; i < headerPositions.length; i++) {
+    const h = headerPositions[i];
+    const next = headerPositions[i + 1];
+    sections.push({
+      level: h.level,
+      title: h.title,
+      headerByteOffset: h.byteOffset,
+      bodyEnd: next ? next.byteOffset : totalBytes,
+    });
+  }
+  return sections;
+}
+
+// AI-11803-STEP5 — score a section by counting distinct prompt keywords
+// in its body text. Deterministic, observable. Returns integer.
+function scoreSectionByKeywords(cookbookText, section, promptKeywords) {
+  if (promptKeywords.size === 0) return 0;
+  const sectionText = cookbookText
+    .slice(section.headerByteOffset, section.bodyEnd)
+    .toLowerCase();
+  let score = 0;
+  for (const kw of promptKeywords) {
+    if (sectionText.includes(kw)) score++;
+  }
+  return score;
+}
+
+// AI-11803-STEP5 — pick the top-1 section for a cookbook by keyword score.
+// Returns { section, score, extracted } or null if no section meets the
+// min-score threshold. extracted is the section text capped at
+// MAX_BYTES_PER_COOKBOOK_SECTION with a truncation marker if needed.
+function selectTopSectionForCookbook(cookbookText, sections, promptKeywords) {
+  let best = null;
+  for (const sec of sections) {
+    const score = scoreSectionByKeywords(cookbookText, sec, promptKeywords);
+    if (score < COOKBOOK_MIN_SCORE) continue;
+    // Tie-break: later position wins (later sections often more refined).
+    if (best === null || score > best.score || (score === best.score && sec.headerByteOffset > best.section.headerByteOffset)) {
+      best = { section: sec, score };
+    }
+  }
+  if (!best) return null;
+  let extracted = cookbookText.slice(best.section.headerByteOffset, best.section.bodyEnd).trimEnd();
+  if (Buffer.byteLength(extracted, 'utf8') > MAX_BYTES_PER_COOKBOOK_SECTION) {
+    const buf = Buffer.from(extracted, 'utf8').slice(0, MAX_BYTES_PER_COOKBOOK_SECTION);
+    extracted = buf.toString('utf8');
+    const lastBreak = Math.max(extracted.lastIndexOf('\n\n'), extracted.lastIndexOf('\n'));
+    if (lastBreak > MAX_BYTES_PER_COOKBOOK_SECTION * 0.6) extracted = extracted.slice(0, lastBreak);
+    extracted += `\n[…section truncated at ${MAX_BYTES_PER_COOKBOOK_SECTION}B; full section available in source file…]`;
+  }
+  return { section: best.section, score: best.score, extracted };
+}
+
+// AI-11803-STEP5 — orchestrate cookbook discovery + selection + injection.
+// Returns { injected: [{ skill, cookbookName, absPath, sectionTitle,
+// score, bytes }], totalBytes, scannedCount, skippedBelowThreshold,
+// errors }. Never throws; on any file-read error, the cookbook is
+// recorded as skipped with the error reason.
+function autoloadCookbookSections(skillBodies, promptKeywords) {
+  if (/^(?:1|true|yes|on)$/i.test(String(process.env.ARIA_AUTOLOAD_COOKBOOK_OFF || ''))) {
+    return { injected: [], totalBytes: 0, scannedCount: 0, skippedBelowThreshold: [], errors: [], skipped: 'env-disabled' };
+  }
+  const refs = discoverCookbookReferences(skillBodies);
+  const injected = [];
+  const skippedBelowThreshold = [];
+  const errors = [];
+  let totalBytes = 0;
+  for (const ref of refs) {
+    if (totalBytes >= MAX_BYTES_COOKBOOK_TOTAL) {
+      skippedBelowThreshold.push({ ...ref, reason: 'total-budget-exhausted' });
+      continue;
+    }
+    let lst;
+    try { lst = lstatSync(ref.absPath); } catch (err) {
+      errors.push(`lstat ${ref.cookbookName}: ${err?.message || err}`);
+      continue;
+    }
+    if (!lst.isFile()) continue;
+    if (lst.size > COOKBOOK_FILE_CEILING) {
+      errors.push(`oversize ${ref.cookbookName}: ${lst.size}B > ${COOKBOOK_FILE_CEILING}B`);
+      continue;
+    }
+    let raw;
+    try { raw = readFileSync(ref.absPath, 'utf8'); } catch (err) {
+      errors.push(`read ${ref.cookbookName}: ${err?.message || err}`);
+      continue;
+    }
+    const sections = parseCookbookSections(raw);
+    if (sections.length === 0) {
+      skippedBelowThreshold.push({ ...ref, reason: 'no-sections-parsed' });
+      continue;
+    }
+    const result = selectTopSectionForCookbook(raw, sections, promptKeywords);
+    if (!result) {
+      skippedBelowThreshold.push({ ...ref, reason: `no-section-met-min-score-${COOKBOOK_MIN_SCORE}` });
+      continue;
+    }
+    const remainingBudget = MAX_BYTES_COOKBOOK_TOTAL - totalBytes;
+    const extractedBytes = Buffer.byteLength(result.extracted, 'utf8');
+    if (extractedBytes > remainingBudget) {
+      skippedBelowThreshold.push({ ...ref, reason: `total-budget-would-overflow (${extractedBytes}B > ${remainingBudget}B remaining)` });
+      continue;
+    }
+    injected.push({
+      skill: ref.skill,
+      cookbookName: ref.cookbookName,
+      absPath: ref.absPath,
+      sectionTitle: result.section.title,
+      score: result.score,
+      bytes: extractedBytes,
+      extracted: result.extracted,
+    });
+    totalBytes += extractedBytes;
+  }
+  return { injected, totalBytes, scannedCount: refs.length, skippedBelowThreshold, errors, skipped: null };
+}
+
+function buildCookbookInjection({ result, promptKeywords }) {
+  if (result.skipped === 'env-disabled') return '';
+  if (result.injected.length === 0) {
+    // Emit a low-information stub only when at least 1 cookbook was scanned
+    // but none scored above threshold — surfaces signal that scoring fired
+    // but selected nothing, so the agent knows cookbook context is empty
+    // by design, not by error.
+    if (result.scannedCount > 0) {
+      return `═══ COOKBOOK AUTOLOAD (scanned ${result.scannedCount} cookbook(s); 0 section(s) met min-score=${COOKBOOK_MIN_SCORE}; ${promptKeywords.size} prompt keywords) ═══`;
+    }
+    return '';
+  }
+  const lines = [];
+  lines.push(`═══ COOKBOOK AUTOLOAD (top-1 sections from ${result.injected.length} cookbook(s); deterministic keyword-overlap scoring) ═══`);
+  for (const entry of result.injected) {
+    lines.push('');
+    lines.push(`──── ${entry.cookbookName} [section: "${entry.sectionTitle}" — score=${entry.score}] ────`);
+    lines.push(entry.extracted);
+  }
+  return lines.join('\n');
+}
+
+// AI-11803-F3 (2026-05-12) — read the parent handoff JSON if present
+// and within TTL. Returns the `parentAutoload` field (skill names,
+// memory filenames, cookbook section pointers) or null if absent / stale
+// / kill-switched / malformed.
+function readParentHandoffAutoload() {
+  if (/^(?:1|true|yes|on)$/i.test(String(process.env.ARIA_AUTOLOAD_PARENT_HANDOFF_OFF || ''))) {
+    return { result: null, skipped: 'env-disabled' };
+  }
+  if (!existsSync(PARENT_HANDOFF_PATH)) {
+    return { result: null, skipped: 'no-handoff-file' };
+  }
+  let raw;
+  try { raw = readFileSync(PARENT_HANDOFF_PATH, 'utf-8'); } catch (err) {
+    process.stderr.write(`[aria-pre-emit-autoload:parent-handoff-read-error] ${err?.message || err}\n`);
+    return { result: null, skipped: `read-error:${err?.message || err}` };
+  }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch (err) {
+    process.stderr.write(`[aria-pre-emit-autoload:parent-handoff-parse-error] ${err?.message || err}\n`);
+    return { result: null, skipped: `parse-error:${err?.message || err}` };
+  }
+  // TTL check — if handoff older than ttlMs vs writtenAt, ignore.
+  const ttlMs = Number(parsed.ttlMs) || (5 * 60 * 1000);
+  const writtenAtMs = new Date(parsed.writtenAt || 0).getTime();
+  if (Number.isFinite(writtenAtMs) && writtenAtMs > 0) {
+    const ageMs = Date.now() - writtenAtMs;
+    if (ageMs > ttlMs) {
+      return { result: null, skipped: `stale:age=${Math.round(ageMs/1000)}s>ttl=${Math.round(ttlMs/1000)}s` };
+    }
+  }
+  const parentAutoload = parsed.parentAutoload;
+  if (!parentAutoload || typeof parentAutoload !== 'object') {
+    return { result: null, skipped: 'no-parentAutoload-field' };
+  }
+  return { result: parentAutoload, skipped: null, ageMs: Date.now() - writtenAtMs };
+}
+
+// Default cognition vocabulary anchors the named-lens labels the
+// substrate-binding gate parses. Agents in the same session converge on
+// one vocabulary so emissions stay coherent across a turn.
+function chooseCognitionVocabulary() {
+  return ['nur', 'mizan', 'hikma', 'tafakkur', 'tadabbur', 'ilham', 'wahi', 'firasah'];
+}
+
+// Stage 5 — cross-turn substrate feedback: read recent gate-block events
+// from the gate-ledger and surface them as next-turn FRAME content. This
+// turns past gate-blocks into structural pressure on the next turn so the
+// agent literally cannot drift the same way twice without seeing it.
+function readRecentGateBlocks({ maxAgeMinutes = 30, maxEntries = 8, sessionId = null } = {}) {
+  const ledgerPath = `${HOME}/.claude/.aria-gate-ledger.jsonl`;
+  if (!existsSync(ledgerPath)) return [];
+  let raw;
+  try {
+    raw = readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const lines = raw.split('\n').filter(Boolean);
+  const recent = lines.slice(-300); // bound the parse cost
+  const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
+  const blocks = [];
+  for (let i = recent.length - 1; i >= 0 && blocks.length < maxEntries; i--) {
+    let entry;
+    try { entry = JSON.parse(recent[i]); } catch { continue; }
+    if (!entry || typeof entry !== 'object') continue;
+    if (entry.decision !== 'block') continue;
+    const t = Date.parse(entry.ts || '');
+    if (!Number.isFinite(t) || t < cutoff) continue;
+    if (sessionId && entry.sessionId && entry.sessionId !== sessionId) continue;
+    blocks.push({
+      ts: entry.ts,
+      hook: entry.hook,
+      source: entry.source,
+      reason: entry.reasonShort || '(no reason)',
+    });
+  }
+  return blocks;
+}
+
+function buildFrameInjection({ requiredSkills, reasons, redirectOnly, cognitionVocab, skillBodies, totalBytes, recentBlocks = [] }) {
+  if (!requiredSkills || requiredSkills.length === 0) {
+    const lines = [`${HEADER_PREFIX} no doctrine-bound skills required for this prompt; standard cognition expected.`];
+    if (recentBlocks && recentBlocks.length > 0) {
+      lines.push('');
+      lines.push('═══ STAGE 5 — RECENT GATE BLOCKS (cross-turn substrate feedback) ═══');
+      lines.push(`Past ${recentBlocks.length} block(s) within last 30 minutes for this session — adjust this turn to NOT recur:`);
+      for (const b of recentBlocks) {
+        lines.push(`  - [${b.hook}] ${b.source}: ${b.reason}`);
+      }
+      lines.push('Apply the lesson: same block reason in this turn means same drift pattern; address the root, not the surface.');
+    }
+    return lines.join('\n');
+  }
+  const lines = [];
+  lines.push(`${HEADER_PREFIX} FRAME — required skills loaded for this turn (content below should shape your work BEFORE you draft).`);
+  lines.push('');
+  lines.push(`Required skills (${requiredSkills.length}): ${requiredSkills.join(', ')}`);
+  if (reasons.length > 0) {
+    lines.push('Why these skills:');
+    for (const reason of reasons) lines.push(`  - ${reason}`);
+  }
+  lines.push('');
+  lines.push(`Total injected: ${totalBytes}B across ${skillBodies.filter(s => s.bytes > 0).length} skill(s).`);
+  lines.push('');
+  lines.push('═══ SKILL BODIES (operative content — apply, do not narrate) ═══');
+  lines.push('');
+  for (const entry of skillBodies) {
+    if (entry.bytes === 0) {
+      if (entry.reason !== 'missing' && entry.reason !== 'ok') {
+        lines.push(`──── ${entry.skill} ──── [SKIPPED: ${entry.reason}]`);
+        lines.push('');
+      }
+      continue;
+    }
+    lines.push(`──── ${entry.skill}${entry.truncated ? ' (truncated)' : ''} ────`);
+    lines.push(entry.body);
+    lines.push('');
+  }
+  lines.push('═══ END SKILL BODIES ═══');
+  lines.push('');
+  lines.push('═══ DRIVING RULES (apply during work) ═══');
+  lines.push('- Each skill above carries operative rules. Apply them as you draft, edit, and tool-call.');
+  lines.push('- Do NOT emit lens blocks as ceremony at end-of-turn. The lens IS the thinking that already happened.');
+  lines.push('- If a skill names a doctrine memory, treat it as an active constraint, not a citation.');
+  lines.push('- If two skills conflict, the more specific one (e.g., aria-harness-deploy) outranks the general (e.g., aria-forge-guardrails).');
+  lines.push('');
+  lines.push('═══ COGNITION VOCABULARY ═══');
+  lines.push(`Use these named lenses for substantive emissions: ${cognitionVocab.join(', ')}`);
+  lines.push('Per substantive action emit:');
+  lines.push('  <cognition> with all 8 named lenses (≥20 chars per lens, anchored to substrate)');
+  lines.push('  <expected> with measurable predicate');
+  lines.push('  <applied_cognition> with decision_delta + dominant_domain + binds_to + expected_predicate + artifact_change');
+  lines.push('');
+  lines.push('═══ POST-QA CRITERIA (verify before completion claim) ═══');
+  lines.push('- Did at least one substrate change as a result of cognition firing?');
+  lines.push('- Is every readiness/completion word ("done", "fixed", "shipped", "verified") backed by tool-output evidence?');
+  lines.push('- Does the closing prose match output discipline (no raw IPs/SHAs/file-paths in chat; semantic reframing applied)?');
+  lines.push('- Are unresolved discoveries either fixed-now or tracked-as-task before turn end?');
+  if (redirectOnly) {
+    lines.push('');
+    lines.push('NOTE: redirectOnly mode — gate guides not hard-blocks. Treat guidance as quality bar, not skip-license.');
+  }
+  if (recentBlocks && recentBlocks.length > 0) {
+    lines.push('');
+    lines.push('═══ STAGE 5 — RECENT GATE BLOCKS (cross-turn substrate feedback) ═══');
+    lines.push(`Past ${recentBlocks.length} block(s) within last 30 minutes for this session — adjust this turn to NOT recur:`);
+    for (const b of recentBlocks) {
+      lines.push(`  - [${b.hook}] ${b.source}: ${b.reason}`);
+    }
+    lines.push('Apply the lesson: the same block reason in this turn means the same drift pattern; address the root, not the surface.');
+  }
+  return lines.join('\n');
+}
+
+// Baseline skill set that loads unconditionally for any non-empty prompt.
+// Per Hamza directive 2026-05-12: the autoloader is NOT cheap — any 1%
+// chance a skill helps must fire it; no non-trivial prompt continues
+// without at least one skill loaded. aria-cognition-autofire is the
+// foundational substrate trigger that every turn deserves in context.
+const BASELINE_SKILLS = ['aria-cognition-autofire'];
+
+// AI-11803-F5 (2026-05-12): active-workflow skill allow-list. These
+// skills have explicit "Required Workflow" / "Apply the pipeline" /
+// "TRIGGER for cognitive turn" imperatives in their bodies. Loading
+// them as context is NOT the same as running their workflow — the LLM
+// MUST invoke them via the Skill tool when their body is loaded.
+// See feedback_autoload_does_not_invoke_skills.md for the full Recovery
+// Contract (classification A/B/C/D, 5-per-turn cap, parent composition).
+// Maintenance protocol: review new skills' frontmatter for active-shape
+// signals; add to this list. False-positive operator-frustration → move
+// back to passive-substrate (default).
+// QA-FIX-1 (2026-05-12, qiyas Tadabbur EXCAVATE): allow-list expanded from
+// 5 to 8 after qiyas+tadabbur QA pass found 3 missing active-workflow
+// skills. ghazali-8lens has explicit Required Workflow + 8-lens validation
+// pipeline. aria-decision-mizan is active refusal-shape (refuses to choose
+// for owner, surfaces both options — active not passive). tafakkur has
+// explicit 5-lens contemplation workflow. Cap is per-TURN INVOCATION count
+// (5), not list size; list can grow as more active skills are identified.
+const ACTIVE_WORKFLOW_SKILLS = new Set([
+  'tadabbur',
+  'qiyas-analogy',
+  'aria-cognition-batch',
+  'mizan',
+  'aria-forge-guardrails',
+  'ghazali-8lens',
+  'aria-decision-mizan',
+  'tafakkur',
+]);
+const INVOCATION_CAP_PER_TURN = 5;
+
+function main() {
+  const event = readEvent();
+  const prompt = String(
+    event.user_prompt ??
+    event.userPrompt ??
+    event.prompt ??
+    event.text ??
+    event.message ??
+    ''
+  ).trim();
+
+  // ARIA_AUTOLOAD_DISABLE is the proper kill switch for this hook
+  // specifically. Use only when debugging the autoload itself. The
+  // gates-off marker is for blocking gates, NOT for disabling content
+  // enrichment — disabling enrichment is exactly what made cognition
+  // ceremonial in the first place.
+  if (/^(?:1|true|yes|on)$/i.test(String(process.env.ARIA_AUTOLOAD_DISABLE || ''))) {
+    appendGateLedger({ hook: 'pre-emit-autoload', event: HOOK_EVENT_NAME, decision: 'bypass', source: 'pre-emit/autoload-disabled-env', reasonShort: 'ARIA_AUTOLOAD_DISABLE=1', sessionId: event.session_id });
+    emitNoop('ARIA_AUTOLOAD_DISABLE=1');
+  }
+
+  if (!prompt) {
+    appendGateLedger({ hook: 'pre-emit-autoload', event: HOOK_EVENT_NAME, decision: 'allow', source: 'pre-emit/empty-prompt', sessionId: event.session_id });
+    emitNoop('empty user prompt');
+  }
+
+  let classified;
+  try {
+    classified = classifyRequiredSkills({
+      text: prompt,
+      isOutputCloseout: false,
+    });
+  } catch (err) {
+    // Fail-allow on classifier crash. Record the error for postmortem.
+    appendGateLedger({
+      hook: 'pre-emit-autoload',
+      event: HOOK_EVENT_NAME,
+      decision: 'allow',
+      source: 'pre-emit/classifier-error',
+      reasonShort: err instanceof Error ? err.message : String(err),
+      sessionId: event.session_id,
+    });
+    emitNoop(`classifier error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Abundance doctrine — two-component substrate provisioning:
+  // (1) BASELINE_SKILLS unconditionally for any non-empty prompt
+  // (2) keyword classifier results (already in classified.requiredSkills)
+  //
+  // No LLM-call semantic backstop. Per Hamza directive 2026-05-12:
+  // adding an LLM call to teach the LLM which skills to use is
+  // regressive — it outsources meta-cognition the model is supposed
+  // to perform from the substrate already loaded. The keyword
+  // classifier picks obvious matches; the baseline ensures non-empty
+  // substrate; the model itself is accountable for applying the
+  // loaded skills correctly (forced by the anchor-verification gate
+  // and the cognition vocabulary requirements downstream).
+  const initialSkillSet = new Set(classified.requiredSkills || []);
+  for (const s of BASELINE_SKILLS) {
+    if (existsSync(`${SKILLS_DIR}/${s}/SKILL.md`)) initialSkillSet.add(s);
+  }
+
+  // AI-11803-F3: parent-handoff substrate inheritance. If this autoload
+  // is firing inside a sub-agent session, layer the parent's pinned
+  // skill names into the load set BEFORE cascade expansion. Sub-agent's
+  // own classifier output is preserved (already in initialSkillSet);
+  // parent pins are additive — sub-agent sees its own narrow-prompt
+  // skills + the parent's broader doctrine context.
+  const parentHandoffRead = readParentHandoffAutoload();
+  const parentHandoff = parentHandoffRead.result;
+  if (parentHandoff && Array.isArray(parentHandoff.requiredSkills)) {
+    let inheritedCount = 0;
+    for (const s of parentHandoff.requiredSkills) {
+      if (typeof s !== 'string') continue;
+      if (existsSync(`${SKILLS_DIR}/${s}/SKILL.md`) && !initialSkillSet.has(s)) {
+        initialSkillSet.add(s);
+        inheritedCount++;
+      }
+    }
+    process.stderr.write(`[aria-pre-emit-autoload:parent-handoff-inherited] skills=${inheritedCount} memories=${(parentHandoff.memoryFilenames||[]).length} cookbooks=${(parentHandoff.cookbookSelections||[]).length} ageMs=${parentHandoffRead.ageMs}\n`);
+  }
+
+  const cognitionVocab = chooseCognitionVocabulary();
+
+  // AI-11803-LOOP1 (2026-05-12) — cascade expansion replaces the prior
+  // single-pass body-injection loop. The cascade reads each skill body,
+  // parses its Load First / Mode Selection / Load Order sections, and
+  // recursively enqueues the named skills (existence-filtered, cycle-safe,
+  // budget-capped). Final requiredSkills reflects the FULL loaded set so
+  // sidecar + ledger downstream consumers see what actually ran in context.
+  const cascade = expandSkillCascade([...initialSkillSet]);
+  classified.requiredSkills = [...cascade.order].sort();
+  const skillBodies = cascade.order.map((skill) => ({ skill, ...cascade.loadedBodies.get(skill) }));
+  const totalBytes = cascade.totalBytes;
+  const cascadeDepth = cascade.cascadeDepth;
+  const depthInjected = cascade.depthInjected;
+  const depthAttempted = cascade.depthAttempted;
+  const cascadedSkills = cascade.order.filter((s) => !initialSkillSet.has(s));
+
+  // AI-11803-LOOP2: doctrine-trigger pre-emit scan. Matches the prompt
+  // against the 79-trigger map. Computed here (before sidecar+ledger writes)
+  // so its results land in the meta + sidecar telemetry too.
+  const doctrineScan = scanDoctrineTriggers(prompt);
+
+  // AI-11803-F5 (2026-05-12) — compute invocationRequired set: which of
+  // the loaded skills this turn are active-workflow (Skill tool MUST be
+  // called) vs passive-substrate (body-as-context is sufficient). Capped
+  // at INVOCATION_CAP_PER_TURN to prevent operator-overhead from too many
+  // sequential invocations. The list is surfaced to the LLM via a
+  // dedicated additionalContext section AND persisted to sidecar so the
+  // future F5.c stop-gate can verify the named skills were actually
+  // invoked before turn-close.
+  //
+  // QA-FIX-2 (2026-05-12): source the candidate skills from cascade.order
+  // (the FINAL loaded set after cascade expansion) instead of
+  // classified.requiredSkills (initial classifier output). Cascade can
+  // pull active-workflow skills depth-N (e.g. aria-cognition-batch in
+  // initial set loads tadabbur via Load First section); those depth-N
+  // active skills must also appear in invocationRequired or the contract
+  // misses them.
+  //
+  // QA-FIX-3 (2026-05-12): include parent-handoff inherited active skills
+  // so sub-agents continue to honor the parent's invocation requirements
+  // even when the sub-agent's own classifier didn't trigger them.
+  const invocationRequiredSet = new Set();
+  for (const skill of cascade.order) {
+    if (invocationRequiredSet.size >= INVOCATION_CAP_PER_TURN) break;
+    if (ACTIVE_WORKFLOW_SKILLS.has(skill)) invocationRequiredSet.add(skill);
+  }
+  if (parentHandoff && Array.isArray(parentHandoff.invocationRequired)) {
+    for (const skill of parentHandoff.invocationRequired) {
+      if (invocationRequiredSet.size >= INVOCATION_CAP_PER_TURN) break;
+      if (typeof skill === 'string' && ACTIVE_WORKFLOW_SKILLS.has(skill)) {
+        invocationRequiredSet.add(skill);
+      }
+    }
+  }
+  const invocationRequired = [...invocationRequiredSet];
+
+  // AI-11803-STEP4 (2026-05-12) — MEMORY.md auto-load + top-N body injection.
+  // Dedup set: memories already injected via trigger-map this turn must not
+  // double-inject as top-N bodies (would waste budget + repeat content).
+  // QA-FIX-2 (2026-05-12): kill switch parity with cascade + trigger-map.
+  // ARIA_AUTOLOAD_MEMORY_OFF=1 disables memory autoload while leaving the
+  // other primitives running, for isolated debugging of this primitive.
+  const memoryAutoloadDisabled = /^(?:1|true|yes|on)$/i.test(String(process.env.ARIA_AUTOLOAD_MEMORY_OFF || ''));
+  const triggerMatchedMemories = new Set(doctrineScan.matches.map((m) => m.memory));
+  const memoryIndexResult = memoryAutoloadDisabled
+    ? { body: '', bytes: 0, totalLines: 0, droppedLines: 0, reason: 'env-disabled' }
+    : readMemoryIndex();
+  const memoryBodyResult = memoryAutoloadDisabled
+    ? { injected: [], totalBytes: 0, dedupedFilenames: [], scoredCount: 0, errors: [] }
+    : selectTopNMemoryBodies(triggerMatchedMemories);
+
+  // AI-11803-STEP5 (2026-05-12) — cookbook auto-pull from loaded skill bodies.
+  // Scans skillBodies for `references/<name>.md` patterns, parses each
+  // cookbook's sections, scores by prompt-keyword overlap, injects top-1
+  // section per cookbook above min-score threshold. Same-turn dedup via
+  // Set of absPath. Loop-safe: depth cap = 1 (cookbooks don't transitively
+  // pull other cookbooks). Kill switch: ARIA_AUTOLOAD_COOKBOOK_OFF=1.
+  const promptKeywords = extractPromptKeywords(prompt);
+  const cookbookResult = autoloadCookbookSections(skillBodies, promptKeywords);
+
+  const sidecar = {
+    schema: 'aria-current-turn-context.v2',
+    ts: new Date().toISOString(),
+    sessionId: event.session_id ?? null,
+    // AI-11803-F3: chain-depth marker — if this autoload inherited parent
+    // handoff substrate, downstream Agent dispatch hook reads this and
+    // SKIPS propagating to grandchild (chain depth cap = 1).
+    parentHandoffChainDepth: parentHandoff ? 1 : 0,
+    parentHandoffSkipped: parentHandoffRead.skipped,
+    // AI-11803-F5: active-workflow skills that MUST be invoked via the
+    // Skill tool this turn. Doctrine: feedback_autoload_does_not_invoke_skills.md.
+    // The F5.c stop-gate (future step) reads this and verifies invocations
+    // before turn-close.
+    invocationRequired,
+    promptHash: createHash('sha256').update(prompt).digest('hex').slice(0, 16),
+    requiredSkills: classified.requiredSkills,
+    redirectOnly: classified.redirectOnly === true,
+    reasons: classified.reasons,
+    cognitionVocabulary: cognitionVocab,
+    injection: {
+      totalBytes,
+      perSkill: skillBodies.map(s => ({
+        skill: s.skill,
+        bytes: s.bytes,
+        fullBytes: s.fullBytes,
+        truncated: !!s.truncated,
+        redacted: !!s.redacted,
+        reason: s.reason,
+        // First 600 chars of injected body so post-phase can verify what
+        // was actually visible to the agent.
+        excerpt: typeof s.body === 'string' ? s.body.slice(0, 600) : '',
+      })),
+    },
+    memoryAutoload: {
+      indexBytes: memoryIndexResult.bytes,
+      indexReason: memoryIndexResult.reason,
+      indexDroppedLines: memoryIndexResult.droppedLines,
+      bodiesBytes: memoryBodyResult.totalBytes,
+      bodiesInjected: memoryBodyResult.injected.map((e) => ({
+        filename: e.filename, tier: e.tier, score: e.score, bytes: e.bytes,
+      })),
+      bodiesDeduped: memoryBodyResult.dedupedFilenames,
+      scoredCount: memoryBodyResult.scoredCount,
+    },
+    cookbookAutoload: {
+      scannedCount: cookbookResult.scannedCount,
+      keywordCount: promptKeywords.size,
+      totalBytes: cookbookResult.totalBytes,
+      injected: cookbookResult.injected.map((e) => ({
+        skill: e.skill,
+        cookbookName: e.cookbookName,
+        sectionTitle: e.sectionTitle,
+        score: e.score,
+        bytes: e.bytes,
+      })),
+      skippedBelowThreshold: cookbookResult.skippedBelowThreshold,
+      skipped: cookbookResult.skipped,
+      errors: cookbookResult.errors,
+    },
+  };
+  writeSidecar(sidecar);
+
+  appendGateLedger({
+    hook: 'pre-emit-autoload',
+    event: HOOK_EVENT_NAME,
+    decision: 'allow',
+    source: 'pre-emit/autoload',
+    reasonShort: classified.requiredSkills.length > 0
+      ? `injected=${totalBytes}B skills=${classified.requiredSkills.join(',')}`
+      : 'no doctrine-bound skills required',
+    meta: {
+      requiredSkills: classified.requiredSkills,
+      redirectOnly: classified.redirectOnly === true,
+      promptLen: prompt.length,
+      injectedBytes: totalBytes,
+      injectedSkills: skillBodies.filter(s => s.bytes > 0).map(s => s.skill),
+      skippedSkills: skillBodies.filter(s => s.bytes === 0).map(s => ({ skill: s.skill, reason: s.reason })),
+      cascadeDepth,
+      depthInjected,
+      depthAttempted,
+      cascadedSkills,
+      doctrineTriggerMatchCount: doctrineScan.matches.length,
+      doctrineTriggersMatched: doctrineScan.matches.map((m) => m.trigger),
+      doctrineTriggerSkipped: doctrineScan.skipped,
+      memoryIndexBytes: memoryIndexResult.bytes,
+      memoryIndexReason: memoryIndexResult.reason,
+      memoryIndexDroppedLines: memoryIndexResult.droppedLines,
+      memoryBodiesInjected: memoryBodyResult.injected.length,
+      memoryBodiesInjectedBytes: memoryBodyResult.totalBytes,
+      memoryBodiesScoredCount: memoryBodyResult.scoredCount,
+      memoryBodiesDeduped: memoryBodyResult.dedupedFilenames,
+      memoryBodiesSelected: memoryBodyResult.injected.map((e) => ({ filename: e.filename, tier: e.tier, bytes: e.bytes })),
+      cookbookScannedCount: cookbookResult.scannedCount,
+      cookbookInjectedCount: cookbookResult.injected.length,
+      cookbookInjectedBytes: cookbookResult.totalBytes,
+      cookbookKeywordCount: promptKeywords.size,
+      cookbookSkippedReasons: cookbookResult.skippedBelowThreshold.map((s) => `${s.cookbookName}:${s.reason}`),
+      cookbookSkipped: cookbookResult.skipped,
+      invocationRequired,
+      invocationRequiredCount: invocationRequired.length,
+    },
+    sessionId: event.session_id,
+  });
+
+  // Stage 5: pull recent gate-blocks for this session so the agent sees
+  // them as pre-flight FRAME context and cannot drift the same way twice.
+  const recentBlocks = readRecentGateBlocks({ sessionId: event.session_id });
+
+  const doctrineInjection = buildDoctrineTriggerInjection(doctrineScan.matches);
+
+  const memoryInjection = buildMemoryAutoloadInjection({
+    indexResult: memoryIndexResult,
+    bodyResult: memoryBodyResult,
+  });
+
+  const frameInjection = buildFrameInjection({
+    requiredSkills: classified.requiredSkills,
+    reasons: classified.reasons,
+    redirectOnly: classified.redirectOnly === true,
+    cognitionVocab,
+    skillBodies,
+    totalBytes,
+    recentBlocks,
+  });
+
+  const cookbookInjection = buildCookbookInjection({
+    result: cookbookResult,
+    promptKeywords,
+  });
+
+  // AI-11803-F5: INVOCATION REQUIRED section — make it explicit that
+  // active-workflow skills loaded as bodies still need Skill tool
+  // invocation. Doctrine drift if skipped (see
+  // feedback_autoload_does_not_invoke_skills.md).
+  let invocationInjection = '';
+  if (invocationRequired.length > 0) {
+    const lines = [];
+    lines.push('═══ INVOCATION REQUIRED (active-workflow skills — body in context is NOT enough) ═══');
+    lines.push(`The following loaded skills are ACTIVE-WORKFLOW. You MUST invoke each via the Skill tool BEFORE drafting substantive work this turn. Reading the body in context does NOT run the workflow.`);
+    lines.push('');
+    for (const skill of invocationRequired) {
+      lines.push(`  • ${skill}`);
+    }
+    lines.push('');
+    lines.push('Doctrine: feedback_autoload_does_not_invoke_skills.md');
+    lines.push('Recovery Contract — every loaded active-workflow skill closes the turn classified as:');
+    lines.push('  A. INVOKED — Skill tool call visible in transcript');
+    lines.push('  B. COMPOSED-VIA-PARENT — parent skill (e.g., aria-cognition-batch) invoked, child is a composition member');
+    lines.push('  C. SCOPE-EXEMPT — prompt is read-only inspection of the skill body, not asking the workflow to run');
+    lines.push('  D. CAP-DEFERRED — > 5 active-workflow skills loaded; deferred to follow-up');
+    lines.push(`No other classifications permitted. "I considered it" / "it's loaded" / "substrate has it" = the antipattern.`);
+    invocationInjection = lines.join('\n');
+  }
+
+  const parts = [frameInjection];
+  if (invocationInjection) parts.push(invocationInjection);
+  if (doctrineInjection) parts.push(doctrineInjection);
+  if (memoryInjection) parts.push(memoryInjection);
+  if (cookbookInjection) parts.push(cookbookInjection);
+  const additionalContext = parts.join('\n\n');
+
+  emit({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT_NAME,
+      additionalContext,
+    },
+  });
+}
+
+main();