@aria_asi/cli 0.2.30 → 0.2.32

package/dist/runtime/codex-bridge.mjs

@@ -0,0 +1,644 @@
+#!/usr/bin/env node
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, resolve } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { WebSocketServer, WebSocket } = require('ws');
+
+const HOME = homedir();
+const LOG_PATH = `${HOME}/.aria/runtime/logs/codex-bridge.log`;
+const RUNTIME_BASE_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+const BRIDGE_PORT = Number(process.env.ARIA_CODEX_BRIDGE_PORT || '4320');
+const DOWNSTREAM_PORT = Number(process.env.ARIA_CODEX_DOWNSTREAM_PORT || '4321');
+const BRIDGE_HOST = process.env.ARIA_CODEX_BRIDGE_HOST || '127.0.0.1';
+const DOWNSTREAM_URL = process.env.ARIA_CODEX_DOWNSTREAM_URL || `ws://${BRIDGE_HOST}:${DOWNSTREAM_PORT}`;
+const DOWNSTREAM_STARTUP_GRACE_MS = Number(process.env.ARIA_CODEX_DOWNSTREAM_STARTUP_GRACE_MS || '5000');
+const BRIDGE_WARNING_METHOD = 'guardianWarning';
+
+let downstreamProcess = null;
+let downstreamProcessStarting = null;
+
+const turnState = new Map();
+
+function resolveRealCodexBin() {
+  if (process.env.ARIA_CODEX_REAL_BIN && existsSync(process.env.ARIA_CODEX_REAL_BIN)) {
+    return process.env.ARIA_CODEX_REAL_BIN;
+  }
+
+  const wrapperDir = resolve(HOME, '.aria', 'wrappers');
+  const sanitizedPath = String(process.env.PATH || '')
+    .split(delimiter)
+    .filter((entry) => entry && resolve(entry) !== wrapperDir)
+    .join(delimiter);
+
+  try {
+    const result = spawnSync('bash', ['-lc', 'which -a codex'], {
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        PATH: sanitizedPath,
+      },
+    });
+    const candidates = String(result.stdout || '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .filter((candidate) => !candidate.startsWith(`${wrapperDir}/`));
+    if (candidates.length > 0 && existsSync(candidates[0])) {
+      return candidates[0];
+    }
+  } catch {}
+
+  const fallbackCandidates = [
+    resolve(HOME, '.npm-global', 'bin', 'codex'),
+    resolve(HOME, '.local', 'bin', 'codex'),
+    '/usr/local/bin/codex',
+    '/usr/bin/codex',
+  ];
+  return fallbackCandidates.find((candidate) => existsSync(candidate)) || resolve(HOME, '.npm-global', 'bin', 'codex');
+}
+
+const CODEx_REAL_BIN = resolveRealCodexBin();
+
+function log(message) {
+  try {
+    if (!existsSync(dirname(LOG_PATH))) mkdirSync(dirname(LOG_PATH), { recursive: true });
+    appendFileSync(LOG_PATH, `${new Date().toISOString()} ${message}\n`);
+  } catch {}
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+function readRuntimeToken() {
+  const envToken = process.env.ARIA_HARNESS_TOKEN || process.env.ARIA_API_KEY || process.env.OPENAI_API_KEY || process.env.ARIA_MASTER_TOKEN;
+  if (envToken) return envToken;
+  const ownerTokenPath = `${HOME}/.aria/owner-token`;
+  if (existsSync(ownerTokenPath)) {
+    try {
+      return readFileSync(ownerTokenPath, 'utf8').trim();
+    } catch {}
+  }
+  return '';
+}
+
+function runtimeHeaders() {
+  const token = readRuntimeToken();
+  return {
+    'Content-Type': 'application/json',
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  };
+}
+
+async function postRuntime(pathname, body) {
+  const response = await fetch(`${RUNTIME_BASE_URL}${pathname}`, {
+    method: 'POST',
+    headers: runtimeHeaders(),
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {}
+  if (!response.ok) {
+    const message = parsed?.error || parsed?.message || `${response.status} ${response.statusText}`;
+    throw new Error(`${pathname} failed: ${message}`);
+  }
+  return parsed;
+}
+
+function ensureTurnState(threadId, turnId) {
+  const key = `${threadId}:${turnId}`;
+  let state = turnState.get(key);
+  if (!state) {
+    state = {
+      threadId,
+      turnId,
+      userText: '',
+      preReceiptId: null,
+      agentText: '',
+      bufferedAgentNotifications: [],
+      firstAgentItemId: null,
+    };
+    turnState.set(key, state);
+  }
+  return state;
+}
+
+function extractInputText(input) {
+  if (!Array.isArray(input)) return '';
+  const parts = [];
+  for (const item of input) {
+    if (!item || typeof item !== 'object') continue;
+    if (typeof item.text === 'string' && item.text.trim()) {
+      parts.push(item.text.trim());
+      continue;
+    }
+    if (typeof item.message === 'string' && item.message.trim()) {
+      parts.push(item.message.trim());
+      continue;
+    }
+    if (Array.isArray(item.content)) {
+      for (const contentItem of item.content) {
+        if (contentItem && typeof contentItem.text === 'string' && contentItem.text.trim()) {
+          parts.push(contentItem.text.trim());
+        }
+      }
+    }
+  }
+  return parts.join('\n\n').trim();
+}
+
+function deriveActionFromCommand(command = '') {
+  const text = String(command || '').trim();
+  if (!text) return 'write';
+  if (/\bkubectl\s+(apply|set\s+image|rollout\s+(restart|undo)|create|replace|delete)\b|\bdocker\s+(push|build\b.*--push)|\bdeploy-service\.sh\b/i.test(text)) {
+    return 'deploy';
+  }
+  if (/\brm\b|\bgit\s+reset\s+--hard\b|\bgit\s+checkout\s+--\b|\bDROP\s+(TABLE|DATABASE|SCHEMA|INDEX)\b/i.test(text)) {
+    return 'delete';
+  }
+  if (/\b(?:npm|pnpm|yarn)\s+run\s+(?:build|typecheck|test)\b|\btsc\b|\bmake\b|\bcargo\s+(?:build|test)\b/i.test(text)) {
+    return 'build';
+  }
+  return 'write';
+}
+
+function summarizeRuntimeFailures(result) {
+  const failures = Array.isArray(result?.layer3?.failures) ? result.layer3.failures : [];
+  const validationViolations = Array.isArray(result?.validation?.violations) ? result.validation.violations : [];
+  const messages = [
+    ...validationViolations,
+    ...failures.map((failure) => failure?.detail || failure?.message || JSON.stringify(failure)),
+  ].filter(Boolean);
+  return messages.slice(0, 6).join(' | ');
+}
+
+async function validateTurnText(threadId, turnId) {
+  const state = ensureTurnState(threadId, turnId);
+  const text = String(state.agentText || '').trim();
+  if (!text) {
+    return { ok: false, reason: 'No assistant text exists for this turn yet. Codex must emit readable cognition before action.' };
+  }
+  const result = await postRuntime('/validate-output', {
+    text,
+    sessionId: `codex:${threadId}:${turnId}`,
+    runLayer3: true,
+    requireCognitionBlock: true,
+    packetRequest: {
+      sessionId: `codex:${threadId}`,
+      platform: 'codex',
+      message: state.userText || text,
+      stage: 'codex-turn',
+      actor: 'codex-bridge',
+      system: 'codex-bridge',
+    },
+  });
+  const pass = result?.pass === true && result?.validation?.passed !== false;
+  return pass
+    ? { ok: true, result }
+    : {
+        ok: false,
+        reason: summarizeRuntimeFailures(result) || 'Runtime validation failed for this turn before action/output release.',
+        result,
+      };
+}
+
+async function checkActionAgainstRuntime(action, target, threadId, turnId) {
+  const result = await postRuntime('/check-action', {
+    action,
+    target,
+    sessionId: `codex:${threadId}:${turnId}`,
+  });
+  if (result?.allowed === false) {
+    return {
+      ok: false,
+      reason: result.reason || `Runtime denied ${action} on ${target}`,
+      result,
+    };
+  }
+  return { ok: true, result };
+}
+
+async function recordMizanPre(threadId, turnId) {
+  const state = ensureTurnState(threadId, turnId);
+  try {
+    const result = await postRuntime('/mizan/pre', {
+      sessionId: `codex:${threadId}:${turnId}`,
+      packetRequest: {
+        sessionId: `codex:${threadId}`,
+        platform: 'codex',
+        message: state.userText || 'codex turn start',
+        stage: 'codex-pre',
+        actor: 'codex-bridge',
+        system: 'codex-bridge',
+      },
+      context: {
+        sessionId: `codex:${threadId}:${turnId}`,
+        surface: 'codex-bridge',
+        platform: 'codex',
+        userText: state.userText,
+      },
+    });
+    state.preReceiptId = result?.receipt?.receiptId || null;
+  } catch (error) {
+    log(`warn mizan/pre thread=${threadId} turn=${turnId} error="${error instanceof Error ? error.message : String(error)}"`);
+  }
+}
+
+async function recordMizanPost(threadId, turnId, pass, summary) {
+  const state = ensureTurnState(threadId, turnId);
+  try {
+    await postRuntime('/mizan/post', {
+      sessionId: `codex:${threadId}:${turnId}`,
+      parentReceiptId: state.preReceiptId,
+      text: state.agentText || summary,
+      evidence: {
+        validated_output: pass,
+        bridge: 'codex',
+      },
+      context: {
+        sessionId: `codex:${threadId}:${turnId}`,
+        surface: 'codex-bridge',
+        platform: 'codex',
+        userText: state.userText,
+        summary,
+      },
+    });
+  } catch (error) {
+    log(`warn mizan/post thread=${threadId} turn=${turnId} error="${error instanceof Error ? error.message : String(error)}"`);
+  }
+  try {
+    await postRuntime('/decision/log', {
+      session_id: `codex:${threadId}:${turnId}`,
+      decision_type: 'codex_turn',
+      decision_category: 'runtime-control-plane',
+      summary,
+      outcome: pass ? 'validated' : 'blocked',
+      surface: 'codex-bridge',
+      details: {
+        threadId,
+        turnId,
+      },
+    });
+  } catch (error) {
+    log(`warn decision/log thread=${threadId} turn=${turnId} error="${error instanceof Error ? error.message : String(error)}"`);
+  }
+}
+
+function makeGuardianWarning(threadId, message) {
+  return {
+    method: BRIDGE_WARNING_METHOD,
+    params: {
+      threadId,
+      message,
+    },
+  };
+}
+
+async function handleApprovalRequest(upstream, downstream, message) {
+  const { id, method, params = {} } = message;
+  const threadId = params.threadId || params.conversationId || 'unknown-thread';
+  const turnId = params.turnId || 'legacy-turn';
+  const validation = await validateTurnText(threadId, turnId);
+
+  if (!validation.ok) {
+    const reason = `Aria runtime blocked action before tool approval: ${validation.reason}`;
+    upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
+    const declineResult =
+      method === 'item/commandExecution/requestApproval'
+        ? { decision: 'decline' }
+        : method === 'item/fileChange/requestApproval'
+          ? { decision: 'decline' }
+          : method === 'item/permissions/requestApproval'
+            ? { permissions: { fileSystem: { entries: [] }, network: { enabled: false } }, scope: 'turn', strictAutoReview: true }
+            : method === 'execCommandApproval'
+              ? { decision: 'denied' }
+              : { decision: 'denied' };
+    downstream.send(JSON.stringify({ id, result: declineResult }));
+    log(`deny approval method=${method} thread=${threadId} turn=${turnId} reason="${validation.reason}"`);
+    return true;
+  }
+
+  if (method === 'item/commandExecution/requestApproval' || method === 'execCommandApproval') {
+    const command = method === 'item/commandExecution/requestApproval'
+      ? params.command || ''
+      : Array.isArray(params.command) ? params.command.join(' ') : '';
+    const action = deriveActionFromCommand(command);
+    const target = JSON.stringify({
+      command,
+      cwd: params.cwd || null,
+      commandActions: params.commandActions || params.parsedCmd || null,
+    }).slice(0, 1500);
+    const actionCheck = await checkActionAgainstRuntime(action, target, threadId, turnId);
+    if (!actionCheck.ok) {
+      const reason = `Aria runtime denied ${action}: ${actionCheck.reason}`;
+      upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
+      downstream.send(JSON.stringify({
+        id,
+        result: method === 'item/commandExecution/requestApproval'
+          ? { decision: 'decline' }
+          : { decision: 'denied' },
+      }));
+      log(`deny command method=${method} action=${action} thread=${threadId} turn=${turnId} reason="${actionCheck.reason}"`);
+      return true;
+    }
+    downstream.send(JSON.stringify({
+      id,
+      result: method === 'item/commandExecution/requestApproval'
+        ? { decision: 'accept' }
+        : { decision: 'approved' },
+    }));
+    log(`allow command method=${method} action=${action} thread=${threadId} turn=${turnId}`);
+    return true;
+  }
+
+  if (method === 'item/fileChange/requestApproval' || method === 'applyPatchApproval') {
+    const target = params.grantRoot || params.reason || params.itemId || 'file-change';
+    const actionCheck = await checkActionAgainstRuntime('write', String(target), threadId, turnId);
+    if (!actionCheck.ok) {
+      const reason = `Aria runtime denied file change: ${actionCheck.reason}`;
+      upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
+      downstream.send(JSON.stringify({
+        id,
+        result: method === 'item/fileChange/requestApproval'
+          ? { decision: 'decline' }
+          : { decision: 'denied' },
+      }));
+      log(`deny file-change method=${method} thread=${threadId} turn=${turnId} reason="${actionCheck.reason}"`);
+      return true;
+    }
+    downstream.send(JSON.stringify({
+      id,
+      result: method === 'item/fileChange/requestApproval'
+        ? { decision: 'accept' }
+        : { decision: 'approved' },
+    }));
+    log(`allow file-change method=${method} thread=${threadId} turn=${turnId}`);
+    return true;
+  }
+
+  if (method === 'item/permissions/requestApproval') {
+    const target = JSON.stringify({
+      cwd: params.cwd || null,
+      permissions: params.permissions || null,
+      reason: params.reason || null,
+    }).slice(0, 1500);
+    const actionCheck = await checkActionAgainstRuntime('write', target, threadId, turnId);
+    if (!actionCheck.ok) {
+      const reason = `Aria runtime denied permissions request: ${actionCheck.reason}`;
+      upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
+      downstream.send(JSON.stringify({
+        id,
+        result: {
+          permissions: {
+            fileSystem: {
+              entries: [],
+            },
+            network: {
+              enabled: false,
+            },
+          },
+          scope: 'turn',
+          strictAutoReview: true,
+        },
+      }));
+      log(`deny permissions thread=${threadId} turn=${turnId} reason="${actionCheck.reason}"`);
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function releaseTurnOutput(upstream, notification) {
+  const threadId = notification?.params?.threadId;
+  const turnId = notification?.params?.turn?.id || notification?.params?.turnId;
+  if (!threadId || !turnId) {
+    upstream.send(JSON.stringify(notification));
+    return;
+  }
+
+  const state = ensureTurnState(threadId, turnId);
+  if (state.bufferedAgentNotifications.length === 0) {
+    upstream.send(JSON.stringify(notification));
+    turnState.delete(`${threadId}:${turnId}`);
+    return;
+  }
+
+  const validation = await validateTurnText(threadId, turnId);
+  if (validation.ok) {
+    for (const buffered of state.bufferedAgentNotifications) {
+      upstream.send(JSON.stringify(buffered));
+    }
+    await recordMizanPost(threadId, turnId, true, 'codex turn validated and released');
+    log(`release turn thread=${threadId} turn=${turnId} chars=${state.agentText.length}`);
+  } else {
+    const refusalText = `Aria runtime blocked final output for this Codex turn.\n\n${validation.reason}`;
+    if (state.firstAgentItemId) {
+      upstream.send(JSON.stringify({
+        method: 'item/agentMessage/delta',
+        params: {
+          threadId,
+          turnId,
+          itemId: state.firstAgentItemId,
+          delta: refusalText,
+        },
+      }));
+    }
+    upstream.send(JSON.stringify(makeGuardianWarning(threadId, refusalText)));
+    await recordMizanPost(threadId, turnId, false, validation.reason);
+    log(`block turn thread=${threadId} turn=${turnId} reason="${validation.reason}"`);
+  }
+
+  upstream.send(JSON.stringify(notification));
+  turnState.delete(`${threadId}:${turnId}`);
+}
+
+async function ensureDownstreamReady() {
+  if (downstreamProcess && !downstreamProcess.killed) return;
+  if (downstreamProcessStarting) {
+    await downstreamProcessStarting;
+    return;
+  }
+
+  downstreamProcessStarting = (async () => {
+    log(`start downstream codex app-server bin=${CODEx_REAL_BIN} port=${DOWNSTREAM_PORT}`);
+    const env = {
+      ...process.env,
+      PATH: (process.env.PATH || '')
+        .split(':')
+        .filter((entry) => entry && entry !== `${HOME}/.aria/wrappers`)
+        .join(':'),
+    };
+    delete env.ARIA_CODEX_BRIDGE_PORT;
+    delete env.ARIA_CODEX_DOWNSTREAM_PORT;
+    delete env.ARIA_CODEX_DOWNSTREAM_URL;
+    delete env.ARIA_CODEX_REAL_BIN;
+
+    downstreamProcess = spawn(CODEx_REAL_BIN, ['app-server', '--listen', `ws://${BRIDGE_HOST}:${DOWNSTREAM_PORT}`], {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    downstreamProcess.stdout.on('data', (chunk) => log(`[downstream stdout] ${String(chunk).trimEnd()}`));
+    downstreamProcess.stderr.on('data', (chunk) => log(`[downstream stderr] ${String(chunk).trimEnd()}`));
+    downstreamProcess.on('exit', (code, signal) => {
+      log(`downstream exit code=${code} signal=${signal || ''}`);
+      downstreamProcess = null;
+    });
+
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < DOWNSTREAM_STARTUP_GRACE_MS) {
+      try {
+        await new Promise((resolvePromise, rejectPromise) => {
+          const socket = new WebSocket(DOWNSTREAM_URL);
+          socket.once('open', () => {
+            socket.terminate();
+            resolvePromise();
+          });
+          socket.once('error', rejectPromise);
+        });
+        return;
+      } catch {
+        await sleep(100);
+      }
+    }
+    throw new Error(`downstream codex app-server not reachable at ${DOWNSTREAM_URL}`);
+  })();
+
+  try {
+    await downstreamProcessStarting;
+  } finally {
+    downstreamProcessStarting = null;
+  }
+}
+
+function maybePrimeTurnState(message) {
+  if (!message || typeof message !== 'object') return;
+  const method = message.method;
+  const params = message.params || {};
+  if (method === 'turn/start' || method === 'turn/steer') {
+    const threadId = params.threadId;
+    if (!threadId) return;
+    const userText = extractInputText(params.input);
+    const state = ensureTurnState(threadId, `${Date.now()}`);
+    state.userText = userText;
+  }
+}
+
+async function startBridge() {
+  await ensureDownstreamReady();
+
+  const wss = new WebSocketServer({
+    host: BRIDGE_HOST,
+    port: BRIDGE_PORT,
+    perMessageDeflate: false,
+  });
+
+  wss.on('connection', async (upstream) => {
+    await ensureDownstreamReady();
+    const downstream = new WebSocket(DOWNSTREAM_URL);
+
+    upstream.once('close', () => {
+      try { downstream.close(); } catch {}
+    });
+    downstream.once('close', () => {
+      try { upstream.close(); } catch {}
+    });
+
+    upstream.on('message', async (data) => {
+      const raw = typeof data === 'string' ? data : data.toString();
+      let message;
+      try {
+        message = JSON.parse(raw);
+      } catch {
+        downstream.send(raw);
+        return;
+      }
+
+      if (message?.method === 'turn/start' && message?.params?.threadId) {
+        const state = ensureTurnState(message.params.threadId, String(Date.now()));
+        state.userText = extractInputText(message.params.input);
+        if (!message.params.approvalPolicy) {
+          message.params.approvalPolicy = 'untrusted';
+        }
+        void recordMizanPre(message.params.threadId, state.turnId);
+      }
+
+      downstream.send(JSON.stringify(message));
+    });
+
+    downstream.on('message', async (data) => {
+      const raw = typeof data === 'string' ? data : data.toString();
+      let message;
+      try {
+        message = JSON.parse(raw);
+      } catch {
+        upstream.send(raw);
+        return;
+      }
+
+      if (message?.id != null && typeof message?.method === 'string') {
+        const intercepted = await handleApprovalRequest(upstream, downstream, message).catch((error) => {
+          const threadId = message?.params?.threadId || 'unknown-thread';
+          const reason = `Aria Codex bridge approval hook failed: ${error instanceof Error ? error.message : String(error)}`;
+          upstream.send(JSON.stringify(makeGuardianWarning(threadId, reason)));
+          log(`error approval method=${message.method} reason="${reason}"`);
+          return false;
+        });
+        if (intercepted) return;
+      }
+
+      if (message?.method === 'item/agentMessage/delta') {
+        const { threadId, turnId, itemId, delta } = message.params || {};
+        if (threadId && turnId && typeof delta === 'string') {
+          const state = ensureTurnState(threadId, turnId);
+          state.agentText += delta;
+          state.bufferedAgentNotifications.push(message);
+          if (!state.firstAgentItemId && itemId) state.firstAgentItemId = itemId;
+          return;
+        }
+      }
+
+      if (message?.method === 'turn/completed') {
+        await releaseTurnOutput(upstream, message);
+        return;
+      }
+
+      if (message?.method === 'turn/started') {
+        const threadId = message?.params?.threadId;
+        const turnId = message?.params?.turn?.id || message?.params?.turnId;
+        if (threadId && turnId) {
+          const state = ensureTurnState(threadId, turnId);
+          if (!state.userText) {
+            state.userText = message?.params?.turn?.input?.map?.((entry) => entry?.text).filter(Boolean).join('\n\n') || '';
+          }
+          void recordMizanPre(threadId, turnId);
+        }
+      }
+
+      upstream.send(JSON.stringify(message));
+    });
+
+    downstream.on('error', (error) => {
+      log(`downstream socket error ${error.message}`);
+      try {
+        upstream.send(JSON.stringify(makeGuardianWarning('codex-bridge', `Codex downstream socket error: ${error.message}`)));
+      } catch {}
+    });
+    upstream.on('error', (error) => log(`upstream socket error ${error.message}`));
+  });
+
+  log(`bridge listening ws://${BRIDGE_HOST}:${BRIDGE_PORT} downstream=${DOWNSTREAM_URL}`);
+}
+
+startBridge().catch((error) => {
+  log(`fatal ${error instanceof Error ? error.stack || error.message : String(error)}`);
+  process.exit(1);
+});

package/dist/runtime/discipline/CLAUDE.md

@@ -4,6 +4,18 @@
 > the gates this surface installs. Following this saves multi-turn iteration
 > loops on gate-blocks and substrate-binding violations.
 
+## Must-read order for weaker or drifting models
+
+Read these in order before the first non-trivial action:
+
+1. `~/.claude/ARIA_MUST_READ.md` for Claude surfaces, `~/.codex/ARIA_MUST_READ.md` for Codex, or `~/.aria/ARIA_MUST_READ.md` for OpenCode.
+2. This file.
+3. `~/.aria/runtime/discipline/skills/aria-harness/aria-harness-onboarding/SKILL.md`
+4. `~/.aria/runtime/discipline/skills/aria-harness/aria-harness-substrate-binding/SKILL.md`
+5. The live doctrine trigger map for the current surface.
+
+If compaction, gate deadlock, or repeated drift happens, restart from that order instead of guessing from stale memory.
+
 ## What this SDK is
 
 `@aria/harness-http-client` is the Aria harness SDK. It binds a process
@@ -152,6 +164,22 @@ Every non-trivial assistant turn must satisfy all three.
 
 **REJECTED (qualitative drift):** `better`, `improved`, `should work`, `more reliable`, `cleaner`, `nicer`. These are unmeasurable.
 
+### `<applied_cognition>` — required with every non-trivial cognition block
+
+The cognition block is not accepted as proof by itself. It must bind to a concrete action or output claim and state what changed because cognition ran.
+
+```
+<applied_cognition>
+  decision_delta: <what changed because cognition ran; not "none">
+  dominant_domain: <engineering_quality | trust | operations | security | product | ...>
+  binds_to: <the next tool/action/output claim this cognition constrains>
+  expected_predicate: <numeric, boolean, or state-string predicate proving success>
+  artifact_change: <how the produced artifact/action/output differs because cognition ran>
+</applied_cognition>
+```
+
+**Rejected:** missing fields, `decision_delta: none`, or a contract that does not bind to the next action/output. This is the structural enforcement for apply-lenses-don't-perform.
+
 ### `<verify>` — required for deploy commands
 
 A deploy is anything matching `deploy-service.sh|kubectl apply -f|kubectl set image|docker push|trivial deploy|fast path deploy`. Without a verify block, the pre-tool-gate hard-blocks.