total-recall-brain 3.41.4 → 3.41.6

package/src/cli/release.mjs

@@ -0,0 +1,386 @@
+/**
+ * total-recall release — publish a package, propagate it, and verify every consumer.
+ *
+ * The missing capability this fills: publishing to npm and verifying that the
+ * published artifact actually reached every registered consumer were manual
+ * steps outside any TR command. A release that is only on npm is not released,
+ * and a release whose consumers were never verified is a claim, not a fact.
+ *
+ * Usage:
+ *   npx total-recall release plan <pkg> [--version X.Y.Z]
+ *   npx total-recall release publish <pkg> [--version X.Y.Z] [--otp N]
+ *   npx total-recall release propagate [--apply]
+ *   npx total-recall release verify <pkg> [--version X.Y.Z]
+ *   npx total-recall release all <pkg> [--version X.Y.Z] [--apply] [--otp N]
+ *
+ * Never publishes without --apply. Never trusts the publish command's own
+ * report: verification reads the registry and each consumer's resolved
+ * installation independently.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { BRAIN_PACKAGES, updateAllBrains } from '../core/brain-updates.mjs';
+import { listUpdateRoots, rootsFromEnv } from '../core/package-auto-update.mjs';
+
+const DEFAULT_PACKAGES = BRAIN_PACKAGES;
+
+/** @param {string[]} args */
+export function parseArgs(args) {
+  const opts = {
+    action: null,
+    packages: [],
+    version: null,
+    apply: false,
+    otp: null,
+    json: false,
+    help: false,
+    root: null,
+    timeoutMs: 20 * 60 * 1000,
+  };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--apply') opts.apply = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--version' && args[i + 1]) opts.version = args[++i];
+    else if (a === '--otp' && args[i + 1]) opts.otp = args[++i];
+    else if (a === '--root' && args[i + 1]) opts.root = args[++i];
+    else if (a === '--timeout' && args[i + 1]) opts.timeoutMs = Number(args[++i]);
+    else if (!a.startsWith('-')) positional.push(a);
+  }
+  opts.action = positional.shift() || null;
+  opts.packages = positional;
+  return opts;
+}
+
+const ACTIONS = ['plan', 'publish', 'propagate', 'verify', 'all'];
+
+function printHelp() {
+  console.log(`
+  total-recall release — publish, propagate and verify a package release
+
+  Usage:
+    total-recall release plan <pkg> [--version X.Y.Z]
+    total-recall release publish <pkg> [--version X.Y.Z] [--otp N] --apply
+    total-recall release propagate [--apply] [--json]
+    total-recall release verify <pkg> [--version X.Y.Z] [--json]
+    total-recall release all <pkg> [--version X.Y.Z] [--apply] [--otp N] [--json]
+
+  Actions:
+    plan        Resolve the release version and report gate/consumer readiness. No writes.
+    publish     Run the package's prepublish gate, then npm publish. Requires --apply.
+    propagate   Pin the published version across every registered consumer (update --all-brains).
+    verify      Independently confirm the registry artifact and each consumer's resolved install.
+    all         plan → publish → propagate → verify, stopping at the first failure.
+
+  Rules enforced here:
+    • Publishing requires --apply; plan/verify never write.
+    • Verification never trusts the publish or propagate report: it re-reads the
+      npm registry and each consumer's own resolved package.json.
+    • A version that is only on npm is reported as incomplete, not as released.
+
+  Options:
+    --apply          Perform writes (required for publish/propagate).
+    --version X.Y.Z  Expect or assert a specific version (defaults to the source package.json).
+    --otp N          npm one-time password, passed through to npm publish.
+    --root PATH      Source repo for the package (defaults to $PWD).
+    --json           Machine-readable output.
+`);
+}
+
+/** Read a package's source metadata without assuming a monorepo layout. */
+export function readSourcePackage(root, pkg) {
+  const candidates = [path.join(root, 'package.json')];
+  // A workspace source may live one level down (packages/<dir>/package.json).
+  for (const dir of ['packages', 'apps']) {
+    const base = path.join(root, dir);
+    if (!fs.existsSync(base)) continue;
+    for (const entry of fs.readdirSync(base)) {
+      candidates.push(path.join(base, entry, 'package.json'));
+    }
+  }
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      const pkgJson = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (pkgJson.name === pkg) return { file, dir: path.dirname(file), pkgJson };
+    } catch {
+      /* ignore malformed candidates rather than failing the whole release */
+    }
+  }
+  return null;
+}
+
+/** npm registry read. This is the independent source of truth for "published". */
+export function publishedVersion(pkg, { exec = spawnSync } = {}) {
+  const res = exec('npm', ['view', pkg, 'version'], { encoding: 'utf8', timeout: 60000 });
+  if (res.status !== 0) return { ok: false, version: null, error: (res.stderr || '').trim() || 'npm view failed' };
+  return { ok: true, version: (res.stdout || '').trim(), error: null };
+}
+
+/** Wait for a just-published version to become readable from the registry. */
+export async function awaitPublished(pkg, version, { attempts = 8, delayMs = 20000, exec = spawnSync, sleep } = {}) {
+  const pause = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    const read = publishedVersion(pkg, { exec });
+    last = read;
+    if (read.ok && read.version === version) return { ok: true, version: read.version, attempts: i + 1 };
+    if (i < attempts - 1) await pause(delayMs);
+  }
+  return { ok: false, version: last?.version ?? null, error: last?.error ?? `registry still reports ${last?.version}`, attempts };
+}
+
+/**
+ * Every consumer root TR knows about: the project registry plus TR_SYNC_REPOS.
+ * Used by verify so it never depends on the propagate step's own bookkeeping.
+ */
+export function consumerRoots(opts = {}) {
+  // Explicit roots are authoritative: passing them means "verify exactly these",
+  // which is what makes this callable from tests and from --root. Without them,
+  // fall back to the whole registered fleet plus TR_SYNC_REPOS.
+  const explicit = (opts.roots || []).filter(Boolean);
+  const source = explicit.length
+    ? explicit
+    : [...listUpdateRoots(opts).map((row) => (typeof row === 'string' ? row : row.root)), ...rootsFromEnv()];
+  const seen = new Set();
+  const out = [];
+  for (const root of source) {
+    if (!root) continue;
+    const resolved = path.resolve(root);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+/** Read the version a consumer actually resolves for a package (declared + installed). */
+export function consumerState(root, pkg, version = null) {
+  const declaredFiles = [];
+  const pkgFile = path.join(root, 'package.json');
+  let declared = null;
+  if (fs.existsSync(pkgFile)) {
+    try {
+      const j = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+      const all = { ...(j.dependencies || {}), ...(j.devDependencies || {}), ...(j.optionalDependencies || {}) };
+      declared = all[pkg] ?? null;
+      if (declared) declaredFiles.push(pkgFile);
+    } catch {
+      /* unreadable package.json is reported as unknown, not as satisfied */
+    }
+  }
+  if (!declared) return { root, declared: null, installed: null, satisfied: false, reason: 'not-declared' };
+
+  // Resolve the version a spec pins. Handles plain versions ("0.14.4"),
+  // npm: aliases ("npm:@scope/pkg@0.14.4") and ranges. A range is satisfied by
+  // the installed version rather than by string equality.
+  const spec = String(declared).trim();
+  let want = null;
+  let range = false;
+  if (spec.startsWith('npm:')) {
+    const afterAt = spec.slice(4);
+    const idx = afterAt.lastIndexOf('@');
+    want = idx > 0 ? afterAt.slice(idx + 1) : null;
+  } else if (/^[~^]|^[<>]=?|\|\||\s-\s|\*|x$/i.test(spec)) {
+    range = true;
+  } else {
+    want = spec;
+  }
+
+  const installedCandidates = [
+    path.join(root, 'node_modules', pkg, 'package.json'),
+    // npm: aliases install under the alias directory, which is what .bin shims run.
+    ...aliasDirs(root, pkg),
+  ];
+  let installed = null;
+  for (const file of installedCandidates) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      installed = JSON.parse(fs.readFileSync(file, 'utf8')).version ?? null;
+      if (installed) break;
+    } catch {
+      /* keep looking */
+    }
+  }
+  const satisfied = range ? Boolean(installed) && installed === version : Boolean(want && installed === want);
+  return {
+    root,
+    declared,
+    want,
+    range,
+    installed,
+    satisfied,
+    reason: !installed ? 'not-installed' : satisfied ? 'ok' : 'installed-mismatch',
+  };
+}
+
+/** Alias install dirs for a package, e.g. @ssss/cli -> node_modules/@ssss/cli. */
+function aliasDirs(root, pkg) {
+  const dirs = [];
+  const nm = path.join(root, 'node_modules');
+  if (!fs.existsSync(nm)) return dirs;
+  // Known alias pair for the SSSS CLI: the alias dir is what .bin/ssss executes.
+  if (pkg === '@gregiteen/ssss-cli') {
+    dirs.push(path.join(nm, '@ssss', 'cli', 'package.json'));
+  }
+  return dirs;
+}
+
+export function verifyConsumers(pkg, version, opts = {}) {
+  const roots = consumerRoots(opts);
+  const states = roots.map((root) => consumerState(root, pkg, version));
+  const relevant = states.filter((s) => s.declared);
+  const failing = relevant.filter((s) => !s.satisfied);
+  return {
+    pkg,
+    version,
+    roots_considered: roots.length,
+    consumers: relevant.length,
+    failing: failing.length,
+    failures: failing.map((s) => ({ root: s.root, declared: s.declared, installed: s.installed, reason: s.reason })),
+  };
+}
+
+function runPrepublish(dir, pkgJson, { exec = spawnSync, timeoutMs } = {}) {
+  if (!pkgJson?.scripts?.prepublishOnly) return { ok: true, skipped: true };
+  const manager = fs.existsSync(path.join(dir, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
+  const res = exec(manager, ['run', 'prepublishOnly'], { cwd: dir, encoding: 'utf8', stdio: 'pipe', timeout: timeoutMs });
+  return { ok: res.status === 0, skipped: false, output: `${res.stdout || ''}${res.stderr || ''}`.trim() };
+}
+
+function doPublish(dir, { otp, exec = spawnSync, timeoutMs } = {}) {
+  const args = ['publish'];
+  if (otp) args.push('--otp', otp);
+  const res = exec('npm', args, { cwd: dir, encoding: 'utf8', stdio: 'pipe', timeout: timeoutMs });
+  return { ok: res.status === 0, output: `${res.stdout || ''}${res.stderr || ''}`.trim() };
+}
+
+/**
+ * @param {string[]} argv full process argv (bin convention)
+ */
+export async function run(argv = process.argv, deps = {}) {
+  const opts = parseArgs(argv.slice(3));
+  const log = opts.json ? () => {} : (...a) => console.log(...a);
+  const emit = (obj) => { if (opts.json) console.log(JSON.stringify(obj, null, 2)); };
+
+  if (opts.help || !opts.action) {
+    printHelp();
+    if (!opts.action && !opts.help) process.exitCode = 1;
+    return;
+  }
+  if (!ACTIONS.includes(opts.action)) {
+    console.error(`Unknown release action: ${opts.action}. Expected one of: ${ACTIONS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const report = { action: opts.action, packages: {}, ok: false, steps: [] };
+  const fail = (message) => {
+    report.error = message;
+    report.ok = false;
+    if (opts.json) emit(report); else console.error(`\n  ✗ ${message}\n`);
+    process.exitCode = 1;
+  };
+
+  // propagate and verify act on the whole fleet and need no package argument.
+  if (opts.action === 'propagate') {
+    const dryRun = !opts.apply;
+    log(`\n  Propagating ${DEFAULT_PACKAGES.join(' + ')} across every registered consumer${dryRun ? ' (plan)' : ''}...`);
+    const summary = await (deps.updateAllBrains || updateAllBrains)({ dryRun, force: !dryRun, skipThrottle: !dryRun });
+    report.steps.push({ step: 'propagate', dryRun, summary });
+    report.ok = (summary.failed || 0) === 0;
+    if (opts.json) { emit(report); return; }
+    log(`\n  roots: ${summary.root_count ?? '—'}  consumers: ${summary.consumer_count ?? '—'}  failed: ${summary.failed ?? 0}`);
+    if (dryRun) log('  Run with --apply to install.\n');
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+
+  const packages = opts.packages.length ? opts.packages : DEFAULT_PACKAGES;
+  if (!packages.length) return fail('No package given.');
+
+  for (const pkg of packages) {
+    const root = opts.root || process.cwd();
+    const source = readSourcePackage(root, pkg);
+    const entry = { pkg, root, source: source?.file ?? null };
+    report.packages[pkg] = entry;
+
+    if (opts.action === 'verify') {
+      const version = opts.version || source?.pkgJson?.version;
+      if (!version) return fail(`${pkg}: no --version and no source package.json found under ${root}`);
+      entry.version = version;
+      const reg = await awaitPublished(pkg, version, { attempts: 1, delayMs: 0 });
+      entry.registry = reg;
+      const consumers = verifyConsumers(pkg, version, { roots: opts.root ? [opts.root] : [] });
+      entry.consumers = consumers;
+      if (!reg.ok) return fail(`${pkg}@${version} is not readable from the npm registry (${reg.error}).`);
+      if (consumers.failing > 0) {
+        return fail(`${pkg}@${version}: ${consumers.failing}/${consumers.consumers} consumers not satisfied. First: ${consumers.failures[0].root} (${consumers.failures[0].installed ?? 'not installed'}).`);
+      }
+      log(`  ✓ ${pkg}@${version} verified: registry + ${consumers.consumers}/${consumers.consumers} consumers`);
+      continue;
+    }
+
+    if (!source) return fail(`${pkg}: source package.json not found under ${root}. Pass --root <repo>.`);
+    const version = opts.version || source.pkgJson.version;
+    entry.version = version;
+    if (opts.version && source.pkgJson.version !== opts.version) {
+      return fail(`${pkg}: source is ${source.pkgJson.version} but --version ${opts.version} was requested. Bump the source first.`);
+    }
+
+    if (opts.action === 'plan') {
+      const reg = publishedVersion(pkg);
+      entry.registry = reg;
+      entry.gates = source.pkgJson.scripts?.prepublishOnly ? 'present' : 'absent';
+      entry.alreadyPublished = reg.ok && reg.version === version;
+      log(`  ${pkg}: source ${version}, registry ${reg.version ?? '—'}${entry.alreadyPublished ? ' (already published)' : ''}, prepublish gate ${entry.gates}`);
+      continue;
+    }
+
+    if (opts.action === 'publish' || opts.action === 'all') {
+      const reg = publishedVersion(pkg);
+      entry.registry_before = reg;
+      if (reg.ok && reg.version === version) {
+        log(`  · ${pkg}@${version} already published — skipping publish`);
+        entry.published = 'already';
+      } else {
+        if (!opts.apply) return fail(`publish requires --apply (would publish ${pkg}@${version}).`);
+        const gate = runPrepublish(source.dir, source.pkgJson, { timeoutMs: opts.timeoutMs });
+        entry.gate = gate.ok ? 'passed' : 'failed';
+        report.steps.push({ step: 'prepublish', pkg, ok: gate.ok, skipped: gate.skipped });
+        if (!gate.ok) return fail(`${pkg}: prepublishOnly gate failed.\n${gate.output}`);
+        const pub = doPublish(source.dir, { otp: opts.otp, timeoutMs: opts.timeoutMs });
+        entry.publish_output = pub.output;
+        if (!pub.ok) return fail(`${pkg}: npm publish failed.\n${pub.output}`);
+        const confirmed = await (deps.awaitPublished || awaitPublished)(pkg, version, deps);
+        entry.registry_after = confirmed;
+        if (!confirmed.ok) return fail(`${pkg}@${version} published but the registry still reports ${confirmed.version}. Treat as NOT released.`);
+        entry.published = 'yes';
+        log(`  ✓ ${pkg}@${version} published and confirmed on the registry`);
+      }
+      if (opts.action === 'publish') continue;
+    }
+
+    if (opts.action === 'all') {
+      const dryRun = !opts.apply;
+      const summary = await (deps.updateAllBrains || updateAllBrains)({ dryRun, force: !dryRun, skipThrottle: !dryRun });
+      report.steps.push({ step: 'propagate', pkg, summary });
+      if ((summary.failed || 0) > 0) return fail(`${pkg}: propagation reported ${summary.failed} failure(s).`);
+      const consumers = verifyConsumers(pkg, version, {});
+      entry.consumers = consumers;
+      if (consumers.failing > 0) {
+        return fail(`${pkg}@${version}: ${consumers.failing}/${consumers.consumers} consumers still not satisfied after propagation.`);
+      }
+      log(`  ✓ ${pkg}@${version}: registry + ${consumers.consumers}/${consumers.consumers} consumers`);
+    }
+  }
+
+  report.ok = true;
+  if (opts.json) emit(report);
+  else if (opts.action === 'plan') log('\n  Plan only — nothing published or changed.\n');
+  else log('');
+}

package/src/cli/remember.mjs

@@ -234,7 +234,7 @@ export default async function remember(args) {
         i++;
       }
     } else if (arg === '--no-dedup') {
-      // Accepted for compatibility; remember never archives another node.
+      // Skips the duplicate guard below; remember never archives another node.
     } else if (arg === '--allow-long') {
       allowLong = true;
     } else if (arg === '--universal') {
@@ -324,6 +324,24 @@ export default async function remember(args) {
     node.immutable = true;
   }
 
+  // Hermes-grade fail-closed duplicate guard: prevent writing duplicate rules/invariants
+  if (!layerArgs.includes('--force') && !layerArgs.includes('--no-dedup')) {
+    try {
+      const { assertNoDuplicateRule } = await import('../core/duplicate-guard.mjs');
+      assertNoDuplicateRule(node, {
+        vaultDir,
+        derivedDir,
+        globalVaultDir: path.join(getBothBrains().global.brainDir, 'memory-vault'),
+        projectRoot: (project && project.projectRoot) ? project.projectRoot : process.cwd(),
+      });
+    } catch (err) {
+      if (err.code === 'ERR_DUPLICATE_RULE') {
+        process.exit(1);
+      }
+      throw err;
+    }
+  }
+
   // Saving memory never optimizes or archives other canonical documents.
 
   const vaultResult = await writeNodeValidatedAsync(node, vaultDir);

package/src/cli/rules.mjs

@@ -15,17 +15,49 @@ const POLICY_SLUG = 'context-policy';
 const ALL_ACTIONS = [...CONTEXT_ACTIONS];
 const DEFAULT_BUDGET = 4000;
 
+const explicitBudget = (flags) => {
+  const explicit = Number(flags.budget);
+  return Number.isFinite(explicit) && explicit > 0 ? explicit : undefined;
+};
+
 /** Budget for capsule checks: --budget, else the context_budget setting, else 4000. */
 function resolveBudget(flags) {
-  const explicit = Number(flags.budget);
-  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  return explicitBudget(flags) ?? configuredBudget() ?? DEFAULT_BUDGET;
+}
+
+function configuredBudget() {
   for (const layer of ['project', 'global']) {
     try {
       const value = readConfigValue('context_budget', layer);
       if (Number.isFinite(value) && value > 0) return value;
     } catch { /* fall through to the next layer */ }
   }
-  return DEFAULT_BUDGET;
+  return undefined;
+}
+
+/** The budget `context` applies when none is given. */
+async function effectiveBudget() {
+  const { CAPSULE_LIMIT } = await import('./context.mjs');
+  return Math.min(configuredBudget() ?? CAPSULE_LIMIT, CAPSULE_LIMIT);
+}
+
+/** Whether `context` can really serve each capsule: it compacts automatically, so raw size alone is not a failure (CAPSULE-R15). */
+async function checkCompactable(capsules, budget, problems) {
+  const { loadContextNodes, compactedHeader } = await import('./context.mjs');
+  const { compactNodes } = await import('./compact.mjs');
+  const { nodes, skillsDir, derivedDirs } = loadContextNodes();
+  const header = compactedHeader('0'.repeat(64), budget);
+  for (const capsule of capsules) {
+    capsule.compacted = capsule.tokens > budget;
+    try {
+      await compactNodes({ task: '', actions: capsule.actions.split(','), budget, complete: true, rank: false, nodes, skillsDir, derivedDirs, header });
+      capsule.withinBudget = true;
+    } catch (error) {
+      if (!error.requiredBudget) throw error;
+      capsule.withinBudget = false;
+      problems.push(`capsule for ${capsule.actions} cannot fit ${budget} tokens even compacted; it needs ${error.requiredBudget}`);
+    }
+  }
 }
 
 function help() {
@@ -37,7 +69,7 @@ function help() {
     audit   [--budget N] [--top N] [--json]   Capsule size per action, largest rules, curation health
     draft   [--all] [--actions a,b] [--out F]  Write a policy scaffold (original text as directives) to shorten
     apply   <file> [--dry-run] [--allow-exclude]  Validate a policy file and merge it into this repo's policy node
-    verify  [--budget N] [--json]              Exit 1 on stale/orphan curation or an action capsule over budget
+    verify  [--budget N] [--json]              Exit 1 on stale/orphan curation or a capsule context cannot serve even compacted; --budget checks raw size
     prune   [--apply] [--archive] [--json]     Drop stale policy entries; list (or archive) expired/superseded/duplicate rules
 
   Workflow: audit -> draft -> shorten each directive by hand (keep every operative
@@ -107,9 +139,10 @@ function parseFlags(args, valued = []) {
   return { flags, rest };
 }
 
-function audit(args) {
+async function audit(args) {
   const { flags } = parseFlags(args, ['budget', 'top']);
-  const budget = resolveBudget(flags);
+  const explicit = explicitBudget(flags);
+  const budget = explicit ?? await effectiveBudget();
   const state = loadState();
   const curated = curatedRules(state.nodes);
   const rows = curated.filter(n => RULE_CATEGORIES.has(n.category) && n.status === 'active').map(n => {
@@ -119,7 +152,12 @@ function audit(args) {
     return { id, original, current, curated: Boolean(n._directive), excluded: Boolean(n._contextExcluded) };
   });
   const sz = sizes(state);
-  const over = sz.filter(s => s.actions !== '(none)' && s.tokens > budget);
+  const capsules = sz.filter(s => s.actions !== '(none)');
+  // Without --budget, `over` means what it means to `context`: not servable even compacted.
+  const problems = [];
+  if (explicit) for (const s of capsules) s.withinBudget = s.tokens <= budget;
+  else await checkCompactable(capsules, budget, problems);
+  const over = capsules.filter(s => !s.withinBudget);
   const report = {
     policy: state.health, rules: rows.length, curated: rows.filter(r => r.curated).length,
     excluded: rows.filter(r => r.excluded).length, stale: state.stale, orphan: state.orphan,
@@ -131,9 +169,11 @@ function audit(args) {
   if (state.stale.length) console.log(`Stale curation (rule edited since; full text in use): ${state.stale.join(', ')}`);
   if (state.orphan.length) console.log(`Orphan curation (rule gone): ${state.orphan.join(', ')}`);
   console.log(`\nCapsule tokens by action (budget ${budget}):`);
-  for (const s of sz) console.log(`  ${s.actions !== '(none)' && s.tokens > budget ? 'OVER' : 'ok  '} ${String(s.tokens).padStart(6)}  ${s.actions} (${s.count} rules)`);
+  for (const s of sz) console.log(`  ${s.withinBudget === false ? 'OVER' : s.compacted ? 'comp' : 'ok  '} ${String(s.tokens).padStart(6)}  ${s.actions} (${s.count} rules)`);
+  if (sz.some(s => s.compacted)) console.log('  comp = larger than the budget; `context` compacts it automatically and every rule still applies');
   console.log('\nLargest rules (current/original tokens):');
   for (const r of report.largest) console.log(`  ${String(r.current).padStart(5)}/${String(r.original).padEnd(5)} ${r.id}${r.curated ? ' (curated)' : ''}`);
+  for (const p of problems) console.log(`\n${p}`);
   if (over.length) console.log('\nOver budget: run `total-recall rules draft --out policy.json`, shorten the directives, then `rules apply policy.json`.');
 }
 
@@ -224,20 +264,22 @@ async function apply(args) {
   console.log(`Applied ${Object.keys(clean).length} entries (${Object.keys(merged.rules).length} total). Run \`total-recall rules verify\` after the vault recompiles.`);
 }
 
-function verify(args) {
+async function verify(args) {
   const { flags } = parseFlags(args, ['budget']);
-  const budget = resolveBudget(flags);
+  const explicit = explicitBudget(flags);
+  const budget = explicit ?? await effectiveBudget();
   const state = loadState();
   const problems = [];
   if (state.health === 'ambiguous' || state.health === 'malformed') problems.push(`policy is ${state.health}; curation is ignored`);
   for (const id of state.stale) problems.push(`stale curation: ${id} (rule edited; full text in use)`);
   for (const id of state.orphan) problems.push(`orphan curation: ${id} (rule no longer exists)`);
   const capsules = sizes(state).filter(s => s.actions !== '(none)').map(s => ({ actions: s.actions, tokens: s.tokens, rules: s.count, withinBudget: s.tokens <= budget }));
-  for (const s of capsules) if (!s.withinBudget) problems.push(`capsule for ${s.actions} is ${s.tokens} tokens > ${budget}`);
+  if (explicit) for (const s of capsules) { if (!s.withinBudget) problems.push(`capsule for ${s.actions} is ${s.tokens} tokens > ${budget}`); }
+  else await checkCompactable(capsules, budget, problems);
   const ok = problems.length === 0;
   if (flags.json) { console.log(JSON.stringify({ ok, health: state.health, budget, capsules, problems }, null, 1)); if (!ok) process.exitCode = 1; return; }
   if (!ok) { for (const p of problems) console.log(`✖ ${p}`); process.exitCode = 1; return; }
-  console.log(`✔ policy ${state.health}; every action capsule within ${budget} tokens`);
+  console.log(`✔ policy ${state.health}; every action capsule within ${budget} tokens${explicit ? '' : ' (compacted where needed)'}`);
 }
 
 async function prune(args) {

package/src/cli/startup.mjs

@@ -41,7 +41,7 @@ export default async function startup(args = []) {
     const availH = harnesses.filter(h => h.available);
     const readyH = availH.filter(h => h.authed);
     if (availH.length) {
-      console.log(`Harnesses: ${readyH.length}/${availH.length} ready (${readyH.map(h => `${h.id}: 5h ${h.rolling5hRemainingPct}`).join(', ')})`);
+      console.log(`Harnesses: ${readyH.length}/${availH.length} ready (${readyH.map(h => `${h.id}: 5h ${h.rolling5hRemainingPct} [${h.enforcement || 'enforced'}]`).join(', ')})`);
     }
     for (const action of (report.actions || [])) console.log(`Action: ${action.component} ${action.action} (${action.accepted === true ? 'accepted; see observed readiness' : action.reason || 'failed'})`);
   }

package/src/cli/status.mjs

@@ -78,7 +78,16 @@ function projectionsStatus(clients, instructionsMtime) {
         fresh = projMtime >= instructionsMtime;
       } catch { fresh = false; }
     }
-    return { name, label: info.label, mode: info.mode, connectedAt: info.connectedAt, projectionPath: info.projectionPath, fresh };
+    return {
+      name,
+      label: info.label,
+      mode: info.mode,
+      enforcement: info.enforcement || 'advisory',
+      enforcementReason: info.enforcementReason || null,
+      connectedAt: info.connectedAt,
+      projectionPath: info.projectionPath,
+      fresh
+    };
   });
 }
 
@@ -312,7 +321,8 @@ export default async function statusCmd(args) {
       if (c.mode === 'file' || c.mode === 'symlink') {
         freshnessTag = c.fresh === null ? '  (no projection)' : c.fresh ? '  ✅ fresh' : '  ⚠️  stale — run: total-recall connect ' + c.name;
       }
-      console.log(`    ${c.label.padEnd(18)} [${c.mode}]${freshnessTag}`);
+      const enfTag = c.enforcement ? ` [${c.enforcement}]` : '';
+      console.log(`    ${c.label.padEnd(18)} [${c.mode}]${enfTag}${freshnessTag}`);
     }
   } else {
     console.log('  Connected clients: (none — run total-recall connect <client>)');

package/src/core/claude-hooks.mjs

@@ -21,18 +21,24 @@ const GATE_MATCHER = 'Bash|RemoteTrigger|CronCreate|mcp__scheduled-tasks__.*|mcp
 
 const SKILL_COMMAND = 'f="$CLAUDE_PROJECT_DIR/.agent/skills/total-recall/SKILL.md"; [ -f "$f" ] || f="$HOME/.agent/skills/total-recall/SKILL.md"; if [ -f "$f" ]; then echo "MANDATORY CONTEXT: the Total Recall skill ($f), loaded by a SessionStart hook. Follow it; use the total-recall CLI as documented here."; cat "$f"; fi';
 
+export const PREFLIGHT_GATE_COMMAND = 'total-recall preflight gate --harness claude';
+export const PREFLIGHT_REMIND_COMMAND = 'total-recall preflight remind';
+export const STOPGAP_FILE = 'total-recall-preflight.mjs';
+
 const hasCommand = (entries, needle) => (entries || []).some((e) => (e.hooks || []).some((h) => String(h.command || h.statusMessage || '').includes(needle)));
 
 /**
  * @param {{ home?: string, dryRun?: boolean }} [opts]
- * @returns {{ gate: string, settings: string, added: string[] }}
+ * @returns {{ gate: string, settings: string, added: string[], removed: string[] }}
  */
 export function installClaudeCodeHooks(opts = {}) {
   const home = opts.home || os.homedir();
   const claudeDir = path.join(home, '.claude');
   const hookPath = path.join(claudeDir, 'hooks', GATE_FILE);
+  const stopgapPath = path.join(claudeDir, 'hooks', STOPGAP_FILE);
   const settingsPath = path.join(claudeDir, 'settings.json');
   const added = [];
+  const removed = [];
 
   const template = fs.readFileSync(GATE_TEMPLATE, 'utf8');
   const current = fs.existsSync(hookPath) ? fs.readFileSync(hookPath, 'utf8') : null;
@@ -46,6 +52,28 @@ export function installClaudeCodeHooks(opts = {}) {
     }
   }
   const hooks = settings.hooks || (settings.hooks = {});
+
+  // Clean up 2026-11-02 stopgap entries from settings and filesystem (ENFORCE-R14)
+  for (const event of ['PreToolUse', 'UserPromptSubmit', 'SessionStart', 'PostToolUse']) {
+    if (Array.isArray(hooks[event])) {
+      const beforeLen = hooks[event].length;
+      hooks[event] = hooks[event].filter(entry => {
+        const sub = entry.hooks || [];
+        return !sub.some(h => String(h.command || '').includes(STOPGAP_FILE));
+      });
+      if (hooks[event].length < beforeLen) {
+        removed.push(`stopgap ${event} hook`);
+      }
+    }
+  }
+
+  if (!opts.dryRun && fs.existsSync(stopgapPath)) {
+    try {
+      fs.unlinkSync(stopgapPath);
+      removed.push('stopgap hook script');
+    } catch { /* ignore */ }
+  }
+
   const gateCommand = `node "$HOME/.claude/hooks/${GATE_FILE}"`;
   if (!hasCommand(hooks.SessionStart, SKILL_MARK) && !hasCommand(hooks.SessionStart, 'total-recall/SKILL.md')) {
     (hooks.SessionStart ||= []).push({ hooks: [{ type: 'command', command: SKILL_COMMAND, timeout: 10, statusMessage: SKILL_MARK }] });
@@ -60,11 +88,21 @@ export function installClaudeCodeHooks(opts = {}) {
     added.push('PostToolUse recorder');
   }
 
-  if (!opts.dryRun && added.length) {
+  // Managed preflight enforcement hooks (ENFORCE-R1, ENFORCE-R2, ENFORCE-R14)
+  if (!hasCommand(hooks.PreToolUse, 'preflight gate --harness claude')) {
+    (hooks.PreToolUse ||= []).push({ matcher: '*', hooks: [{ type: 'command', command: PREFLIGHT_GATE_COMMAND, timeout: 5 }] });
+    added.push('managed PreToolUse preflight gate');
+  }
+  if (!hasCommand(hooks.UserPromptSubmit, 'preflight remind')) {
+    (hooks.UserPromptSubmit ||= []).push({ hooks: [{ type: 'command', command: PREFLIGHT_REMIND_COMMAND, timeout: 5 }] });
+    added.push('managed UserPromptSubmit preflight reminder');
+  }
+
+  if (!opts.dryRun && (added.length || removed.length)) {
     fs.mkdirSync(path.dirname(hookPath), { recursive: true });
     if (current !== template) fs.writeFileSync(hookPath, template, { mode: 0o755 });
     if (fs.existsSync(settingsPath)) fs.copyFileSync(settingsPath, `${settingsPath}.bak-total-recall`);
     fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   }
-  return { gate: hookPath, settings: settingsPath, added };
+  return { gate: hookPath, settings: settingsPath, added, removed };
 }