@aria_asi/cli 0.2.39 → 0.2.41

package/scripts/self-test-qiyas-label-alignment.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// Guard against F2 recurrence: verify END_OF_PHASE_QA_QIYAS_15 / PROJECT_END_QIYAS_PERSPECTIVES
+// / ARIA_QIYAS_15_PERSPECTIVES position-by-position semantically match atlas kernel's
+// QIYAS_PERSPECTIVES. The kernel-row index map only works when the display list is
+// 1:1 with the canonical list; if the display list collapses/splits a perspective,
+// kernel verdicts get assigned to wrong labels (the F2 bug discovered 2026-05-17).
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { QIYAS_PERSPECTIVES } from '../runtime-src/lib/kernel/deterministic-cognitive-kernel.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '..', '..', '..');
+
+// Mapping from kernel canonical (snake_case) -> expected display family.
+// Each kernel name maps to a list of substring markers; the display label
+// at the same index must contain at least one marker.
+const EXPECTED_FAMILIES = {
+  owner_now: ['owner', 'now'],
+  owner_future: ['owner', 'future'],
+  operator_client: ['operator'],
+  investor_or_buyer: ['investor'],
+  llm_consumer: ['llm'],
+  human_end_user: ['human', 'end-user'],
+  skeptic: ['skeptic'],
+  compliance: ['compliance'],
+  engineering_quality: ['engineering'],
+  cognitive_load: ['cognitive'],
+  scale: ['scale'],
+  islamic_scholar: ['islamic'],
+  clinical_scholar: ['clinical'],
+  red_team_attacker: ['red-team'],
+  future_self: ['future'],
+};
+
+const TARGETS = [
+  { file: 'ops/claude-hooks/lib/end-phase-qa-autofire.mjs', symbol: 'END_OF_PHASE_QA_QIYAS_15' },
+  { file: 'ops/claude-hooks/lib/project-boundary-cognition.mjs', symbol: 'PROJECT_END_QIYAS_PERSPECTIVES' },
+  { file: 'ops/claude-hooks/codex-native/lib/runtime-client.mjs', symbol: 'ARIA_QIYAS_15_PERSPECTIVES' },
+  { file: 'ops/claude-hooks/codex-native/lib/runtime-client.mjs', symbol: 'END_OF_PHASE_QA_QIYAS_15' },
+  { file: 'packages/aria-connector/hooks/lib/end-phase-qa-autofire.mjs', symbol: 'END_OF_PHASE_QA_QIYAS_15' },
+  { file: 'packages/aria-connector/hooks/lib/project-boundary-cognition.mjs', symbol: 'PROJECT_END_QIYAS_PERSPECTIVES' },
+  { file: 'packages/aria-connector/hooks/codex-native/lib/runtime-client.mjs', symbol: 'ARIA_QIYAS_15_PERSPECTIVES' },
+  { file: 'packages/aria-connector/hooks/codex-native/lib/runtime-client.mjs', symbol: 'END_OF_PHASE_QA_QIYAS_15' },
+];
+
+function extractArray(text, symbol) {
+  const rx = new RegExp(`(?:export\\s+)?const\\s+${symbol}\\s*=\\s*Object\\.freeze\\(\\[([\\s\\S]*?)\\]\\)`);
+  const m = text.match(rx);
+  if (!m) return null;
+  const body = m[1];
+  const items = [];
+  for (const line of body.split('\n')) {
+    const s = line.replace(/\/\/.*$/, '').trim();
+    const q = s.match(/^['"]([^'"]+)['"]\s*,?\s*$/);
+    if (q) items.push(q[1]);
+  }
+  return items;
+}
+
+let pass = 0, fail = 0;
+function ok(n) { console.log(`  ok  - ${n}`); pass++; }
+function bad(n, d) { console.log(`  FAIL - ${n}\n        ${d}`); fail++; }
+
+if (QIYAS_PERSPECTIVES.length !== 15) {
+  bad('kernel exports 15 perspectives', `actual=${QIYAS_PERSPECTIVES.length}`);
+} else ok('kernel exports 15 perspectives');
+
+for (const { file, symbol } of TARGETS) {
+  const path = resolve(ROOT, file);
+  let text;
+  try { text = readFileSync(path, 'utf8'); }
+  catch (e) { bad(`${file}::${symbol} readable`, e.message); continue; }
+  const arr = extractArray(text, symbol);
+  if (!arr) { bad(`${file}::${symbol} extractable`, 'no Object.freeze([...]) match'); continue; }
+  if (arr.length !== 15) { bad(`${file}::${symbol} length=15`, `actual=${arr.length}`); continue; }
+  let aligned = true;
+  for (let i = 0; i < 15; i++) {
+    const canonical = QIYAS_PERSPECTIVES[i];
+    const display = arr[i].toLowerCase();
+    const family = EXPECTED_FAMILIES[canonical] || [];
+    if (!family.some((marker) => display.includes(marker))) {
+      bad(`${file}::${symbol}[${i}]`, `expected family ${JSON.stringify(family)} (canonical=${canonical}) got display="${arr[i]}"`);
+      aligned = false;
+      break;
+    }
+  }
+  if (aligned) ok(`${file}::${symbol} aligned 1:1 with kernel QIYAS_PERSPECTIVES`);
+}
+
+console.log();
+console.log(`qiyas label alignment: ${pass} pass, ${fail} fail`);
+process.exit(fail === 0 ? 0 : 1);

package/scripts/self-test-recovery-context.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Recovery context lib unit test (M1.2 — Bug B fix).
+ *
+ * Doctrine bind:
+ *   - feedback_no_graceful_degradation.md — recovery contract MUST be delivered
+ *     to the next-turn model, never silently dropped
+ *   - aria-repo-doctrine — real implementation, real proof
+ *
+ * Validates lib/recovery-context.mjs end-to-end:
+ *   1. readGovernanceRecoveryContext returns empty when no file present
+ *   2. readGovernanceRecoveryContext returns block + pickupId for a valid file
+ *   3. archiveRecoveryAfterPickup moves the file to the archive dir
+ *   4. After archive, readGovernanceRecoveryContext is empty again
+ *   5. Malformed file returns empty + writes stderr (no silent crash)
+ */
+
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Sandbox HOME so we don't touch the real ~/.aria/
+const tempHome = mkdtempSync(join(tmpdir(), 'aria-recovery-test-'));
+process.env.HOME = tempHome;
+const realHome = homedir();
+// Some platforms cache HOME via os.homedir() on first call; we set HOME first.
+assert.equal(realHome, tempHome, `expected sandboxed HOME ${tempHome}, got ${realHome}`);
+
+const ariaDir = join(tempHome, '.aria');
+const recoveryPath = join(ariaDir, 'governance-recovery-current.json');
+const archiveDir = join(ariaDir, 'governance-recovery-archive');
+mkdirSync(ariaDir, { recursive: true });
+
+// Re-import after HOME is set so module-level path resolution uses the sandbox
+const repoRoot = join(import.meta.dirname, '..', '..', '..');
+const libPath = join(repoRoot, 'ops', 'claude-hooks', 'lib', 'recovery-context.mjs');
+const lib = await import(pathToFileURL(libPath));
+
+// ── 1. Empty when no file ──────────────────────────────────────────────────
+const empty = lib.readGovernanceRecoveryContext();
+assert.equal(empty.block, '', 'no recovery file → empty block');
+assert.equal(empty.pickupId, null, 'no recovery file → null pickupId');
+
+// ── 2. Valid file → block + pickupId ───────────────────────────────────────
+const sampleRecovery = {
+  schema: 'aria.governance_recovery_current.v1',
+  updatedAt: new Date().toISOString(),
+  ok: true,
+  decision: 'block',
+  source: 'aria-stop-gate',
+  governanceMode: 'recovery-required',
+  recoveryLoop: {
+    fingerprint: 'abc123def456ghi789',
+    allowedRecoveryAttempts: 1,
+    priorRecoveryAttempts: 0,
+    remainingRecoveryAttempts: 1,
+    nextStep: 'Re-author the blocked output using the recovery contract',
+    architectFallback: 'use the strongest available client LLM under architect harness',
+  },
+  recoveryContract: {
+    retry: 'one attempt',
+    repairRecoveryCycle: ['re-author', 'verify'],
+    retest: 'submit revised output through the gate',
+  },
+};
+writeFileSync(recoveryPath, JSON.stringify(sampleRecovery, null, 2));
+
+const valid = lib.readGovernanceRecoveryContext();
+assert.match(valid.block, /CURRENT GOVERNANCE RECOVERY CONTEXT/, 'block contains header');
+assert.match(valid.block, /Mode: recovery-required/, 'block contains mode');
+assert.match(valid.block, /Decision: block/, 'block contains decision');
+assert.match(valid.block, /Fingerprint: abc123def456ghi789/, 'block contains fingerprint');
+assert.match(valid.block, /Re-author the blocked output/, 'block contains nextStep');
+assert.equal(valid.pickupId, 'abc123def456ghi789', 'pickupId is the recovery fingerprint');
+
+// ── 3. Archive moves the file ──────────────────────────────────────────────
+lib.archiveRecoveryAfterPickup(valid.pickupId);
+assert.ok(!existsSync(recoveryPath), 'recovery file moved out of live path');
+assert.ok(existsSync(archiveDir), 'archive dir created');
+const archived = readdirSync(archiveDir);
+assert.equal(archived.length, 1, 'one archived recovery file present');
+assert.match(archived[0], /^recovery-.*-abc123def456\.json$/, 'archive file named with timestamp + pickup prefix');
+
+// ── 4. After archive, read returns empty ───────────────────────────────────
+const afterArchive = lib.readGovernanceRecoveryContext();
+assert.equal(afterArchive.block, '', 'post-archive block empty');
+assert.equal(afterArchive.pickupId, null, 'post-archive pickupId null');
+
+// ── 5. Malformed JSON returns empty (no silent crash) ──────────────────────
+writeFileSync(recoveryPath, 'this is not json {{{ broken');
+const malformed = lib.readGovernanceRecoveryContext();
+assert.equal(malformed.block, '', 'malformed file → empty block (logged to stderr per doctrine)');
+assert.equal(malformed.pickupId, null, 'malformed file → null pickupId');
+
+// ── 6. Mode=allow returns empty (advisory state, not block-required) ──────
+writeFileSync(recoveryPath, JSON.stringify({
+  ok: true,
+  decision: 'allow',
+  governanceMode: 'allow',
+}));
+const allowed = lib.readGovernanceRecoveryContext();
+assert.equal(allowed.block, '', 'governanceMode=allow → empty block (no recovery needed)');
+
+// ── Cleanup ────────────────────────────────────────────────────────────────
+rmSync(tempHome, { recursive: true, force: true });
+
+console.log('OK self-test-recovery-context (M1.2 lib unit checks pass)');

package/scripts/self-test-repo-guard.mjs

@@ -8,6 +8,16 @@ import { pathToFileURL } from 'node:url';
 import { execFileSync } from 'node:child_process';
 
 const repoRoot = join(import.meta.dirname, '..', '..', '..');
+const previousAriaHome = process.env.ARIA_HOME;
+const isolatedAriaHome = mkdtempSync(join(tmpdir(), 'aria-repo-guard-home-'));
+process.env.ARIA_HOME = isolatedAriaHome;
+
+process.on('exit', () => {
+  if (previousAriaHome === undefined) delete process.env.ARIA_HOME;
+  else process.env.ARIA_HOME = previousAriaHome;
+  rmSync(isolatedAriaHome, { recursive: true, force: true });
+});
+
 const modulePath = pathToFileURL(join(repoRoot, 'packages/aria-connector/dist/aria-connector/src/connectors/repo-guard.js'));
 const { approveRepoGuardDelete, isRepoGuardedPath } = await import(modulePath);
 

package/scripts/self-test-runtime-health-self-heal.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+const serviceSource = readFileSync(path.join(packageRoot, 'runtime-src', 'service.mjs'), 'utf8');
+const taskRunnerSource = readFileSync(path.join(packageRoot, 'src', 'task-runner.ts'), 'utf8');
+
+assert.match(serviceSource, /url\.pathname === '\/health\/ready'/, 'runtime must expose a readiness health route');
+assert.match(serviceSource, /function runtimeLivenessHealth\(\)/, 'liveness health must use a minimal in-process response');
+const livenessRouteBlock = serviceSource.match(/if \(req\.method === 'GET' && url\.pathname === '\/health'\) \{[\s\S]*?\n  \}/)?.[0] || '';
+assert.ok(livenessRouteBlock, 'liveness route block must be inspectable');
+assert.doesNotMatch(livenessRouteBlock, /runtimeManifest/, 'liveness health must not build the full runtime manifest');
+assert.match(serviceSource, /runtimeManifest\(\{ checkAvailability: true \}\)/, 'readiness health must run dependency checks');
+assert.match(serviceSource, /async function hivePostgresAvailable\(\)/, 'readiness dependency probe must be async');
+assert.match(serviceSource, /createConnection\(\{ host, port \}\)/, 'readiness dependency probe must use non-blocking socket connect');
+assert.doesNotMatch(serviceSource, /psqlCheck/, 'readiness dependency probe must not spawn psql version checks');
+assert.match(serviceSource, /HIVE_POSTGRES_QUERY_BUDGET_MS/, 'Postgres query execution must declare a bounded query budget');
+assert.match(serviceSource, /new Pool\(\{/, 'Postgres Hive execution must use an async pg pool');
+assert.match(serviceSource, /query_timeout: HIVE_POSTGRES_QUERY_BUDGET_MS/, 'Postgres Hive queries must be budgeted in the pg client');
+assert.doesNotMatch(serviceSource, /spawnSync\('timeout'|spawnSync\('psql'|psqlCheck/, 'Postgres Hive execution must not shell out synchronously');
+assert.match(serviceSource, /postgres_availability_checked/, 'health payload must declare whether dependency checks ran');
+assert.match(taskRunnerSource, /runtimePublishOutboxPath/, 'task runner must expose runtime publish outbox path');
+assert.match(taskRunnerSource, /runtime_ledger_publish_failed/, 'task runner must record runtime publish failures locally');
+assert.match(taskRunnerSource, /queued_for_runtime_publish_replay/, 'task runner must queue failed runtime publishes for replay');
+assert.match(taskRunnerSource, /runtime_ledger_publish_replayed/, 'task runner must record runtime publish replay success');
+
+function spawnCapture(command, args, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options);
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('close', (status, signal) => resolve({ status, signal, stdout, stderr }));
+    child.on('error', (error) => resolve({ status: null, signal: null, stdout, stderr: String(error.message || error) }));
+  });
+}
+
+const ariaHome = mkdtempSync(path.join(tmpdir(), 'aria-task-self-heal-'));
+const taskRoot = path.join(ariaHome, '.aria', 'cli-tasks');
+mkdirSync(taskRoot, { recursive: true, mode: 0o700 });
+
+const taskId = 'self-heal-ledger-smoke';
+const taskState = {
+  schema: 'aria.cli_task.v2',
+  taskId,
+  goal: 'Smoke local task writes survive runtime publish failure.',
+  cwd: repoRoot,
+  status: 'active',
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+  requiredSkills: [],
+  forcedSkillLoad: null,
+  projectContext: null,
+  qualityLoops: [],
+  checkpoints: [],
+  phases: [],
+  activePhaseId: null,
+  recovery: { attempts: 0, lastReason: null, lastAt: null },
+};
+writeFileSync(path.join(taskRoot, `${taskId}.json`), `${JSON.stringify(taskState, null, 2)}\n`, { mode: 0o600 });
+
+const result = spawnSync(process.execPath, [
+  path.join(packageRoot, 'bin', 'aria.js'),
+  'task',
+  'checkpoint',
+  taskId,
+  '--phase',
+  'self-heal-smoke',
+  '--summary',
+  'Local checkpoint survives runtime publish failure.',
+  '--evidence',
+  'runtime url points to a closed local port for this smoke',
+], {
+  cwd: repoRoot,
+  env: {
+    ...process.env,
+    ARIA_HOME: ariaHome,
+    ARIA_RUNTIME_URL: 'http://127.0.0.1:9',
+  },
+  encoding: 'utf8',
+  maxBuffer: 1024 * 1024,
+});
+
+assert.equal(result.status, 0, `aria task checkpoint must not fail after local save when runtime publish fails: ${result.stderr || result.stdout}`);
+
+const taskFiles = readdirSync(taskRoot).sort();
+assert.ok(taskFiles.includes(`${taskId}.json`), 'task state file missing');
+assert.ok(taskFiles.includes(`${taskId}.events.jsonl`), 'task event file missing');
+assert.ok(taskFiles.includes(`${taskId}.runtime-publish-outbox.jsonl`), 'runtime publish outbox missing');
+
+const events = readFileSync(path.join(taskRoot, `${taskId}.events.jsonl`), 'utf8');
+const outbox = readFileSync(path.join(taskRoot, `${taskId}.runtime-publish-outbox.jsonl`), 'utf8');
+assert.match(events, /"type":"checkpoint"/, 'checkpoint event missing');
+assert.match(events, /runtime_ledger_publish_failed/, 'runtime publish failure event missing');
+assert.match(outbox, /queued_for_runtime_publish_replay/, 'outbox replay marker missing');
+
+const requests = [];
+const server = createServer((req, res) => {
+  let raw = '';
+  req.on('data', (chunk) => { raw += chunk; });
+  req.on('end', () => {
+    requests.push({ method: req.method, url: req.url, body: raw });
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ ok: true }));
+  });
+});
+await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+const address = server.address();
+assert.equal(typeof address, 'object', 'test server address missing');
+const runtimeUrl = `http://127.0.0.1:${address.port}`;
+const replayResult = await spawnCapture(process.execPath, [
+  path.join(packageRoot, 'bin', 'aria.js'),
+  'task',
+  'checkpoint',
+  taskId,
+  '--phase',
+  'self-heal-replay-smoke',
+  '--summary',
+  'Runtime publish outbox replays when runtime is reachable.',
+  '--evidence',
+  'local fake runtime accepted current and queued publish records',
+], {
+  cwd: repoRoot,
+  env: {
+    ...process.env,
+    ARIA_HOME: ariaHome,
+    ARIA_RUNTIME_URL: runtimeUrl,
+  },
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+await new Promise((resolve) => server.close(resolve));
+
+assert.equal(replayResult.status, 0, `aria task checkpoint replay smoke failed: ${replayResult.stderr || replayResult.stdout}`);
+assert.ok(requests.length >= 2, `expected current publish plus replay publish, got ${requests.length}`);
+const afterReplayEvents = readFileSync(path.join(taskRoot, `${taskId}.events.jsonl`), 'utf8');
+const afterReplayOutbox = readFileSync(path.join(taskRoot, `${taskId}.runtime-publish-outbox.jsonl`), 'utf8');
+assert.match(afterReplayEvents, /runtime_ledger_publish_replayed/, 'replay success event missing');
+assert.equal(afterReplayOutbox.trim(), '', 'outbox should be empty after successful replay');
+
+console.log(JSON.stringify({
+  ok: true,
+  taskId,
+  ariaHome,
+  checks: [
+    'health_liveness_readiness_split',
+    'task_runtime_publish_failure_outbox',
+    'local_checkpoint_exit_zero_when_publish_fails',
+    'runtime_publish_outbox_replay',
+  ],
+}, null, 2));

package/scripts/self-test-runtime-postcondition.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const runtimeUrl = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+const envPath = join(homedir(), '.aria', 'runtime', 'runtime.env');
+
+function parseEnvFile(text) {
+  const env = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const index = line.indexOf('=');
+    if (index <= 0) continue;
+    env[line.slice(0, index).trim()] = line.slice(index + 1);
+  }
+  return env;
+}
+
+function readRuntimePid() {
+  return execFileSync('/bin/systemctl', ['--user', 'show', 'aria-mounted-runtime.service', '-p', 'MainPID', '--value'], {
+    encoding: 'utf8',
+  }).trim();
+}
+
+function readProcessEnv(pid) {
+  return parseEnvFile(readFileSync(`/proc/${pid}/environ`, 'utf8').replace(/\0/g, '\n'));
+}
+
+function redactPostgresUrl(value) {
+  return String(value || '').replace(/(postgres(?:ql)?:\/\/[^:@/]+:)[^@/]+@/i, '$1<redacted>@');
+}
+
+const fileEnv = parseEnvFile(readFileSync(envPath, 'utf8'));
+const pid = readRuntimePid();
+const processEnv = readProcessEnv(pid);
+
+assert.equal(processEnv.ARIA_HIVE_STORAGE, fileEnv.ARIA_HIVE_STORAGE, 'running runtime ARIA_HIVE_STORAGE must match runtime.env');
+assert.equal(processEnv.ARIA_HIVE_POSTGRES_URL, fileEnv.ARIA_HIVE_POSTGRES_URL, 'running runtime ARIA_HIVE_POSTGRES_URL must match runtime.env');
+
+const storageResponse = await fetch(`${runtimeUrl}/api/hive/storage`);
+assert.equal(storageResponse.ok, true, `/api/hive/storage failed: ${storageResponse.status}`);
+const storage = await storageResponse.json();
+assert.equal(storage.ok, true);
+assert.equal(storage.storage.mode, fileEnv.ARIA_HIVE_STORAGE);
+
+if (fileEnv.ARIA_HIVE_STORAGE === 'postgres') {
+  assert.equal(storage.storage.postgres_local_only, true);
+  assert.equal(storage.storage.postgres_available, true);
+  assert.equal(storage.storage.postgres_forbidden_reason, null);
+}
+
+console.log(JSON.stringify({
+  ok: true,
+  runtimeUrl,
+  pid,
+  assertions: {
+    processEnvMatchesRuntimeEnv: true,
+    storageEndpointMatchesRuntimeEnv: true,
+    postgresReadyWhenConfigured: fileEnv.ARIA_HIVE_STORAGE === 'postgres',
+  },
+  runtimeEnv: {
+    ARIA_HIVE_STORAGE: fileEnv.ARIA_HIVE_STORAGE,
+    ARIA_HIVE_POSTGRES_URL: redactPostgresUrl(fileEnv.ARIA_HIVE_POSTGRES_URL),
+  },
+}, null, 2));

package/scripts/self-test-soul-precommit-hook.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..', '..');
+const hookPath = resolve(repoRoot, '.husky', 'pre-commit');
+const hook = readFileSync(hookPath, 'utf8');
+
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+const shellCheck = spawnSync('sh', ['-n', hookPath], {
+  cwd: repoRoot,
+  encoding: 'utf8',
+});
+
+assert(shellCheck.status === 0, `pre-commit shell parse failed: ${shellCheck.stderr || shellCheck.stdout}`);
+assert(hook.includes('SOUL_HASH_SALT='), 'soul hook must keep a salt for hash-only authorization');
+assert(/SOUL_PASSPHRASE_SHA256="[a-f0-9]{64}"/.test(hook), 'soul hook must store a 64-char sha256, not a plaintext passphrase');
+assert(hook.includes("printf '%s' \"${PASSPHRASE}${SOUL_HASH_SALT}\""), 'soul hook must hash exact passphrase+salt with printf');
+assert(hook.includes('stty -echo'), 'soul hook must hide terminal input in POSIX sh');
+assert(!hook.includes('read -s'), 'soul hook must not use bash-only read -s under /usr/bin/env sh');
+assert(!hook.includes('echo -n "${PASSPHRASE}'), 'soul hook must not use echo -n for hash input');
+assert(!hook.includes('PASSPHRASE" !='), 'soul hook must not compare plaintext passphrases');
+assert(!hook.includes('a]f1c2'), 'soul hook must not keep the malformed legacy hash literal');
+
+if (failures.length > 0) {
+  console.error('[self-test-soul-precommit-hook] FAIL');
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log('[self-test-soul-precommit-hook] OK - soul pre-commit authorization is POSIX-safe and hash-only');