@aria_asi/cli 0.2.36 → 0.2.38

package/scripts/check-managed-runtime-ledger.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..', '..');
+const packageRoot = resolve(here, '..');
+const failures = [];
+
+function fail(check, message, details = {}) {
+  failures.push({ check, message, details });
+}
+
+function readText(pathname) {
+  return existsSync(pathname) ? readFileSync(pathname, 'utf8') : '';
+}
+
+function readJson(pathname) {
+  try {
+    return JSON.parse(readText(pathname));
+  } catch (error) {
+    fail('ledger-json', `invalid JSON at ${pathname}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+const ledgerPath = resolve(repoRoot, 'docs', 'system', 'ARIA_MANAGED_RUNTIME_PROVIDER_QUALITY_LEDGER.json');
+const servicePath = resolve(packageRoot, 'runtime-src', 'service.mjs');
+const providerProxyPath = resolve(packageRoot, 'runtime-src', 'provider-proxy.mjs');
+const packageJsonPath = resolve(packageRoot, 'package.json');
+
+const ledger = readJson(ledgerPath);
+const service = readText(servicePath);
+const providerProxy = readText(providerProxyPath);
+const packageJson = readJson(packageJsonPath);
+
+if (!ledger) {
+  fail('managed-ledger', 'managed runtime provider ledger is missing or invalid');
+} else {
+  if (ledger.schemaVersion !== 1) fail('managed-ledger.schemaVersion', 'schemaVersion must be 1');
+  if (ledger.ledgerId !== 'aria-managed-runtime-provider-quality-ledger') fail('managed-ledger.ledgerId', 'unexpected managed ledger id');
+  if (ledger.readinessClaimAllowed === true && Array.isArray(ledger.openBlockers) && ledger.openBlockers.length > 0) {
+    fail('managed-ledger.readinessClaimAllowed', 'readiness cannot be true while open blockers remain');
+  }
+  const gates = new Set((ledger.qualityGates || []).map((gate) => gate?.id).filter(Boolean));
+  for (const gate of ['pre_generation_binding_gate', 'skill_autoload_gate', 'repair_first_gate', 'client_safe_ux_gate', 'credential_plane_gate', 'runtime_ledger_enforcement_gate']) {
+    if (!gates.has(gate)) fail('managed-ledger.qualityGates', `missing quality gate ${gate}`);
+  }
+}
+
+if (!service) {
+  fail('runtime-service', 'runtime service source is missing');
+} else {
+  for (const token of [
+    'MANAGED_RUNTIME_LEDGER_PATH',
+    'appendManagedRuntimeLedger',
+    'buildManagedRuntimeLedgerRecord',
+    'classifyRuntimeRequiredSkills',
+    'loadRuntimeRequiredSkills',
+    'buildForcedSkillPromptBlock',
+    'ARIA RUNTIME FORCED SKILL LOAD',
+    'pre_provider_call',
+    'provider_candidate_evaluated',
+    'repair_before_provider_call',
+    'repair_candidate_evaluated',
+    'final_release_decision',
+    'harness_packet_hash',
+    'loaded_skill_ids',
+    'loaded_skill_hashes',
+    'credential_plane',
+  ]) {
+    if (!service.includes(token)) fail('runtime-service.ledger-contract', `missing runtime ledger token ${token}`);
+  }
+
+  const preCallIndex = service.indexOf("phase: 'pre_provider_call'");
+  const providerCallIndex = service.indexOf('providerMeta = await callProviderByStyle');
+  if (preCallIndex < 0 || providerCallIndex < 0 || preCallIndex > providerCallIndex) {
+    fail('runtime-service.pre-provider-order', 'managed ledger pre_provider_call record must be written before upstream provider call');
+  }
+
+  const repairRecordIndex = service.indexOf("phase: 'repair_before_provider_call'");
+  const repairCallIndex = service.indexOf('const recoveryMeta = await callProviderByStyle');
+  if (repairRecordIndex < 0 || repairCallIndex < 0 || repairRecordIndex > repairCallIndex) {
+    fail('runtime-service.repair-order', 'repair ledger record must be written before regenerated provider call');
+  }
+}
+
+if (!providerProxy.includes('function secretEnv(')) {
+  fail('provider-proxy.secret-env', 'provider proxy must define secretEnv before reading secret-backed provider env vars');
+}
+
+const scripts = packageJson?.scripts || {};
+if (!scripts['check:managed-runtime-ledger']) {
+  fail('package.scripts.check:managed-runtime-ledger', 'package must expose managed runtime ledger check');
+}
+
+const result = {
+  ok: failures.length === 0,
+  checkedAt: new Date().toISOString(),
+  ledgerPath,
+  servicePath,
+  failures,
+};
+console.log(JSON.stringify(result, null, 2));
+process.exit(result.ok ? 0 : 1);

package/scripts/check-opencode-config-contract.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, '..');
+const home = homedir();
+const failures = [];
+
+function fail(check, message, details = {}) {
+  failures.push({ check, message, details });
+}
+
+function readText(pathname) {
+  return existsSync(pathname) ? readFileSync(pathname, 'utf8') : '';
+}
+
+function readJsonIfExists(pathname) {
+  if (!existsSync(pathname)) return null;
+  try {
+    return JSON.parse(readFileSync(pathname, 'utf8'));
+  } catch (error) {
+    fail('opencode-config-json', `invalid JSON at ${pathname}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+const connectorSourcePath = resolve(packageRoot, 'src', 'connectors', 'opencode.ts');
+const connectorSource = readText(connectorSourcePath);
+if (!connectorSource) {
+  fail('opencode-connector-source', 'OpenCode connector source is missing');
+} else {
+  if (/agentsMdPath\s*=|agentsMdPath['"]?\s*:/.test(connectorSource)) {
+    fail('opencode-connector-source.agentsMdPath', 'connector must not write unsupported OpenCode agentsMdPath config key');
+  }
+  for (const token of ['packageOpenCodeHooksDir', "path.join(opencodeDir, 'hooks')", "path.join(homedir(), '.config', 'opencode', 'config.json')"]) {
+    if (!connectorSource.includes(token)) fail('opencode-connector-source.contract', `missing connector contract token ${token}`);
+  }
+}
+
+const activeConfigPaths = [
+  join(home, '.opencode', 'config.json'),
+  join(home, '.config', 'opencode', 'config.json'),
+];
+for (const configPath of activeConfigPaths) {
+  const config = readJsonIfExists(configPath);
+  if (!config) continue;
+  if (Object.prototype.hasOwnProperty.call(config, 'agentsMdPath')) {
+    fail('opencode-active-config.agentsMdPath', 'active OpenCode config contains unsupported agentsMdPath key', { configPath });
+  }
+  const provider = config.provider && typeof config.provider === 'object' ? config.provider : {};
+  const aria = provider.aria && typeof provider.aria === 'object' ? provider.aria : null;
+  if (aria) {
+    if (aria.endpoint !== 'http://127.0.0.1:4319/v1') {
+      fail('opencode-active-config.aria-endpoint', 'active aria provider endpoint must point to mounted runtime v1 endpoint', { configPath, endpoint: aria.endpoint });
+    }
+    if (aria.name !== 'Aria Runtime') {
+      fail('opencode-active-config.aria-name', 'active aria provider must be named Aria Runtime', { configPath, name: aria.name });
+    }
+  }
+}
+
+const installedHelper = join(home, '.opencode', 'hooks', 'lib', 'skill-autoload-gate.mjs');
+const sourceHelper = resolve(packageRoot, 'hooks', 'lib', 'skill-autoload-gate.mjs');
+if (!existsSync(sourceHelper)) fail('opencode-source-hook-helper', 'bundled OpenCode hook helper is missing');
+if (!existsSync(installedHelper)) fail('opencode-installed-hook-helper', 'installed OpenCode hook helper is missing');
+
+const result = {
+  ok: failures.length === 0,
+  checkedAt: new Date().toISOString(),
+  checkedConfigs: activeConfigPaths.filter((configPath) => existsSync(configPath)),
+  failures,
+};
+console.log(JSON.stringify(result, null, 2));
+process.exit(result.ok ? 0 : 1);

package/scripts/check-quality-ledger.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..', '..');
+const packageRoot = resolve(here, '..');
+const ledgerPath = resolve(repoRoot, 'docs', 'system', 'ARIA_CLIENT_COMPATIBILITY_QUALITY_LEDGER.json');
+const failures = [];
+
+const PROOF_STATUSES = new Set(['pending', 'in_progress', 'completed', 'blocked']);
+
+function fail(path, message, details = {}) {
+  failures.push({ path, message, details });
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function readJson(pathname) {
+  if (!existsSync(pathname)) return null;
+  try {
+    return JSON.parse(readFileSync(pathname, 'utf8'));
+  } catch (error) {
+    fail(pathname, `invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+const ledger = readJson(ledgerPath);
+const packageJson = readJson(resolve(packageRoot, 'package.json'));
+
+if (!ledger) {
+  fail('ledger', 'Client compatibility quality ledger is missing.');
+} else {
+  if (ledger.schemaVersion !== 1) fail('schemaVersion', 'Expected schemaVersion 1.');
+  if (ledger.ledgerId !== 'aria-client-compatibility-quality-ledger') fail('ledgerId', 'Unexpected ledger id.');
+  if (!ledger.ownerIntent || typeof ledger.ownerIntent !== 'string') fail('ownerIntent', 'ownerIntent is required.');
+  if (!ledger.releaseRule || typeof ledger.releaseRule !== 'string') fail('releaseRule', 'releaseRule is required.');
+  if (!Array.isArray(ledger.nonDriftRules) || ledger.nonDriftRules.length < 5) fail('nonDriftRules', 'At least five non-drift rules are required.');
+
+  const gateDefinitions = asArray(ledger.qualityGateDefinitions);
+  const gateIds = new Set(gateDefinitions.map((gate) => gate?.id).filter(Boolean));
+  if (gateDefinitions.length < 8) fail('qualityGateDefinitions', 'Expected at least eight quality gates.');
+  for (const gate of gateDefinitions) {
+    if (!gate?.id) fail('qualityGateDefinitions', 'Every gate needs an id.');
+    if (!gate?.description) fail(`qualityGateDefinitions.${gate?.id || 'unknown'}`, 'Every gate needs a description.');
+  }
+
+  const requiredGateIds = [
+    'source_wrapper_contract',
+    'active_wrapper_contract',
+    'claude_black_box_contract',
+    'codex_black_box_contract',
+    'runtime_stale_path_contract',
+    'provider_model_contract',
+    'closeout_verifier_contract',
+    'ledger_contract',
+  ];
+  for (const gateId of requiredGateIds) {
+    if (!gateIds.has(gateId)) fail('qualityGateDefinitions', `Missing required gate: ${gateId}`);
+  }
+
+  const platforms = asArray(ledger.platformLifecycleMatrix);
+  if (platforms.length < 4) fail('platformLifecycleMatrix', 'Expected Claude, Codex, runtime, and release governance rows.');
+  for (const platform of platforms) {
+    if (!platform?.platform) fail('platformLifecycleMatrix', 'Every platform row needs a platform id.');
+    if (!Array.isArray(platform?.requiredChecks) || platform.requiredChecks.length === 0) {
+      fail(`platformLifecycleMatrix.${platform?.platform || 'unknown'}.requiredChecks`, 'Every platform row needs required checks.');
+    }
+    for (const check of asArray(platform?.requiredChecks)) {
+      if (!gateIds.has(check)) fail(`platformLifecycleMatrix.${platform?.platform || 'unknown'}.requiredChecks`, `Unknown required check: ${check}`);
+    }
+    if (!PROOF_STATUSES.has(platform?.runtimeProofStatus)) {
+      fail(`platformLifecycleMatrix.${platform?.platform || 'unknown'}.runtimeProofStatus`, `Invalid runtime proof status: ${String(platform?.runtimeProofStatus)}`);
+    }
+    if (platform?.promotionAllowed === true && platform.runtimeProofStatus !== 'completed') {
+      fail(`platformLifecycleMatrix.${platform.platform}.promotionAllowed`, 'Promotion cannot be allowed unless runtime proof is completed.');
+    }
+  }
+
+  const requiredCommands = asArray(ledger.requiredCommands);
+  const commandIds = new Set(requiredCommands.map((command) => command?.id).filter(Boolean));
+  for (const commandId of ['connector_typecheck', 'hook_contracts', 'client_compatibility', 'closeout_verifier']) {
+    if (!commandIds.has(commandId)) fail('requiredCommands', `Missing required command: ${commandId}`);
+  }
+  if (ledger.readinessClaimAllowed === true) {
+    const incompletePlatforms = platforms.filter((platform) => platform.runtimeProofStatus !== 'completed' || platform.promotionAllowed !== true);
+    const blockers = asArray(ledger.openBlockers);
+    if (incompletePlatforms.length > 0) fail('readinessClaimAllowed', 'Readiness cannot be allowed with incomplete platform runtime proof.', { incompletePlatforms: incompletePlatforms.map((platform) => platform.platform) });
+    if (blockers.length > 0) fail('readinessClaimAllowed', 'Readiness cannot be allowed while open blockers remain.', { blockers: blockers.map((blocker) => blocker.id) });
+  }
+}
+
+if (!packageJson) {
+  fail('package.json', 'package.json is missing or invalid.');
+} else {
+  const scripts = packageJson.scripts || {};
+  if (!scripts['check:client-compat']) fail('package.scripts.check:client-compat', 'Package must expose the client compatibility gate.');
+  if (!scripts['check:quality-ledger']) fail('package.scripts.check:quality-ledger', 'Package must expose the quality ledger gate.');
+  if (!scripts['check:release']) fail('package.scripts.check:release', 'Package must expose the release gate.');
+}
+
+if (!existsSync(resolve(repoRoot, 'harness', 'aria-verify.mjs'))) {
+  fail('harness.aria-verify', 'Closeout verifier script is missing.');
+}
+if (!existsSync(resolve(packageRoot, 'scripts', 'check-client-compatibility.mjs'))) {
+  fail('scripts.check-client-compatibility', 'Client compatibility gate script is missing.');
+}
+
+const result = {
+  ok: failures.length === 0,
+  ledgerPath,
+  checkedAt: new Date().toISOString(),
+  failures,
+};
+console.log(JSON.stringify(result, null, 2));
+process.exit(result.ok ? 0 : 1);

package/scripts/self-test-harness-gates.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -9,6 +10,23 @@ import { pathToFileURL } from 'node:url';
 const repoRoot = join(import.meta.dirname, '..', '..', '..');
 const gateModule = await import(pathToFileURL(join(repoRoot, 'ops/claude-hooks/lib/skill-autoload-gate.mjs')));
 
+async function captureStderr(fn) {
+  const originalWrite = process.stderr.write;
+  let captured = '';
+  process.stderr.write = (chunk, encoding, callback) => {
+    captured += String(chunk || '');
+    if (typeof encoding === 'function') encoding();
+    if (typeof callback === 'function') callback();
+    return true;
+  };
+  try {
+    const value = await fn();
+    return { value, captured };
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+}
+
 assert.equal(typeof gateModule.evaluateSkillGate, 'function', 'evaluateSkillGate export missing');
 assert.equal(typeof gateModule.formatSkillGateBlock, 'function', 'formatSkillGateBlock export missing');
 
@@ -19,10 +37,8 @@ const broadClaim = gateModule.evaluateSkillGate({
   text: 'This is production-ready in general for client npm packages, SDKs, runtimes, and harnesses.',
   autoLoadAvailable: false,
 });
-assert.equal(broadClaim.ok, false, 'broad readiness claim must block without required skills');
-assert.ok(broadClaim.missingSkills.includes('architecture-decision'), 'architecture-decision must be required');
-assert.ok(broadClaim.missingSkills.includes('testing-strategy'), 'testing-strategy must be required');
-assert.ok(broadClaim.missingSkills.includes('aria-forge-guardrails'), 'aria-forge-guardrails must be required');
+assert.equal(broadClaim.redirectOnly, true, 'broad readiness language must redirect/teach instead of creating a permanent block');
+assert.ok(broadClaim.reasons.some((reason) => /recovery guidance/.test(reason)), 'broad readiness must carry recovery guidance');
 
 const deployAction = gateModule.evaluateSkillGate({
   sessionId: 'self-test-deploy',
@@ -36,6 +52,42 @@ const deployAction = gateModule.evaluateSkillGate({
 assert.equal(deployAction.ok, false, 'deploy action must block without aria-harness-deploy');
 assert.ok(deployAction.missingSkills.includes('aria-harness-deploy'), 'aria-harness-deploy must be required');
 
+const deployActionWithContractEvidence = gateModule.evaluateSkillGate({
+  sessionId: 'self-test-deploy-contract-evidence',
+  surface: 'self-test-action',
+  isDeploy: true,
+  toolName: 'Bash',
+  action: [
+    '<verify>',
+    'target: deployment/test namespace test replicas 1',
+    'role: test service',
+    'verified: syntax check exit=0',
+    'rollback: rollout undo test',
+    'axiom: truth_over_deception',
+    '</verify>',
+    '<cognition>',
+    'nur: observed state with doctrine:feedback_no_assumption_without_verification and axiom:truth_over_deception',
+    'mizan: proportionate gate with doctrine:feedback_deploy_requires_verify_cognition and axiom:reflection_before_action',
+    'hikma: policy proof with doctrine:feedback_admission_policy_verification and axiom:sacred_trust',
+    'tafakkur: structural read with doctrine:feedback_dalio_expected_required and axiom:truth_over_deception',
+    'tadabbur: if check passes continue with doctrine:feedback_no_assumption_without_verification and axiom:reflection_before_action',
+    'ilham: preserve mechanism with doctrine:feedback_admission_policy_verification and axiom:sacred_trust',
+    'wahi: proof landed with doctrine:feedback_deploy_requires_verify_cognition and axiom:truth_over_deception',
+    'firasah: owner needs true state with doctrine:feedback_deploy_requires_verify_cognition and axiom:sacred_trust',
+    '</cognition>',
+    '<expected>',
+    'predicate: exit=0',
+    'measurable_type: boolean',
+    '</expected>',
+    'bash scripts/deploy-service.sh test',
+  ].join('\n'),
+  text: 'deploy service with full contract evidence and transcript-invisible skill evidence',
+  autoLoadAvailable: false,
+});
+assert.equal(deployActionWithContractEvidence.ok, true, gateModule.formatSkillGateBlock(deployActionWithContractEvidence));
+assert.ok(deployActionWithContractEvidence.contractEvidence.includes('aria-harness-deploy'), 'deploy contract evidence must satisfy deploy skill');
+assert.ok(deployActionWithContractEvidence.contractEvidence.includes('aria-forge-guardrails'), 'deploy contract evidence must satisfy forge guardrails');
+
 const missingProof = gateModule.evaluateSkillGate({
   sessionId: 'self-test-missing-proof',
   surface: 'self-test-output',
@@ -46,12 +98,32 @@ const missingProof = gateModule.evaluateSkillGate({
   ].join('\n'),
   autoLoadAvailable: false,
 });
-assert.equal(missingProof.ok, false, 'completion with failed/missing proof must block');
-assert.ok(missingProof.recoveryMissing.includes('successful proof from a concrete command/probe'), 'successful proof must be required');
-assert.ok(missingProof.recoveryMissing.includes('re-submission'), 're-submission must be required');
-assert.ok(missingProof.recoveryMissing.includes('re-write'), 're-write must be required');
-assert.ok(missingProof.recoveryMissing.includes('re-test'), 're-test must be required');
-assert.ok(missingProof.recoveryMissing.includes('ARIA console escalation'), 'ARIA console escalation must be required');
+assert.equal(missingProof.ok, true, 'completion with explicit unresolved state must redirect instead of permanently blocking');
+assert.ok(missingProof.reasons.some((reason) => /unresolved state/.test(reason)), 'unresolved state must be recognized');
+
+const skillRecoveryBlock = gateModule.formatSkillGateBlock(missingProof);
+assert.match(skillRecoveryBlock, /Recovery contract:/, 'skill block must include recovery contract');
+assert.match(skillRecoveryBlock, /<applied_cognition>/, 'skill block must include applied cognition template');
+assert.doesNotMatch(skillRecoveryBlock, /counter_action:/, 'skill block must not emit old counter_action-only recovery');
+assert.doesNotMatch(skillRecoveryBlock, /Required repair:/, 'skill block must not emit out-of-contract repair text');
+
+const postCompactSkillGate = gateModule.evaluateSkillGate({
+  sessionId: 'self-test-post-compact-skill',
+  surface: 'opencode-harness-stop',
+  isOutputCloseout: true,
+  text: [
+    'post_compact_continuation',
+    'post commission',
+    'current objective: continue the recovery without bricking.',
+    'known blockers: prior skill-autoload block included deploy/readiness words.',
+    'next executable step: run the gate self-test.',
+    'what not to touch: unrelated dirty files.',
+    'verification already run: not run.',
+    'deploy production-ready complete blocked no proof fail open advisory remove strip test',
+  ].join('\n'),
+  autoLoadAvailable: false,
+});
+assert.equal(postCompactSkillGate.ok, true, gateModule.formatSkillGateBlock(postCompactSkillGate));
 
 const loaded = gateModule.evaluateSkillGate({
   sessionId: 'self-test-loaded',
@@ -70,9 +142,105 @@ assert.equal(loaded.ok, true, gateModule.formatSkillGateBlock(loaded));
 
 const installedStop = await import(pathToFileURL(join(repoRoot, 'packages/aria-connector/opencode-plugins/harness-stop/index.js')));
 assert.equal(typeof installedStop.default, 'function', 'harness-stop default export missing');
+assert.equal(typeof installedStop.classifyContinuationHandoff, 'function', 'harness-stop continuation classifier export missing');
+
+const previousGateOff = process.env.ARIA_GATES_OFF;
+process.env.ARIA_GATES_OFF = '1';
+try {
+  const { captured } = await captureStderr(async () => {
+    const plugin = await installedStop.default({});
+    await plugin['experimental.text.complete']({}, { text: [
+      'This intentionally long output would normally trip the text gate because it makes a decision-bearing claim without the required recovery shape.',
+      'The emergency flag must allow the owner to keep a session unbricked while preserving the underlying gate code for later manual re-enable.',
+      'The content is long enough to exceed the non-trivial threshold and would otherwise be inspected by local output rules.',
+    ].join(' ') });
+  });
+  assert.doesNotMatch(captured, /emergency gate-off allow/, 'emergency gate-off must not spam the OpenCode screen');
+  assert.match(captured, /harness-stop.*Active/, 'emergency gate-off path must still load the stop plugin');
+} finally {
+  if (previousGateOff === undefined) delete process.env.ARIA_GATES_OFF;
+  else process.env.ARIA_GATES_OFF = previousGateOff;
+}
+
+const validHandoff = installedStop.classifyContinuationHandoff([
+  'post_compact_continuation',
+  'current objective: continue repairing the gate without claiming completion.',
+  'known blockers: lane gateway backend is offline and unrelated work remains unresolved.',
+  'next executable step: inspect the stop gate classifier and run the self-test.',
+  'what not to touch: do not revert unrelated user changes or deploy Soul.',
+  'verification already run: npm run test:executor-contract passed previously; current gate test pending.',
+].join('\n'));
+assert.equal(validHandoff.isContinuation, true, 'handoff marker must classify as continuation');
+assert.equal(validHandoff.ok, true, `valid handoff must pass: ${JSON.stringify(validHandoff)}`);
+
+const incompleteHandoff = installedStop.classifyContinuationHandoff([
+  'handoff_resume',
+  'current objective: continue work.',
+  'known blockers: unresolved.',
+].join('\n'));
+assert.equal(incompleteHandoff.ok, false, 'handoff missing required fields must block');
+assert.ok(incompleteHandoff.missingFields.includes('next executable step'), 'missing next executable step must be reported');
+try {
+  const { captured } = await captureStderr(async () => {
+    const plugin = await installedStop.default({});
+    await plugin['experimental.text.complete']({}, { text: [
+      'handoff_resume',
+      'current objective: continue work.',
+      'known blockers: unresolved.',
+      'This intentionally long malformed handoff forces the stop gate to return recovery instructions instead of bricking the next session.'.repeat(4),
+    ].join('\n') });
+  });
+  assert.match(captured, /recovery-required/, 'malformed handoff must emit captured recovery-required diagnostics');
+} catch (error) {
+  const message = String(error?.message || error);
+  assert.doesNotMatch(message, /ARIA LOCAL OUTPUT BLOCK/, 'malformed handoff must not brick the whole screen');
+}
+const recoveryPath = join(process.env.HOME || tmpdir(), '.aria', 'governance-recovery-current.json');
+assert.equal(existsSync(recoveryPath), true, 'malformed handoff must persist recovery context');
+const recoveryState = JSON.parse(readFileSync(recoveryPath, 'utf8'));
+assert.equal(recoveryState.governanceMode, 'recovery-required', 'malformed handoff must require recovery');
+assert.match(recoveryState.recoveryContract.blockedReason, /Recovery contract:/, 'recovery state must include recovery contract');
+assert.match(recoveryState.recoveryContract.blockedReason, /post_compact_continuation/, 'recovery state must include exact continuation marker');
+assert.match(recoveryState.recoveryContract.blockedReason, /next executable step:/, 'recovery state must include next executable step field');
+assert.match(recoveryState.recoveryContract.retry, /One recovery attempt/, 'recovery state must include one-shot retry rule');
+
+const fakeCompleteHandoff = installedStop.classifyContinuationHandoff([
+  'post_compact_continuation',
+  'current objective: everything is done and fixed.',
+  'known blockers: none.',
+  'next executable step: continue.',
+  'what not to touch: unrelated files.',
+  'verification already run: not run.',
+].join('\n'));
+assert.equal(fakeCompleteHandoff.ok, false, 'handoff with fake completion claim must block');
+assert.equal(fakeCompleteHandoff.hasFakeCompletionClaim, true, 'fake completion claim must be identified');
 const installedGate = await import(pathToFileURL(join(repoRoot, 'packages/aria-connector/opencode-plugins/harness-gate/index.js')));
 assert.equal(typeof installedGate.default, 'function', 'harness-gate default export missing');
 
+const postCompactPayload = JSON.stringify({
+  text: [
+    'post_compact_continuation',
+    'current objective: continue gate recovery.',
+    'known blockers: none.',
+    'next executable step: resume the next concrete verification.',
+    'what not to touch: unrelated dirty files.',
+    'verification already run: current self-test in progress.',
+  ].join('\n'),
+});
+for (const gatePath of [
+  join(repoRoot, 'scripts/aria-governance-gate.mjs'),
+  join(repoRoot, 'harness/packages/harness-http-client/scripts/aria-governance-gate.mjs'),
+]) {
+  const child = spawnSync(process.execPath, [gatePath], {
+    input: `${postCompactPayload}\n`,
+    encoding: 'utf8',
+  });
+  assert.equal(child.status, 0, `post-compact governance allow failed for ${gatePath}: ${child.stdout}${child.stderr}`);
+  const result = JSON.parse(child.stdout);
+  assert.equal(result.decision, 'allow', `post-compact governance must allow for ${gatePath}`);
+  assert.equal(result.postCompactContinuation?.active, true, `post-compact marker missing for ${gatePath}`);
+}
+
 const temp = mkdtempSync(join(tmpdir(), 'aria-harness-gates-'));
 rmSync(temp, { recursive: true, force: true });
 

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const repoRoot = join(import.meta.dirname, '..', '..', '..');
+const modulePath = pathToFileURL(join(repoRoot, 'packages/aria-connector/dist/aria-connector/src/connectors/repo-guard.js'));
+const { approveRepoGuardDelete, isRepoGuardedPath } = await import(modulePath);
+
+assert.equal(isRepoGuardedPath('apps/service/source.ts'), true, 'repo source paths must be guarded');
+assert.equal(isRepoGuardedPath('docs/important-note.md'), true, 'whole-repo docs must be guarded');
+assert.equal(isRepoGuardedPath('node_modules/pkg/index.js'), false, 'node_modules must be ignored');
+assert.equal(isRepoGuardedPath('apps/service/dist/index.js'), false, 'build output must be ignored');
+assert.equal(isRepoGuardedPath('package-lock.json'), false, 'lockfiles are not repo-guard delete targets');
+
+const tempRepo = mkdtempSync(join(tmpdir(), 'aria-repo-guard-'));
+try {
+  execFileSync('git', ['init'], { cwd: tempRepo, stdio: 'ignore' });
+  execFileSync('git', ['config', 'user.email', 'repo-guard@example.local'], { cwd: tempRepo, stdio: 'ignore' });
+  execFileSync('git', ['config', 'user.name', 'Repo Guard Test'], { cwd: tempRepo, stdio: 'ignore' });
+  writeFileSync(join(tempRepo, 'keep.md'), 'tracked\n');
+  execFileSync('git', ['add', 'keep.md'], { cwd: tempRepo, stdio: 'ignore' });
+  execFileSync('git', ['commit', '-m', 'seed'], { cwd: tempRepo, stdio: 'ignore' });
+
+  const approval = approveRepoGuardDelete(tempRepo, 'keep.md', 'self-test', 'explicit test approval', 1000);
+  assert.equal(approval.repoRoot, tempRepo, 'approval must bind to the repo root');
+  assert.equal(approval.relPath, 'keep.md', 'approval must bind to the relative path');
+  assert.equal(approval.approvedBy, 'self-test', 'approval must record approver');
+  assert.ok(Date.parse(approval.expiresAt) > Date.now(), 'approval must be time-boxed');
+} finally {
+  rmSync(tempRepo, { recursive: true, force: true });
+}
+
+console.log('repo guard self-test passed');

package/scripts/validate-skill-prompts.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -9,7 +10,11 @@ const repoRoot = path.resolve(here, '..', '..', '..');
 const skillRoots = [
   path.join(repoRoot, 'packages/aria-connector/skills'),
   path.join(repoRoot, 'harness/packages/harness-http-client/skills'),
-];
+  path.join(homedir(), '.agents/skills'),
+  path.join(homedir(), '.claude/skills'),
+].filter((root) => {
+  try { return statSync(root).isDirectory(); } catch { return false; }
+});
 
 function walkSkills(dir, acc = []) {
   for (const name of readdirSync(dir)) {
@@ -77,6 +82,14 @@ for (const root of skillRoots) {
       warnings.push(`${rel}: no explicit workflow section`);
     }
 
+    if (!hasSection(text, ['First-Class Production Contract'])) {
+      errors.push(`${rel}: missing First-Class Production Contract section`);
+    }
+
+    if (!/\b(no placeholders|no fake fallbacks|real proof|architect\/ARIA console|re-test|redo contract)\b/i.test(text)) {
+      errors.push(`${rel}: first-class contract must require no placeholders, no fake fallbacks, real proof, re-test, redo contract, and architect/ARIA console escalation`);
+    }
+
     if (/\bcoming soon\b/i.test(text)) {
       warnings.push(`${rel}: contains deferred-language phrase`);
     }

package/skills/aria-cognition/aria-essence/SKILL.md

@@ -61,3 +61,21 @@ For non-trivial work, make sure your internal workflow yields at least:
 - [references/domain-matrix.md](references/domain-matrix.md)
 - [references/evolution-loop.md](references/evolution-loop.md)
 - [references/readable-cognition.md](references/readable-cognition.md)
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.