@aria_asi/cli 0.2.30 → 0.2.32

package/runtime-src/workflow-engine.mjs

@@ -0,0 +1,322 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STATE_DIR = join(__dirname, '..', 'state');
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+function workflowsPath(tenantId) {
+  return join(STATE_DIR, `workflows-${tenantId}.json`);
+}
+
+const WORKFLOW_TEMPLATES = {
+  'lead-qualification-pipeline': {
+    id: 'lead-qualification-pipeline',
+    archetype: 'leadQualifier',
+    name: 'Lead Qualification Pipeline',
+    description: 'Receive inbound lead, classify, enrich data, score, and route to appropriate agent',
+    steps: [
+      { name: 'receive_and_classify', type: 'receive', description: 'Receive lead input and classify by source and intent' },
+      { name: 'enrich_data', type: 'enrich', description: 'Look up additional data points for the lead' },
+      { name: 'score_and_route', type: 'score', description: 'Score the lead and determine routing' },
+      { name: 'approval_gate', type: 'approve', description: 'Confirm routing decision (auto-approve if score above threshold)', autoApprove: { field: 'score', operator: '>=', value: 80 } },
+      { name: 'execute_routing', type: 'execute', description: 'Route lead to assigned agent or pipeline' },
+      { name: 'log_and_notify', type: 'log', description: 'Log the qualification result and notify relevant agents' },
+    ],
+    escalation: { to: 'directorOfSales', condition: 'score >= 90' },
+    retryPolicy: { maxAttempts: 3, backoffMs: 5000 },
+  },
+  'deal-evaluation-pipeline': {
+    id: 'deal-evaluation-pipeline',
+    archetype: 'dealAnalyzer',
+    name: 'Deal Evaluation Pipeline',
+    description: 'Collect deal data, compare terms, assess risk, and provide recommendation',
+    steps: [
+      { name: 'collect_deal_data', type: 'receive', description: 'Gather all deal parameters and context' },
+      { name: 'compare_terms', type: 'enrich', description: 'Compare against historical deals and market benchmarks' },
+      { name: 'risk_assessment', type: 'score', description: 'Evaluate financial, operational, and strategic risks' },
+      { name: 'recommend', type: 'execute', description: 'Generate go/no-go recommendation with rationale' },
+    ],
+    escalation: { to: 'directorOfFinance', condition: 'risk_level == high' },
+    retryPolicy: { maxAttempts: 2, backoffMs: 10000 },
+  },
+  'outreach-sequence': {
+    id: 'outreach-sequence',
+    archetype: 'outboundCloser',
+    name: 'Outreach Sequence',
+    description: 'Target selection, initial contact, follow-up, objection handling, and close',
+    steps: [
+      { name: 'target_selection', type: 'receive', description: 'Identify target prospects based on criteria' },
+      { name: 'initial_contact', type: 'execute', description: 'Send initial outreach message' },
+      { name: 'follow_up', type: 'execute', description: 'Send follow-up based on prospect engagement' },
+      { name: 'objection_handle', type: 'score', description: 'Address objections and refine approach' },
+      { name: 'close', type: 'execute', description: 'Attempt to close or schedule next action' },
+    ],
+    escalation: { to: 'directorOfSales', condition: 'stage == stalled > 3 days' },
+    retryPolicy: { maxAttempts: 5, backoffMs: 86400000 },
+  },
+  'content-calendar': {
+    id: 'content-calendar',
+    archetype: 'contentStrategist',
+    name: 'Content Calendar',
+    description: 'Plan content topics, draft, review, publish, and measure performance',
+    steps: [
+      { name: 'plan_topics', type: 'receive', description: 'Generate content calendar based on strategy and trends' },
+      { name: 'draft_content', type: 'execute', description: 'Create initial content draft' },
+      { name: 'review', type: 'approve', description: 'Review for quality, brand alignment, and compliance' },
+      { name: 'publish', type: 'execute', description: 'Publish approved content to designated channels' },
+      { name: 'measure', type: 'score', description: 'Track performance metrics and feed back into planning' },
+    ],
+    escalation: { to: 'directorOfMarketing', condition: 'engagement < threshold' },
+    retryPolicy: { maxAttempts: 2, backoffMs: 0 },
+  },
+  'deal-lifecycle': {
+    id: 'deal-lifecycle',
+    archetype: 'transactionCoordinator',
+    name: 'Deal Lifecycle',
+    description: 'Initiate deal, track milestones, coordinate stakeholders, verify, and close',
+    steps: [
+      { name: 'initiate', type: 'receive', description: 'Create deal record and assign stakeholders' },
+      { name: 'track_milestones', type: 'enrich', description: 'Monitor and update milestone progress' },
+      { name: 'coordinate', type: 'execute', description: 'Coordinate between parties and resolve blockers' },
+      { name: 'verify', type: 'score', description: 'Final verification of all requirements and documents' },
+      { name: 'close', type: 'execute', description: 'Execute close and update records' },
+    ],
+    escalation: { to: 'chiefOfStaff', condition: 'blocker unresolved > 48h' },
+    retryPolicy: { maxAttempts: 3, backoffMs: 3600000 },
+  },
+  'reporting-cycle': {
+    id: 'reporting-cycle',
+    archetype: 'financialAnalyst',
+    name: 'Reporting Cycle',
+    description: 'Collect financial data, reconcile, analyze, forecast, and produce reports',
+    steps: [
+      { name: 'collect_data', type: 'receive', description: 'Gather financial data from all sources' },
+      { name: 'reconcile', type: 'enrich', description: 'Cross-reference and reconcile discrepancies' },
+      { name: 'analyze', type: 'score', description: 'Perform variance analysis and trend detection' },
+      { name: 'forecast', type: 'enrich', description: 'Generate forward-looking projections' },
+      { name: 'produce_report', type: 'execute', description: 'Compile and distribute report' },
+    ],
+    escalation: { to: 'directorOfFinance', condition: 'variance > 10%' },
+    retryPolicy: { maxAttempts: 2, backoffMs: 0 },
+  },
+  'audit-trail': {
+    id: 'audit-trail',
+    archetype: 'compliance-guard',
+    name: 'Audit Trail',
+    description: 'Monitor activity, flag anomalies, investigate, remediate, and document',
+    steps: [
+      { name: 'monitor', type: 'receive', description: 'Continuously monitor agent outputs and actions' },
+      { name: 'flag', type: 'score', description: 'Flag potential compliance issues or anomalies' },
+      { name: 'investigate', type: 'enrich', description: 'Investigate flagged items for root cause' },
+      { name: 'remediate', type: 'execute', description: 'Apply corrective actions for confirmed violations' },
+      { name: 'document', type: 'log', description: 'Document findings and update compliance records' },
+    ],
+    escalation: { to: 'chiefOfStaff', condition: 'severity == critical' },
+    retryPolicy: { maxAttempts: 3, backoffMs: 5000 },
+  },
+};
+
+export function listWorkflowTemplates() {
+  return Object.values(WORKFLOW_TEMPLATES).map(t => ({
+    id: t.id,
+    archetype: t.archetype,
+    name: t.name,
+    description: t.description,
+    stepCount: t.steps.length,
+    hasApprovalGate: t.steps.some(s => s.type === 'approve'),
+    escalation: t.escalation,
+  }));
+}
+
+export function getWorkflowTemplate(workflowId) {
+  return WORKFLOW_TEMPLATES[workflowId] || null;
+}
+
+export function configureWorkflow(tenantId, workflowId, config = {}) {
+  const template = WORKFLOW_TEMPLATES[workflowId];
+  if (!template) return { ok: false, error: `Unknown workflow: ${workflowId}. Available: ${Object.keys(WORKFLOW_TEMPLATES).join(', ')}` };
+  const pp = workflowsPath(tenantId);
+  let state = existsSync(pp) ? JSON.parse(readFileSync(pp, 'utf-8')) : { configured: [], instances: [] };
+  const existing = state.configured.findIndex(w => w.id === workflowId);
+  const entry = {
+    id: workflowId,
+    templateId: workflowId,
+    config: {
+      agentId: config.agentId || null,
+      trigger: config.trigger || { type: 'manual' },
+      autoApproveThreshold: config.autoApproveThreshold ?? template.steps.find(s => s.type === 'approve')?.autoApprove?.value ?? 80,
+      customSteps: config.customSteps || null,
+      escalationOverride: config.escalationOverride || null,
+      ...config,
+    },
+    configuredAt: new Date().toISOString(),
+  };
+  if (existing >= 0) state.configured[existing] = entry; else state.configured.push(entry);
+  ensureDir(dirname(pp));
+  writeFileSync(pp, JSON.stringify(state, null, 2));
+  return { ok: true, workflow: entry };
+}
+
+export function startWorkflow(tenantId, workflowId, initialPayload = {}) {
+  const template = WORKFLOW_TEMPLATES[workflowId];
+  if (!template) return { ok: false, error: `Unknown workflow: ${workflowId}` };
+  const pp = workflowsPath(tenantId);
+  let state = existsSync(pp) ? JSON.parse(readFileSync(pp, 'utf-8')) : { configured: [], instances: [] };
+  const instance = {
+    instanceId: randomUUID(),
+    workflowId,
+    templateId: workflowId,
+    status: 'running',
+    currentStep: 0,
+    steps: template.steps.map((s, i) => ({
+      ...s,
+      index: i,
+      status: i === 0 ? 'active' : 'pending',
+      startedAt: i === 0 ? new Date().toISOString() : null,
+      completedAt: null,
+      attempts: 0,
+      result: null,
+    })),
+    payload: initialPayload,
+    history: [{ event: 'started', at: new Date().toISOString(), step: 0 }],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  state.instances.push(instance);
+  ensureDir(dirname(pp));
+  writeFileSync(pp, JSON.stringify(state, null, 2));
+  return { ok: true, instance };
+}
+
+export function advanceWorkflow(tenantId, instanceId, stepResult = {}) {
+  const pp = workflowsPath(tenantId);
+  if (!existsSync(pp)) return { ok: false, error: 'No workflows configured' };
+  let state = JSON.parse(readFileSync(pp, 'utf-8'));
+  const instance = (state.instances || []).find(i => i.instanceId === instanceId);
+  if (!instance) return { ok: false, error: `Instance ${instanceId} not found` };
+  if (instance.status !== 'running') return { ok: false, error: `Workflow is ${instance.status}` };
+  const current = instance.steps[instance.currentStep];
+  if (!current) return { ok: false, error: 'No current step' };
+  current.status = 'completed';
+  current.completedAt = new Date().toISOString();
+  current.result = stepResult;
+  instance.history.push({ event: 'step_completed', step: instance.currentStep, result: stepResult, at: new Date().toISOString() });
+  const template = WORKFLOW_TEMPLATES[instance.workflowId];
+  const nextIdx = instance.currentStep + 1;
+  if (nextIdx >= instance.steps.length) {
+    instance.status = 'completed';
+    instance.currentStep = -1;
+    instance.history.push({ event: 'workflow_completed', at: new Date().toISOString() });
+  } else {
+    const nextStep = instance.steps[nextIdx];
+    if (nextStep.type === 'approve') {
+      const autoApprove = nextStep.autoApprove || template?.steps[nextIdx]?.autoApprove;
+      const shouldAutoApprove = autoApprove && stepResult[autoApprove.field] !== undefined &&
+        ((autoApprove.operator === '>=' && stepResult[autoApprove.field] >= autoApprove.value) ||
+         (autoApprove.operator === '>' && stepResult[autoApprove.field] > autoApprove.value) ||
+         (autoApprove.operator === '==' && stepResult[autoApprove.field] == autoApprove.value));
+      if (shouldAutoApprove) {
+        nextStep.status = 'completed';
+        nextStep.completedAt = new Date().toISOString();
+        nextStep.result = { autoApproved: true };
+        instance.history.push({ event: 'auto_approved', step: nextIdx, at: new Date().toISOString() });
+        const afterNext = nextIdx + 1;
+        if (afterNext < instance.steps.length) {
+          instance.currentStep = afterNext;
+          instance.steps[afterNext].status = 'active';
+          instance.steps[afterNext].startedAt = new Date().toISOString();
+        } else {
+          instance.status = 'completed';
+          instance.currentStep = -1;
+          instance.history.push({ event: 'workflow_completed', at: new Date().toISOString() });
+        }
+      } else {
+        nextStep.status = 'awaiting_approval';
+        nextStep.startedAt = new Date().toISOString();
+        instance.currentStep = nextIdx;
+        instance.status = 'awaiting_approval';
+        instance.history.push({ event: 'awaiting_approval', step: nextIdx, at: new Date().toISOString() });
+      }
+    } else {
+      instance.currentStep = nextIdx;
+      nextStep.status = 'active';
+      nextStep.startedAt = new Date().toISOString();
+    }
+  }
+  instance.updatedAt = new Date().toISOString();
+  writeFileSync(pp, JSON.stringify(state, null, 2));
+  return { ok: true, instance };
+}
+
+export function approveWorkflowStep(tenantId, instanceId, approved = true) {
+  const pp = workflowsPath(tenantId);
+  if (!existsSync(pp)) return { ok: false, error: 'No workflows configured' };
+  let state = JSON.parse(readFileSync(pp, 'utf-8'));
+  const instance = (state.instances || []).find(i => i.instanceId === instanceId);
+  if (!instance) return { ok: false, error: `Instance ${instanceId} not found` };
+  if (instance.status !== 'awaiting_approval') return { ok: false, error: 'Workflow is not awaiting approval' };
+  const current = instance.steps[instance.currentStep];
+  if (!current) return { ok: false, error: 'No current step' };
+  if (approved) {
+    current.status = 'completed';
+    current.completedAt = new Date().toISOString();
+    current.result = { approved: true, approvedAt: new Date().toISOString() };
+    instance.history.push({ event: 'approved', step: instance.currentStep, at: new Date().toISOString() });
+    instance.status = 'running';
+    const nextIdx = instance.currentStep + 1;
+    if (nextIdx < instance.steps.length) {
+      instance.currentStep = nextIdx;
+      instance.steps[nextIdx].status = 'active';
+      instance.steps[nextIdx].startedAt = new Date().toISOString();
+    } else {
+      instance.status = 'completed';
+      instance.currentStep = -1;
+      instance.history.push({ event: 'workflow_completed', at: new Date().toISOString() });
+    }
+  } else {
+    current.status = 'rejected';
+    current.completedAt = new Date().toISOString();
+    current.result = { approved: false, rejectedAt: new Date().toISOString() };
+    instance.status = 'rejected';
+    instance.history.push({ event: 'rejected', step: instance.currentStep, at: new Date().toISOString() });
+  }
+  instance.updatedAt = new Date().toISOString();
+  writeFileSync(pp, JSON.stringify(state, null, 2));
+  return { ok: true, instance };
+}
+
+export function getWorkflowStatus(tenantId) {
+  const pp = workflowsPath(tenantId);
+  if (!existsSync(pp)) return { tenantId, configured: [], instances: [], summary: null };
+  const state = JSON.parse(readFileSync(pp, 'utf-8'));
+  const instances = state.instances || [];
+  const summary = {
+    total: instances.length,
+    running: instances.filter(i => i.status === 'running').length,
+    completed: instances.filter(i => i.status === 'completed').length,
+    awaitingApproval: instances.filter(i => i.status === 'awaiting_approval').length,
+    rejected: instances.filter(i => i.status === 'rejected').length,
+  };
+  return { tenantId, configured: state.configured || [], instances: instances.map(i => ({
+    instanceId: i.instanceId,
+    workflowId: i.workflowId,
+    status: i.status,
+    currentStep: i.currentStep >= 0 ? i.steps[i.currentStep]?.name : null,
+    progress: `${i.steps.filter(s => s.status === 'completed').length}/${i.steps.length}`,
+    createdAt: i.createdAt,
+    updatedAt: i.updatedAt,
+  })), summary };
+}
+
+export function getWorkflowInstance(tenantId, instanceId) {
+  const pp = workflowsPath(tenantId);
+  if (!existsSync(pp)) return null;
+  const state = JSON.parse(readFileSync(pp, 'utf-8'));
+  return (state.instances || []).find(i => i.instanceId === instanceId) || null;
+}

package/scripts/bundle-sdk.mjs

@@ -32,6 +32,7 @@ const RUNTIME_DISCIPLINE_DST = resolve(RUNTIME_DST, 'discipline');
 const CONNECTOR_HOOKS_SRC = resolve(PKG_ROOT, 'hooks');
 const OPENCODE_PLUGINS_SRC = resolve(PKG_ROOT, 'opencode-plugins');
 const CLIENT_ONBOARDING_SRC = resolve(PKG_ROOT, 'CLIENT-ONBOARDING.md');
+const DOCTRINE_TRIGGER_MAP_SRC = resolve(CONNECTOR_HOOKS_SRC, 'doctrine_trigger_map.json');
 const REQUIRED_HOOK_FILES = [
   'aria-harness-via-sdk.mjs',
   'aria-pre-tool-gate.mjs',
@@ -287,6 +288,10 @@ if (existsSync(SDK_SKILLS_SRC)) {
 if (existsSync(COGNITIVE_SKILLS_SRC)) {
   copyTree(COGNITIVE_SKILLS_SRC, join(RUNTIME_DISCIPLINE_DST, 'skills', 'aria-cognition'));
 }
+if (existsSync(DOCTRINE_TRIGGER_MAP_SRC)) {
+  copyFileSync(DOCTRINE_TRIGGER_MAP_SRC, join(RUNTIME_DISCIPLINE_DST, 'doctrine_trigger_map.json'));
+  copyFileSync(DOCTRINE_TRIGGER_MAP_SRC, join(RUNTIME_DST, 'doctrine_trigger_map.json'));
+}
 if (existsSync(CONNECTOR_HOOKS_SRC)) {
   copyTree(CONNECTOR_HOOKS_SRC, join(DIST_ASSETS_DST, 'hooks'));
 }

package/src/connectors/claude-code.ts

@@ -1,8 +1,11 @@
-import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync, readdirSync, statSync, lstatSync, realpathSync } from 'fs';
 import { homedir } from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'node:url';
 import type { AriaConfig } from '../config.js';
+import { syncDoctrineTriggerMap } from './doctrine-trigger-map.js';
+import { buildMustReadGuide } from './must-read.js';
+import { connectShell } from './shell.js';
 
 // ── Hooks shipped with this package ──────────────────────────────────
 // The connector installs these into ~/.claude/hooks/ so Claude Code's
@@ -241,16 +244,27 @@ const HOOKS_BLOCK = {
   }],
 };
 
-function installHooks(claudeDir: string, logs: string[], opts: { force?: boolean } = {}): void {
-  const hooksTargetDir = path.join(claudeDir, 'hooks');
-  if (!existsSync(hooksTargetDir)) {
-    mkdirSync(hooksTargetDir, { recursive: true, mode: 0o700 });
+function discoverManagedHookSymlinkTargets(hooksTargetDir: string, logs: string[]): Map<string, string> {
+  const targets = new Map<string, string>();
+  for (const name of HOOK_FILES) {
+    const hookPath = path.join(hooksTargetDir, name);
+    if (!existsSync(hookPath)) continue;
+    try {
+      const stat = lstatSync(hookPath);
+      if (!stat.isSymbolicLink()) continue;
+      const targetPath = realpathSync(hookPath);
+      targets.set(name, targetPath);
+      logs.push(`Detected managed hook symlink: ${name} -> ${targetPath}`);
+    } catch {}
   }
-  const sourceDir = packageHooksDir();
+  return targets;
+}
+
+function installHookHelpersToRoot(sourceDir: string, targetRoot: string, logs: string[]): void {
   for (const dirName of HOOK_DIRS) {
     const srcDir = path.join(sourceDir, dirName);
     if (!existsSync(srcDir)) continue;
-    const dstDir = path.join(hooksTargetDir, dirName);
+    const dstDir = path.join(targetRoot, dirName);
     if (!existsSync(dstDir)) {
       mkdirSync(dstDir, { recursive: true, mode: 0o700 });
     }
@@ -263,42 +277,74 @@ function installHooks(claudeDir: string, logs: string[], opts: { force?: boolean
       if (child.endsWith('.mjs') || child.endsWith('.js')) {
         try { chmodSync(dst, 0o755); } catch {}
       }
-      logs.push(`Installed hook helper: ${dirName}/${child}`);
+      logs.push(`Installed hook helper: ${path.relative(targetRoot, dst)}`);
     }
   }
+}
+
+function installHookFilesToRoot(
+  sourceDir: string,
+  targetRoot: string,
+  logs: string[],
+  opts: { force?: boolean },
+  symlinkTargets: Map<string, string>,
+  preserveSymlinkStubs: boolean,
+): void {
   for (const name of HOOK_FILES) {
     const src = path.join(sourceDir, name);
     if (!existsSync(src)) {
       logs.push(`⚠ hook source missing: ${src} (package may be incomplete)`);
       continue;
     }
-    const dst = path.join(hooksTargetDir, name);
-    // Idempotent skip — if existing file matches bundled file byte-for-byte,
-    // no overwrite + no backup churn. Re-running connect stays clean.
+    const dst = path.join(targetRoot, name);
+    if (preserveSymlinkStubs && symlinkTargets.has(name)) {
+      logs.push(`Preserved managed hook symlink: ${name}`);
+      continue;
+    }
     if (existsSync(dst) && !isSamePath(src, dst) && !opts.force) {
       try {
         const existingContent = readFileSync(dst, 'utf-8');
         const newContent = readFileSync(src, 'utf-8');
         if (existingContent === newContent) {
-          logs.push(`Hook unchanged: ${name}`);
+          logs.push(`Hook unchanged: ${path.relative(targetRoot, dst)}`);
           continue;
         }
       } catch {/* fall through to backup+overwrite */}
     }
-    // Back up any existing real file before overwriting (never silently
-    // clobber a user's customizations).
     if (existsSync(dst) && !isSamePath(src, dst)) {
       const backup = `${dst}.pre-aria-connect.${Date.now()}`;
-      try { copyFileSync(dst, backup); logs.push(`Backed up existing ${name} → ${path.basename(backup)}`); } catch {}
+      try { copyFileSync(dst, backup); logs.push(`Backed up existing ${path.basename(dst)} → ${path.basename(backup)}`); } catch {}
     }
     copyFileSync(src, dst);
-    // Only the .mjs scripts need executable perms; data files (e.g. the
-    // doctrine_trigger_map.json shipped alongside hooks) get default 0o644.
     if (name.endsWith('.mjs') || name.endsWith('.js')) {
       try { chmodSync(dst, 0o755); } catch {}
     }
-    logs.push(`Installed hook: ${name}`);
+    logs.push(`Installed hook: ${path.relative(targetRoot, dst)}`);
+  }
+}
+
+function installHooks(claudeDir: string, logs: string[], opts: { force?: boolean } = {}): void {
+  const hooksTargetDir = path.join(claudeDir, 'hooks');
+  if (!existsSync(hooksTargetDir)) {
+    mkdirSync(hooksTargetDir, { recursive: true, mode: 0o700 });
+  }
+  const sourceDir = packageHooksDir();
+  const symlinkTargets = discoverManagedHookSymlinkTargets(hooksTargetDir, logs);
+  const targetRoots = new Set<string>([hooksTargetDir]);
+  for (const targetPath of symlinkTargets.values()) {
+    targetRoots.add(path.dirname(targetPath));
+  }
+  for (const root of targetRoots) {
+    if (!existsSync(root)) {
+      mkdirSync(root, { recursive: true, mode: 0o700 });
+    }
+    installHookHelpersToRoot(sourceDir, root, logs);
+    installHookFilesToRoot(sourceDir, root, logs, opts, symlinkTargets, root === hooksTargetDir);
   }
+
+  const mustReadPath = path.join(claudeDir, 'ARIA_MUST_READ.md');
+  writeFileSync(mustReadPath, buildMustReadGuide('claude'), { mode: 0o644 });
+  logs.push(`Installed Claude must-read guide → ${mustReadPath}`);
 }
 
 // Install bundled SDK to ~/.claude/aria-sdk/. Hooks dynamic-import from this
@@ -389,6 +435,8 @@ Before any tool call, Read the harness packet at: $ARIA_HARNESS_PACKET_PATH
 (path is also in your environment as ARIA_HARNESS_PACKET_PATH variable)
 Cite it in your first cognition block — reference at least one axiom + one frame + one memory class from the packet.
 Without packet-citation in your first cognition block, your output will be rejected by aria-pre-tool-gate.mjs in your sub-process.
+
+If you are a spawned sub-agent, also read the active Aria handoff file when present. Use its cognitionOperatingMethod to execute the task: substrate first, constraints second, action shape third, evidence return last. Your final response to the parent must include substrate used, decision delta, artifact impact, evidence, and unresolved risk.
 [/ARIA_HARNESS_BINDING]
 
 [ARIA_DISCOVERY_RECORDING — when you find a defect, doctrine violation, or notable observation during work]
@@ -397,6 +445,57 @@ Record findings to your session ledger via:
 This makes findings visible to the parent session's ledger-merge hook + the auto-fix spawner.
 [/ARIA_DISCOVERY_RECORDING]`;
 
+const ARIA_GATE_PHASE_DIRECTIVE = `[ARIA_GATE_SHAPE — DO THIS EVERY TURN]
+PRE-GATE before the first non-trivial tool call or non-trivial answer:
+1. Read the harness packet and any [ARIA_DIRECTION] / [ARIA_BINDING_PLAN] context already injected this turn.
+2. Choose the action shape before acting: tool call, text-only answer, or replan.
+3. Emit a visible <cognition> block using the required labels for this surface. Each lens must cite loaded substrate anchors and change the action, not merely describe values.
+4. Emit <applied_cognition> for every non-trivial answer or tool action so the model proves what cognition changed.
+5. If the action is destructive, deployment-related, or materially mutates state, emit a <verify> block before the tool call.
+6. If the action claims or changes an outcome, emit an <expected> block with a measurable predicate before the tool call or final answer.
+
+MID-GATE when a hook blocks or warns:
+1. Do not repeat the same tool call or same draft unchanged.
+2. Name the exact missing requirement in one line.
+3. Re-emit the missing structure only: <cognition>, <verify>, <expected>, and/or <reflection>.
+4. Change the plan before retrying. If recovering from a repeated block, do not put the retrying tool call in the same message as the diagnosis.
+5. If the blocker is stale gate residue or stale ledger state, say that explicitly. Never invent proofOfFix or fake task resolution.
+
+LOOP-RECOVERY after the second block of the same shape:
+1. Emit [LOOP_RECOVERY gate=<name> cause=<one line>] in plain text.
+2. Summarize what repeated, what changed, and why the next attempt is materially different.
+3. Produce the corrected preflight structure first. Retry only after the structure is complete.
+
+OUTPUT-GATE before final emission:
+1. Keep user-visible cognition readable, but preserve the canonical lens labels. Readability comes from the prose inside each lens, never from replacing the lens names.
+2. If Mizan warns, include <reflection> addressing the exact warning instead of repeating lens text.
+3. Discoveries are atomic with their fixes. Either fix inline now or bind to a real tracked task with proof-shaped evidence.
+[/ARIA_GATE_SHAPE]`;
+
+const ARIA_STRUCTURAL_COGNITION_CONTRACT = `[ARIA_STRUCTURAL_COGNITION_CONTRACT — NON-NEGOTIABLE]
+The harness is not a style guide. It is a runtime contract.
+
+Aria cognition is a work method, not a footer. Use it to improve the input and output before gates fire:
+1. Perceive the real substrate: user intent, repo/runtime state, loaded harness packet, memories, prior tool results, and uncertainty.
+2. Infer constraints: what must be true, what must not be harmed, what prior doctrine changes, and what evidence is missing.
+3. Shape the next action: choose the smallest useful tool call, edit, question, or answer that satisfies those constraints.
+4. Improve the artifact: make the tool input, code change, review finding, or prose more specific because of the cognition.
+5. Predict the observable result: define what would prove the action or answer succeeded before claiming it.
+6. Report evidence: final output should distinguish observed fact, bounded inference, unresolved risk, and next real action.
+
+For every non-trivial response or action:
+1. <cognition> must use the canonical lens labels for the active tier and each lens must contain real substrate anchors: axiom:, frame:, memory:, doctrine:, packet:, or active language:.
+2. The cognition must reference first_principle explicitly and only cite substrate that was loaded this turn.
+3. Each lens must affect the action: if a lens reveals risk, missing evidence, or a better path, change the tool input/output accordingly.
+4. <applied_cognition> must include all fields exactly: decision_delta, dominant_domain, binds_to, expected_predicate, artifact_change.
+5. decision_delta must name what changed because cognition ran. Values like none, unchanged, no change, or n/a are rejected.
+6. binds_to must name the exact answer, tool call, file mutation, deploy, review, or decision being shaped.
+7. expected_predicate must be observable: numeric, boolean, state string, command result, endpoint result, or explicit unverified boundary.
+8. artifact_change must describe the semantic effect on the artifact or output, not restate the task.
+9. If a gate blocks, do not apologize-loop. Read the block reason, re-open the must-read guide, and re-author the missing structure before retrying.
+10. Before long or risky final prose, dry-run the draft with the Claude pre-emit validator when available.
+[/ARIA_STRUCTURAL_COGNITION_CONTRACT]`;
+
 function buildAriaSystemBlock(config: AriaConfig): string {
   const repoList = config.repositories.map((r) => `- ${r.name} (${r.path})`).join('\n');
   const schemaText = Object.entries(config.schemaImages)
@@ -410,6 +509,8 @@ You are augmented with Aria's cognitive harness. This provides:
 - 8-lens cognition: multi-perspective analysis for every decision
 
 ${ARIA_HARNESS_BINDING_PREFIX}
+${ARIA_GATE_PHASE_DIRECTIVE}
+${ARIA_STRUCTURAL_COGNITION_CONTRACT}
 
 [SELF-GATE PROTOCOL]
 Before emitting any claim, verify against these hard constraints:
@@ -463,8 +564,10 @@ export async function connectClaudeCode(
     ? settings.systemPromptPrefix
     : '';
 
-  if (existing.includes('ARIA HARNESS')) {
-    logs.push('Aria harness prefix already present — skipping prompt injection');
+  const ariaBlockRx = /<!-- ARIA HARNESS.*?<!-- END ARIA HARNESS -->/s;
+  if (ariaBlockRx.test(existing)) {
+    settings.systemPromptPrefix = existing.replace(ariaBlockRx, ariaBlock);
+    logs.push('Refreshed Aria harness systemPromptPrefix block');
   } else {
     settings.systemPromptPrefix = existing
       ? `${ariaBlock}\n\n${existing}`
@@ -477,6 +580,7 @@ export async function connectClaudeCode(
   // just a system-prompt addendum.
   installHooks(claudeDir, logs, { force: opts.force });
   installSdk(claudeDir, logs);
+  syncDoctrineTriggerMap(logs);
   wireHooksBlock(settings, logs);
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
 
@@ -498,6 +602,8 @@ export async function connectClaudeCode(
     }
   }
 
+  logs.push(...await connectShell('claude', config));
+
   return logs;
 }