@aria_asi/cli 0.2.39 → 0.2.41

package/dist/assets/hooks/lib/atlas-orchestrator-postwire.mjs

@@ -0,0 +1,221 @@
+// atlas-orchestrator-postwire — post-turn enrichment writeback for the
+// atlas-as-orchestrator pre/intra/post wire.
+//
+// Called from aria-stop-gate.mjs (and any other Stop-class surface) BEFORE
+// the emergency-gateoff check so adherence/QA data is persisted on every
+// non-empty turn regardless of gates-on/off state. The hive WAL append is
+// substrate enrichment, not gate enforcement — gates-off should not silence
+// the learning loop.
+//
+// Operates on:
+//   1. event.transcript_path → walk for Skill tool_use invocations.
+//   2. ~/.claude/.aria-current-turn-context.json → sidecar carries the
+//      atlas selections persisted by the pre-emit autoload.
+//   3. runEndOfPhaseQaAutofire → full Qiyas-15 + Tadabbur-12 court receipt
+//      anchored to the adherence observation.
+//
+// Schemas emitted (next turn's pre-emit reads these as substrate):
+//   aria.atlas_orchestrator_turn_outcome.v1
+//   aria.end_of_phase_qa_court.v1 (when court ran)
+//   aria.atlas_orchestrator_hardening_directive.v1 (conditional on gap or
+//     non-verified court verdict; pre-emit autoload consumes this to
+//     force-add the missed skills to invocationRequired)
+//
+// LOUD-stderr on every error path per
+// feedback_no_silent_fail_open_in_hooks.md. Returns a summary object the
+// caller can include in its own telemetry; the WAL is the durable receipt.
+
+import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { runEndOfPhaseQaAutofire } from './end-phase-qa-autofire.mjs';
+
+const HOME = homedir();
+const HIVE_WAL_PATH = `${HOME}/.aria/runtime/state/hive-ledger-wal.jsonl`;
+const SIDECAR_TURN_CONTEXT_PATH = `${HOME}/.claude/.aria-current-turn-context.json`;
+const LOG = '[atlas-orchestrator-postwire]';
+
+function loudErr(reason, detail) {
+  try {
+    process.stderr.write(`${LOG}:${reason} ${detail}\n`);
+  } catch { /* stderr may be closed */ }
+}
+
+export function runAtlasOrchestratorPostWire({ event }) {
+  const summary = {
+    selected: 0,
+    honored: 0,
+    gap: 0,
+    adherenceRatio: 1,
+    invoked: 0,
+    qaVerdict: null,
+    walAppended: false,
+    hardeningEmitted: false,
+  };
+  try {
+    const transcriptPath = event?.transcript_path ?? event?.transcriptPath ?? null;
+    const sessionId = String(event?.session_id || 'unknown');
+
+    // 1. Walk transcript for invoked Skill names.
+    const invokedSkillsSet = new Set();
+    if (transcriptPath && existsSync(transcriptPath)) {
+      try {
+        const lines = readFileSync(transcriptPath, 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const m = JSON.parse(line);
+            const role = m.message?.role ?? m.role;
+            if (role !== 'assistant') continue;
+            const content = m.message?.content ?? m.content ?? [];
+            if (!Array.isArray(content)) continue;
+            for (const block of content) {
+              if (block && block.type === 'tool_use' && block.name === 'Skill') {
+                const skillName = block.input?.skill || block.input?.name || null;
+                if (typeof skillName === 'string' && skillName.trim()) {
+                  invokedSkillsSet.add(skillName.trim());
+                }
+              }
+            }
+          } catch { /* line-parse fail acceptable on partial jsonl */ }
+        }
+      } catch (transcriptErr) {
+        loudErr('transcript_read', transcriptErr instanceof Error ? transcriptErr.message : String(transcriptErr));
+      }
+    }
+    const invokedSkills = [...invokedSkillsSet];
+
+    // 2. Read sidecar atlas selections persisted by pre-emit.
+    let sidecarOrchestrator = null;
+    let sidecarSelection = null;
+    let sidecarInvocationRequired = [];
+    if (existsSync(SIDECAR_TURN_CONTEXT_PATH)) {
+      try {
+        const sidecarRaw = readFileSync(SIDECAR_TURN_CONTEXT_PATH, 'utf8');
+        const sidecarParsed = JSON.parse(sidecarRaw);
+        sidecarOrchestrator = sidecarParsed?.atlasOrchestrator || null;
+        sidecarSelection = sidecarParsed?.atlasSelection || null;
+        sidecarInvocationRequired = Array.isArray(sidecarParsed?.invocationRequired)
+          ? sidecarParsed.invocationRequired
+          : [];
+      } catch (sidecarErr) {
+        loudErr('sidecar_parse', sidecarErr instanceof Error ? sidecarErr.message : String(sidecarErr));
+      }
+    }
+    const selectedByDossier = Array.isArray(sidecarOrchestrator?.governingSkills)
+      ? sidecarOrchestrator.governingSkills.filter((s) => typeof s === 'string')
+      : [];
+    const selectedByKernel = Array.isArray(sidecarSelection?.selectedSkillIds)
+      ? sidecarSelection.selectedSkillIds.filter((s) => typeof s === 'string')
+      : [];
+    const selectedSet = new Set([...selectedByDossier, ...selectedByKernel]);
+    const selected = [...selectedSet];
+    const gap = selected.filter((s) => !invokedSkillsSet.has(s));
+    const honored = selected.filter((s) => invokedSkillsSet.has(s));
+    const adherenceRatio = selected.length > 0 ? Number((honored.length / selected.length).toFixed(3)) : 1;
+
+    summary.selected = selected.length;
+    summary.honored = honored.length;
+    summary.gap = gap.length;
+    summary.adherenceRatio = adherenceRatio;
+    summary.invoked = invokedSkills.length;
+
+    // 3. Run end-of-phase QA court on the adherence observation. The court
+    // generates full Qiyas-15 + Tadabbur-12 evidence anchored to a kernel
+    // verdict. Gate-off does NOT skip the court — substrate enrichment runs.
+    // runEndOfPhaseQaAutofire returns {ok, receipt, latestPath, eventPath};
+    // the actual court receipt is nested under .receipt.
+    const adherenceSummary = `Atlas orchestrator adherence: ${honored.length}/${selected.length} skills honored, ${gap.length} gap. Invoked: [${invokedSkills.join(', ')}]. Selected-by-atlas: [${selected.join(', ')}].`;
+    let qaResult = null;
+    let qaCourtReceipt = null;
+    try {
+      qaResult = runEndOfPhaseQaAutofire({
+        sessionId,
+        phase: 'atlas_orchestrator_adherence',
+        trigger: 'stop_gate_atlas_postwire',
+        text: adherenceSummary,
+        source: 'aria-stop-gate-atlas-postwire',
+        autoRecoverPartial: false,
+      });
+      qaCourtReceipt = qaResult?.receipt || null;
+    } catch (qaErr) {
+      loudErr('qa_court_error', qaErr instanceof Error ? qaErr.message : String(qaErr));
+    }
+    // claim-gate verdict lives at receipt.claim_gate.verdict (top-level on
+    // the receipt — autofire is a sibling key, not the parent).
+    const qaVerdict = qaCourtReceipt?.claim_gate?.verdict
+      || qaCourtReceipt?.autofire?.claim_gate?.verdict
+      || qaCourtReceipt?.verdict
+      || null;
+    const qaHardBlock = qaCourtReceipt?.hardBlock === true;
+    summary.qaVerdict = qaVerdict;
+
+    // 4. Build outcome event + append to hive WAL.
+    const at = new Date().toISOString();
+    const walEvent = {
+      schema: 'aria.atlas_orchestrator_turn_outcome.v1',
+      at,
+      session_id: sessionId,
+      surface: 'claude-code',
+      selectedByAtlas: {
+        dossier: selectedByDossier,
+        kernelClass: selectedByKernel,
+        total: selected.length,
+      },
+      invokedSkills,
+      honored,
+      gap,
+      adherenceRatio,
+      invocationRequiredCount: sidecarInvocationRequired.length,
+      kernelObservationKind: sidecarSelection?.observationKind || null,
+      kernelCompilationHash: sidecarSelection?.compilation_hash || null,
+      dossierTargetsHarvested: sidecarOrchestrator?.targetsHarvested ?? 0,
+      dossierTargetsResolved: sidecarOrchestrator?.targetsResolved ?? 0,
+      qaCourt: qaCourtReceipt
+        ? {
+            verdict: qaVerdict,
+            hardBlock: qaHardBlock,
+            qiyasPerspectives: Array.isArray(qaCourtReceipt?.qiyas_15_pass) ? qaCourtReceipt.qiyas_15_pass.length : 15,
+            tadabburStages: Array.isArray(qaCourtReceipt?.tadabbur_12_pass) ? qaCourtReceipt.tadabbur_12_pass.length : 12,
+            receiptHash: qaCourtReceipt?.receipt_hash || null,
+          }
+        : { error: 'qa-court-did-not-run' },
+    };
+
+    try {
+      mkdirSync(dirname(HIVE_WAL_PATH), { recursive: true });
+      appendFileSync(HIVE_WAL_PATH, JSON.stringify(walEvent) + '\n', 'utf8');
+      if (qaCourtReceipt) {
+        appendFileSync(HIVE_WAL_PATH, JSON.stringify(qaCourtReceipt) + '\n', 'utf8');
+      }
+      summary.walAppended = true;
+
+      // 5. First-class hardening loop: gap or non-verified QA verdict
+      // triggers a directive the next pre-emit autoload reads and
+      // force-adds to invocationRequired.
+      if (gap.length > 0 || (qaVerdict && qaVerdict !== 'verified' && qaVerdict !== 'verified_narrowly')) {
+        const hardeningEvent = {
+          schema: 'aria.atlas_orchestrator_hardening_directive.v1',
+          at,
+          session_id: sessionId,
+          surface: 'claude-code',
+          reason: gap.length > 0
+            ? `adherence_gap: ${gap.length}/${selected.length} skills selected-by-atlas not invoked`
+            : `qa_verdict_below_threshold: ${qaVerdict}`,
+          forceInvokeNextTurn: gap,
+          qaVerdict,
+          adherenceRatio,
+          sourceTurnOutcomeAt: at,
+        };
+        appendFileSync(HIVE_WAL_PATH, JSON.stringify(hardeningEvent) + '\n', 'utf8');
+        summary.hardeningEmitted = true;
+        process.stderr.write(`${LOG}:hardening reason="${hardeningEvent.reason}" forceInvokeNextTurn=[${gap.join(',')}] qaVerdict=${qaVerdict}\n`);
+      }
+      process.stderr.write(`${LOG}:emit selected=${selected.length} honored=${honored.length} gap=${gap.length} adherence=${adherenceRatio} invoked=${invokedSkills.length} qaVerdict=${qaVerdict || 'none'} session=${sessionId}\n`);
+    } catch (walErr) {
+      loudErr('wal_write', `${walErr instanceof Error ? walErr.message : String(walErr)} path=${HIVE_WAL_PATH}`);
+    }
+  } catch (outer) {
+    loudErr('outer_error', outer instanceof Error ? outer.message : String(outer));
+  }
+  return summary;
+}

package/dist/assets/hooks/lib/canonical-lenses.mjs

@@ -38,28 +38,105 @@ export function extractLensTexts(cognitionInner, lensNames = ALL_LENS_NAMES) {
   return out;
 }
 
+// M9.DRIFT.10u — credential-shape redaction for diagnostic content_preview
+// fields. Local copy so this lib has no dependency on coach-kernel
+// (avoids circular imports across hook libs).
+function redactPotentialSecretsInPreview(text) {
+  return String(text || '')
+    .replace(/Bearer\s+[A-Za-z0-9._~+\/-]{12,}/gi, 'Bearer [redacted]')
+    .replace(/\bsk-[A-Za-z0-9_-]{12,}\b/g, '[redacted-secret]')
+    .replace(/\bgh[pousr]_[A-Za-z0-9_]{12,}\b/g, '[redacted-secret]')
+    .replace(/\bxox[baprs]-[A-Za-z0-9-]{12,}\b/g, '[redacted-secret]')
+    .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[redacted-secret]');
+}
+
+// M9.DRIFT.10u — find "<word>:" patterns inside the cognition block
+// that look like lens declarations but are NOT in any canonical set.
+// Surfaces operator-emitted non-canonical lens names for self-correction
+// (the agent emitting sirat/adl/rahma/sabr finds out exactly which
+// names fell outside the canonical sets, instead of getting 0/8 with
+// no breakdown).
+function findUnrecognizedTokens(searchSpace, knownLensNames) {
+  const knownLower = new Set(knownLensNames.map((n) => n.toLowerCase()));
+  const out = new Set();
+  const rx = /(?:^|\n)\s*([A-Za-z][A-Za-z_-]{1,40})\s*:/g;
+  let m;
+  while ((m = rx.exec(searchSpace)) !== null) {
+    const token = m[1].toLowerCase();
+    if (!knownLower.has(token)) out.add(token);
+  }
+  return [...out];
+}
+
+/**
+ * Detect cognition lenses in the given text.
+ *
+ * BACKWARDS-COMPATIBLE: existing top-level fields {count, names,
+ * matchedSet} preserved at root for callers destructuring those.
+ *
+ * M9.DRIFT.10u additive fields:
+ *   blockFound: boolean — whether a <cognition>...</cognition> block was found
+ *   perLens: [{lens, present, charCount, content_preview}] — one entry per
+ *     iterated canonical lens; content_preview is 50-char redacted slice
+ *   unrecognizedTokens: string[] — "<word>:" patterns inside the cognition
+ *     block that look like lens declarations but are NOT in any canonical set
+ *   canonicalSets: { older: string[], newer: string[] } — the canonical
+ *     sets the parser attempted, surfaced for operator visibility
+ */
 export function detectCognitionLenses(text, {
   minChars = 0,
   placeholderRx = null,
   cognitionBlockRx = /<cognition>([\s\S]*?)<\/cognition>/i,
   lensNames = ALL_LENS_NAMES,
 } = {}) {
-  if (!text) return { count: 0, names: [], matchedSet: null };
+  if (!text) {
+    return {
+      count: 0,
+      names: [],
+      matchedSet: null,
+      blockFound: false,
+      perLens: [],
+      unrecognizedTokens: [],
+      canonicalSets: { older: [...LENS_NAMES_OLDER], newer: [...LENS_NAMES_NEWER] },
+    };
+  }
   const block = text.match(cognitionBlockRx);
+  const blockFound = Boolean(block);
   const searchSpace = block ? block[1] : text;
   const lensTexts = extractLensTexts(searchSpace, lensNames);
   const names = [];
+  const perLens = [];
   for (const lens of lensNames) {
     const content = (lensTexts[lens] || '').trim();
-    if (!content) continue;
-    if (minChars > 0 && content.length < minChars) continue;
-    if (placeholderRx && placeholderRx.test(content)) continue;
-    names.push(lens);
+    const passesMin = !content || (minChars > 0 ? content.length >= minChars : true);
+    const passesPlaceholder = !content || !placeholderRx || !placeholderRx.test(content);
+    const present = Boolean(content) && passesMin && passesPlaceholder;
+    if (present) names.push(lens);
+    perLens.push({
+      lens,
+      present,
+      charCount: content.length,
+      content_preview: content
+        ? redactPotentialSecretsInPreview(content).slice(0, 50)
+        : '',
+    });
   }
 
   const matchedSet =
     [LENS_NAMES_OLDER, LENS_NAMES_NEWER]
       .find((candidateSet) => candidateSet.every((name) => names.includes(name))) || null;
 
-  return { count: names.length, names, matchedSet };
+  const unrecognizedTokens = blockFound
+    ? findUnrecognizedTokens(searchSpace, lensNames)
+    : [];
+
+  return {
+    count: names.length,
+    names,
+    matchedSet,
+    blockFound,
+    perLens,
+    unrecognizedTokens,
+    canonicalSets: { older: [...LENS_NAMES_OLDER], newer: [...LENS_NAMES_NEWER] },
+  };
 }

package/dist/assets/hooks/lib/coach-intent-classifier.mjs

@@ -0,0 +1,248 @@
+// coach-intent-classifier.mjs
+//
+// Hybrid intent classifier for the runtime coach's
+// `unverified_deploy_or_infra_mutation` block reason.
+//
+// Per Hamza directive 2026-05-09: deterministic-first-pass with LLM
+// fallback for ambiguous cases — not deterministic alone. The remote
+// runtime coach pattern-matches prose vocabulary regardless of whether
+// the prose actually CLAIMS that a mutation occurred. This wrapper
+// adds intent discrimination so legitimate proposals/reports/descriptions
+// don't trigger the block.
+//
+// Intent taxonomy:
+//   CLAIM    — asserts that a mutation HAS occurred ("I deployed X", "X was rolled out")
+//   PROPOSE  — recommends a future action ("we should deploy", "the next step would be")
+//   REPORT   — describes work without claiming done ("source corrections recorded", "fix prepared")
+//   DESCRIBE — meta-discussion of mutation as a topic ("the deploy step", "rollout patterns")
+//
+// Only CLAIM intent without backing evidence triggers a real block.
+// PROPOSE/REPORT/DESCRIBE are valid prose that the dumb regex
+// false-positives. The hybrid downgrades those to warn-only.
+
+import { readFileSync } from 'node:fs';
+
+const FLASH_MODEL_DEFAULTS = {
+  endpoint: process.env.ARIA_FLASH_ENDPOINT || 'http://localhost:30080/api/aria/speak',
+  model: process.env.ARIA_FLASH_MODEL || 'deepseek-v4-flash',
+  timeoutMs: Math.max(2000, Math.min(15000, Number(process.env.ARIA_FLASH_TIMEOUT_MS || '8000'))),
+};
+
+// Vocabulary the upstream coach pattern-matches as deploy/infra mutation.
+// Used by deterministic pass to identify which prose substrings would
+// have triggered the upstream regex.
+const MUTATION_VOCAB_RX = /\b(?:deploy|deployed|deploys|rollout|rolling|rolled|rebuild|rebuilt|build|built|kubectl|docker|push|pushed|image|imaged|pod|pods|set image|apply|applied|mutate|mutation|infrastructure|infra|provision|provisioned|migrate|migrated|patch|patched|restart|restarted)\b/i;
+
+// Past-tense completion verbs that, paired with mutation vocab, signal CLAIM intent.
+const COMPLETION_PAST_TENSE_RX = /\b(?:was|were|has been|have been|got|is now|are now|just|already|successfully)\s+(?:deployed|rolled out|rebuilt|pushed|set|applied|restarted|patched|live|active|running)\b/i;
+
+// First-person past-tense action claims.
+const FIRST_PERSON_CLAIM_RX = /\bI\s+(?:deployed|rolled out|rebuilt|pushed|set the image|applied|restarted|patched|published|shipped|landed)\b/i;
+
+// Modal/proposal markers — future or conditional, not claim.
+const PROPOSE_MARKER_RX = /\b(?:will|would|could|might|may|recommend|recommended|suggest|suggested|propose|proposed|next step|next steps|going to|plan to|intend|consider|let'?s|let us|should|need to)\b/i;
+
+// Authorization-pending markers — explicitly waiting on external action.
+const PENDING_AUTH_RX = /\b(?:awaiting|pending|held|holding|queued|staged|prepared|ready to|authoriz|authorisation|owner authoriz|owner word|your nod|your direction|after your|once you|with your)\b/i;
+
+// Past-tense reporting markers — describing work done WITHOUT mutation claim.
+const REPORT_MARKER_RX = /\b(?:source corrections recorded|source edits applied|source fix(?:es)? (?:landed|in source|in place|recorded)|fix prepared|edited the source|edited the file|wrote (?:the|to) source|wrote the file|recorded in (?:source|the ledger)|justification (?:written|prepared|accepted)|sweep (?:returned|confirms|cleaned))\b/i;
+
+// Evidence anchors — when a claim has these nearby, it's a verified claim, not unverified.
+const EVIDENCE_ANCHOR_RX = /\b(?:exit\s*code|HTTP\s+\d{3}|status\s*=\s*\d|sha256:[a-f0-9]+|line\s+\d+|log shows|log shows that|returned|returns|received\s+\d|response\s+(?:body|payload|code)|verified by|probe (?:returned|showed)|grep (?:found|returned)|test (?:passed|failed))\b/i;
+
+// Meta-discussion markers — topic-level discussion, not action.
+const META_DISCUSSION_RX = /\b(?:the (?:deploy|rollout|build|rebuild) (?:step|action|phase|process|pattern|mechanism|approach)|deploy[- ]?(?:class|gating|authorization|justification|pattern)|how (?:we|to) deploy|what (?:happens|happened) (?:on|during) (?:deploy|rollout))\b/i;
+
+/**
+ * Deterministic intent classification.
+ *
+ * Returns:
+ *   { intent: 'CLAIM' | 'PROPOSE' | 'REPORT' | 'DESCRIBE' | 'AMBIGUOUS',
+ *     confidence: 0.0-1.0,
+ *     features: [list of matched feature names],
+ *     evidenceAnchored: bool,
+ *     mutationVocabPresent: bool }
+ */
+export function classifyIntentDeterministic(prose) {
+  const text = String(prose || '');
+  const features = [];
+  if (!text.trim()) {
+    return { intent: 'DESCRIBE', confidence: 1.0, features: ['empty'], evidenceAnchored: false, mutationVocabPresent: false };
+  }
+  const mutationVocabPresent = MUTATION_VOCAB_RX.test(text);
+  if (!mutationVocabPresent) {
+    return { intent: 'DESCRIBE', confidence: 0.95, features: ['no-mutation-vocab'], evidenceAnchored: false, mutationVocabPresent: false };
+  }
+  if (FIRST_PERSON_CLAIM_RX.test(text)) features.push('first-person-claim');
+  if (COMPLETION_PAST_TENSE_RX.test(text)) features.push('completion-past-tense');
+  if (PROPOSE_MARKER_RX.test(text)) features.push('propose-marker');
+  if (PENDING_AUTH_RX.test(text)) features.push('pending-auth');
+  if (REPORT_MARKER_RX.test(text)) features.push('report-marker');
+  if (EVIDENCE_ANCHOR_RX.test(text)) features.push('evidence-anchor');
+  if (META_DISCUSSION_RX.test(text)) features.push('meta-discussion');
+  const evidenceAnchored = features.includes('evidence-anchor');
+
+  // Strong CLAIM signals: first-person past-tense action without evidence anchor and without pending-auth.
+  const claimStrong = features.includes('first-person-claim') && !evidenceAnchored && !features.includes('pending-auth');
+  if (claimStrong) {
+    return { intent: 'CLAIM', confidence: 0.85, features, evidenceAnchored, mutationVocabPresent };
+  }
+
+  // Strong PROPOSE: propose marker AND no first-person-claim AND no completion-past-tense.
+  const proposeStrong = features.includes('propose-marker') && !features.includes('first-person-claim') && !features.includes('completion-past-tense');
+  if (proposeStrong) {
+    return { intent: 'PROPOSE', confidence: 0.85, features, evidenceAnchored, mutationVocabPresent };
+  }
+
+  // Strong REPORT: report-marker present, NOT first-person-claim with mutation completion verb.
+  const reportStrong = features.includes('report-marker') && !features.includes('first-person-claim');
+  if (reportStrong) {
+    return { intent: 'REPORT', confidence: 0.85, features, evidenceAnchored, mutationVocabPresent };
+  }
+
+  // Strong DESCRIBE: meta-discussion or pending-auth without first-person-claim.
+  const describeStrong = (features.includes('meta-discussion') || features.includes('pending-auth')) && !features.includes('first-person-claim');
+  if (describeStrong) {
+    return { intent: 'DESCRIBE', confidence: 0.80, features, evidenceAnchored, mutationVocabPresent };
+  }
+
+  // Weak CLAIM (completion-past-tense without first-person but no pending-auth or evidence)
+  if (features.includes('completion-past-tense') && !evidenceAnchored && !features.includes('pending-auth')) {
+    return { intent: 'CLAIM', confidence: 0.65, features, evidenceAnchored, mutationVocabPresent };
+  }
+
+  // Verified CLAIM (completion + evidence)
+  if (features.includes('completion-past-tense') && evidenceAnchored) {
+    return { intent: 'CLAIM', confidence: 0.85, features: [...features, 'verified-claim'], evidenceAnchored, mutationVocabPresent };
+  }
+
+  // AI-11803-QA-GAP2 (2026-05-12): first-person CLAIM with evidence anchor
+  // even without the aux-verb completion pattern ("was deployed", "has been
+  // rolled out"). The first-person form ("I deployed X — exit 0") doesn't
+  // match COMPLETION_PAST_TENSE_RX because that regex requires an auxiliary
+  // verb. Without this branch, verified first-person claims fall to AMBIGUOUS
+  // and the posture downgrade preserves the hard_block — over-conservative.
+  // Route to CLAIM(evidenceAnchored=true) so decisionFromIntent → WARN (allow).
+  if (features.includes('first-person-claim') && evidenceAnchored) {
+    return { intent: 'CLAIM', confidence: 0.85, features: [...features, 'verified-claim-first-person'], evidenceAnchored, mutationVocabPresent };
+  }
+
+  return { intent: 'AMBIGUOUS', confidence: 0.5, features, evidenceAnchored, mutationVocabPresent };
+}
+
+/**
+ * LLM-backed intent classification via deepseek-v4-flash (or configured model).
+ * Used as fallback when deterministic returns AMBIGUOUS.
+ *
+ * Returns same shape as classifyIntentDeterministic, but with `source: 'llm'`
+ * and adds a `rationale` field from the model.
+ *
+ * Falls back to AMBIGUOUS with source: 'llm-error' if the call fails.
+ */
+export async function classifyIntentLLM(prose, { endpoint = FLASH_MODEL_DEFAULTS.endpoint, model = FLASH_MODEL_DEFAULTS.model, timeoutMs = FLASH_MODEL_DEFAULTS.timeoutMs, apiKey = null } = {}) {
+  const text = String(prose || '').slice(0, 6000);
+  if (!text.trim()) {
+    return { intent: 'DESCRIBE', confidence: 0.9, features: ['empty'], evidenceAnchored: false, mutationVocabPresent: false, source: 'llm-skipped-empty' };
+  }
+  const systemPrompt = `You are an intent classifier for assistant prose. Output STRICT JSON only, no prose, no markdown.
+
+Classify the prose intent regarding infrastructure mutation language (deploy, rollout, rebuild, push, kubectl, etc).
+
+Categories:
+- CLAIM: asserts a mutation HAS occurred (past tense + first-person OR third-person completion). Triggers a real block ONLY when no evidence anchor is present in the prose.
+- PROPOSE: recommends a future or conditional action. Modal verbs (will, would, should, could, recommend, suggest, next step). Not a real block.
+- REPORT: describes work done at the SOURCE level WITHOUT claiming runtime mutation (source corrections recorded, fix prepared, edits applied to file). Not a real block.
+- DESCRIBE: meta-discussion of mutation as a topic, OR pending authorization framing. Not a real block.
+
+Output schema (strict JSON):
+{
+  "intent": "CLAIM" | "PROPOSE" | "REPORT" | "DESCRIBE",
+  "confidence": 0.0..1.0,
+  "evidenceAnchored": boolean,
+  "rationale": "one sentence why"
+}
+
+Do NOT include the prose in your output. Do NOT include any other fields.`;
+  const body = {
+    message: `Classify this prose:\n\n---PROSE_START---\n${text}\n---PROSE_END---`,
+    systemPrompt,
+    model,
+    metadata: {
+      platform: 'aria-coach-intent-classifier',
+      use_case: 'block_decision_second_look',
+    },
+  };
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    const resp = await fetch(endpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    clearTimeout(timer);
+    if (!resp.ok) {
+      return { intent: 'AMBIGUOUS', confidence: 0.4, features: ['llm-http-' + resp.status], evidenceAnchored: false, mutationVocabPresent: true, source: 'llm-error', rationale: `HTTP ${resp.status}` };
+    }
+    const json = await resp.json();
+    const raw = String(json?.response || json?.message || json?.text || '').trim();
+    // Extract JSON from possibly noisy response.
+    const match = raw.match(/\{[\s\S]*\}/);
+    if (!match) {
+      return { intent: 'AMBIGUOUS', confidence: 0.4, features: ['llm-no-json'], evidenceAnchored: false, mutationVocabPresent: true, source: 'llm-error', rationale: 'no JSON in LLM response' };
+    }
+    const parsed = JSON.parse(match[0]);
+    const intent = ['CLAIM', 'PROPOSE', 'REPORT', 'DESCRIBE'].includes(parsed.intent) ? parsed.intent : 'AMBIGUOUS';
+    return {
+      intent,
+      confidence: typeof parsed.confidence === 'number' ? Math.max(0, Math.min(1, parsed.confidence)) : 0.6,
+      features: ['llm-classified'],
+      evidenceAnchored: parsed.evidenceAnchored === true,
+      mutationVocabPresent: true,
+      source: 'llm',
+      rationale: typeof parsed.rationale === 'string' ? parsed.rationale.slice(0, 280) : '',
+    };
+  } catch (err) {
+    return { intent: 'AMBIGUOUS', confidence: 0.4, features: ['llm-exception'], evidenceAnchored: false, mutationVocabPresent: true, source: 'llm-error', rationale: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Hybrid classifier: deterministic first, LLM fallback only for AMBIGUOUS.
+ *
+ * Returns:
+ *   { ...classification, decision: 'BLOCK' | 'OVERRIDE' | 'WARN', source: 'deterministic' | 'llm-fallback' }
+ *
+ * Decision rules:
+ *   - CLAIM (high confidence) without evidence → BLOCK
+ *   - CLAIM with evidence → WARN (verified)
+ *   - PROPOSE / REPORT / DESCRIBE → OVERRIDE (downgrade upstream block)
+ *   - AMBIGUOUS at deterministic layer → call LLM, then re-evaluate
+ */
+export async function hybridClassify(prose, opts = {}) {
+  const det = classifyIntentDeterministic(prose);
+  if (det.intent !== 'AMBIGUOUS') {
+    return decisionFromIntent(det, 'deterministic');
+  }
+  // LLM fallback path
+  const llm = await classifyIntentLLM(prose, opts);
+  return decisionFromIntent(llm, llm.source === 'llm' ? 'llm-fallback' : 'llm-error-fallback');
+}
+
+function decisionFromIntent(classification, source) {
+  let decision;
+  if (classification.intent === 'CLAIM' && !classification.evidenceAnchored) {
+    decision = 'BLOCK'; // real unverified claim
+  } else if (classification.intent === 'CLAIM' && classification.evidenceAnchored) {
+    decision = 'WARN'; // verified claim, log but allow
+  } else if (classification.intent === 'AMBIGUOUS') {
+    decision = 'WARN'; // can't tell — be conservative, log but allow with warning
+  } else {
+    decision = 'OVERRIDE'; // PROPOSE / REPORT / DESCRIBE — false-positive of upstream regex
+  }
+  return { ...classification, decision, source };
+}