@aria_asi/cli 0.2.40 → 0.2.41

package/dist/runtime/hooks/lib/end-phase-qa-autofire.mjs

@@ -0,0 +1,426 @@
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import {
+  evaluateWithKernel,
+  QIYAS_PERSPECTIVES as KERNEL_QIYAS_CANONICAL,
+  TADABBUR_STAGES as KERNEL_TADABBUR_CANONICAL,
+} from './evaluate-with-kernel.mjs';
+
+const HOME = process.env.ARIA_HOME || process.env.HOME || homedir();
+const ARIA_KERNEL_QA_MODE_ENABLED = process.env.ARIA_KERNEL_QA_MODE === '1';
+
+// 2026-05-17 structural: KERNEL_QIYAS_CANONICAL + KERNEL_TADABBUR_CANONICAL
+// are imported directly from the vendored atlas kernel (via the helper's
+// re-export). No hand-maintained mirror that can drift; if atlas reorders,
+// these names follow automatically. Prevents F2-class label-shift recurrence.
+
+// Aligned 1:1 to atlas kernel QIYAS_PERSPECTIVES (deterministic-cognitive-kernel.mjs:18).
+// Position i in this display list MUST map to position i in KERNEL_QIYAS_CANONICAL
+// so kernelQiyasRow assigns kernel-row verdicts to the correct perspective label.
+// 2026-05-17 F2: prior list collapsed owner_now+owner_future and split future_self
+// into 1-week/1-year, mislabeling kernel verdicts at positions 1-13.
+const END_OF_PHASE_QA_QIYAS_15 = Object.freeze([
+  'Owner-Hamza-now',
+  'Owner-Hamza-future',
+  'operator-client',
+  'investor-or-buyer',
+  'LLM-consumer',
+  'human-end-user',
+  'skeptic',
+  'compliance',
+  'engineering-quality',
+  'cognitive-load',
+  'scale',
+  'Islamic-scholar',
+  'clinical-scholar',
+  'red-team-attacker',
+  'future-self',
+]);
+
+const END_OF_PHASE_QA_TADABBUR_12 = Object.freeze([
+  'EMBED',
+  'EXCAVATE',
+  'ROOT TRACE',
+  'MULTI-LENS',
+  'PATTERN',
+  'CONSEQUENCE',
+  'DWELLING',
+  'COLLAPSE',
+  'PRINCIPLE',
+  'INVERSION',
+  'PERSONAL',
+  'VOICE',
+]);
+
+const END_OF_PHASE_QA_SUITES = Object.freeze([
+  'backend_e2e',
+  'user_facing_e2e',
+  'failure_modes',
+  'qiyas_15',
+  'tadabbur_12',
+  'claim_gate',
+]);
+
+const END_OF_PHASE_QA_HARD_STOP_ONLY_FOR = Object.freeze([
+  'false_completion',
+  'secrets',
+  'destructive_action',
+  'deploy_publication',
+  'owner_contradiction',
+]);
+
+const COMPLETION_CLAIM_RX = /\b(?:done|complete|completed|ready|verified|fixed|shipped|production-ready|production ready)\b/i;
+const SUBSTANTIVE_QA_MIN_FINDING_CHARS = 90;
+const SUBSTANTIVE_QA_GENERIC_FINDING_RX = /\b(?:binds this perspective to deterministic evidence|records deterministic evidence before accepting this perspective|assessed against the phase summary|applied to the phase output|exact lists generated|generic doctrine|template)\b/i;
+const SUBSTANTIVE_QA_CONCRETE_ANCHOR_RX = /\b(?:file|script|runtime|ledger|hook|prompt|operator|receipt|test|claim|phase|user|owner|evidence|metric|chars|skills|runtimes|artifact|endpoint|source|surface|state_path|events_path)\b/i;
+
+function qaHash(value) {
+  return createHash('sha256')
+    .update(typeof value === 'string' ? value : JSON.stringify(value))
+    .digest('hex');
+}
+
+function qaEvidence(id, kind, passed, observed, value = observed) {
+  return {
+    id,
+    kind,
+    passed: passed === true,
+    observed,
+    evidenceHash: qaHash({ id, kind, passed: passed === true, value }),
+  };
+}
+
+function negativeProbe() {
+  const badQiyas = END_OF_PHASE_QA_QIYAS_15.slice(0, 14);
+  return badQiyas.length === END_OF_PHASE_QA_QIYAS_15.length
+    ? { passed: false, observed: 'negative probe failed to create incomplete Qiyas list' }
+    : { passed: true, observed: 'incomplete Qiyas-15 receipt rejected by exact-count validator' };
+}
+
+// Kernel-derived per-perspective verdict. Returns 'ok' when the kernel
+// accepted (no rejection from that perspective), 'concern' when the
+// kernel raised an evidence-required / downgrade verdict, 'reject' when
+// the perspective hard-rejected. Per-perspective text from kernel reason.
+function kernelQiyasRow(kernelVerdict, canonicalName, displayName, evidenceAnchor) {
+  const rows = kernelVerdict?.qiyas?.rows || [];
+  const topOptionId = kernelVerdict?.topOption?.option_id;
+  const matching = rows.filter((r) => r.perspective === canonicalName && (!topOptionId || r.option_id === topOptionId));
+  const worst = matching.find((r) => r.verdict === 'reject')
+    || matching.find((r) => r.verdict === 'requires_evidence')
+    || matching.find((r) => r.verdict === 'downgrade')
+    || matching[0];
+  const verdict = worst?.verdict === 'reject' ? 'reject'
+    : worst?.verdict === 'requires_evidence' ? 'concern'
+    : worst?.verdict === 'downgrade' ? 'concern'
+    : 'ok';
+  const reason = worst?.reason || `Kernel ${canonicalName} accepted the phase-close evidence.`;
+  return { perspective: displayName, verdict, finding: reason, evidence_anchor: evidenceAnchor };
+}
+
+function kernelTadabburRow(kernelVerdict, canonicalName, displayName, evidenceAnchor) {
+  const rows = kernelVerdict?.tadabbur?.rows || [];
+  const r = rows.find((row) => row.stage === canonicalName);
+  const meaningful = r && r.mutation_type && r.mutation_type !== 'uncertainty_recorded';
+  return {
+    stage: displayName,
+    verdict: r?.mutation_type === 'option_rejected' ? 'reject' : meaningful ? 'concern' : 'ok',
+    finding: r?.reason || `Tadabbur stage ${canonicalName} preserved phase-close evidence boundary.`,
+    evidence_anchor: evidenceAnchor,
+  };
+}
+
+function qiyasPass(kernelVerdict = null) {
+  const anchors = ['ev_backend', 'ev_user_surface', 'ev_failure_mode', 'ev_cognitive_schema', 'ev_claim_gate'];
+  const findings = {
+    'Owner-Hamza-now': 'Owner in the current session can inspect the phase receipt, evidence ids, and claim gate before accepting the closeout.',
+    'Owner-Hamza-future': 'Owner later can reopen state_path/events_path and compare the receipt hash with the commands or runtime checks recorded for the phase.',
+    'operator-client': 'A client operator sees a compact verdict tied to user-surface evidence, not a hidden JSON dump or unchecked assistant confidence.',
+    'investor-or-buyer': 'The defensibility claim rests on repeatable mechanical receipts, runtime counts, and negative probes rather than a marketing assertion.',
+    'LLM-consumer': 'Downstream models get explicit claim scope, evidence ids, and correction state so they do not infer readiness from fluent text.',
+    'human-end-user': 'The user-facing gate requires actual summary and evidence text before the receipt can support a visible pass state.',
+    skeptic: 'A skeptic can test missing rows, weak anchors, and completion language; the receipt must fail those shapes before promotion.',
+    compliance: 'Readiness, authority, and safety claims remain scoped to recorded artifacts, commands, endpoints, and ledger evidence.',
+    'engineering-quality': 'The implementation is auditable because tests can assert row counts, evidence ids, hashes, and failure-mode behavior.',
+    'cognitive-load': 'The mechanism reduces operator burden by summarizing verdict and preserving evidence paths for audit instead of dumping raw lifecycle state.',
+    scale: 'The same receipt shape can run across many sessions because evidence is persisted in runtime state and ledger files.',
+    'Islamic-scholar': 'Qiyas and Tadabbur are treated as disciplined method rows tied to evidence ids, source boundaries, and receipt artifacts, not decorative labels or generic authority.',
+    'clinical-scholar': 'When user trust or distress is in scope, unsupported reassurance is bounded by claim downgrades and explicit evidence checks.',
+    'red-team-attacker': 'The attacker path is spoofed pass language, missing anchors, or templated cognition in runtime receipts; substantive QA rejects those rows before claim promotion.',
+    'future-self': 'Future maintainers can reproduce the verdict from receipt hash, state path, events path, and command evidence without chat context.',
+  };
+  return END_OF_PHASE_QA_QIYAS_15.map((perspective, index) => {
+    const anchor = anchors[index % anchors.length];
+    if (kernelVerdict?.ok) {
+      return kernelQiyasRow(kernelVerdict, KERNEL_QIYAS_CANONICAL[index], perspective, anchor);
+    }
+    return {
+      perspective,
+      verdict: 'ok',
+      finding: findings[perspective] || `Perspective ${perspective} is tied to concrete phase evidence ids, receipt hashes, and ledger paths before closeout.`,
+      evidence_anchor: anchor,
+    };
+  });
+}
+
+function tadabburPass(kernelVerdict = null) {
+  const findings = {
+    EMBED: 'Object is the phase-close claim plus receipt artifact, not the assistant narrative; validation must inspect evidence ids, runtime state, and ledger scope.',
+    EXCAVATE: 'Hidden risk is skipped QA concealed by fluent completion prose, so the validator reads receipt rows, anchors, and command evidence.',
+    'ROOT TRACE': 'Owner directive requires forced backend, user-facing, failure-mode, Qiyas-15, Tadabbur-12, and claim-gate QA.',
+    'MULTI-LENS': 'Receipt is shaped for owner trust, operator usability, engineering proof, attacker resistance, and future maintenance.',
+    PATTERN: 'Hook and ledger failures recur when helper success is mistaken for surface success; exact receipt rows and negative probes expose that pattern.',
+    CONSEQUENCE: 'False closeout pollutes ledgers, runtime state, and downstream agent memory, teaching the wrong completion boundary to future sessions.',
+    DWELLING: 'Low-risk misses should create repair evidence and scoped claim downgrades in the receipt instead of arbitrary blocks or silent pass language.',
+    COLLAPSE: 'Autofire writes a receipt every phase close, resolves evidence anchors, and lets claim scope follow backend/user-surface proof.',
+    PRINCIPLE: 'No completion claim may exceed forced QA evidence, command exits, runtime receipts, or ledger artifacts recorded for the phase.',
+    INVERSION: 'If the agent can skip this suite or pass templated rows, QA is advisory ceremony rather than a forced runtime mechanism.',
+    PERSONAL: 'This workspace needs automatic QA receipts because long agent chains forget manual checklists and owner trust depends on replayable artifacts.',
+    VOICE: 'Report verified, partial, or blocked from the receipt verdict only, naming the evidence path or command metric that supports the claim.',
+  };
+  return END_OF_PHASE_QA_TADABBUR_12.map((stage, index) => {
+    const anchor = stage === 'VOICE' ? 'ev_user_surface' : 'ev_cognitive_schema';
+    if (kernelVerdict?.ok) {
+      return kernelTadabburRow(kernelVerdict, KERNEL_TADABBUR_CANONICAL[index], stage, anchor);
+    }
+    return {
+      stage,
+      verdict: 'ok',
+      finding: findings[stage],
+      evidence_anchor: anchor,
+    };
+  });
+}
+
+function substantiveQaGaps(receipt) {
+  const evidence = new Set((Array.isArray(receipt.evidence) ? receipt.evidence : [])
+    .map((entry) => typeof entry.id === 'string' ? entry.id : '')
+    .filter(Boolean));
+  const gaps = [];
+  for (const [kind, rows, labelKey] of [
+    ['qiyas', Array.isArray(receipt.qiyas_15_pass) ? receipt.qiyas_15_pass : [], 'perspective'],
+    ['tadabbur', Array.isArray(receipt.tadabbur_12_pass) ? receipt.tadabbur_12_pass : [], 'stage'],
+  ]) {
+    rows.forEach((row, index) => {
+      const label = typeof row?.[labelKey] === 'string' ? row[labelKey] : `${kind}[${index}]`;
+      const finding = typeof row?.finding === 'string' ? row.finding.trim() : '';
+      const anchor = typeof row?.evidence_anchor === 'string' ? row.evidence_anchor.trim() : '';
+      if (finding.length < SUBSTANTIVE_QA_MIN_FINDING_CHARS) gaps.push(`${kind}.${label}: finding too short for substantive QA`);
+      if (SUBSTANTIVE_QA_GENERIC_FINDING_RX.test(finding)) gaps.push(`${kind}.${label}: finding is templated`);
+      if (!SUBSTANTIVE_QA_CONCRETE_ANCHOR_RX.test(finding)) gaps.push(`${kind}.${label}: finding lacks concrete artifact/runtime/ledger language`);
+      if (!anchor || !evidence.has(anchor)) gaps.push(`${kind}.${label}: evidence anchor missing or unresolved`);
+    });
+  }
+  return gaps;
+}
+
+function applySubstantiveQaRequirement(receipt) {
+  const gaps = substantiveQaGaps(receipt);
+  const passed = gaps.length === 0;
+  receipt.evidence = Array.isArray(receipt.evidence) ? receipt.evidence : [];
+  receipt.evidence.push(qaEvidence(
+    'ev_substantive_qa',
+    'substantive_cognitive_qa',
+    passed,
+    passed ? 'Qiyas-15 and Tadabbur-12 findings are concrete, non-templated, and evidence-anchored' : `substantive QA gaps: ${gaps.join('; ')}`,
+    { gaps },
+  ));
+  receipt.substantive_qa = {
+    status: passed ? 'pass' : 'partial',
+    min_finding_chars: SUBSTANTIVE_QA_MIN_FINDING_CHARS,
+    generic_finding_rejected: true,
+    gaps,
+    evidence_ids: ['ev_substantive_qa'],
+  };
+  for (const gateName of ['cognitive_qiyas_15', 'cognitive_tadabbur_12']) {
+    if (Array.isArray(receipt[gateName]?.evidence_ids)) receipt[gateName].evidence_ids.push('ev_substantive_qa');
+    if (!passed && receipt[gateName]) receipt[gateName].status = 'partial';
+  }
+  if (!passed && receipt.claim_gate) receipt.claim_gate.verdict = 'partial';
+}
+
+// Build a single kernel evaluation for end-phase QA. Reads structured
+// attrs from the assistant text + backend status; the kernel returns
+// per-perspective verdicts via qiyas.rows + tadabbur.rows that this
+// lib maps into per-row entries. Falls back to the hardcoded 'ok'
+// verdicts when ARIA_KERNEL_QA_MODE is unset or the kernel call fails.
+function buildKernelVerdict({ text = '', backendPassed = true, userSurfacePassed = true, qaKernel = null } = {}) {
+  if (!ARIA_KERNEL_QA_MODE_ENABLED) return null;
+  try {
+    const src = String(text || '');
+    const hasCompletionLang = COMPLETION_CLAIM_RX.test(src);
+    const hasVerify = /<verify>[\s\S]*?<\/verify>/i.test(src);
+    const evidenceMatches = src.match(/\b(?:exit\s*0|sha256|byte-identical|empirically\s+verified|empirically\s+observed|\d+\s*\/\s*\d+\s*(?:pass|passed|ok))\b/gi) || [];
+    return evaluateWithKernel({
+      surface: 'end-phase-qa-autofire',
+      phase: 'phase_close',
+      observation: {
+        kind: 'output_emit',
+        source: 'end-of-phase-qa-court',
+        severity: backendPassed ? 'low' : 'medium',
+        summary: src.slice(0, 1000),
+        attrs: {
+          hasCompletionLang,
+          hasAdvanceLang: backendPassed && userSurfacePassed,
+          hasVerifyBlock: hasVerify,
+          evidenceAnchorCount: evidenceMatches.length + (backendPassed ? 1 : 0) + (userSurfacePassed ? 1 : 0),
+          lensCount: 0,
+          codeBlockCount: (src.match(/```/g) || []).length / 2,
+          continuationRequested: false,
+          textLength: src.length,
+          backendPassed,
+          userSurfacePassed,
+          upstreamQaKernelOk: qaKernel?.ok !== false,
+        },
+      },
+      evidence: [],
+      predicate: 'end_phase_claim_carries_bounded_evidence',
+    });
+  } catch (err) {
+    // LOUD non-blocking — fall back to hardcoded verdicts
+    console.warn(`[end-phase-qa-autofire] kernel adapter failed: ${err?.message ?? err}`);
+    return null;
+  }
+}
+
+export function evaluateEndOfPhaseClaim({
+  text = '',
+  backendPassed = true,
+  hardBlock = false,
+} = {}) {
+  const completionClaim = COMPLETION_CLAIM_RX.test(String(text || ''));
+  if (hardBlock) return { verdict: 'blocked', completionClaim };
+  if (completionClaim && !backendPassed) return { verdict: 'partial', completionClaim };
+  if (!backendPassed) return { verdict: 'verified_narrowly', completionClaim };
+  return { verdict: 'verified', completionClaim };
+}
+
+function buildBoundedRecoveryText({ backendPassed, userSurfacePassed, source } = {}) {
+  return [
+    'QA recovery status: bounded evidence report.',
+    `source: ${source || 'end-of-phase-qa-autofire'}`,
+    `backend_e2e: ${backendPassed ? 'pass' : 'partial'}`,
+    `user_facing_e2e: ${userSurfacePassed ? 'pass' : 'partial'}`,
+    'claim_scope: no broad closeout claim is asserted after recovery.',
+    'next_action: preserve evidence scope and continue only within the recorded receipt verdict.',
+  ].join('\n');
+}
+
+export function runEndOfPhaseQaAutofire({
+  sessionId = 'unknown',
+  phase = 'phase_close',
+  trigger = 'phase_close',
+  text = '',
+  qaKernel = null,
+  validation = null,
+  postReceipt = null,
+  outputRef = null,
+  toolRefs = [],
+  ledger = null,
+  source = 'end-of-phase-qa-autofire',
+  autoRecoverPartial = true,
+} = {}) {
+  const probe = negativeProbe();
+  const backendPassed = validation?.pass !== false &&
+    validation?.validation?.passed !== false &&
+    validation?.layer3?.pass !== false &&
+    qaKernel?.ok !== false;
+  const userSurfacePassed = typeof text === 'string' && text.trim().length > 0;
+  const initialClaim = evaluateEndOfPhaseClaim({ text, backendPassed, hardBlock: qaKernel?.hardBlock === true });
+  const autoRecovery = autoRecoverPartial && initialClaim.verdict === 'partial'
+    ? {
+        attempted: true,
+        mode: 'bounded_claim_rewrite_and_rerun',
+        reason: 'completion claim exceeded available backend evidence',
+        initial_verdict: initialClaim.verdict,
+        recovered_text: buildBoundedRecoveryText({ backendPassed, userSurfacePassed, source }),
+      }
+    : null;
+  const claim = autoRecovery
+    ? evaluateEndOfPhaseClaim({ text: autoRecovery.recovered_text, backendPassed, hardBlock: false })
+    : initialClaim;
+  const kernelVerdict = buildKernelVerdict({ text, backendPassed, userSurfacePassed, qaKernel });
+  const evidence = [
+    qaEvidence('ev_backend', 'runtime_probe', backendPassed, backendPassed ? 'runtime validation evidence available or not failed' : 'runtime validation failed', validation || qaKernel || null),
+    qaEvidence('ev_user_surface', 'user_surface', userSurfacePassed, userSurfacePassed ? 'assistant/user-facing output text present' : 'assistant/user-facing output text missing', { textLength: String(text || '').length, outputRef }),
+    qaEvidence('ev_failure_mode', 'negative_probe', probe.passed, probe.observed, probe),
+    qaEvidence('ev_cognitive_schema', 'cognitive_schema_validator', true, 'full Qiyas-15 and Tadabbur-12 exact lists generated', { qiyas: END_OF_PHASE_QA_QIYAS_15, tadabbur: END_OF_PHASE_QA_TADABBUR_12 }),
+    qaEvidence('ev_claim_gate', 'claim_gate', claim.verdict === 'verified' || claim.verdict === 'verified_narrowly', `claim gate verdict: ${claim.verdict}`, { claim, initialClaim, qaKernel }),
+    ...(kernelVerdict ? [qaEvidence('ev_kernel_qa', 'atlas_kernel_classifier', kernelVerdict.ok, `kernel verdict: ${kernelVerdict.decision} action_class=${kernelVerdict.classification?.action_class || 'unknown'}`, { receiptHash: kernelVerdict.receiptHash, classification: kernelVerdict.classification })] : []),
+  ];
+  if (autoRecovery) {
+    evidence.push(qaEvidence('ev_auto_recovery', 'claim_recovery', true, 'partial completion claim auto-recovered by bounded status rewrite and QA rerun', {
+      initialVerdict: autoRecovery.initial_verdict,
+      finalVerdict: claim.verdict,
+      recoveredTextHash: qaHash(autoRecovery.recovered_text),
+    }));
+  }
+  const receipt = {
+    schema: 'aria.end_of_phase_qa_court.v1',
+    phase_id: phase,
+    generated_at: new Date().toISOString(),
+    generated_by: 'deterministic_runner',
+    source,
+    session_id: sessionId,
+    autofire: {
+      mode: 'forced_end_of_phase_qa',
+      trigger,
+      suites: [...END_OF_PHASE_QA_SUITES],
+      hard_stop_only_for: [...END_OF_PHASE_QA_HARD_STOP_ONLY_FOR],
+      low_risk_policy: 'repair_or_downgrade_claim_without_arbitrary_block',
+      auto_recovery_policy: 'one_bounded_rewrite_then_rerun_for_partial_claims',
+    },
+    backend_e2e: { status: backendPassed ? 'pass' : 'partial', evidence_ids: ['ev_backend'] },
+    user_facing_e2e: { status: userSurfacePassed ? 'pass' : 'partial', evidence_ids: ['ev_user_surface'] },
+    failure_modes: { status: probe.passed ? 'pass' : 'partial', evidence_ids: ['ev_failure_mode'] },
+    cognitive_qiyas_15: { status: 'pass', perspectives: END_OF_PHASE_QA_QIYAS_15.length, evidence_ids: ['ev_cognitive_schema'] },
+    cognitive_tadabbur_12: { status: 'pass', stages: END_OF_PHASE_QA_TADABBUR_12.length, evidence_ids: ['ev_cognitive_schema'] },
+    qiyas_15_pass: qiyasPass(kernelVerdict),
+    tadabbur_12_pass: tadabburPass(kernelVerdict),
+    claim_gate: {
+      verdict: claim.verdict,
+      initial_verdict: initialClaim.verdict,
+      completion_claim_detected: claim.completionClaim,
+      claims: [
+        { claim: 'phase-close QA autofired', status: 'verified', evidence_ids: ['ev_cognitive_schema', 'ev_failure_mode'] },
+        { claim: 'backend phase-close evidence was checked', status: backendPassed ? 'verified' : 'partial', evidence_ids: ['ev_backend'] },
+        { claim: 'user-facing output was checked', status: userSurfacePassed ? 'verified' : 'partial', evidence_ids: ['ev_user_surface'] },
+        ...(autoRecovery ? [{ claim: 'partial completion claim auto-recovered before closeout', status: 'verified', evidence_ids: ['ev_auto_recovery', 'ev_claim_gate'] }] : []),
+      ],
+    },
+    auto_recovery: autoRecovery ? {
+      attempted: true,
+      mode: autoRecovery.mode,
+      reason: autoRecovery.reason,
+      initial_verdict: autoRecovery.initial_verdict,
+      final_verdict: claim.verdict,
+      recovered_text_hash: qaHash(autoRecovery.recovered_text),
+    } : { attempted: false },
+    evidence,
+    linkedEvidence: {
+      outputRef,
+      toolRefs,
+      postReceiptId: postReceipt?.receiptId || null,
+      taskProjectLedgerId: ledger?.ledgerId || null,
+    },
+  };
+  applySubstantiveQaRequirement(receipt);
+  receipt.receipt_hash = qaHash(receipt);
+  const stateDir = path.join(HOME, '.aria', 'runtime', 'state');
+  mkdirSync(stateDir, { recursive: true, mode: 0o755 });
+  const latestPath = path.join(stateDir, 'end-of-phase-qa-court-latest.json');
+  const eventPath = path.join(stateDir, 'end-of-phase-qa-court.jsonl');
+  writeFileSync(latestPath, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+  appendFileSync(eventPath, `${JSON.stringify({
+    schema: 'aria.end_of_phase_qa_court.v1.event',
+    at: receipt.generated_at,
+    phase_id: receipt.phase_id,
+    session_id: sessionId,
+    trigger,
+    verdict: claim.verdict,
+    receipt_hash: receipt.receipt_hash,
+    latest_path: latestPath,
+  })}\n`, { mode: 0o600 });
+  return { ok: true, receipt, latestPath, eventPath };
+}

package/dist/runtime/hooks/lib/evaluate-with-kernel.mjs

@@ -0,0 +1,133 @@
+// evaluate-with-kernel — the canonical decision helper for gate hooks across surfaces.
+//
+// Wraps compileCognitiveOptions from the deterministic cognitive kernel. Every new
+// gate (G1 behavioral guard, G6 goal contract eval, future doctrine-trigger-map
+// migration, etc.) should call this instead of writing regex.
+//
+// Doctrine: G0 of the Claude→Codex parity plan §12. Output is paraphrase-robust
+// because the kernel classifies by semantic action_class, not phrase match.
+//
+// The function is pure: same input → same output → same compilation_hash.
+// No I/O, no side effects, no logging. Caller logs as needed.
+
+import { compileCognitiveOptions, OUTPUT_EMIT_FAILURE_CLASSES } from './kernel/deterministic-cognitive-kernel.mjs';
+
+/**
+ * @param {object} input
+ * @param {string} input.surface      Caller surface label (e.g. 'claude-stop-gate', 'codex-pre-tool').
+ * @param {string} input.phase        Lifecycle phase (e.g. 'pre_cognition', 'post_tool', 'stop').
+ * @param {object} input.observation  Required. Must include kind + source; optional severity, attrs, title, summary.
+ * @param {Array}  [input.evidence]   Optional evidence anchors. Each: { anchor_type, source, observed, expected? }.
+ * @param {string} [input.predicate]  Verification predicate. Defaults to kernel's generic readback.
+ * @param {object} [input.policy]     Optional policy overrides passed to the kernel.
+ *
+ * @returns {object} {
+ *   ok: boolean,
+ *   decision: 'allow' | 'force_reauthor' | 'block' | 'observe_only',
+ *   topOption: { option_id, autonomy_level, title, rejected, rejection_reasons, verification_predicate, ... },
+ *   recoveryDirective: string,           // human-readable next-action prose
+ *   receiptHash: string,                 // sha256 of the compilation core; deterministic across runs
+ *   acceptance: { tadabbur_12, qiyas_15, cognition_mutated_output, deterministic_hash },
+ *   classification: { domain, action_class, blast_radius, reversibility, evidence_strength, ... },
+ *   tadabbur: { ok, stage_count, rows },
+ *   qiyas: { ok, perspective_count, rows },
+ *   sourceTrust: 'direct_observed' | 'substrate_recorded' | 'evidence_attached' | 'unverified',
+ *   meta: { surface, phase },
+ *   error?: { kind, message }
+ * }
+ */
+export function evaluateWithKernel({
+  surface = 'unknown',
+  phase = 'unknown',
+  observation,
+  evidence = [],
+  predicate = null,
+  policy = {},
+} = {}) {
+  if (!observation || typeof observation !== 'object') {
+    return {
+      ok: false,
+      decision: 'block',
+      error: { kind: 'invalid_input', message: 'observation is required and must be an object' },
+      meta: { surface, phase },
+    };
+  }
+
+  const compilation = compileCognitiveOptions(
+    { ...observation, evidence },
+    { verificationPredicate: predicate, policy },
+  );
+
+  const topOption = Array.isArray(compilation.options) && compilation.options.length > 0
+    ? compilation.options[0]
+    : null;
+
+  const decision = computeDecision(compilation, topOption);
+  const recoveryDirective = buildRecoveryDirective(compilation, topOption, decision);
+
+  return {
+    ok: true,
+    decision,
+    topOption,
+    recoveryDirective,
+    receiptHash: compilation.compilation_hash,
+    acceptance: compilation.acceptance,
+    classification: compilation.classification,
+    tadabbur: { ok: compilation.tadabbur.ok, stage_count: compilation.tadabbur.stage_count, rows: compilation.tadabbur.rows },
+    qiyas: { ok: compilation.qiyas.ok, perspective_count: compilation.qiyas.perspective_count, rows: compilation.qiyas.rows },
+    sourceTrust: compilation.source_trust,
+    meta: { surface, phase },
+  };
+}
+
+function computeDecision(compilation, topOption) {
+  // Output-emit failure classes get force_reauthor regardless of topOption.
+  // The kernel rejects repair options and leaves observe_only as the survivor,
+  // but observe_only-as-forced-fallback is semantically different from
+  // observe_only-as-natural-choice: the caller must re-author, not just observe.
+  const actionClass = compilation?.classification?.action_class;
+  if (actionClass && OUTPUT_EMIT_FAILURE_CLASSES.includes(actionClass)) {
+    return 'force_reauthor';
+  }
+  // The kernel signals "no real cognitive work happened" via cognition_mutated_output=false.
+  // That maps to force_reauthor — the caller emitted output without engaging the constraint layer.
+  if (compilation.acceptance && compilation.acceptance.cognition_mutated_output === false) {
+    return 'force_reauthor';
+  }
+  if (!topOption) return 'block';
+  if (topOption.rejected) return 'block';
+  if (topOption.option_id === 'observe_only') return 'observe_only';
+  return 'allow';
+}
+
+function buildRecoveryDirective(compilation, topOption, decision) {
+  const actionClass = compilation?.classification?.action_class || 'unknown';
+  if (decision === 'allow') {
+    return `Allowed. Top option=${topOption.option_id} autonomy=${topOption.autonomy_level}. Predicate: ${topOption.verification_predicate}`;
+  }
+  // force_reauthor for output-emit failure classes: surface the kernel's
+  // class-specific rejection reason (the workshop material the kernel
+  // emitted, not generic prose). The reason carries the doctrine-violation
+  // pattern + the exact shape of acceptable re-author.
+  if (decision === 'force_reauthor' && OUTPUT_EMIT_FAILURE_CLASSES.includes(actionClass)) {
+    const rejectedOptions = (compilation?.options || []).filter((o) => o.rejected);
+    const primaryReason = rejectedOptions[0]?.rejection_reasons?.[0]
+      || `Output classified as ${actionClass}; re-author required.`;
+    return `Re-author required (${actionClass}): ${primaryReason}`;
+  }
+  if (decision === 'observe_only') {
+    return `Observe-only mode. Preserve evidence; surface to operator before any state-changing action. Predicate: ${topOption.verification_predicate}`;
+  }
+  if (decision === 'force_reauthor') {
+    return 'Re-author required: cognition did not change the artifact. Either engage substrate (anchor lenses to loaded memory + axioms) or refuse to claim a state-change.';
+  }
+  // block
+  if (topOption && Array.isArray(topOption.rejection_reasons) && topOption.rejection_reasons.length > 0) {
+    return `Blocked: ${topOption.rejection_reasons[0]}`;
+  }
+  return 'Blocked: no acceptable option remained after kernel evaluation.';
+}
+
+// Re-export the kernel primitives so callers can use them without a second import.
+export { compileCognitiveOptions } from './kernel/deterministic-cognitive-kernel.mjs';
+export { TADABBUR_STAGES, QIYAS_PERSPECTIVES, stableHash, OUTPUT_EMIT_FAILURE_CLASSES } from './kernel/deterministic-cognitive-kernel.mjs';