@aria_asi/cli 0.2.36 → 0.2.37

package/dist/runtime/hooks/lib/first-class-coach.mjs

@@ -0,0 +1,755 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+export const FIRST_CLASS_COACH_VERSION = 'aria.first_class_coach.v1';
+export const TASK_PROJECT_LEDGER_VERSION = 'aria.task_project_ledger.v1';
+export const RUNTIME_COACH_BRIDGE_VERSION = 'aria.runtime_coach_bridge.v1';
+
+export const FIRST_CLASS_AXIOMS = [
+  'truth_over_deception',
+  'no_harm',
+  'sacred_trust',
+  'power_obligates_service',
+  'reflection_before_action',
+];
+
+export const FIRST_CLASS_DOMAINS = [
+  'engineering_quality',
+  'reliability',
+  'security',
+  'operations',
+  'trust',
+  'developer_experience',
+  'product',
+  'learning',
+];
+
+export const FIRST_CLASS_PRINCIPLES = [
+  'complete_implementation_not_claim_only',
+  'verified_behavior_not_assumption',
+  'domain_uplift_not_local_green_only',
+  'axiom_bound_decisioning',
+  'first_principles_before_action',
+  'senior_production_grade_change_control',
+  'recoverable_fail_closed_governance',
+  'evidence_ledger_before_readiness_claim',
+];
+
+export const LIFECYCLE_PHASES = [
+  { id: 'session_start', labels: ['SessionStart', 'session.start'], blocks: false },
+  { id: 'pre_prompt_injection', labels: ['UserPromptSubmit', 'user.prompt.submit'], blocks: false },
+  { id: 'post_prompt_injection', labels: ['post_prompt_injection'], blocks: false },
+  { id: 'pre_cognition', labels: ['pre_cognition', 'cognition.pre'], blocks: true },
+  { id: 'post_cognition', labels: ['post_cognition', 'cognition.post'], blocks: true },
+  { id: 'pre_tool', labels: ['PreToolUse', 'pre.tool'], blocks: true },
+  { id: 'post_tool', labels: ['PostToolUse', 'post.tool'], blocks: true },
+  { id: 'pre_emit', labels: ['pre_emit', 'pre.text'], blocks: true },
+  { id: 'stop', labels: ['Stop', 'text.complete', 'message.updated'], blocks: true },
+  { id: 'post_turn', labels: ['post_turn', 'outcome'], blocks: false },
+  { id: 'background_worker', labels: ['worker', 'agent', 'background'], blocks: true },
+];
+
+export const PLATFORM_PHASES = {
+  claude: ['session_start', 'pre_prompt_injection', 'pre_tool', 'post_tool', 'pre_emit', 'post_cognition', 'stop', 'post_turn', 'background_worker'],
+  codex: ['pre_prompt_injection', 'pre_tool', 'post_tool', 'stop', 'post_turn'],
+  opencode: ['session_start', 'pre_tool', 'post_tool', 'stop', 'post_turn'],
+  sdk: ['pre_prompt_injection', 'pre_cognition', 'post_cognition', 'pre_tool', 'post_tool', 'pre_emit', 'stop', 'post_turn'],
+  owner_runtime: ['session_start', 'pre_prompt_injection', 'pre_tool', 'post_tool', 'pre_emit', 'stop', 'post_turn', 'background_worker'],
+  openclaw: ['standing_order', 'task_record', 'task_flow', 'lobster_run', 'approval_resume', 'plugin_hook', 'audit_maintenance'],
+  garden_hive: ['context_hydration', 'decision_log', 'outcome_writeback', 'living_memory', 'worker_continuity'],
+};
+
+export const TASK_PROJECT_QUALITY_GATES = [
+  {
+    id: 'ledger_created',
+    description: 'A durable task/project ledger exists before work proceeds.',
+    readinessRequired: true,
+  },
+  {
+    id: 'intent_boundary',
+    description: 'The ledger records what task or project is being attempted.',
+    readinessRequired: true,
+  },
+  {
+    id: 'scope_boundary',
+    description: 'The ledger records the platform and phase boundaries that govern the work.',
+    readinessRequired: true,
+  },
+  {
+    id: 'execution_trace',
+    description: 'The ledger records at least one execution, tool, workflow, or background phase event when work changes state.',
+    readinessRequired: false,
+  },
+  {
+    id: 'verification_trace',
+    description: 'The ledger records real verification evidence before completion/readiness claims are allowed.',
+    readinessRequired: true,
+  },
+  {
+    id: 'post_turn_writeback',
+    description: 'The ledger records post-turn or outcome writeback for continuity.',
+    readinessRequired: false,
+  },
+  {
+    id: 'final_claim_guard',
+    description: 'The ledger actively guards final claims against missing evidence.',
+    readinessRequired: true,
+  },
+];
+
+const CLAIM_RX = /\b(?:first[- ]class|production[- ]ready|ready|complete|completed|done|verified|gold[- ]standard|shipped|fixed|landed)\b/i;
+const MAX_LEDGER_EVENTS = 500;
+const RUNTIME_COACH_ENDPOINT_PATH = '/coach/phase';
+export const RUNTIME_COACH_RELEASE_PHASES = ['claim_or_release', 'post_output'];
+const RUNTIME_COACH_BLOCKING_LOCAL_PHASES = new Set(['pre_tool', 'pre_emit', 'stop', 'post_cognition']);
+const RUNTIME_PHASES_BY_LOCAL_PHASE = {
+  session_start: ['pre_turn'],
+  pre_prompt_injection: ['pre_turn', 'pre_cognition'],
+  post_prompt_injection: ['post_cognition'],
+  pre_cognition: ['pre_cognition'],
+  post_cognition: ['post_cognition'],
+  pre_tool: ['pre_tool'],
+  post_tool: ['post_tool'],
+  pre_emit: ['pre_output'],
+  stop: ['post_generation', 'pre_output'],
+  post_turn: ['post_output'],
+  background_worker: ['background_checkpoint'],
+};
+
+export const FIRST_CLASS_ACCEPTANCE = {
+  version: FIRST_CLASS_COACH_VERSION,
+  definition: 'first-class means complete, verified, domain-uplifted, axiom-bound, first-principles-applied, recoverable, and senior-production-grade across every controlled platform and lifecycle phase before any readiness claim',
+  requiredEvidence: [
+    'source_path',
+    'package_path',
+    'active_runtime_path',
+    'import_check',
+    'allow_smoke',
+    'block_smoke',
+    'recovery_smoke',
+    'fresh_install_smoke',
+    'domain_review',
+    'axiom_review',
+    'first_principles_review',
+    'warning_clean_check',
+  ],
+  axioms: FIRST_CLASS_AXIOMS,
+  domains: FIRST_CLASS_DOMAINS,
+  principles: FIRST_CLASS_PRINCIPLES,
+  platforms: Object.keys(PLATFORM_PHASES),
+  lifecyclePhases: LIFECYCLE_PHASES.map((phase) => phase.id),
+};
+
+function stableHash(value = '') {
+  return createHash('sha256').update(String(value || 'unknown')).digest('hex').slice(0, 20);
+}
+
+function stableJson(value = {}) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value || '');
+  }
+}
+
+function hashJson(value = {}) {
+  return createHash('sha256').update(stableJson(value)).digest('hex');
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  }
+  return '';
+}
+
+function compactHint(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return 'unknown';
+  const tail = raw.includes('/') ? basename(raw) : raw;
+  return tail.replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 80) || 'unknown';
+}
+
+function readJsonFile(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function appendRuntimeCoachBridgeError(record) {
+  try {
+    const target = join(homedir(), '.aria', 'first-class-coach-runtime-publish-errors.jsonl');
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    appendFileSync(target, `${JSON.stringify({ schema: `${RUNTIME_COACH_BRIDGE_VERSION}.error`, at: new Date().toISOString(), ...record })}\n`, { mode: 0o600 });
+  } catch {}
+}
+
+function readRuntimeToken(env = process.env) {
+  const envToken = firstString(env.ARIA_HARNESS_TOKEN, env.ARIA_API_KEY, env.ARIA_MASTER_TOKEN);
+  if (envToken) return envToken;
+  const ownerPath = join(homedir(), '.aria', 'owner-token');
+  if (existsSync(ownerPath)) return readFileSync(ownerPath, 'utf8').trim();
+  const license = readJsonFile(join(homedir(), '.aria', 'license.json'));
+  return firstString(license?.harnessToken, license?.token);
+}
+
+function runtimeBaseUrl(env = process.env) {
+  return firstString(env.ARIA_RUNTIME_URL, 'http://127.0.0.1:4319').replace(/\/+$/, '');
+}
+
+function runtimeCoachPhasesForLocalPhase(phase = '') {
+  return RUNTIME_PHASES_BY_LOCAL_PHASE[phase] || ['pre_turn'];
+}
+
+function inferRuntimeSessionId(event = {}, platform = 'claude') {
+  const explicit = firstString(
+    event.session_id,
+    event.sessionId,
+    event.conversationId,
+    event.conversation_id,
+    event.threadId,
+    event.thread_id,
+    event.transcript_path,
+    event.transcriptPath
+  );
+  return explicit || `${platform}:${stableHash(firstString(event.cwd, event.workspaceDir, process.cwd()))}`;
+}
+
+function inferRuntimeRequestId(event = {}, platform = 'claude') {
+  return firstString(
+    event.request_id,
+    event.requestId,
+    event.turn_id,
+    event.turnId,
+    event.message_id,
+    event.messageId,
+    `${inferRuntimeSessionId(event, platform)}:${event.hookEventName || event.hook_event_name || event.type || Date.now()}`
+  );
+}
+
+function summarizeRuntimeToolTarget(event = {}) {
+  const value = {
+    tool_name: event.tool_name || event.toolName || event.tool?.name || null,
+    tool_input: event.tool_input || event.toolInput || event.input || null,
+  };
+  return stableJson(value).slice(0, 6000);
+}
+
+function inferRuntimeAction(event = {}, phase = '') {
+  const haystack = `${phase}\n${summarizeRuntimeToolTarget(event)}\n${stableJson(event).slice(0, 6000)}`;
+  if (/\b(?:kubectl\s+(?:apply|set|rollout|delete)|helm\s+upgrade|terraform\s+apply|docker\s+push|deploy)\b/i.test(haystack)) return 'deploy';
+  if (/\b(?:rm\s+-[rRfF]+|delete|drop\s+(?:table|database|schema)|git\s+reset\s+--hard)\b/i.test(haystack)) return 'delete';
+  if (phase === 'stop' || phase === 'pre_emit') return 'release';
+  if (phase === 'pre_tool' || phase === 'post_tool') return 'write';
+  return '';
+}
+
+function readHarnessPacketHash(event = {}) {
+  const direct = firstString(event.harnessPacketHash, event.harness_packet_hash);
+  if (direct) return direct;
+  for (const candidate of [
+    join(homedir(), '.claude', '.aria-harness-last-packet.json'),
+    join(homedir(), '.aria', '.aria-harness-last-packet.json'),
+  ]) {
+    const packet = readJsonFile(candidate);
+    if (packet) return hashJson(packet);
+  }
+  return '';
+}
+
+function runtimeTextForPhase(event = {}, localPhase = '') {
+  if (localPhase === 'pre_tool' || localPhase === 'post_tool') return summarizeRuntimeToolTarget(event);
+  if (localPhase === 'stop' || localPhase === 'pre_emit' || localPhase === 'post_cognition') return extractAssistantText(event);
+  return firstString(
+    event.prompt,
+    event.userPrompt,
+    event.user_input,
+    event.message,
+    event.text,
+    event.body,
+    event.context?.prompt,
+    event.context?.bodyForAgent
+  );
+}
+
+function buildRuntimeCoachBody({ platform = 'claude', phase = 'unknown', runtimePhase, event = {}, ledgerResult = null, evidence = {} } = {}) {
+  const taskLedger = ledgerResult?.ledger || null;
+  const paths = ledgerResult?.paths || null;
+  return {
+    phase: runtimePhase,
+    requestId: inferRuntimeRequestId(event, platform),
+    sessionId: inferRuntimeSessionId(event, platform),
+    surface: `${platform}-hooks`,
+    lane: `${platform}_native_hooks`,
+    action: inferRuntimeAction(event, phase),
+    target: phase === 'pre_tool' || phase === 'post_tool' ? summarizeRuntimeToolTarget(event) : '',
+    text: runtimeTextForPhase(event, phase),
+    harnessPacketHash: readHarnessPacketHash(event),
+    roleProfile: `${platform}_code_assistant`,
+    evidenceRefs: [
+      taskLedger ? { kind: 'task_project_ledger', ledgerId: taskLedger.ledgerId, ledgerPath: paths?.ledgerPath || null } : null,
+      { kind: 'first_class_coach_phase', platform, localPhase: phase, hookEventName: process.env.HOOK_EVENT_NAME || event.hookEventName || event.hook_event_name || null },
+      Object.keys(evidence || {}).length > 0 ? { kind: 'local_evidence', evidence } : null,
+    ].filter(Boolean),
+    qualityGateStatus: evidence.blocked === true ? 'blocked' : 'passed',
+    complianceGateStatus: 'coach_bound',
+    metadata: {
+      bridge_version: RUNTIME_COACH_BRIDGE_VERSION,
+      local_phase: phase,
+      hook_event_name: process.env.HOOK_EVENT_NAME || event.hookEventName || event.hook_event_name || null,
+      task_project_ledger_id: taskLedger?.ledgerId || null,
+      readiness_claim_allowed: taskLedger?.controls?.readinessClaimAllowed === true,
+    },
+  };
+}
+
+async function postRuntimeCoachPhase(body, env = process.env) {
+  const token = readRuntimeToken(env);
+  const headers = { 'Content-Type': 'application/json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const response = await fetch(`${runtimeBaseUrl(env)}${RUNTIME_COACH_ENDPOINT_PATH}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => response.statusText);
+    throw new Error(`runtime ${RUNTIME_COACH_ENDPOINT_PATH} failed (${response.status}): ${detail.slice(0, 500)}`);
+  }
+  return response.json();
+}
+
+export async function recordRuntimeCoachForLifecycle({ platform = 'claude', phase = 'unknown', event = {}, ledgerResult = null, runtimePhases = null, evidence = {}, env = process.env } = {}) {
+  const phases = Array.isArray(runtimePhases) && runtimePhases.length > 0
+    ? runtimePhases
+    : runtimeCoachPhasesForLocalPhase(phase);
+  const results = [];
+  for (const runtimePhase of phases) {
+    const body = buildRuntimeCoachBody({ platform, phase, runtimePhase, event, ledgerResult, evidence });
+    try {
+      results.push(await postRuntimeCoachPhase(body, env));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      appendRuntimeCoachBridgeError({ platform, phase, runtimePhase, message, requestId: body.requestId, sessionId: body.sessionId });
+      results.push({
+        ok: false,
+        permitted: true,
+        decision: 'warn_operator_only',
+        phase: runtimePhase,
+        error: message,
+      });
+    }
+  }
+  const blocking = results.find((result) => result?.permitted === false) || null;
+  return {
+    ok: results.every((result) => result?.ok !== false),
+    platform,
+    phase,
+    runtimePhases: phases,
+    results,
+    blocking,
+  };
+}
+
+export function runtimeCoachBlocksLocalPhase(phase = '', runtimeResult = {}) {
+  if (!RUNTIME_COACH_BLOCKING_LOCAL_PHASES.has(phase)) return null;
+  return runtimeResult?.blocking || null;
+}
+
+export function formatRuntimeCoachBlock(result = {}) {
+  const record = result.record || {};
+  const reasons = Array.isArray(result.reasons)
+    ? result.reasons
+    : Array.isArray(record.reasons)
+      ? record.reasons
+      : ['coach_kernel_policy_block'];
+  return [
+    '=== ARIA RUNTIME COACH BLOCK ===',
+    '',
+    `decision: ${result.decision || record.decision || 'blocked'}`,
+    `coach_event_id: ${record.coach_event_id || 'unknown'}`,
+    `reasons: ${reasons.join(', ') || 'coach_kernel_policy_block'}`,
+    `next: ${result.clientMessage || record.next_action || 'repair the blocked condition and retry'}`,
+    '',
+  ].join('\n');
+}
+
+function writeJsonAtomic(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+function markGate(ledger, gateId, status, evidence = undefined) {
+  const gate = ledger.qualityGates?.[gateId];
+  if (!gate) return;
+  if (gate.status === 'passed' && status !== 'blocked') return;
+  gate.status = status;
+  gate.updatedAt = ledger.updatedAt;
+  if (evidence) gate.evidence = evidence;
+}
+
+function hasPromptIntent(event = {}) {
+  return Boolean(firstString(
+    event.prompt,
+    event.userPrompt,
+    event.user_input,
+    event.message,
+    event.text,
+    event.body,
+    event.context?.prompt,
+    event.context?.bodyForAgent
+  ));
+}
+
+function hasVerificationEvidence(evidence = {}, event = {}) {
+  if (evidence.warning_clean === true || evidence.verification === true || evidence.validation_run === true) return true;
+  if (event.verified === true || event.validation?.ok === true || event.test?.ok === true) return true;
+  const text = firstString(event.verification, event.validation, event.testResult, event.commandResult, evidence.commandResult);
+  return /\b(?:ok|passed|pass|success|succeeded|exit\s*0|0\s*failures?)\b/i.test(text);
+}
+
+function isExecutionPhase(phase = '') {
+  return ['pre_tool', 'post_tool', 'background_worker', 'task_record', 'task_flow', 'lobster_run', 'approval_resume'].includes(phase);
+}
+
+function isPostTurnPhase(phase = '') {
+  return ['post_turn', 'outcome_writeback', 'decision_log'].includes(phase);
+}
+
+export function taskProjectLedgerRoot(env = process.env) {
+  return env.ARIA_TASK_PROJECT_LEDGER_DIR || join(homedir(), '.aria', 'task-project-ledgers');
+}
+
+export function resolveTaskProjectIdentity(event = {}, env = process.env) {
+  const projectRaw = firstString(
+    env.ARIA_PROJECT_ID,
+    event.projectId,
+    event.project_id,
+    event.project,
+    event.workspaceDir,
+    event.workspace_dir,
+    event.cwd,
+    event.currentWorkingDirectory,
+    event.context?.workspaceDir,
+    env.PWD,
+    process.cwd()
+  );
+  const taskRaw = firstString(
+    env.ARIA_TASK_ID,
+    event.taskId,
+    event.task_id,
+    event.session_id,
+    event.sessionId,
+    event.sessionKey,
+    event.conversationId,
+    event.threadId,
+    event.transcript_path,
+    event.prompt,
+    event.message,
+    projectRaw
+  );
+  const projectHash = stableHash(projectRaw || 'unknown-project');
+  const taskHash = stableHash(`${projectHash}:${taskRaw || 'unknown-task'}`);
+  return {
+    projectHash,
+    taskHash,
+    projectHint: compactHint(projectRaw),
+    taskHint: compactHint(taskRaw),
+  };
+}
+
+export function taskProjectLedgerPaths(identity, env = process.env) {
+  const dir = join(taskProjectLedgerRoot(env), identity.projectHash);
+  return {
+    dir,
+    ledgerPath: join(dir, `${identity.taskHash}.json`),
+    eventPath: join(dir, `${identity.taskHash}.events.jsonl`),
+  };
+}
+
+function createTaskProjectLedger(identity, now) {
+  const qualityGates = Object.fromEntries(TASK_PROJECT_QUALITY_GATES.map((gate) => [
+    gate.id,
+    {
+      status: gate.id === 'ledger_created' || gate.id === 'final_claim_guard' ? 'passed' : 'pending',
+      description: gate.description,
+      readinessRequired: gate.readinessRequired,
+      updatedAt: now,
+    },
+  ]));
+  return {
+    schema: `${TASK_PROJECT_LEDGER_VERSION}.ledger`,
+    version: TASK_PROJECT_LEDGER_VERSION,
+    ledgerId: `tpl_${identity.projectHash}_${identity.taskHash}`,
+    createdAt: now,
+    updatedAt: now,
+    status: 'active',
+    identity,
+    controls: {
+      readinessClaimAllowed: false,
+      readinessClaimRule: 'Completion/readiness claims require all readinessRequired quality gates to pass and no open blockers.',
+    },
+    qualityGates,
+    phaseEvents: [],
+    evidence: [],
+    openBlockers: [],
+    blockedClaims: [],
+  };
+}
+
+export function readinessMissingGates(ledger = {}) {
+  const qualityGates = ledger.qualityGates || {};
+  return TASK_PROJECT_QUALITY_GATES
+    .filter((gate) => gate.readinessRequired)
+    .filter((gate) => qualityGates[gate.id]?.status !== 'passed' && qualityGates[gate.id]?.status !== 'not_applicable')
+    .map((gate) => gate.id);
+}
+
+export function updateTaskProjectLedger({ platform, phase, source = 'first-class-coach', event = {}, evidence = {}, env = process.env } = {}) {
+  const now = new Date().toISOString();
+  const identity = resolveTaskProjectIdentity(event, env);
+  const paths = taskProjectLedgerPaths(identity, env);
+  const existing = readJsonFile(paths.ledgerPath);
+  const ledger = existing?.schema === `${TASK_PROJECT_LEDGER_VERSION}.ledger`
+    ? existing
+    : createTaskProjectLedger(identity, now);
+
+  ledger.updatedAt = now;
+  ledger.status = ledger.status || 'active';
+  ledger.identity = ledger.identity || identity;
+  ledger.controls = ledger.controls || {};
+  ledger.qualityGates = ledger.qualityGates || {};
+  for (const gate of TASK_PROJECT_QUALITY_GATES) {
+    if (!ledger.qualityGates[gate.id]) {
+      ledger.qualityGates[gate.id] = {
+        status: 'pending',
+        description: gate.description,
+        readinessRequired: gate.readinessRequired,
+        updatedAt: now,
+      };
+    }
+  }
+
+  markGate(ledger, 'ledger_created', 'passed', { ledgerPath: paths.ledgerPath });
+  if (hasPromptIntent(event) || phase === 'pre_prompt_injection' || phase === 'session_start') {
+    markGate(ledger, 'intent_boundary', 'passed', { source, phase });
+  }
+  if (platform && phase && phase !== 'unknown') {
+    markGate(ledger, 'scope_boundary', 'passed', { platform, phase });
+  }
+  if (isExecutionPhase(phase)) {
+    markGate(ledger, 'execution_trace', 'passed', { platform, phase, source });
+  }
+  if (hasVerificationEvidence(evidence, event)) {
+    markGate(ledger, 'verification_trace', 'passed', { source, phase });
+  }
+  if (isPostTurnPhase(phase)) {
+    markGate(ledger, 'post_turn_writeback', 'passed', { platform, phase, source });
+  }
+  markGate(ledger, 'final_claim_guard', 'passed', { source: 'task_project_ledger_claim_guard' });
+
+  const row = {
+    at: now,
+    platform: platform || inferCoachPlatform(event, env),
+    phase: phase || inferCoachPhase(event, env),
+    source,
+    evidence,
+  };
+  ledger.phaseEvents = Array.isArray(ledger.phaseEvents) ? ledger.phaseEvents : [];
+  ledger.phaseEvents.push(row);
+  if (ledger.phaseEvents.length > MAX_LEDGER_EVENTS) {
+    ledger.phaseEvents = ledger.phaseEvents.slice(-MAX_LEDGER_EVENTS);
+  }
+  if (Object.keys(evidence || {}).length > 0) {
+    ledger.evidence = Array.isArray(ledger.evidence) ? ledger.evidence : [];
+    ledger.evidence.push({ at: now, source, phase: row.phase, evidence });
+    if (ledger.evidence.length > MAX_LEDGER_EVENTS) {
+      ledger.evidence = ledger.evidence.slice(-MAX_LEDGER_EVENTS);
+    }
+  }
+  const missingReadinessGates = readinessMissingGates(ledger);
+  ledger.controls.readinessClaimAllowed = missingReadinessGates.length === 0 && (ledger.openBlockers || []).length === 0;
+  ledger.controls.missingReadinessGates = missingReadinessGates;
+
+  writeJsonAtomic(paths.ledgerPath, ledger);
+  mkdirSync(dirname(paths.eventPath), { recursive: true, mode: 0o700 });
+  appendFileSync(paths.eventPath, `${JSON.stringify({ schema: `${TASK_PROJECT_LEDGER_VERSION}.event`, ledgerId: ledger.ledgerId, ...row })}\n`, { mode: 0o600 });
+  return { ledger, paths, identity };
+}
+
+function extractTextFromContent(value) {
+  if (!value) return '';
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.map(extractTextFromContent).filter(Boolean).join('\n');
+  if (typeof value === 'object') {
+    return firstString(value.text, value.content, value.message) || extractTextFromContent(value.parts);
+  }
+  return '';
+}
+
+export function extractAssistantText(event = {}) {
+  const direct = firstString(
+    event.assistantText,
+    event.assistant_text,
+    event.response,
+    event.output,
+    event.finalText,
+    event.final_text,
+    event.text
+  );
+  if (direct) return direct;
+  const nested = extractTextFromContent(event.message) || extractTextFromContent(event.result) || extractTextFromContent(event.assistant);
+  if (nested) return nested;
+  const transcriptPath = firstString(event.transcript_path, event.transcriptPath);
+  if (!transcriptPath || !existsSync(transcriptPath)) return '';
+  try {
+    const lines = readFileSync(transcriptPath, 'utf8').trim().split('\n').filter(Boolean);
+    for (const line of lines.slice(-100).reverse()) {
+      let parsed;
+      try { parsed = JSON.parse(line); } catch { continue; }
+      const role = parsed.role || parsed.message?.role || parsed.type;
+      if (role !== 'assistant') continue;
+      const text = extractTextFromContent(parsed.content) || extractTextFromContent(parsed.message?.content) || extractTextFromContent(parsed.text);
+      if (text) return text;
+    }
+  } catch {}
+  return '';
+}
+
+export function evaluateTaskProjectClaim({ text = '', ledger = {} } = {}) {
+  const claim = CLAIM_RX.test(String(text || ''));
+  if (!claim) return { ok: true, claim: false, missingReadinessGates: [], openBlockers: [] };
+  const missingReadinessGates = readinessMissingGates(ledger);
+  const openBlockers = Array.isArray(ledger.openBlockers) ? ledger.openBlockers : [];
+  return {
+    ok: missingReadinessGates.length === 0 && openBlockers.length === 0 && ledger.controls?.readinessClaimAllowed === true,
+    claim: true,
+    missingReadinessGates,
+    openBlockers,
+  };
+}
+
+export function recordBlockedTaskProjectClaim({ ledger, paths, text, evaluation } = {}) {
+  if (!ledger || !paths?.ledgerPath) return null;
+  const now = new Date().toISOString();
+  ledger.blockedClaims = Array.isArray(ledger.blockedClaims) ? ledger.blockedClaims : [];
+  ledger.blockedClaims.push({
+    at: now,
+    textHash: stableHash(text || ''),
+    missingReadinessGates: evaluation?.missingReadinessGates || [],
+    openBlockerCount: evaluation?.openBlockers?.length || 0,
+  });
+  ledger.updatedAt = now;
+  writeJsonAtomic(paths.ledgerPath, ledger);
+  return ledger.blockedClaims[ledger.blockedClaims.length - 1];
+}
+
+export function formatTaskProjectLedgerContext({ ledger, paths, platform = 'unknown', phase = 'unknown' } = {}) {
+  const missing = readinessMissingGates(ledger);
+  return [
+    '--- ARIA TASK/PROJECT LEDGER CONTRACT ---',
+    `version: ${TASK_PROJECT_LEDGER_VERSION}`,
+    `ledger_id: ${ledger?.ledgerId || 'unknown'}`,
+    `platform: ${platform}`,
+    `phase: ${phase}`,
+    `project_ref: ${ledger?.identity?.projectHint || 'unknown'}`,
+    `task_ref: ${ledger?.identity?.taskHint || 'unknown'}`,
+    `ledger_event_count: ${Array.isArray(ledger?.phaseEvents) ? ledger.phaseEvents.length : 0}`,
+    `readiness_claim_allowed: ${ledger?.controls?.readinessClaimAllowed === true ? 'true' : 'false'}`,
+    `missing_readiness_gates: ${missing.length > 0 ? missing.join(', ') : 'none'}`,
+    `ledger_path: ${paths?.ledgerPath || 'unknown'}`,
+    'required_behavior: create/update this ledger for every task and project; use it as the controlling anti-drift artifact before tool use, final claims, and long-running handoff.',
+    'claim_rule: do not say done/complete/ready/verified/fixed/shipped unless this ledger has verification evidence and no open blockers.',
+    'quality_rule: every phase must preserve intent, scope, evidence, verification, recovery, and post-turn writeback where applicable.',
+    '--- /ARIA TASK/PROJECT LEDGER CONTRACT ---',
+  ].join('\n');
+}
+
+const PHASE_BY_LABEL = new Map(
+  LIFECYCLE_PHASES.flatMap((phase) => phase.labels.map((label) => [label.toLowerCase(), phase.id]))
+);
+
+export function normalizeCoachPhase(value = '') {
+  const key = String(value || '').trim().toLowerCase();
+  return PHASE_BY_LABEL.get(key) || key.replace(/[^a-z0-9]+/g, '_') || 'unknown';
+}
+
+export function coachEventPath() {
+  return join(homedir(), '.aria', 'first-class-coach-events.jsonl');
+}
+
+export function inferCoachPhase(input = {}, env = process.env) {
+  return normalizeCoachPhase(
+    env.HOOK_EVENT_NAME ||
+      input.hook_event_name ||
+      input.hookEventName ||
+      input.event ||
+      input.type ||
+      input.phase ||
+      ''
+  );
+}
+
+export function inferCoachPlatform(input = {}, env = process.env) {
+  const value = env.ARIA_COACH_PLATFORM || env.ARIA_PLATFORM || input.platform || input.sourceRuntime || input.runtime || 'claude';
+  const normalized = String(value || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_');
+  return PLATFORM_PHASES[normalized] ? normalized : normalized || 'unknown';
+}
+
+export function recordCoachEvent({ platform, phase, source = 'first-class-coach', event = {}, evidence = {} } = {}) {
+  const row = {
+    schema: `${FIRST_CLASS_COACH_VERSION}.event`,
+    at: new Date().toISOString(),
+    platform: platform || inferCoachPlatform(event),
+    phase: phase || inferCoachPhase(event),
+    source,
+    evidence,
+  };
+  const target = coachEventPath();
+  mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+  appendFileSync(target, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+  return row;
+}
+
+export function formatCoachContext({ platform = 'unknown', phase = 'unknown' } = {}) {
+  return [
+    '--- ARIA FIRST-CLASS COACH CONTRACT ---',
+    `version: ${FIRST_CLASS_COACH_VERSION}`,
+    `platform: ${platform}`,
+    `phase: ${phase}`,
+    `definition: ${FIRST_CLASS_ACCEPTANCE.definition}`,
+    `axioms: ${FIRST_CLASS_AXIOMS.join(', ')}`,
+    `domains: ${FIRST_CLASS_DOMAINS.join(', ')}`,
+    `first_principles: ${FIRST_CLASS_PRINCIPLES.join(', ')}`,
+    'required_behavior: coach contract controls the turn; local green checks are insufficient without cross-platform evidence, recovery proof, and warning-clean verification.',
+    'readiness_claim_rule: do not claim first-class/ready/complete until the evidence ledger covers every required platform and lifecycle phase.',
+    'recovery_rule: when evidence is missing, execute one concrete recovery/verification action before emitting status; if repeated, enter architect mode instead of asking the owner to take over.',
+    '--- /ARIA FIRST-CLASS COACH CONTRACT ---',
+  ].join('\n');
+}
+
+export function verifyCoachTopology(registrations = []) {
+  const seen = new Set(registrations.map((entry) => `${entry.platform}:${entry.phase}`));
+  const missing = [];
+  for (const [platform, phases] of Object.entries(PLATFORM_PHASES)) {
+    for (const phase of phases) {
+      if (!seen.has(`${platform}:${phase}`)) missing.push({ platform, phase });
+    }
+  }
+  return { ok: missing.length === 0, missing, requiredCount: Object.values(PLATFORM_PHASES).reduce((sum, phases) => sum + phases.length, 0), observedCount: seen.size };
+}
+
+export function evaluateFirstClassClaim({ text = '', evidence = {} } = {}) {
+  const claim = /\b(?:first[- ]class|production[- ]ready|ready|complete|completed|done|verified|gold[- ]standard)\b/i.test(String(text || ''));
+  if (!claim) return { ok: true, claim: false, missingEvidence: [] };
+  const missingEvidence = FIRST_CLASS_ACCEPTANCE.requiredEvidence.filter((key) => evidence[key] !== true);
+  return { ok: missingEvidence.length === 0, claim: true, missingEvidence };
+}