@aria_asi/cli 0.2.40 → 0.2.41

package/hooks/codex-native/lib/task-project-ledger.mjs

@@ -0,0 +1,294 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, appendFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+export const TASK_PROJECT_LEDGER_VERSION = 'aria.task_project_ledger.v1';
+
+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;
+
+export const TASK_PROJECT_QUALITY_GATES = [
+  { id: 'ledger_created', readinessRequired: true, description: 'A durable task/project ledger exists before work proceeds.' },
+  { id: 'intent_boundary', readinessRequired: true, description: 'The ledger records what task or project is being attempted.' },
+  { id: 'scope_boundary', readinessRequired: true, description: 'The ledger records platform and phase boundaries.' },
+  { id: 'execution_trace', readinessRequired: false, description: 'The ledger records execution, tool, workflow, or background events.' },
+  { id: 'verification_trace', readinessRequired: true, description: 'The ledger records real verification evidence before completion/readiness claims.' },
+  { id: 'post_turn_writeback', readinessRequired: false, description: 'The ledger records post-turn or outcome writeback.' },
+  { id: 'final_claim_guard', readinessRequired: true, description: 'The ledger guards final claims against missing evidence.' },
+];
+
+function stableHash(value = '') {
+  return createHash('sha256').update(String(value || 'unknown')).digest('hex').slice(0, 20);
+}
+
+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 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.goal,
+    event.taskGoal,
+    event.prompt,
+    event.userPrompt,
+    event.user_input,
+    event.message,
+    event.text,
+    event.body,
+    event.sessionID,
+    event.sessionId,
+    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;
+  if (evidence.qa?.ok === true || evidence.qaLearningLoop?.ok === true || event.qa?.ok === true || event.qaLearningLoop?.ok === true) return true;
+  if (['verified', 'verified_narrowly'].includes(String(evidence.endPhaseQaAutofire?.verdict || event.endPhaseQaAutofire?.verdict || ''))) return true;
+  const text = firstString(event.verification, event.validation, event.testResult, event.commandResult, event.evidence, evidence.commandResult, evidence.outputPreview, evidence.evidence);
+  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.sessionID,
+    event.session_id,
+    event.sessionId,
+    event.sessionKey,
+    event.conversationId,
+    event.threadId,
+    event.messageId,
+    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 = 'task-project-ledger', 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.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 || 'unknown',
+    phase: phase || 'unknown',
+    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 = ledger.controls || {};
+  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 };
+}
+
+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');
+}
+
+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];
+}