@aria_asi/cli 0.2.40 → 0.2.41

package/hooks/lib/action-ledger-core.mjs

@@ -0,0 +1,269 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+function defaultHome() {
+  return process.env.ARIA_HOME || process.env.HOME || homedir();
+}
+
+function safeSegment(value) {
+  return String(value || 'global')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'global';
+}
+
+function stableJson(value) {
+  const seen = new WeakSet();
+  const normalize = (input) => {
+    if (!input || typeof input !== 'object') return input;
+    if (seen.has(input)) return '[Circular]';
+    seen.add(input);
+    if (Array.isArray(input)) return input.map((entry) => normalize(entry));
+    return Object.fromEntries(
+      Object.entries(input)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entry]) => [key, normalize(entry)]),
+    );
+  };
+  return JSON.stringify(normalize(value));
+}
+
+export function actionLedgerSha256(value) {
+  return createHash('sha256')
+    .update(typeof value === 'string' ? value : stableJson(value))
+    .digest('hex');
+}
+
+export function actionLedgerPaths({ home = defaultHome(), projectId = 'global' } = {}) {
+  const root = path.join(home, '.aria', 'action-ledger', safeSegment(projectId));
+  return {
+    root,
+    eventsPath: path.join(root, 'events.jsonl'),
+    projectionPath: path.join(root, 'projection.json'),
+    publishOutboxPath: path.join(root, 'publish-outbox.jsonl'),
+  };
+}
+
+function uniqueBy(items, keyFn) {
+  const seen = new Set();
+  const out = [];
+  for (const item of Array.isArray(items) ? items : []) {
+    const key = keyFn(item);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function taskStatusFromEvent(event) {
+  if (event.status === 'blocked' || event.status === 'failed' || event.status === 'needs_owner') return event.status;
+  if (event.lifecyclePhase === 'task_complete' || event.status === 'completed' || event.status === 'verified') return 'completed';
+  return 'active';
+}
+
+export function readActionLedgerEvents({ home = defaultHome(), projectId = 'global', sessionId = null } = {}) {
+  const paths = actionLedgerPaths({ home, projectId });
+  if (!existsSync(paths.eventsPath)) return [];
+  return readFileSync(paths.eventsPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter(Boolean)
+    .filter((event) => !sessionId || event.sessionId === sessionId);
+}
+
+export function projectActionLedger(events = []) {
+  const tasks = {};
+  const sessions = {};
+  let latestQa = null;
+  let latestLearningDelta = null;
+  let latestAtlas = null;
+  let correctionRequired = false;
+  const sentinelFindings = [];
+  const sorted = [...events].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+  for (const event of sorted) {
+    sessions[event.sessionId] = {
+      sessionId: event.sessionId,
+      threadId: event.threadId,
+      surface: event.surface,
+      latestEventId: event.eventId,
+      latestPhase: event.lifecyclePhase,
+      latestStatus: event.status,
+      updatedAt: event.createdAt,
+    };
+    if (event.qaReceipt) {
+      latestQa = event.qaReceipt;
+      if (event.qaReceipt.ok === false || event.qaReceipt.passed === false || event.qaReceipt.decision === 'repair') {
+        correctionRequired = true;
+      }
+    }
+    if (event.correctionPlan?.required === true) correctionRequired = true;
+    if (event.learningDelta) latestLearningDelta = event.learningDelta;
+    if (event.atlas) latestAtlas = event.atlas;
+    if (Array.isArray(event.sentinelFindings)) sentinelFindings.push(...event.sentinelFindings);
+    if (!event.taskId) continue;
+    const prior = tasks[event.taskId] || {
+      taskId: event.taskId,
+      projectId: event.projectId,
+      threadId: event.threadId,
+      status: 'active',
+      activePhase: null,
+      phases: {},
+      fileClaims: [],
+      evidenceRefs: [],
+      latestEventId: null,
+      latestQa: null,
+      latestLearningDelta: null,
+      latestAtlas: null,
+      sentinelFindingCount: 0,
+      updatedAt: null,
+    };
+    const phases = prior.phases && typeof prior.phases === 'object' ? prior.phases : {};
+    if (event.phaseId) {
+      phases[event.phaseId] = {
+        phaseId: event.phaseId,
+        status: event.status,
+        latestLifecyclePhase: event.lifecyclePhase,
+        latestEventId: event.eventId,
+        updatedAt: event.createdAt,
+      };
+    }
+    tasks[event.taskId] = {
+      ...prior,
+      status: taskStatusFromEvent(event),
+      activePhase: event.phaseId || prior.activePhase,
+      phases,
+      fileClaims: uniqueBy([...(Array.isArray(prior.fileClaims) ? prior.fileClaims : []), ...(event.fileClaims || [])], (claim) => claim.path).slice(-100),
+      evidenceRefs: [...(Array.isArray(prior.evidenceRefs) ? prior.evidenceRefs : []), ...(event.evidenceRefs || [])].slice(-100),
+      latestEventId: event.eventId,
+      latestQa: event.qaReceipt || prior.latestQa || null,
+      latestLearningDelta: event.learningDelta || prior.latestLearningDelta || null,
+      latestAtlas: event.atlas || prior.latestAtlas || null,
+      sentinelFindingCount: Number(prior.sentinelFindingCount || 0) + (Array.isArray(event.sentinelFindings) ? event.sentinelFindings.length : 0),
+      correctionRequired,
+      updatedAt: event.createdAt,
+    };
+  }
+  const latest = sorted[sorted.length - 1] || null;
+  return {
+    schema: 'aria.action_ledger_projection.v1',
+    generatedAt: new Date().toISOString(),
+    eventCount: sorted.length,
+    latestEvent: latest ? {
+      eventId: latest.eventId,
+      actionId: latest.actionId,
+      surface: latest.surface,
+      lifecyclePhase: latest.lifecyclePhase,
+      status: latest.status,
+      createdAt: latest.createdAt,
+    } : null,
+    tasks,
+    sessions,
+    correctionRequired,
+    latestQa,
+    latestLearningDelta,
+    latestAtlas,
+    sentinelFindings: uniqueBy(sentinelFindings, (finding) => String(finding.id || `${finding.source}:${finding.kind}:${finding.target}`)).slice(-50),
+  };
+}
+
+export function buildActionEvent(input = {}) {
+  const createdAt = input.createdAt || new Date().toISOString();
+  const actionId = input.actionId || `act_${randomUUID()}`;
+  const base = {
+    schema: 'aria.action_event.v1',
+    eventId: '',
+    actionId,
+    parentActionId: input.parentActionId || null,
+    sessionId: input.sessionId || 'unknown',
+    threadId: input.threadId || null,
+    surface: input.surface || 'claude-code',
+    projectId: input.projectId || null,
+    taskId: input.taskId || null,
+    phaseId: input.phaseId || null,
+    lifecyclePhase: input.lifecyclePhase || 'turn',
+    status: input.status || 'active',
+    cwd: input.cwd || null,
+    intent: input.intent || null,
+    toolName: input.toolName || null,
+    fileClaims: uniqueBy(input.fileClaims || [], (claim) => claim.path),
+    evidenceRefs: Array.isArray(input.evidenceRefs) ? input.evidenceRefs : [],
+    skillReceipt: input.skillReceipt && typeof input.skillReceipt === 'object' && !Array.isArray(input.skillReceipt) ? input.skillReceipt : null,
+    runtimeReceipt: input.runtimeReceipt && typeof input.runtimeReceipt === 'object' && !Array.isArray(input.runtimeReceipt) ? input.runtimeReceipt : null,
+    qaReceipt: input.qaReceipt && typeof input.qaReceipt === 'object' && !Array.isArray(input.qaReceipt) ? input.qaReceipt : null,
+    correctionPlan: input.correctionPlan && typeof input.correctionPlan === 'object' && !Array.isArray(input.correctionPlan) ? input.correctionPlan : null,
+    learningDelta: input.learningDelta && typeof input.learningDelta === 'object' && !Array.isArray(input.learningDelta) ? input.learningDelta : null,
+    atlas: input.atlas || null,
+    sentinelFindings: uniqueBy(input.sentinelFindings || [], (finding) => String(finding.id || `${finding.source}:${finding.kind}:${finding.target}`)),
+    metadata: input.metadata || {},
+    createdAt,
+  };
+  const eventHash = actionLedgerSha256(base);
+  return {
+    ...base,
+    eventId: `ev_${eventHash.slice(0, 24)}`,
+    eventHash,
+  };
+}
+
+export function recordActionEventLocal(input = {}, options = {}) {
+  const event = buildActionEvent(input);
+  const projectId = event.projectId || options.projectId || 'global';
+  const paths = actionLedgerPaths({ home: options.home || defaultHome(), projectId });
+  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  appendFileSync(paths.eventsPath, JSON.stringify(event) + '\n', { mode: 0o600 });
+  const projection = projectActionLedger(readActionLedgerEvents({ home: options.home || defaultHome(), projectId }));
+  writeFileSync(paths.projectionPath, JSON.stringify(projection, null, 2) + '\n', { mode: 0o600 });
+  return { ok: true, event, paths, projection };
+}
+
+export function queueActionEventPublishReplay(actionLedger = {}, options = {}) {
+  const event = actionLedger?.event;
+  if (!event) return { ok: false, skipped: true, reason: 'missing_action_event' };
+  const paths = actionLedger?.paths || actionLedgerPaths({
+    home: options.home || defaultHome(),
+    projectId: event.projectId || options.projectId || 'global',
+  });
+  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  const entry = {
+    schema: 'aria.action_event_publish_pending.v1',
+    at: new Date().toISOString(),
+    eventId: event.eventId,
+    eventHash: event.eventHash,
+    actionId: event.actionId,
+    projectId: event.projectId,
+    taskId: event.taskId,
+    phaseId: event.phaseId,
+    recovery: 'queued_for_action_event_publish_replay',
+    event,
+    metadata: {
+      source: options.source || `${event.surface}-hook-action-ledger`,
+    },
+  };
+  appendFileSync(paths.publishOutboxPath, JSON.stringify(entry) + '\n', { mode: 0o600 });
+  return { ok: true, paths, entry };
+}
+
+export function actionLedgerPhaseForHook(event) {
+  const name = String(event || '').toLowerCase();
+  if (name === 'userpromptsubmit') return 'pre_cognition';
+  if (name === 'pretooluse') return 'pre_tool';
+  if (name === 'posttooluse') return 'post_tool';
+  if (name === 'stop') return 'post_cognition';
+  if (name === 'precompact') return 'post_cognition';
+  return 'turn';
+}
+
+export function actionLedgerStatusForDecision(decision) {
+  const value = String(decision || '').toLowerCase();
+  if (value === 'block') return 'blocked';
+  if (value === 'warn') return 'repaired';
+  if (value === 'allow' || value === 'pass') return 'verified';
+  if (value === 'bypass') return 'active';
+  return 'active';
+}

package/hooks/lib/aria-gate-ledger.mjs

@@ -0,0 +1,143 @@
+// aria-gate-ledger.mjs — single observability ledger for every gate decision.
+//
+// 2026-05-08 Hamza directive: "make it where output is gold every time. for
+// you and me and every user." — gates were blocking emissions but the
+// reasons spread across multiple .log / .audit.jsonl files, and the agent
+// had to chase them per-hook. This ledger gives one append-only record so
+// every block + allow + recovery carries a single audit trail visible to
+// the orchestrator and Hamza.
+//
+// Schema per line (jsonl):
+//   ts:           ISO timestamp
+//   hook:         hook short name (pre-tool-gate, stop-gate, coach, etc.)
+//   event:        Claude Code hook event (PreToolUse, Stop, UserPromptSubmit, ...)
+//   tool:         tool name when relevant (Bash, Edit, Write, Skill, ...)
+//   decision:     allow | block | bypass | warn
+//   source:       sub-source within hook (e.g. pre-tool/missing-cognition,
+//                 pre-tool/discovery-binding, stop/skill-autoload, ...)
+//   reasonShort:  one-line reason summary (truncated to 200 chars)
+//   meta:         arbitrary structured context (lensCount, missingSkills, etc.)
+//   sessionId:    Claude session id when available
+//
+// Append is best-effort — ledger write failure must NEVER block the gate's
+// primary decision. We swallow write errors and surface to stderr for
+// operator visibility (per feedback_non_blocking_errors_unacceptable.md the
+// failure must be loud, but the gate must continue to make its decision).
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  actionLedgerPhaseForHook,
+  actionLedgerSha256,
+  actionLedgerStatusForDecision,
+  queueActionEventPublishReplay,
+  recordActionEventLocal,
+} from './action-ledger-core.mjs';
+
+const LEDGER_PATH = `${homedir()}/.claude/.aria-gate-ledger.jsonl`;
+
+let dirEnsured = false;
+function ensureDir() {
+  if (dirEnsured) return;
+  try {
+    mkdirSync(dirname(LEDGER_PATH), { recursive: true, mode: 0o700 });
+    dirEnsured = true;
+  } catch (err) {
+    process.stderr.write(`[aria-gate-ledger:mkdir] ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
+export function appendGateLedger({
+  hook = 'unknown',
+  event = process.env.HOOK_EVENT_NAME || null,
+  tool = null,
+  decision = 'unknown',
+  source = null,
+  reasonShort = null,
+  meta = null,
+  sessionId = process.env.HOOK_SESSION_ID || null,
+} = {}) {
+  ensureDir();
+  const entry = {
+    ts: new Date().toISOString(),
+    hook,
+    event,
+    tool,
+    decision,
+    source,
+    reasonShort: typeof reasonShort === 'string' ? reasonShort.slice(0, 200) : reasonShort,
+    meta: meta && typeof meta === 'object' ? meta : null,
+    sessionId,
+  };
+  try {
+    appendFileSync(LEDGER_PATH, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+  } catch (err) {
+    process.stderr.write(`[aria-gate-ledger:append] ${err instanceof Error ? err.message : String(err)} (entry preview: ${JSON.stringify({ hook, decision, source }).slice(0, 120)})\n`);
+  }
+  try {
+    const sessionId = entry.sessionId || 'claude-code-unknown';
+    const lifecyclePhase = actionLedgerPhaseForHook(event);
+    const projectId = process.env.ARIA_ACTION_LEDGER_PROJECT_ID || `claude-${actionLedgerSha256(sessionId).slice(0, 16)}`;
+    const taskId = process.env.ARIA_ACTION_LEDGER_TASK_ID || `claude-session-${actionLedgerSha256(`${sessionId}:${projectId}`).slice(0, 12)}`;
+    const actionLedger = recordActionEventLocal({
+      sessionId,
+      threadId: process.env.HOOK_THREAD_ID || null,
+      surface: 'claude-code',
+      projectId,
+      taskId,
+      phaseId: lifecyclePhase,
+      lifecyclePhase,
+      status: actionLedgerStatusForDecision(decision),
+      cwd: process.cwd(),
+      intent: reasonShort || `${hook} ${decision}`,
+      toolName: tool,
+      fileClaims: Array.isArray(meta?.fileClaims) ? meta.fileClaims : [],
+      evidenceRefs: [{
+        kind: 'claude_gate_ledger_entry',
+        sha256: actionLedgerSha256(entry),
+        preview: JSON.stringify({
+          hook: entry.hook,
+          event: entry.event,
+          decision: entry.decision,
+          source: entry.source,
+          reasonShort: entry.reasonShort,
+        }).slice(0, 500),
+        path: LEDGER_PATH,
+        at: entry.ts,
+        metadata: {
+          hook: entry.hook,
+          source: entry.source,
+          event: entry.event,
+        },
+      }],
+      qaReceipt: {
+        schema: 'aria.claude_gate_action_qa.v1',
+        hook: entry.hook,
+        event: entry.event,
+        decision: entry.decision,
+        source: entry.source,
+        passed: entry.decision !== 'block',
+      },
+      correctionPlan: {
+        required: entry.decision === 'block' || entry.decision === 'warn',
+        findings: entry.reasonShort ? [entry.reasonShort] : [],
+      },
+      learningDelta: {
+        style: 'dalio_reflexion',
+        lesson: 'Claude Code hook gate decisions must enter the shared action spine, not only the gate-specific ledger.',
+        nextAction: entry.decision === 'block'
+          ? 'Correct the gate finding, rerun the hook action, and compare the next action event.'
+          : 'Continue while preserving action-event projection for cross-surface QA.',
+      },
+      metadata: {
+        gateLedger: entry,
+      },
+    }, { projectId });
+    queueActionEventPublishReplay(actionLedger, { source: 'claude-gate-ledger' });
+  } catch (err) {
+    process.stderr.write(`[aria-gate-ledger:action-ledger] ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
+export const GATE_LEDGER_PATH = LEDGER_PATH;

package/hooks/lib/ast-stub-shape-detector.mjs

@@ -0,0 +1,107 @@
+// AST-shape stub detector — STRUCTURAL function-body shape detection.
+//
+// Replaces vocabulary regex (stub|mock|placeholder|will be wired) with
+// shape patterns matching the actual STRUCTURE of stub code:
+//   1. Empty function body:           function f(...) {}
+//   2. Throw-only body:                function f(...) { throw new Error(...) }
+//   3. Return-null-only body:          function f(...) { return null; }
+//   4. Return-undefined-only body:     function f(...) { return undefined; }
+//   5. Return-no-arg body:             function f(...) { return; }
+//   6. Comment-only body with pending: function f(...) { /* TODO ... */ }
+//   7. Arrow empty body:               (...) => {}
+//   8. Arrow throw-only body:          (...) => { throw new Error(...) }
+//
+// These match SHAPE, not vocabulary. A description in prose like "the
+// stub function" does not trip this detector. A variable named
+// `mockHandler` does not trip this detector. Only actual stub-shaped
+// function bodies do.
+//
+// Per Q15 of the 2026-05-17 Qiyas-15 — vocabulary detectors are
+// paraphrase-fragile; shape detectors are paraphrase-robust.
+
+// Match `function name(...)` or `name(...) {` or `name = (...) =>` or
+// `async function name(...)` etc., then capture the body between `{` and
+// the matching `}`. Limited to one-line bodies to keep the regex tractable
+// (multi-line stub bodies are caught by counting opens/closes; out of scope
+// for this conservative first pass).
+const FUNCTION_HEAD_RX = /(?:^|\n|;)\s*(?:export\s+)?(?:async\s+)?(?:function\s+\w+\s*\([^)]*\)|(?:const|let|var)\s+\w+\s*=\s*(?:async\s*)?\([^)]*\)\s*=>|\w+\s*[:=]\s*(?:async\s*)?(?:function\s*\([^)]*\)|\([^)]*\)\s*=>)|\w+\s*\([^)]*\)\s*\{)/g;
+
+// Body shapes (single-line, between balanced `{` `}`). Matched against the
+// body string AFTER extracting it from the function head.
+const SHAPE_PATTERNS = Object.freeze([
+  { id: 'ast_empty_body',           rx: /^\s*$/ },
+  { id: 'ast_throw_only_body',      rx: /^\s*throw\s+new\s+\w*Error\s*\([^)]*\)\s*;?\s*$/ },
+  { id: 'ast_return_null_body',     rx: /^\s*return\s+null\s*;?\s*$/ },
+  { id: 'ast_return_undefined_body',rx: /^\s*return\s+undefined\s*;?\s*$/ },
+  { id: 'ast_return_void_body',     rx: /^\s*return\s*;?\s*$/ },
+  // Comment-only body with a pending/TODO marker — body has comments and
+  // nothing else. The `TODO|FIXME|XXX|implement|pending` words inside a
+  // comment ARE shape evidence (the comment IS the body — there's no real
+  // implementation), not vocabulary used in prose.
+  { id: 'ast_comment_only_pending', rx: /^(?:\s*(?:\/\/[^\n]*|\/\*[\s\S]*?\*\/)\s*)+$/, requires: /TODO|FIXME|XXX|implement|pending/i },
+]);
+
+/**
+ * Extract function bodies from source text. Returns array of
+ * { body: string, headIndex: number, bodyStartIndex: number, bodyEndIndex: number }.
+ * Conservative: skips bodies containing nested `{` to avoid false positives
+ * on real implementations.
+ */
+function extractFunctionBodies(source) {
+  const out = [];
+  const headRx = new RegExp(FUNCTION_HEAD_RX.source, 'g');
+  let m;
+  while ((m = headRx.exec(source)) !== null) {
+    // Find the opening `{` after the head.
+    let i = m.index + m[0].length - 1;
+    while (i < source.length && source[i] !== '{') i++;
+    if (i >= source.length) continue;
+    const bodyStart = i + 1;
+    // Find the matching `}` by brace-counting, abort on nested `{` for
+    // conservatism (a nested brace means this is a real implementation,
+    // not a stub shape).
+    let depth = 1;
+    let j = bodyStart;
+    let nested = false;
+    while (j < source.length && depth > 0) {
+      const ch = source[j];
+      if (ch === '{') { depth++; nested = true; break; }
+      if (ch === '}') depth--;
+      j++;
+    }
+    if (nested || depth !== 0) continue;
+    const body = source.slice(bodyStart, j - 1);
+    out.push({ body, headIndex: m.index, bodyStartIndex: bodyStart, bodyEndIndex: j - 1 });
+  }
+  return out;
+}
+
+/**
+ * Detect stub-shaped function bodies in the given source text.
+ * Returns array of { ruleId, body, headIndex } findings.
+ */
+export function detectStubShapes(source) {
+  if (typeof source !== 'string' || source.length === 0) return [];
+  const findings = [];
+  const bodies = extractFunctionBodies(source);
+  for (const { body, headIndex } of bodies) {
+    for (const pattern of SHAPE_PATTERNS) {
+      if (pattern.rx.test(body)) {
+        if (pattern.requires && !pattern.requires.test(body)) continue;
+        findings.push({ ruleId: pattern.id, body: body.slice(0, 120), headIndex });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Returns true if ANY stub shape is detected. Cheap check for callers
+ * that just want a boolean (e.g. the kernel attrs.shapeMatched flag).
+ */
+export function hasStubShape(source) {
+  return detectStubShapes(source).length > 0;
+}
+
+export const __SHAPE_PATTERNS_FOR_TEST = SHAPE_PATTERNS;

package/hooks/lib/atlas-dossier-client.mjs

@@ -0,0 +1,151 @@
+// atlas-dossier-client — dossier fetcher for the pre-tool gate.
+//
+// Calls the Atlas server's /dossier endpoint over its Unix socket and returns
+// the governing_skills array (skill names only). Used by aria-pre-tool-gate.mjs
+// to consult Atlas's verified per-file skill bindings before evaluating the
+// autoload gate. The classifier (classifyRequiredSkills) handles intent-shape
+// triggers; the dossier handles file-bound triggers — Phase 1 of the
+// corpus-to-runtime auto-trigger wiring.
+//
+// Doctrine: feedback_no_silent_fail_open_in_hooks.md (2026-05-17).
+// Every error path writes a LOUD stderr line before returning the permissive
+// value. The empty-return is acceptable; SILENT empty-return is the violation.
+// Memory file names the three patterns that were forbidden in the first pass:
+// fire-and-forget timeout, swallowed catches, fail-open without log. Each one
+// is now surfaced as a single stderr line per hook invocation so next-turn
+// substrate scanners + ledger writers can recognize the failure mode.
+//
+// Doctrine cited: feedback_atlas_dossier_required_before_hot_path_edit.md
+// (any hot-path edit MUST consult dossier — this helper makes that mechanical
+// in the pre-tool-gate). feedback_non_blocking_errors_unacceptable.md is the
+// root rule the LOUD logs satisfy.
+
+import http from 'node:http';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const DEFAULT_SOCKET = join(homedir(), '.aria', 'atlas', 'atlas-server.sock');
+const DEFAULT_TIMEOUT_MS = 500;
+const LOG_PREFIX = '[atlas-dossier-client]';
+
+function emit(reason, detail) {
+  // LOUD per feedback_no_silent_fail_open_in_hooks.md.
+  // One line per error path per hook invocation — short-lived subprocess
+  // means no inter-call throttling is needed (each invocation logs at most
+  // once because finish() is idempotent via the `settled` guard).
+  try {
+    process.stderr.write(`${LOG_PREFIX}:${reason} ${detail}\n`);
+  } catch {
+    // process.stderr can be in a bad state if the parent already closed
+    // the fd; the doctrine requires the attempt, not perfect delivery.
+  }
+}
+
+/**
+ * Fetch dossier governing_skills for a file target. Returns [] on any failure,
+ * always preceded by a LOUD stderr line naming the failure mode.
+ *
+ * @param {string} target — repo-relative file path or symbol identifier.
+ * @param {object} [opts]
+ * @param {string} [opts.socketPath] — override Atlas server socket.
+ * @param {number} [opts.timeoutMs] — abort + log after this many ms.
+ * @returns {Promise<string[]>} array of skill names (e.g. ['aria-harness-deploy']).
+ */
+export async function fetchGoverningSkills(target, opts = {}) {
+  if (!target || typeof target !== 'string') {
+    emit('bad_target', `type=${typeof target} len=${(target ?? '').length}`);
+    return [];
+  }
+  const socketPath = opts.socketPath || DEFAULT_SOCKET;
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+  if (!existsSync(socketPath)) {
+    emit('socket_missing', `path=${socketPath}`);
+    return [];
+  }
+
+  const start = Date.now();
+  return new Promise((resolve) => {
+    let settled = false;
+    let req;
+    const finish = (val) => {
+      if (settled) return;
+      settled = true;
+      resolve(Array.isArray(val) ? val : []);
+    };
+    const timeout = setTimeout(() => {
+      // Abort the in-flight request so we don't fire-and-forget. The doctrine
+      // forbids leaving an in-flight request to consume server resources while
+      // we silently return — abort + LOUD together close the violation.
+      if (req && !req.destroyed) {
+        try { req.destroy(new Error('atlas-dossier-client timeout')); } catch { /* noop */ }
+      }
+      emit('timeout', `target=${target} budget_ms=${timeoutMs} elapsed_ms=${Date.now() - start}`);
+      finish([]);
+    }, timeoutMs);
+    try {
+      req = http.request(
+        {
+          socketPath,
+          method: 'GET',
+          path: `/dossier?target=${encodeURIComponent(target)}`,
+          headers: { 'Accept': 'application/json' },
+        },
+        (res) => {
+          if (res.statusCode !== 200) {
+            const status = res.statusCode;
+            res.resume();
+            clearTimeout(timeout);
+            emit('non_200', `target=${target} status=${status} elapsed_ms=${Date.now() - start}`);
+            finish([]);
+            return;
+          }
+          let buf = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => { buf += chunk; });
+          res.on('end', () => {
+            clearTimeout(timeout);
+            try {
+              const parsed = JSON.parse(buf);
+              const governing = parsed?.dossier?.governing_skills ?? parsed?.governing_skills ?? [];
+              const skills = [];
+              for (const row of Array.isArray(governing) ? governing : []) {
+                // attrs is a JSON string per dossier wire shape — parse defensively.
+                let attrs = row?.attrs;
+                if (typeof attrs === 'string') {
+                  try { attrs = JSON.parse(attrs); } catch { attrs = null; }
+                }
+                const name = attrs?.skill_name || row?.display_name || null;
+                if (typeof name === 'string' && name.trim()) skills.push(name.trim());
+              }
+              finish(skills);
+            } catch (err) {
+              emit('parse_fail', `target=${target} bytes=${buf.length} err=${err instanceof Error ? err.message : String(err)}`);
+              finish([]);
+            }
+          });
+          res.on('error', (err) => {
+            clearTimeout(timeout);
+            emit('res_error', `target=${target} err=${err instanceof Error ? err.message : String(err)}`);
+            finish([]);
+          });
+        },
+      );
+      req.on('error', (err) => {
+        clearTimeout(timeout);
+        // The timeout's req.destroy() triggers this with an Error message
+        // matching 'atlas-dossier-client timeout'; we don't double-log
+        // because the timeout handler already emitted 'timeout' and
+        // finished. The settled-guard in finish() keeps this idempotent.
+        if (settled) return;
+        emit('req_error', `target=${target} err=${err instanceof Error ? err.message : String(err)}`);
+        finish([]);
+      });
+      req.end();
+    } catch (err) {
+      clearTimeout(timeout);
+      emit('http_request_threw', `target=${target} err=${err instanceof Error ? err.message : String(err)}`);
+      finish([]);
+    }
+  });
+}