@aria_asi/cli 0.2.40 → 0.2.41

package/hooks/lib/probe-discipline-scanner.mjs

@@ -0,0 +1,142 @@
+/**
+ * probe-discipline-scanner.mjs — no-timeouts doctrine enforcement at the
+ * pre-tool-gate Bash surface. Doctrine: feedback_no_timeouts_doctrine.md
+ * + no_timeouts_decision_tree_rule (aria-hardening-worker/src/watcher.ts:6).
+ * Deadline-based escape from retry loops forbidden; use bounded retry by
+ * error count + LOUD failure surfaces.
+ *
+ * Scanned: shell-position `timeout N` wrapper (^timeout, | timeout, &&
+ * timeout, ; timeout, $( timeout). NOT scanned: tool-internal flags like
+ * curl --max-time, which are legitimate tool-bounded probes.
+ *
+ * Behavior: warn 1st-2nd occurrence in session, HARD-BLOCK at 3+ via
+ * ARIA_PROBE_DISCIPLINE_BYPASS=1 escape hatch. Both warn and block paths
+ * log to ~/.claude/aria-discoveries-<session>.jsonl so the hardening
+ * worker (F2) accumulates cross-session signal.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const HOME = homedir();
+const COUNTER_PATH = `${HOME}/.claude/.aria-probe-discipline-counter.jsonl`;
+const DISCOVERY_LEDGER_PREFIX = `${HOME}/.claude/aria-discoveries-`;
+const TIMEOUT_WRAPPER_RX = /(?:^|\||&&|;|\$\()\s*timeout\s+\d+(?:[smhd])?\b/g;
+const HARD_BLOCK_THRESHOLD = 3;
+const SESSION_RECENT_WINDOW_MS = 30 * 60 * 1000;
+
+export function scanProbeDiscipline(cmd, sessionId) {
+  const result = {
+    matched: false,
+    matchCount: 0,
+    sessionCount: 0,
+    blocked: false,
+    bypassed: false,
+    blockReason: null,
+    warned: false,
+  };
+  if (typeof cmd !== 'string' || cmd.length === 0) return result;
+  TIMEOUT_WRAPPER_RX.lastIndex = 0;
+  const matches = cmd.match(TIMEOUT_WRAPPER_RX) || [];
+  if (matches.length === 0) return result;
+
+  result.matched = true;
+  result.matchCount = matches.length;
+  const bypassed = /^(?:1|true|yes|on)$/i.test(String(process.env.ARIA_PROBE_DISCIPLINE_BYPASS || ''));
+  result.bypassed = bypassed;
+
+  const now = Date.now();
+  const ts = new Date(now).toISOString();
+  const entry = {
+    ts,
+    sessionId: String(sessionId || 'unknown'),
+    matches: matches.map((m) => m.trim()).slice(0, 5),
+    cmdPreview: cmd.slice(0, 120).replace(/\s+/g, ' '),
+    bypassed,
+  };
+  try {
+    if (!existsSync(dirname(COUNTER_PATH))) mkdirSync(dirname(COUNTER_PATH), { recursive: true });
+    appendFileSync(COUNTER_PATH, JSON.stringify(entry) + '\n');
+  } catch (err) {
+    process.stderr.write(`[probe-discipline:counter-write] caught: ${err?.message || err}\n`);
+  }
+
+  let sessionCount = 0;
+  try {
+    if (existsSync(COUNTER_PATH)) {
+      const raw = readFileSync(COUNTER_PATH, 'utf-8');
+      const cutoff = now - SESSION_RECENT_WINDOW_MS;
+      for (const line of raw.split('\n')) {
+        if (!line.trim()) continue;
+        let row;
+        try { row = JSON.parse(line); } catch { continue; }
+        if (row.sessionId !== entry.sessionId) continue;
+        const ms = new Date(row.ts).getTime();
+        if (!Number.isFinite(ms) || ms < cutoff) continue;
+        sessionCount++;
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`[probe-discipline:counter-read] caught: ${err?.message || err}\n`);
+    sessionCount = 1;
+  }
+  result.sessionCount = sessionCount;
+
+  const discoveryPath = `${DISCOVERY_LEDGER_PREFIX}${String(sessionId || 'unknown').replace(/[^a-zA-Z0-9_-]/g, '_')}.jsonl`;
+  const discoveryRow = {
+    ts,
+    kind: 'probe_discipline_violation',
+    resolution_status: 'open',
+    pattern: 'shell_timeout_wrapper',
+    sessionCount,
+    bypassed,
+    cmdPreview: entry.cmdPreview,
+    doctrine: 'feedback_no_timeouts_doctrine.md / no_timeouts_decision_tree_rule',
+    counterAction: 'bounded retry by error count + LOUD failure; never deadline-based escape',
+  };
+  try {
+    if (!existsSync(dirname(discoveryPath))) mkdirSync(dirname(discoveryPath), { recursive: true });
+    appendFileSync(discoveryPath, JSON.stringify(discoveryRow) + '\n');
+  } catch (err) {
+    process.stderr.write(`[probe-discipline:ledger-write] caught: ${err?.message || err}\n`);
+  }
+
+  if (bypassed) {
+    process.stderr.write(
+      `[probe-discipline:BYPASS-APPLIED] cmd-match=${matches[0]} sessionCount=${sessionCount} ARIA_PROBE_DISCIPLINE_BYPASS=1 — allowing this turn; bypass logged to ledger\n`,
+    );
+    result.warned = true;
+    return result;
+  }
+
+  if (sessionCount >= HARD_BLOCK_THRESHOLD) {
+    result.blocked = true;
+    result.blockReason = `Aria pre-tool gate: PROBE-DISCIPLINE hard-block.
+
+The command contains a shell-position 'timeout N' wrapper (matched: ${matches.slice(0, 3).join(', ')}).
+This is the ${sessionCount}-th such invocation in this session within the last 30 minutes.
+
+Doctrine 'no_timeouts_decision_tree_rule' (feedback_no_timeouts_doctrine.md): deadline-based escape from a retry loop is forbidden. Use bounded retry by error count + LOUD failure surfaces + explicit recovery, never an opaque deadline.
+
+Legitimate alternatives:
+  - curl --max-time N ...        (tool-bounded probe, NOT shell wrapper)
+  - fs.watchFile(...)            (OS-level polling, no deadline)
+  - bounded retry-by-error-count (per Recovery Contract)
+
+To bypass for an explicitly authorized probe: ARIA_PROBE_DISCIPLINE_BYPASS=1 <your-command>
+(Bypass usage is logged to the discovery ledger; operator gets full audit trail.)
+
+Next action: rewrite the command using a legitimate alternative OR set the bypass env var explicitly.`;
+    process.stderr.write(
+      `[probe-discipline:HARD-BLOCK] sessionCount=${sessionCount}/${HARD_BLOCK_THRESHOLD} matches=${matches.join(',')}\n`,
+    );
+    return result;
+  }
+
+  result.warned = true;
+  process.stderr.write(
+    `[probe-discipline:WARN] shell-position timeout wrapper detected (sessionCount=${sessionCount}/${HARD_BLOCK_THRESHOLD}) matches=${matches.slice(0, 3).join(',')} — doctrine: no_timeouts_decision_tree_rule. Hard-block at ${HARD_BLOCK_THRESHOLD}+. Bypass: ARIA_PROBE_DISCIPLINE_BYPASS=1\n`,
+  );
+  return result;
+}

package/hooks/lib/project-boundary-cognition.mjs

@@ -0,0 +1,143 @@
+const PROJECT_WORK_RX = /\b(?:project|phase|implement|wire|upgrade|fix|repair|continue|finish|execute|end[-\s]?to[-\s]?end|qa|test|verify|ledger|connector|terminal|runtime|hook|skill|autofire|atlas|repo|codebase|first[-\s]?class|symptom\s+fix|doctrine|harness)\b/i;
+const COMPLETION_CLAIM_RX = /\b(?:done|complete|completed|ready|verified|fixed|finished|shipped|implemented|wired|first[-\s]?class|end[-\s]?to[-\s]?end)\b/i;
+const OWNER_CORRECTION_RX = /\b(?:you(?:\s+are|'re| were)?\s+right|u\s+r\s+right|i\s+am\s+right|another\s+failure|that'?s\s+(?:a\s+)?failure|ledger\s+failur\w*|symptom\s+fix|not\s+(?:a\s+)?first[-\s]?class|why\s+(?:not|haven'?t|didn'?t)|self[-\s]?audit|auto[-\s]?trigg\w*|fire\s+(?:the\s+)?skills?|fix\s+what\s+u?\s*found|corrected[\s\S]{0,40}\b\d+(?:k|\+)?\s+times)\b/i;
+const ASSISTANT_CORRECTION_ACK_RX = /\b(?:you(?:\s+are|'re| were)?\s+right|i\s+should\s+have|i\s+missed|i\s+was\s+wrong|that\s+was\s+(?:a\s+)?miss|i\s+failed\s+to)\b/i;
+
+export const PROJECT_START_TADABBUR_QUESTIONS = Object.freeze([
+  'What is the exact project object under reflection, not the surface request?',
+  'Which owner, doctrine, runtime, repo, and no-harm constraints bind the first action?',
+  'What evidence is missing before action, and what source will be checked first?',
+  'What repeated correction or hidden mechanism failure could recur if not handled now?',
+  'What observable predicate will prove the start action and final closeout succeeded?',
+]);
+
+// Aligned 1:1 to atlas kernel QIYAS_PERSPECTIVES (deterministic-cognitive-kernel.mjs:18)
+// for consistency across all project-boundary + end-phase QA receipts. 2026-05-17 F2.
+export const PROJECT_END_QIYAS_PERSPECTIVES = 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',
+]);
+
+export function detectProjectBoundaryNeed(userText = '', assistantText = '') {
+  const user = String(userText || '');
+  const assistant = String(assistantText || '');
+  const projectLike = PROJECT_WORK_RX.test(user) || user.length >= 180;
+  const completionClaim = COMPLETION_CLAIM_RX.test(assistant);
+  const ownerCorrection = OWNER_CORRECTION_RX.test(user) || ASSISTANT_CORRECTION_ACK_RX.test(assistant);
+  return {
+    required: projectLike || completionClaim || ownerCorrection,
+    projectLike,
+    completionClaim,
+    ownerCorrection,
+  };
+}
+
+export function buildProjectStartBoundary({
+  userText = '',
+  cognitiveRuntimeReceipts = null,
+  source = 'project-start-boundary',
+} = {}) {
+  const need = detectProjectBoundaryNeed(userText);
+  const tadabbur = cognitiveRuntimeReceipts?.tadabbur || {};
+  const qiyas = cognitiveRuntimeReceipts?.qiyas || {};
+  const tadabburOk = tadabbur.ok === true && tadabbur.stageCount === 12;
+  return {
+    schema: 'aria.project_boundary_cognition.v1',
+    phase: 'project_start',
+    source,
+    required: need.required,
+    ok: !need.required || tadabburOk,
+    trigger: need,
+    startTadabbur: {
+      required: need.required,
+      ok: !need.required || tadabburOk,
+      expectedStages: 12,
+      observedStages: Number(tadabbur.stageCount || 0),
+      mode: tadabbur.mode || null,
+      questions: [...PROJECT_START_TADABBUR_QUESTIONS],
+    },
+    endQiyasContract: {
+      requiredAtClose: need.required,
+      expectedPerspectives: PROJECT_END_QIYAS_PERSPECTIVES.length,
+      preloadedPerspectives: Number(qiyas.perspectiveCount || 0),
+      status: need.required ? 'pending_phase_close' : 'not_required',
+    },
+  };
+}
+
+export function evaluateProjectEndBoundary({
+  userText = '',
+  assistantText = '',
+  endPhaseQaAutofire = null,
+  source = 'project-end-boundary',
+} = {}) {
+  const need = detectProjectBoundaryNeed(userText, assistantText);
+  const receipt = endPhaseQaAutofire?.receipt || endPhaseQaAutofire || {};
+  const qiyasPass = Array.isArray(receipt.qiyas_15_pass) && receipt.qiyas_15_pass.length === PROJECT_END_QIYAS_PERSPECTIVES.length;
+  const qiyasPerspectiveCount = Number(receipt.cognitive_qiyas_15?.perspectives || 0);
+  const tadabburStageCount = Number(receipt.cognitive_tadabbur_12?.stages || 0);
+  const claimVerdict = receipt.claim_gate?.verdict || null;
+  const claimOk = !claimVerdict || ['verified', 'verified_narrowly'].includes(claimVerdict);
+  const missing = [];
+  if (need.required && qiyasPerspectiveCount !== PROJECT_END_QIYAS_PERSPECTIVES.length) missing.push('qiyas_15_perspective_count');
+  if (need.required && !qiyasPass) missing.push('qiyas_15_pass_entries');
+  if (need.required && tadabburStageCount !== 12) missing.push('tadabbur_12_closeout_count');
+  if (need.required && !claimOk) missing.push('claim_gate_verified_or_narrowly_verified');
+  return {
+    schema: 'aria.project_boundary_cognition.v1',
+    phase: 'project_end',
+    source,
+    required: need.required,
+    ok: !need.required || missing.length === 0,
+    trigger: need,
+    endQiyas: {
+      required: need.required,
+      ok: !need.required || (qiyasPerspectiveCount === PROJECT_END_QIYAS_PERSPECTIVES.length && qiyasPass),
+      expectedPerspectives: PROJECT_END_QIYAS_PERSPECTIVES.length,
+      observedPerspectives: qiyasPerspectiveCount,
+      passEntries: Array.isArray(receipt.qiyas_15_pass) ? receipt.qiyas_15_pass.length : 0,
+    },
+    closeoutTadabbur: {
+      expectedStages: 12,
+      observedStages: tadabburStageCount,
+    },
+    claimGate: {
+      verdict: claimVerdict,
+      ok: claimOk,
+    },
+    missing,
+  };
+}
+
+export function formatProjectBoundaryPrompt(boundary) {
+  if (!boundary?.required) return 'Project boundary: not required for this turn.';
+  return [
+    'Project boundary: start Tadabbur-12 is required before action; end Qiyas-15 is required before closeout.',
+    `Start Tadabbur: ${boundary.startTadabbur?.ok ? 'pass' : 'missing'} (${boundary.startTadabbur?.observedStages || 0}/${boundary.startTadabbur?.expectedStages || 12})`,
+    'Automatic start questions:',
+    ...PROJECT_START_TADABBUR_QUESTIONS.map((question, index) => `${index + 1}. ${question}`),
+    `End Qiyas pending: ${boundary.endQiyasContract?.expectedPerspectives || 15} perspectives at phase close.`,
+  ].join('\n');
+}
+
+export function formatProjectBoundaryBlock(boundary) {
+  return [
+    'Project boundary cognition failed before release.',
+    `phase: ${boundary?.phase || 'unknown'}`,
+    `missing: ${(boundary?.missing || []).join(', ') || 'project_start_tadabbur_12'}`,
+    'required repair: run Tadabbur-12 at project start and Qiyas-15 at phase close, then re-check the claim gate from evidence.',
+  ].join('\n');
+}

package/hooks/lib/recovery-context.mjs

@@ -0,0 +1,151 @@
+// Recovery context loader (M1.2 — Bug B fix).
+//
+// Doctrine bind:
+//   - feedback_no_graceful_degradation.md — recovery contracts written to disk by
+//     stop-gate / cognition-substrate-binding MUST be delivered to the next-turn
+//     model. Writing to disk and never reading is graceful degradation.
+//   - aria-repo-doctrine — real implementation; archive on pickup so the contract
+//     doesn't re-fire indefinitely.
+//
+// Lifted from packages/aria-connector/opencode-plugins/harness-context/inject-context.mjs:90
+// to make the same delivery channel available to the Claude Code surface (was missing,
+// see audit ledger Layer 4 / Bug B).
+//
+// Used by:
+//   - ops/claude-hooks/aria-harness-via-sdk.mjs (SessionStart + UserPromptSubmit)
+//   - packages/aria-connector/hooks/aria-harness-via-sdk.mjs (mirror)
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const HOME = homedir();
+const RECOVERY_PATH = join(HOME, '.aria', 'governance-recovery-current.json');
+const ARCHIVE_DIR = join(HOME, '.aria', 'governance-recovery-archive');
+
+// M0.H.X9 (2026-05-06) — Phase 0 audit Cluster H finding M0.H.19:
+// recovery contracts now schema-versioned. Writers (aria-stop-gate +
+// aria-cognition-substrate-binding) emit `schema: 'aria.governance_
+// recovery_current.v1'`. This reader checks the schema field on read
+// and surfaces version mismatch via stderr — operator sees if a
+// contract was written by an out-of-date writer (e.g., a stale
+// connector hooks installation) before consuming.
+//
+// M0.SELFREVIEW.11 (2026-05-06) — fail-CLOSED on unsupported schema.
+// Previous behavior was consume-with-warn for missing/unknown schema;
+// a malformed or spoofed recovery contract could feed misleading state
+// to the model. Now: missing schema OR unsupported schema = reject,
+// quarantine the contract, return empty block. Operator gets a stderr
+// message naming the schema actually seen vs supported. The quarantine
+// dir prevents the same bad contract from re-firing every turn.
+const SUPPORTED_RECOVERY_SCHEMAS = Object.freeze([
+  'aria.governance_recovery_current.v1',
+]);
+const QUARANTINE_DIR = join(HOME, '.aria', 'governance-recovery-quarantine');
+
+/**
+ * Read the current governance recovery contract (if any) and format it as
+ * a system-prompt block for injection into the next turn's additionalContext.
+ *
+ * Returns empty string when no recovery is pending or the file is malformed —
+ * malformed/parse errors are surfaced via stderr (no silent swallow per
+ * feedback_no_graceful_degradation.md).
+ *
+ * @returns {{ block: string, pickupId: string | null }} block text + pickup
+ *   identifier. The pickup id is the recovery fingerprint; pass it to
+ *   archiveRecoveryAfterPickup() once delivered to the model.
+ */
+export function readGovernanceRecoveryContext() {
+  if (!existsSync(RECOVERY_PATH)) return { block: '', pickupId: null };
+  let recovery;
+  try {
+    recovery = JSON.parse(readFileSync(RECOVERY_PATH, 'utf8'));
+  } catch (error) {
+    process.stderr.write(`[recovery-context] malformed recovery file ignored (${error.message})\n`);
+    return { block: '', pickupId: null };
+  }
+  // M0.SELFREVIEW.11 (2026-05-06): schema-version check now fail-CLOSED.
+  // Missing schema field OR unsupported schema = reject the contract +
+  // quarantine the file (so it doesn't re-fire each turn) + return empty.
+  // This is the defensive direction on safety contracts: a malformed or
+  // spoofed contract should NOT shape model state. Operator sees the
+  // quarantine + stderr line; if they intentionally want to restore the
+  // contract, they can move it back from the quarantine dir manually.
+  const schema = String(recovery.schema || '').trim();
+  if (!schema || !SUPPORTED_RECOVERY_SCHEMAS.includes(schema)) {
+    const reason = !schema
+      ? 'no schema field'
+      : `unsupported schema: ${schema} (supported: ${SUPPORTED_RECOVERY_SCHEMAS.join(', ')})`;
+    process.stderr.write(`[recovery-context] recovery contract REJECTED — ${reason} (M0.SELFREVIEW.11 fail-CLOSED); quarantining\n`);
+    try {
+      if (!existsSync(QUARANTINE_DIR)) {
+        mkdirSync(QUARANTINE_DIR, { recursive: true, mode: 0o700 });
+      }
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      renameSync(RECOVERY_PATH, join(QUARANTINE_DIR, `recovery-rejected-${ts}.json`));
+    } catch (err) {
+      process.stderr.write(`[recovery-context:quarantine] caught: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return { block: '', pickupId: null };
+  }
+  const mode = String(recovery.governanceMode || '').trim();
+  if (!mode || mode === 'allow') return { block: '', pickupId: null };
+
+  const loop = recovery.recoveryLoop && typeof recovery.recoveryLoop === 'object' ? recovery.recoveryLoop : {};
+  const contract = recovery.recoveryContract && typeof recovery.recoveryContract === 'object' ? recovery.recoveryContract : {};
+  const fingerprint = loop.fingerprint || null;
+
+  const block = [
+    '--- CURRENT GOVERNANCE RECOVERY CONTEXT ---',
+    `Mode: ${mode}`,
+    `Decision: ${recovery.decision || 'block'}`,
+    `Fingerprint: ${fingerprint || 'unknown'}`,
+    `Allowed recovery attempts: ${loop.allowedRecoveryAttempts ?? 1}`,
+    `Prior recovery attempts: ${loop.priorRecoveryAttempts ?? 0}`,
+    `Remaining recovery attempts: ${loop.remainingRecoveryAttempts ?? 0}`,
+    `Next step: ${loop.nextStep || 'execute recovery contract before claiming completion'}`,
+    `Architect fallback: ${loop.architectFallback || contract.fallbackWhenAriaUnavailable || 'if Aria consult is unavailable, use the strongest available client LLM under the architect harness'}`,
+    `Load skills first: ${(contract.loadSkillsFirst || []).join(', ') || '(none)'}`,
+    `Repair recovery cycle: ${(contract.repairRecoveryCycle || []).join(', ') || '(none)'}`,
+    `Retest: ${contract.retest || 'run the concrete verification probe'}`,
+    'Mandatory behavior: this is system-prompt recovery state; execute it before final output.',
+  ].join('\n');
+
+  return { block, pickupId: fingerprint };
+}
+
+/**
+ * Move the current recovery file to the archive directory after the contract
+ * has been delivered to the model. Prevents the same recovery contract from
+ * re-firing on every subsequent turn forever.
+ *
+ * Per feedback_no_graceful_degradation.md, archive errors are surfaced via
+ * stderr (never silent). The recovery file is left in place if archiving
+ * fails — it WILL re-fire next turn, which is the correct conservative
+ * behavior (the contract hasn't been actually consumed if archiving failed).
+ *
+ * @param {string | null} pickupId  the fingerprint returned by
+ *   readGovernanceRecoveryContext(). If null/empty, this is a no-op.
+ */
+export function archiveRecoveryAfterPickup(pickupId) {
+  if (!pickupId) return;
+  if (!existsSync(RECOVERY_PATH)) return;
+
+  try {
+    if (!existsSync(ARCHIVE_DIR)) {
+      mkdirSync(ARCHIVE_DIR, { recursive: true, mode: 0o700 });
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const archivePath = join(ARCHIVE_DIR, `recovery-${ts}-${pickupId.slice(0, 12)}.json`);
+    renameSync(RECOVERY_PATH, archivePath);
+  } catch (error) {
+    process.stderr.write(`[recovery-context] archive failed (${error.message}) — recovery will re-fire next turn (conservative)\n`);
+  }
+}
+
+/**
+ * Path to the live recovery file. Exported for callers that want to inspect
+ * it directly (e.g. coach kernel reading recovery state for pre_turn phase).
+ */
+export const RECOVERY_FILE_PATH = RECOVERY_PATH;
+export const RECOVERY_ARCHIVE_DIR = ARCHIVE_DIR;

package/hooks/lib/recovery-template-loader.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// ── doctrine-self-check-file: M0.SELFREVIEW.1+2 (2026-05-06) ──
+// Session added comments describing prior antipatterns being migrated.
+// Each comment names a trigger pattern; file-level ack covers them all.
+// doctrine-self-check-file: (?:based on|from|by) (?:the )?(?:name|function name)|sounds like|looks like (?:a|an)|just memory search|just a search|just a cache|just a wrapper session-added-comments-describing-prior-state-or-migration
+
+/**
+ * recovery-template-loader.mjs — hot-reloading recovery prose templates.
+ *
+ * Phase 0 audit Tier D Meta-X5: extracts hardcoded teaching/recovery
+ * strings from hook source code into editable .md template files.
+ * Operator edits to the template files take effect on next hook
+ * invocation (mtime-based reload) — no redeploy / npm publish / client
+ * reinstall required.
+ *
+ * Closes:
+ *   - M0.H.16   buildForceReauthorReason 70-line template baked in source
+ *   - M0.H.X11  config-driven recovery messages
+ *   - M0.G.X4   (partial) retire hardcoded fallback voice builders —
+ *               applies the same pattern to stop-gate templates first;
+ *               voice-side fallback prose retires in M0.G.X4 follow-up.
+ *
+ * Templating: simple {{variable}} substitution. NOT a full mustache
+ * implementation — just literal string replace. Comments rendered with
+ * {{!-- ... --}} are stripped before output.
+ *
+ * Doctrine bind:
+ *   - clean_cognition (single helper for one concern)
+ *   - feedback_no_flag_without_fix.md (closes the "buildForceReauthorReason
+ *     baked in source" flag with a hot-reloadable fix)
+ *
+ * Mirror: this file MUST be byte-identical between
+ *   ops/claude-hooks/lib/recovery-template-loader.mjs
+ *   packages/aria-connector/hooks/lib/recovery-template-loader.mjs
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Templates live one directory up, in `recovery-templates/`.
+const TEMPLATES_DIR = resolve(HERE, '..', 'recovery-templates');
+
+// Cache: { name → { content, mtimeMs } }. Re-read when mtime changes.
+const _cache = new Map();
+
+/**
+ * Load a template by name (without extension). Hot-reloads when the
+ * file's mtime changes since last read.
+ *
+ * @param {string} name  e.g., 'force-reauthor', 'handoff-recovery'
+ * @returns {string} template content (with comments stripped); empty
+ *   string if template missing (caller should handle).
+ */
+export function loadTemplate(name) {
+  const path = join(TEMPLATES_DIR, `${name}.md`);
+  if (!existsSync(path)) {
+    process.stderr.write(`[recovery-template-loader] template missing: ${path}\n`);
+    return '';
+  }
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch (err) {
+    process.stderr.write(`[recovery-template-loader:stat] caught: ${err instanceof Error ? err.message : String(err)}\n`);
+    return '';
+  }
+  const cached = _cache.get(name);
+  if (cached && cached.mtimeMs === stat.mtimeMs) return cached.content;
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[recovery-template-loader:read] caught: ${err instanceof Error ? err.message : String(err)}\n`);
+    return '';
+  }
+  // Strip {{!-- ... --}} comment blocks (mustache-style block comments).
+  const stripped = raw.replace(/\{\{!--[\s\S]*?--\}\}\s*/g, '');
+  _cache.set(name, { content: stripped, mtimeMs: stat.mtimeMs });
+  return stripped;
+}
+
+/**
+ * Render a template with variable substitution.
+ *
+ * @param {string} name  template name
+ * @param {Object} vars  { varName: value } — values coerced to string
+ * @returns {string} rendered template, or empty string if template missing
+ */
+export function renderTemplate(name, vars = {}) {
+  let body = loadTemplate(name);
+  if (!body) return '';
+  for (const [k, v] of Object.entries(vars)) {
+    const value = v === null || v === undefined ? '' : String(v);
+    // Escape regex meta in key (keys are normally [a-z_] but defensive).
+    const re = new RegExp(`\\{\\{${k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\}\\}`, 'g');
+    body = body.replace(re, value);
+  }
+  // Strip any remaining {{...}} placeholders (variables not provided)
+  // so the output doesn't contain mustache leakage. Operator-side
+  // tip: any unsubstituted variable reaches stderr at debug level.
+  const remaining = body.match(/\{\{[a-z_][a-z0-9_]*\}\}/gi);
+  if (remaining && remaining.length > 0) {
+    process.stderr.write(`[recovery-template-loader:${name}] unsubstituted variables: ${remaining.join(', ')}\n`);
+    body = body.replace(/\{\{[a-z_][a-z0-9_]*\}\}/gi, '');
+  }
+  return body.trim();
+}
+
+/**
+ * Required-template variant — throws if missing. Use for highest-stakes
+ * recovery prose where a missing template should fail-CLOSED rather
+ * than fall back to a weaker hardcoded string.
+ *
+ * M0.SELFREVIEW.10 — when `force-reauthor.md` (or other safety-critical
+ * templates) goes missing, the prior best-effort fallback returned a
+ * minimal placeholder that gave the model a weaker recovery contract
+ * than the real template. An attacker who deletes the template would
+ * silently weaken the gate. This variant fails-CLOSED so the caller
+ * can emit a clear "template missing" block instead.
+ *
+ * @param {string} name
+ * @returns {string} template body (non-empty, comments stripped)
+ * @throws {Error} when template file missing or unreadable
+ */
+export function loadTemplateRequired(name) {
+  const body = loadTemplate(name);
+  if (!body) {
+    throw new Error(`recovery-template-loader: required template missing: ${name} (M0.SELFREVIEW.10 fail-CLOSED)`);
+  }
+  return body;
+}
+
+/**
+ * Render a required template with variable substitution. Throws if
+ * template missing OR if any variable left unsubstituted (the strict
+ * variant — operator-tier templates should not contain unbound vars).
+ */
+export function renderTemplateRequired(name, vars = {}) {
+  let body = loadTemplateRequired(name);
+  for (const [k, v] of Object.entries(vars)) {
+    const value = v === null || v === undefined ? '' : String(v);
+    const re = new RegExp(`\\{\\{${k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\}\\}`, 'g');
+    body = body.replace(re, value);
+  }
+  const remaining = body.match(/\{\{[a-z_][a-z0-9_]*\}\}/gi);
+  if (remaining && remaining.length > 0) {
+    throw new Error(`recovery-template-loader: required template ${name} has unsubstituted variables: ${remaining.join(', ')}`);
+  }
+  return body.trim();
+}
+
+export default { loadTemplate, renderTemplate, loadTemplateRequired, renderTemplateRequired };