@aria_asi/cli 0.2.39 → 0.2.41

package/dist/assets/hooks/lib/self-doctrine-check.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * self-doctrine-check.mjs — scan text against doctrine_trigger_map.
+ *
+ * Phase 0 audit Tier 0 M0.SELFREVIEW.X1 + Phase 7 QA Pass M7.0.X7:
+ * the scanner that pre-commit hooks (and on-demand CLI) use to detect
+ * trip-vocab the doctrine_trigger_map counters. The scanner returns
+ * structured violations; the caller decides whether to block, warn,
+ * or allow with acknowledgment.
+ *
+ * Hamza caught (2026-05-06) that I'd shipped 35 commits with cognition-
+ * lattice labels in commit messages without actually running the
+ * lattice — the labels were performing the work. Real doctrine scan
+ * surfaced 2 unambiguous violations in my own committed code
+ * (the trip-vocab phrase × 2). This scanner is the load-bearing
+ * fix that prevents the recurrence: ceremony cannot substitute for
+ * doctrine-self-check: best.?effort describing-the-finding-the-scanner-detects
+ * substance when the substance check runs at commit time.
+ *
+ * Design principles applied (via REAL qiyas + predictor this time):
+ *
+ *   Qiyas — analogous to ESLint + lint-staged + husky pre-commit. Same
+ *   shape: scan staged content, match against rules, allow explicit
+ *   acknowledgment as escape hatch. Failure modes of that pattern:
+ *     - doctrine-self-check: use the override|skip the gate|emergency flag|temporarily bypass|use the env disable|force through|DEPLOY_ALLOW_NO_ADMISSION_POLICY|ARIA_BINDING_ENABLED=false|--no-verify|--force documenting-bypass-class-explicitly-out-of-scope-for-this-hook
+ *     - Bypass via --no-verify (git allows; outside our control here)
+ *     - Habituation if false-positive rate too high
+ *     - Self-reference: scanner code itself contains trip-vocab
+ *       strings (it has to, to detect them) — must be allowlisted
+ *     - Description-of-antipattern vs invocation-of-antipattern —
+ *       strict scan flags both; we allow per-line acknowledgment
+ *
+ *   Predictor — the falsifiable claim:
+ *     "scanForTripVocab(MY_35_COMMIT_DIFF) returns at least 2 violations
+ *      with trigger='best.?effort'. If not, the scanner is broken."
+ *     The included regression test runs this exact assertion.
+ *
+ *   Tadabbur — 4th-order consequence: commit history accumulates
+ *   explicit `doctrine-self-check:` markers as audit trail. Operator
+ *   can grep for "doctrine-self-check:" to see every intentional
+ *   acknowledgment over time. Discipline-by-construction.
+ *
+ *   Doctrine self-bind — this scanner ITSELF is on the no-graceful-
+ *   degradation path: if doctrine_trigger_map.json is missing or
+ *   malformed, the scanner THROWS (does NOT silently return zero
+ *   violations). Silent-zero would be the antipattern.
+ *
+ * Usage:
+ *   import { scanForTripVocab, formatViolations, loadDoctrineTriggers } from './self-doctrine-check.mjs';
+ *   const triggers = loadDoctrineTriggers();
+ *   const violations = scanForTripVocab(text, { triggers });
+ *   if (violations.length > 0) console.error(formatViolations(violations));
+ *
+ * The acknowledgment-marker contract for callers:
+ *   - In a commit message: a line `doctrine-self-check: <trigger> <counter-applied>`
+ *     allows the named trigger across the entire commit.
+ *   - On a per-line basis (in code): a comment containing
+ *     `doctrine-self-check: <trigger>` adjacent (within 3 lines) to
+ *     the trip-vocab match allows that specific match.
+ *
+ * Doctrine bind:
+ *   - feedback_no_graceful_degradation.md — scanner fails LOUD on
+ *     malformed trigger map (vs returning zero violations).
+ *   - axiom_runtime_rule.admit_ignorance — every match is surfaced;
+ *     acknowledgment is explicit not implicit.
+ *   - clean_cognition — single scanner library; one place for the rules.
+ *
+ * Mirror: this file MUST be byte-identical between
+ *   ops/claude-hooks/lib/self-doctrine-check.mjs
+ *   packages/aria-connector/hooks/lib/self-doctrine-check.mjs
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Search order for the canonical doctrine trigger map. The runtime/state
+// copy (synced by doctrine-trigger-map-sync.mjs) takes precedence — that's
+// the live form gates use. Falls back to the canonical ops/ source.
+const TRIGGER_MAP_SEARCH_PATHS = [
+  join(homedir(), '.aria', 'runtime', 'state', 'doctrine_trigger_map.json'),
+  resolve(HERE, '..', 'doctrine_trigger_map.json'),
+  // Repo-root fallback for CI / on-demand runs from non-installed locations.
+  resolve(HERE, '..', '..', '..', 'ops', 'claude-hooks', 'doctrine_trigger_map.json'),
+];
+
+/**
+ * Load the canonical doctrine trigger map.
+ * Throws if no map can be found OR if the JSON is malformed — never
+ * returns a silently-empty trigger list (that would be the silent-fail
+ * antipattern this scanner exists to detect elsewhere).
+ *
+ * @returns {Array<{ trigger: string, memory: string, teaching: string, counter_action: string, regex: RegExp }>}
+ */
+export function loadDoctrineTriggers() {
+  let path = null;
+  for (const candidate of TRIGGER_MAP_SEARCH_PATHS) {
+    if (existsSync(candidate)) { path = candidate; break; }
+  }
+  if (!path) {
+    throw new Error(
+      `[self-doctrine-check] doctrine_trigger_map.json not found. ` +
+      `Searched: ${TRIGGER_MAP_SEARCH_PATHS.join(', ')}`,
+    );
+  }
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw new Error(`[self-doctrine-check] failed to read ${path}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`[self-doctrine-check] doctrine map at ${path} is malformed JSON: ${err.message}`);
+  }
+  const triggers = Array.isArray(parsed?.triggers) ? parsed.triggers : [];
+  if (triggers.length === 0) {
+    throw new Error(`[self-doctrine-check] doctrine map at ${path} has no triggers`);
+  }
+  // Pre-compile regex per entry. Malformed regex surfaces with a named
+  // entry (was: silent skip in collectDriftHits per M0.H.6).
+  return triggers.map((entry, index) => {
+    let regex;
+    try {
+      regex = new RegExp(entry.trigger, 'gi');
+    } catch (err) {
+      throw new Error(
+        `[self-doctrine-check] doctrine map entry ${index} (${entry.trigger}) has invalid regex: ${err.message}`,
+      );
+    }
+    return {
+      trigger: String(entry.trigger || ''),
+      memory: String(entry.memory || ''),
+      teaching: String(entry.teaching || ''),
+      counter_action: String(entry.counter_action || ''),
+      regex,
+    };
+  });
+}
+
+/**
+ * Scan text for trip-vocab matches against the doctrine trigger map.
+ *
+ * @param {string} text  the input to scan (diff content, commit message, etc.)
+ * @param {Object} opts
+ * @param {Array} opts.triggers  pre-loaded triggers (from loadDoctrineTriggers)
+ * @param {string[]} [opts.acknowledged]  list of trigger strings the caller
+ *   has already acknowledged (e.g., from a commit-message `doctrine-self-check:`
+ *   line). Matches against acknowledged triggers are filtered from output.
+ * @returns {Array<{
+ *   trigger: string, memory: string, teaching: string, counter_action: string,
+ *   match: string, line_number: number, line_text: string,
+ *   has_inline_acknowledgment: boolean,
+ * }>}
+ */
+export function scanForTripVocab(text, opts = {}) {
+  const triggers = opts.triggers;
+  if (!Array.isArray(triggers) || triggers.length === 0) {
+    throw new Error('[self-doctrine-check] scanForTripVocab requires opts.triggers (load via loadDoctrineTriggers)');
+  }
+  const acknowledged = (opts.acknowledged || []).map(String);
+  let src = String(text || '');
+  if (!src) return [];
+
+  // Auto-detect unified-diff format and filter to added lines only.
+  // Heuristic: presence of `diff --git` header OR `^@@ ` hunk header anywhere.
+  // When detected, keep only `+`-prefix lines (excluding the `+++` file
+  // headers). Context lines (` `-prefix) are repo content NOT being added by
+  // this commit — flagging them would be a false positive for the staged
+  // commit. Removed lines (`-`-prefix) are being removed and are not in
+  // the post-commit state, so they don't apply either.
+  const looksLikeDiff = /(^|\n)(?:diff --git |@@ )/.test(src);
+  if (looksLikeDiff) {
+    const filteredLines = [];
+    for (const line of src.split('\n')) {
+      if (line.startsWith('+++ ')) continue;     // file header, not content
+      if (line.startsWith('+')) {
+        filteredLines.push(line.slice(1));        // strip the `+` prefix
+      } else {
+        filteredLines.push('');                   // preserve line numbering
+      }
+    }
+    src = filteredLines.join('\n');
+  }
+
+  const lines = src.split('\n');
+  const violations = [];
+
+  for (const t of triggers) {
+    // Reset regex lastIndex (we share regex across scans with /g).
+    t.regex.lastIndex = 0;
+    let m;
+    while ((m = t.regex.exec(src)) !== null) {
+      const matchedText = m[0];
+      // Compute line number from match index.
+      const upToMatch = src.slice(0, m.index);
+      const lineNumber = upToMatch.split('\n').length;
+      const lineText = lines[lineNumber - 1] || '';
+      // Per-commit acknowledgment: any acknowledgment line whose text
+      // contains the trigger pattern (case-insensitive substring match)
+      // applies to all matches of that trigger across this commit.
+      const tLower = t.trigger.toLowerCase();
+      const isAcknowledged = acknowledged.some((a) => {
+        const aLower = String(a).toLowerCase();
+        return aLower.includes(tLower);
+      });
+      if (isAcknowledged) continue;
+      // Per-line acknowledgment: search ±3 lines around the match for
+      // `doctrine-self-check: <trigger>` comment.
+      const windowStart = Math.max(0, lineNumber - 4);
+      const windowEnd = Math.min(lines.length, lineNumber + 3);
+      const windowText = lines.slice(windowStart, windowEnd).join('\n').toLowerCase();
+      const inlineAckRx = /doctrine-self-check:\s*(.+?)(?:$|\n)/gim;
+      let hasInlineAck = false;
+      let am;
+      while ((am = inlineAckRx.exec(windowText)) !== null) {
+        if (am[1].toLowerCase().includes(tLower)) { hasInlineAck = true; break; }
+      }
+      if (hasInlineAck) continue;
+      // Self-reference allowlist: lines that ARE the trigger map itself
+      // (the trigger string is present in JSON form for legitimate reasons).
+      // Heuristic: skip lines containing `"trigger":` JSON syntax.
+      if (/"trigger":\s*"/.test(lineText)) continue;
+
+      violations.push({
+        trigger: t.trigger,
+        memory: t.memory,
+        teaching: t.teaching,
+        counter_action: t.counter_action,
+        match: matchedText,
+        line_number: lineNumber,
+        line_text: lineText.slice(0, 200),
+        has_inline_acknowledgment: false,
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Extract `doctrine-self-check: <trigger-expression> <counter-action>`
+ * markers from a commit message. Returns the list of acknowledgment
+ * lines (the full text after `doctrine-self-check:` up to end-of-line).
+ *
+ * Acknowledgment matches a trigger when the ack line contains the
+ * trigger's literal text as a substring (case-insensitive) — this lets
+ * multi-word triggers (e.g. the literal phrase the doctrine map counters)
+ * or regex-source triggers be acknowledged with the literal trigger
+ * doctrine-self-check: graceful degradation describing-the-trigger-shape-the-API-supports
+ * string in the ack line.
+ */
+export function parseAcknowledgments(commitMessage) {
+  const src = String(commitMessage || '');
+  const ack = [];
+  const rx = /doctrine-self-check:\s*(.+?)\s*$/gim;
+  let m;
+  while ((m = rx.exec(src)) !== null) {
+    ack.push(m[1].trim());
+  }
+  return ack;
+}
+
+/**
+ * Format violations for human-readable output.
+ */
+export function formatViolations(violations) {
+  if (!violations || violations.length === 0) return '';
+  const lines = [];
+  lines.push('');
+  lines.push('=== ARIA SELF-DOCTRINE-CHECK ===');
+  lines.push(`${violations.length} doctrine trip-vocab match(es) detected:`);
+  lines.push('');
+  // Group by trigger for readability.
+  const byTrigger = new Map();
+  for (const v of violations) {
+    if (!byTrigger.has(v.trigger)) byTrigger.set(v.trigger, []);
+    byTrigger.get(v.trigger).push(v);
+  }
+  let i = 0;
+  for (const [trigger, group] of byTrigger.entries()) {
+    i++;
+    const sample = group[0];
+    lines.push(`${i}. trigger: ${trigger} (${group.length} match${group.length === 1 ? '' : 'es'})`);
+    if (sample.memory) lines.push(`   memory: ${sample.memory}`);
+    if (sample.teaching) lines.push(`   teaching: ${sample.teaching}`);
+    if (sample.counter_action) lines.push(`   counter: ${sample.counter_action}`);
+    lines.push(`   first match: line ${sample.line_number}: "${sample.line_text}"`);
+    if (group.length > 1) {
+      lines.push(`   other lines: ${group.slice(1).map((v) => v.line_number).join(', ')}`);
+    }
+    lines.push('');
+  }
+  lines.push('To proceed:');
+  lines.push('  (a) REWRITE the trip-vocab — remove the phrase, surface the failure, apply the counter-action.');
+  lines.push('  (b) ACKNOWLEDGE the trigger explicitly: add a line to your commit message:');
+  lines.push('        doctrine-self-check: <trigger-pattern> <counter-action-applied>');
+  lines.push('      OR add a comment near the trip-vocab line:');
+  lines.push('        # doctrine-self-check: <trigger-pattern>');
+  lines.push('  (c) Per-line description-of-antipattern (e.g., comments naming what was');
+  lines.push('      replaced) is allowed — add the inline acknowledgment to mark it.');
+  lines.push('');
+  lines.push('See ops/claude-hooks/doctrine_trigger_map.json for full counter-doctrine details.');
+  return lines.join('\n');
+}
+
+function escapeForRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export default {
+  loadDoctrineTriggers,
+  scanForTripVocab,
+  parseAcknowledgments,
+  formatViolations,
+};

package/dist/assets/hooks/lib/sensitive-shape-detector.mjs

@@ -0,0 +1,64 @@
+// Shape-based detector for sealed-material artifacts (PEM blocks, vendor
+// prefixes, JWT bearer shapes, env assignments with high-entropy values).
+//
+// Replaces the bare-word regex at runtime-client.mjs that fired on benign
+// mentions of vocabulary in code comments / variable names / error messages.
+// Per feedback_break_action_class_loops.md the path-fix moves detection to
+// a fresh file with structural matchers, instead of bare lexical words.
+
+const SHAPE_PATTERNS = Object.freeze([
+  // PEM block opener — RFC 7468 framing, any label.
+  /-----BEGIN [A-Z]+( [A-Z]+)*-----/,
+
+  // Anthropic-style sealed prefix (visible vendor framing only).
+  /\bsk-ant-api0[0-9]-[A-Za-z0-9_\-]{40,}/,
+
+  // OpenAI-style sealed prefix.
+  /\bsk-(?:proj|live|test)-[A-Za-z0-9_\-]{30,}/,
+
+  // AWS access-id shape (long-lived + temporary forms).
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bASIA[0-9A-Z]{16}\b/,
+
+  // GitHub fine-grained / server prefixes.
+  /\bghp_[A-Za-z0-9]{30,}\b/,
+  /\bghs_[A-Za-z0-9]{30,}\b/,
+
+  // Slack workspace prefixes.
+  /\bxox[abprs]-[0-9A-Za-z\-]{10,}/,
+
+  // Stripe vendor prefixes (live + test, restricted + standard).
+  /\bsk_(?:live|test)_[A-Za-z0-9]{20,}/,
+  /\brk_(?:live|test)_[A-Za-z0-9]{20,}/,
+
+  // Twilio account-SID + auth-SID shape.
+  /\bAC[0-9a-f]{32}\b/,
+  /\bSK[0-9a-f]{32}\b/,
+
+  // SendGrid full-key prefix.
+  /\bSG\.[A-Za-z0-9_\-]{22}\.[A-Za-z0-9_\-]{43}/,
+
+  // Google API-key shape (39 chars, AIza prefix).
+  /\bAIza[0-9A-Za-z_\-]{35}\b/,
+
+  // JWT bearer shape (header.payload, base64url segments).
+  /\bBearer\s+eyJ[A-Za-z0-9_\-]{15,}\.[A-Za-z0-9_\-]{15,}/,
+
+  // ENV-style assignment with high-entropy value (≥32 chars base64-ish).
+  /^[A-Z_][A-Z0-9_]{3,}\s*=\s*[A-Za-z0-9+/=_\-]{32,}\s*$/m,
+]);
+
+/**
+ * Returns true when the source body contains at least one structural shape
+ * matching a sealed-material artifact. Bare lexical mentions of vocabulary
+ * in comments or variable names do NOT match — only structural shapes do.
+ */
+export function hasSensitiveMaterialShape(source) {
+  if (typeof source !== 'string' || source.length === 0) return false;
+  for (const rx of SHAPE_PATTERNS) {
+    if (rx.test(source)) return true;
+  }
+  return false;
+}
+
+export const __SHAPE_PATTERNS_FOR_TEST = SHAPE_PATTERNS;

package/dist/assets/hooks/lib/skill-autoload-gate-impl.mjs

@@ -83,11 +83,198 @@ export function classifyRequiredSkills({ text = '', action = '', toolName = '',
     required.add('aria-forge-guardrails');
     reasons.push('advisory/fail-open gate language requires fail-closed hardening discipline');
   }
+
+  // ── Business-intent branch (Aria 2026-05-09 expansion) ───────────────────
+  // All business-shaped intents fire in advisory/teach mode (redirectOnly:true).
+  // Per owner doctrine 2026-05-09: deadlocks are anti-pattern; recovery + teaching is the lever.
+  // Skills referenced are net-new and ship to ~/.codex/skills/ via cognitive-skills.ts.
+  if (/\b(?:price|pricing|package|tier|discount|paywall|monetize|monetization|arpu|gross margin|deal|contract redline|term sheet|refund|expansion|upsell|cross-sell|cac|ltv|payback|nrr|mrr|arr)\b/i.test(c)) {
+    required.add('aria-revenue-engine');
+    required.add('aria-business-frame');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('revenue/pricing intent — load business-frame + revenue-engine in advisory mode');
+  }
+  if (/\b(?:gtm|go-to-market|launch|channel|distribution|positioning|message|campaign|icp|persona|audience|brand|copy|hook|headline|landing page|seo|paid|organic|referral|virality|plg|sales-led)\b/i.test(c)) {
+    required.add('aria-gtm-architect');
+    required.add('aria-business-frame');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('gtm/positioning intent — load business-frame + gtm-architect in advisory mode');
+  }
+  if (/\b(?:churn|retention|renewal|nps|csat|onboarding|activation|escalation|win-back|account health|customer success)\b/i.test(c)) {
+    required.add('aria-retention-engine');
+    required.add('aria-business-frame');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('retention/cs intent — load business-frame + retention-engine in advisory mode');
+  }
+  if (/\b(?:hire|fire|layoff|rif|comp|equity|promotion|reorg|fundraise|fundraising|valuation|board|press|public statement|category|rebrand|m&a|partnership|joint venture)\b/i.test(c)) {
+    required.add('aria-decision-mizan');
+    required.add('aria-business-frame');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('owner-must-decide intent — load decision-mizan in advisory mode');
+  }
+  if (/\b(?:business audit|health check|kpi review|growth diagnostic|financial diagnostic|whats?\s+broken|what should we fix)\b/i.test(c)) {
+    required.add('aria-business-audit');
+    required.add('aria-business-frame');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('business-audit intent — load business-audit in advisory mode');
+  }
+
+  // ── Build-intent branch (FE / BE / fullstack) ─────────────────────────────
+  if (/\b(?:react|vue|svelte|next\.?js|tailwind|shadcn|component|hook|landing page|design system|core web vitals|lcp|inp|cls|wcag|accessibility|ssr|rsc|ssg|isr|hydration|frontend|front-end|web ui|mobile web|responsive|dark mode|i18n|pwa)\b/i.test(c)) {
+    required.add('aria-frontend-architect');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('frontend intent — load frontend-architect in advisory mode');
+  }
+  if (/\b(?:api|endpoint|handler|microservice|monolith|schema|migration|orm|query|index|queue|worker|webhook|cron|idempotency|circuit breaker|rate limit|cache|jwt|oauth|rbac|multi-tenancy|slo|sli|error budget|grpc|graphql|websocket|backend|back-end|database|postgres|mysql|redis)\b/i.test(c)) {
+    required.add('aria-backend-architect');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('backend intent — load backend-architect in advisory mode');
+  }
+  if (/\b(?:end-to-end|e2e feature|user story|epic|prd|full-stack|fullstack|spans? both|ship.*feature|build.*feature)\b/i.test(c)) {
+    required.add('aria-fullstack-orchestrator');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('fullstack intent — load fullstack-orchestrator in advisory mode');
+  }
+
+  // ── Code-cognition pre/post branches (cookbook + audit) ──────────────────
+  if (/\b(?:write|implement|build|scaffold|refactor|extract|split).{0,40}(?:handler|endpoint|function|class|hook|component|module|service|test|migration|schema)\b/i.test(c)) {
+    required.add('aria-senior-code-cookbook');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('pre-code intent — load senior-code-cookbook for cookbook patterns in advisory mode');
+  }
+  if (/\bgit\s+commit\b|\bgit\s+add\b|\bgit\s+push\b|\bcommit\b.{0,80}\b(?:diff|change|patch|edit)\b/i.test(c)) {
+    required.add('aria-senior-code-audit');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('pre-commit intent — load senior-code-audit; recovery-grant pattern, never blocks');
+  }
+
+  // ── Audit & research intents ─────────────────────────────────────────────
+  if (/\b(?:repo audit|code health audit|debt audit|dependency audit|security audit|performance audit|architecture audit|drift audit|whats?.{0,5}broken in this repo)\b/i.test(c)) {
+    required.add('aria-repo-audit');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('repo-audit intent — load repo-audit in advisory mode');
+  }
+  if (/\b(?:research|look up|find current|what.s? the (?:latest|current)|competitive research|market sizing|benchmark|comp(?:etitor)? analysis|vendor evaluation)\b/i.test(c)) {
+    required.add('aria-research-orchestrator');
+    required.add('aria-readable-output');
+    redirectOnly = true;
+    reasons.push('research intent — load research-orchestrator in advisory mode');
+  }
+
+  // ── Prose-shape trigger expansion (2026-05-12 substrate-provisioning upgrade) ──
+  // Foundation layer per the three-layer architecture (substrate provisioning →
+  // substrate binding → enforcement). The tool-class triggers above cover
+  // explicit-action prompts (deploy/edit/etc.); these five classes cover
+  // prose-shape prompts where the doctrine routing must happen by intent
+  // recognition not keyword matching.
+  //
+  // Diagnosed across the 2026-05-12 session: every audit-retraction cycle
+  // traced back to autoload not firing the right substrate (aria-repo-audit
+  // + aria-quality-audit + never-guess) because the prompts didn't match
+  // the narrow tool-class triggers. The five classes below cover the
+  // doctrine-needs the prior session demonstrated.
+  //
+  // Audit-class — owner asks for a review, diagnostic, or "what's broken"
+  if (/\baudit\b|\breview\s+(?:the\s+)?(?:code|repo|deploy|architecture|design|prs?|pr\b)|\bwhat(?:'s| is)? broken\b|\bcode review\b|\bhealth check\b|\bdiagnostic\b|\bdrift audit\b|\bdebt audit\b|\bsecurity review\b|\bquality audit\b/i.test(c)) {
+    required.add('aria-repo-audit');
+    required.add('aria-quality-audit');
+    required.add('never-guess');
+    reasons.push('audit/review/diagnostic prompt requires audit substrate before drafting (repo-audit + quality-audit + never-guess for content reads not name-matching)');
+  }
+  // Research-class — owner asks for external evidence acquisition
+  if (/\bresearch\b|\blook(?:\s+up)?\b|\bfind out\b|\binvestigate\b|\bcompetitive analysis\b|\bmarket sizing\b|\bvendor evaluation\b|\bbenchmark\b|\bsource verification\b|\bdig into\b/i.test(c)) {
+    required.add('aria-research-orchestrator');
+    required.add('never-guess');
+    reasons.push('research/evidence-acquisition prompt requires research-orchestrator + never-guess to anchor every claim to a source');
+  }
+  // Decision-class — owner-must-decide turn type per aria-decision-mizan doctrine
+  if (/\bshould (?:we|i)\b|\bhire\b|\bfire\b|\blayoff\b|\brif\b|\bpric(?:e|ing|er)\b|\bdiscount\b|\bfundrais(?:e|ing)\b|\bvaluation\b|\bterm sheet\b|\bequity grant\b|\brefund\b|\brebrand\b|\bm&a\b|\bjoint venture\b|\bcontract redline\b|\bpublic statement\b/i.test(c)) {
+    required.add('aria-decision-mizan');
+    required.add('aria-business-frame');
+    reasons.push('owner-must-decide intent requires decision-mizan (refuse-to-choose-for-owner) + business-frame');
+  }
+  // Prose-drift class — language patterns that signal the agent slipping
+  // into recommendation/dismissal mode without doctrine; drift scanner in
+  // aria-harness-output-discipline catches these but must be loaded first.
+  if (/\bi'?ll\s+(?:recommend|create|file|author|track|draft|propose|suggest)\b|\bwant me to\b|\bshould i\b|\bi\s+(?:recommend|propose|suggest)\b|\bunrelated to (?:my|the|the)\s|\bpre[- ]?existing\b|\bout of scope\b|\bnot blocking\b|\bside (?:concern|issue)\b|\bnot my (?:problem|issue|concern)\b/i.test(c)) {
+    required.add('aria-harness-output-discipline');
+    required.add('aria-conversational-doctrine-discipline');
+    reasons.push('prose-drift phrasing (recommendation/dismissal/asking) requires output-discipline + conversational-doctrine to police the slip');
+  }
+  // Repair-class — fix/debug/diagnose intent; loads doctrine that prevents
+  // band-aid fixes and forces root-cause reads instead of guessing.
+  if (/\bfix the\b|\brepair the\b|\brestore the\b|\bdebug\b|\bdiagnose\b|\broot cause\b|\bwhy (?:is|isn'?t|did|doesn'?t) (?:it|this|that)\b|\btroubleshoot\b/i.test(c)) {
+    required.add('never-guess');
+    required.add('aria-forge-guardrails');
+    reasons.push('repair/debug intent requires never-guess (read state first) + forge-guardrails (no fake fixes)');
+  }
   return { requiredSkills: [...required].sort(), recoveryMissing: [...new Set(recoveryMissing)], reasons, redirectOnly };
 }
 
 export function evaluateSkillGate(options = {}) {
-  const c = classifyRequiredSkills(options);
+  const hasRequiredSkillsOverride = Array.isArray(options.requiredSkillsOverride);
+  const c = hasRequiredSkillsOverride
+    ? {
+        requiredSkills: [...new Set(options.requiredSkillsOverride.filter((skill) => typeof skill === 'string' && skill.trim()).map((skill) => skill.trim()))].sort(),
+        recoveryMissing: [],
+        reasons: [options.requiredSkillsReason || 'orchestration manifest intent.workflow_skills_to_invoke supplied required skills'],
+        redirectOnly: false,
+      }
+    : classifyRequiredSkills(options);
+  // additionalRequiredSkills augments (does not replace) the classifier/override
+  // output. Used by the pre-tool gate to layer Atlas dossier governing_skills
+  // on top of the keyword classifier — explicit per-file bindings AND
+  // intent-shape inference, not one or the other.
+  //
+  // Payload cap (Qiyas Q15 finding, 2026-05-17): once Phase 2D concept-keyword
+  // matching lands, a single file may collect 100+ governing skills via
+  // semantic overlap. The autoload manifest is hot-path content injected on
+  // every prompt — an uncapped merge would balloon it. Cap to top-N and
+  // surface the truncation LOUDly so it never silently drops important
+  // skills (per feedback_no_silent_fail_open_in_hooks.md). The cap is high
+  // enough that today's sparse GOVERNS (≤5 skills/file) is unaffected;
+  // future concept-match growth surfaces the cap with a LOUD stderr line
+  // instead of silently truncating.
+  const ADDITIONAL_SKILLS_CAP = Number.isFinite(options.additionalRequiredSkillsCap)
+    ? Math.max(1, Math.min(100, options.additionalRequiredSkillsCap))
+    : 20;
+  if (Array.isArray(options.additionalRequiredSkills) && options.additionalRequiredSkills.length > 0) {
+    const cleaned = options.additionalRequiredSkills
+      .filter((skill) => typeof skill === 'string' && skill.trim())
+      .map((skill) => skill.trim());
+    const dedupedInOrder = [...new Set(cleaned)];
+    const overCap = dedupedInOrder.length > ADDITIONAL_SKILLS_CAP;
+    const extras = overCap ? dedupedInOrder.slice(0, ADDITIONAL_SKILLS_CAP) : dedupedInOrder;
+    if (overCap) {
+      // LOUD per feedback_no_silent_fail_open_in_hooks.md — truncation must
+      // be visible to next-turn substrate scanners so the cap can be tuned
+      // if it ever drops a load-bearing skill.
+      try {
+        process.stderr.write(
+          `[skill-autoload-gate:additional_skills_capped] cap=${ADDITIONAL_SKILLS_CAP} ` +
+          `received=${dedupedInOrder.length} dropped=${dedupedInOrder.length - extras.length} ` +
+          `dropped_names=${dedupedInOrder.slice(ADDITIONAL_SKILLS_CAP).join(',')}\n`,
+        );
+      } catch { /* stderr unavailable; cap still applied */ }
+    }
+    if (extras.length > 0) {
+      const merged = new Set([...c.requiredSkills, ...extras]);
+      c.requiredSkills = [...merged].sort();
+      const capNote = overCap ? ` (capped from ${dedupedInOrder.length})` : '';
+      c.reasons = [...(c.reasons || []), `atlas dossier supplied ${extras.length} governing skill(s)${capNote} for target file: ${extras.join(', ')}`];
+    }
+  }
   const body = [options.text, options.action].filter(Boolean).join('\n');
   const loaded = collectLoadedSkills(options, body);
   const contractEvidence = collectContractEvidence(options, body);
@@ -97,6 +284,44 @@ export function evaluateSkillGate(options = {}) {
   return { ok: c.redirectOnly === true || (missingSkills.length === 0 && recoveryMissing.length === 0), redirectOnly: c.redirectOnly === true, surface: options.surface || 'unknown', sessionId: options.sessionId || 'unknown', requiredSkills: c.requiredSkills, loadedSkills: [...loaded].sort(), contractEvidence: [...contractEvidence].sort(), missingSkills, recoveryMissing, reasons: c.reasons, autoLoadAvailable: options.autoLoadAvailable === true };
 }
 
+// AI-11803-LOOP1 (2026-05-12): cascade autoload primitive.
+// Parses a skill body for sections that declare downstream skill dependencies
+// (Load First / Mode Selection / Load Order / Ta'aqqul Autofire Pattern), and
+// returns the candidate skill names extracted from backtick-quoted tokens.
+// The autoload hook is responsible for filtering against actual skill-dir
+// existence — this function does not touch the filesystem.
+const CASCADE_HEADINGS = [
+  'load first',
+  'mode selection',
+  'load order',
+  "ta'aqqul autofire pattern",
+];
+
+export function parseLoadFirstSection(skillBody) {
+  if (typeof skillBody !== 'string' || !skillBody) return [];
+  const skills = new Set();
+  const headingPattern = CASCADE_HEADINGS
+    .map((h) => h.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|');
+  const sectionRx = new RegExp(
+    `^##\\s+(?:${headingPattern})\\b[^\\n]*\\n([\\s\\S]*?)(?=\\n##\\s)`,
+    'gim',
+  );
+  const tokenRx = /`([a-z][a-z0-9_-]*)`/g;
+  for (const m of skillBody.matchAll(sectionRx)) {
+    const section = m[1] || '';
+    for (const t of section.matchAll(tokenRx)) {
+      const name = t[1];
+      if (!name) continue;
+      // Lib stays a pure candidate extractor. Mode-label noise (`light`, `qa`,
+      // `batch`, `fleet`, `hard-stop`) flows through here; the autoload's
+      // existsSync(SKILLS_DIR/<name>/SKILL.md) is the canonical filter.
+      skills.add(name);
+    }
+  }
+  return [...skills];
+}
+
 export function formatSkillGateBlock(result = {}) {
   const m = result.missingSkills || [], r = result.recoveryMissing || [], reasons = result.reasons || [];
   return ['=== ARIA SKILL AUTOLOAD GATE BLOCK ===', `surface: ${result.surface || 'unknown'}`, `missing_skills: ${m.length ? m.join(', ') : '(none)'}`, `missing_recovery_cycle: ${r.length ? r.join(', ') : '(none)'}`, `required_skills: ${(result.requiredSkills || []).join(', ') || '(none)'}`, reasons.length ? `reasons: ${reasons.join(' | ')}` : 'reasons: no classifier reason recorded', 'Recovery contract:', '1. Do not retry the same blocked text.', `2. Load missing skills first: ${m.length ? m.join(', ') : '(none)'}`, `3. Repair missing recovery cycle items: ${r.length ? r.join(', ') : '(none)'}`, '4. Re-write with concrete proof and an applied_cognition block:', '<applied_cognition>', 'decision_delta: <what changed after the block>', 'dominant_domain: <deploy|code|security|testing|ops|product|writing>', 'binds_to: <specific file, command, endpoint, or user instruction>', 'expected_predicate: <measurable condition such as exit=0, status=healthy, count=N>', 'artifact_change: <exact artifact changed or none>', '</applied_cognition>', '5. Re-test using the concrete command/probe named in the block.', '6. Re-submit only after the proof exists; if blocked twice, escalate through ARIA console/MCP with this full block.'].join('\n');