liteagents 2.24.1 → 3.5.0

package/packages/opencode/command/remember/sync-rules.cjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sync-rules.cjs — keeps a repo's AGENT_RULES.md current with the installed
+ * template, without ever destroying what was there.
+ *
+ * Run every /remember, from the target repo. Before this existed, the rules
+ * were bootstrapped once and never refreshed, so a measured 35 local repos
+ * drifted to a body many releases old and three hand sweeps failed to hold.
+ *
+ * Three outcomes, decided by a byte compare — not a stored hash, because the
+ * only question is "am I about to change this file?", which any careful copy
+ * asks anyway:
+ *
+ *   absent     copy it in and say so
+ *   identical  do nothing at all: no write, no backup, no output
+ *   differs    move the old body aside, copy the new one in, say so loudly
+ *
+ * THE BACKUP IS A SINGLE FILE and is overwritten on each differing run. A
+ * customised file therefore survives exactly one update: fold your changes
+ * into the new AGENT_RULES.md before the next release, or the next sync
+ * replaces the backup with a vanilla body. This is a deliberate trade — see
+ * docs/product/agent-rules-freshness-prd.md §5 — chosen over accumulating
+ * timestamped backups.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Per-kit PROJECT dir. NOTE this is not always the global config dir: amp
+// installs to ~/.config/amp but writes .amp/ in a repo, and opencode likewise.
+// This is the ONE line that differs across packages.
+const PROJECT_DIR = '.opencode';
+
+const RULES = 'AGENT_RULES.md';
+const BACKUP = 'AGENT_RULES.md.bak';   // keeps the origin name; not .md, so doc tooling ignores it
+
+/** lstat, not existsSync: existsSync follows links, so a DANGLING link reads
+ *  as absent and gets walked straight past. */
+function lexists(p) {
+  try { fs.lstatSync(p); return true; } catch (e) { return false; }
+}
+
+/**
+ * True when writing to `target` would land outside `repo`.
+ *
+ * There are two ways out and a guard on only one of them is false safety:
+ * `target` may itself be a symlink — including a dangling one, which reads as
+ * "the file is absent" and is still followed on write — or any parent
+ * directory may be a link pointing elsewhere. This runs across a whole fleet
+ * of repos, so a relative link only has to reach a sibling checkout.
+ *
+ * A link that stays INSIDE the repo is not an escape: a repo that keeps its
+ * rules or its config behind an in-repo symlink is an ordinary setup, and
+ * refusing it would strand that repo forever. So the leaf is followed by hand
+ * with readlink — which works on a dangling link, where realpath cannot — and
+ * each hop re-resolves the parents, because the file a link points at can sit
+ * behind a linked directory of its own.
+ */
+function escapesRepo(repo, target) {
+  let root;
+  try { root = fs.realpathSync(repo); } catch (e) { return true; }
+
+  let p = path.resolve(target);
+  for (let hop = 0; hop < 40; hop++) {
+    // Resolve the existing part of the path. Walk up to the deepest ancestor
+    // that exists; anything below it cannot be a link yet.
+    const tail = [];
+    let dir = path.dirname(p);
+    while (!lexists(dir)) {
+      tail.unshift(path.basename(dir));
+      const up = path.dirname(dir);
+      if (up === dir) return true;                  // walked off the filesystem root
+      dir = up;
+    }
+    try { p = path.join(fs.realpathSync(dir), ...tail, path.basename(p)); }
+    catch (e) { return true; }                      // an ancestor is a dangling link
+
+    let to;
+    try { to = fs.readlinkSync(p); } catch (e) {
+      return p !== root && !p.startsWith(root + path.sep);   // not a link: decide here
+    }
+    p = path.resolve(path.dirname(p), to);
+  }
+  return true;                                      // a link cycle: refuse
+}
+
+function templatePath() {
+  // Ships beside this script, so no path guessing and no dependence on where
+  // the kit was installed.
+  return path.join(__dirname, RULES);
+}
+
+function targetPath(repo) {
+  return path.join(repo, PROJECT_DIR, 'remember', RULES);
+}
+
+/**
+ * @returns {{action:string, detail?:string}} action is one of:
+ *   'no-template' | 'bootstrapped' | 'unchanged' | 'updated' | 'failed'
+ */
+function sync(repo) {
+  const tpl = templatePath();
+  let template;
+  try {
+    template = fs.readFileSync(tpl);
+  } catch (e) {
+    return { action: 'no-template', detail: tpl };
+  }
+
+  const target = targetPath(repo);
+  if (escapesRepo(repo, target)) return { action: 'escapes', detail: target };
+
+  let current = null;
+  try { current = fs.readFileSync(target); } catch (e) { /* absent */ }
+
+  // Byte compare. No normalisation on either side: the copy below is a plain
+  // byte write, so a mismatch here means the content really differs.
+  if (current && current.equals(template)) return { action: 'unchanged' };
+
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (current) {
+      // Single backup, overwritten. rename() is atomic on the same filesystem
+      // and cannot leave a half-written backup the way copy+truncate could.
+      fs.renameSync(target, path.join(path.dirname(target), BACKUP));
+    }
+    fs.writeFileSync(target, template);
+  } catch (e) {
+    return { action: 'failed', detail: e.message };
+  }
+
+  return current ? { action: 'updated' } : { action: 'bootstrapped' };
+}
+
+function main() {
+  const repo = process.argv[2] || process.cwd();
+  const r = sync(repo);
+  const rel = path.join(PROJECT_DIR, 'remember', RULES);
+
+  switch (r.action) {
+    case 'unchanged':
+      break;                                  // silent: nothing happened
+    case 'bootstrapped':
+      process.stdout.write(`${rel} created from the installed template\n`);
+      break;
+    case 'updated':
+      process.stdout.write(
+        `${rel} updated from the installed template `
+        + `(previous body kept as ${BACKUP} — fold your changes in before the `
+        + `next release, it is a single file and the next update replaces it)\n`);
+      break;
+    case 'escapes':
+      // Loud, never repaired: the path is under the repo but does not stay
+      // there, so any write lands somewhere the run was not invited.
+      process.stdout.write(
+        `${rel} not synced: it leaves the repo via a symlink — refusing to `
+        + `write through it\n`);
+      break;
+    case 'no-template':
+      // Loud: this means the install is incomplete, not that nothing changed.
+      process.stdout.write(
+        `AGENT_RULES.md not synced: no template beside this script (${r.detail})\n`);
+      break;
+    case 'failed':
+      process.stdout.write(`AGENT_RULES.md not synced: ${r.detail}\n`);
+      break;
+  }
+}
+
+if (require.main === module) {
+  // A passenger on /remember, like version-check.cjs: it never gets to fail
+  // the run it rides in.
+  try { main(); } catch (e) { /* silent */ }
+}
+
+module.exports = { sync, PROJECT_DIR, RULES, BACKUP };

package/packages/opencode/command/remember/version-check.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * version-check.cjs — tells the user their liteagents install is behind the
+ * registry, and nothing else.
+ *
+ * Run as step 0 of /remember, alongside friction.cjs. It rides along with a
+ * memory consolidation run, so the only hard requirement is that it can never
+ * cost that run anything: it exits 0 on every path, prints at most one line,
+ * writes nothing but its own cache, and is bounded in wall-clock time.
+ *
+ * Deliberately NOT part of friction.cjs: that file mines friction signals, and
+ * a registry lookup is an unrelated concern.
+ *
+ * A POC (2026-09-03) found the one non-obvious defect guarded here:
+ * req.setTimeout is a socket-INACTIVITY timeout and does not bound connect
+ * time. Against an unroutable host a 2000ms budget overran to 5146ms. Only an
+ * explicit deadline bounds the total, so both are set.
+ *
+ * Environment:
+ *   npm_config_registry            registry base (npm sets this; mirrors work)
+ *   LITEAGENTS_INSTALLED_VERSION   skip local version discovery
+ *   LITEAGENTS_SKIP_NPM_LOOKUP     skip the `npm ls -g` fallback (it is slow)
+ *
+ * Installed version is resolved in cost order: the installer's manifest stamp
+ * (a file read), then our own package.json when run from a checkout, then
+ * `npm ls -g` as a last resort. The last one costs ~500ms on EVERY run, which
+ * is why the installer stamps the manifest at all.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PKG = 'liteagents';
+// Per-kit config dir. This is the ONE line that differs across packages.
+const CONFIG_DIR = '.config/opencode';
+const TTL_MS = 24 * 60 * 60 * 1000;
+const DEADLINE_MS = 2000;
+const NPM_LOOKUP_MS = 3000;
+
+// --- version comparison --------------------------------------------------
+
+/**
+ * Is `b` a newer release than `a`? Numeric per component, so 2.9.0 < 2.10.0 —
+ * a string compare gets that backwards. A prerelease suffix is stripped, so
+ * 2.24.2-beta.1 counts as newer than 2.24.1: it is still a later release, and
+ * a user on it does not need advice about 2.24.1.
+ */
+function isNewer(a, b) {
+  const parse = (v) => String(v).trim().replace(/^v/, '').split('-')[0]
+    .split('.').map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i++) {
+    const d = (y[i] || 0) - (x[i] || 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+// --- installed version ---------------------------------------------------
+
+// Walk up from this file looking for our own package.json. Finds it when
+// running from a checkout; finds nothing when installed into ~/.config/opencode, which
+// is why the npm fallback exists.
+function versionFromPackageJson() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      if (pkg && pkg.name === PKG && pkg.version) return String(pkg.version);
+    } catch (e) { /* keep walking */ }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// The installer stamps the release it wrote into <install root>/manifest.json.
+// version-check.cjs sits at <root>/<skills|commands|command>/remember/, so the root
+// two levels up. This is the fast path: reading a file beats spawning npm.
+function versionFromManifest() {
+  try {
+    const m = JSON.parse(fs.readFileSync(
+      path.join(__dirname, '..', '..', 'manifest.json'), 'utf8'));
+    // NOT m.version -- that is the manifest schema version, a different thing.
+    return m && m.liteagents_version ? String(m.liteagents_version) : null;
+  } catch (e) { return null; }
+}
+
+function versionFromNpm() {
+  if (process.env.LITEAGENTS_SKIP_NPM_LOOKUP) return null;
+  try {
+    const r = require('child_process').spawnSync(
+      'npm', ['ls', '-g', PKG, '--depth=0', '--json'],
+      { encoding: 'utf8', timeout: NPM_LOOKUP_MS }
+    );
+    if (!r.stdout) return null;
+    const deps = JSON.parse(r.stdout).dependencies || {};
+    return deps[PKG] && deps[PKG].version ? String(deps[PKG].version) : null;
+  } catch (e) { return null; }
+}
+
+function installedVersion() {
+  const env = (process.env.LITEAGENTS_INSTALLED_VERSION || '').trim();
+  if (env) return env;
+  return versionFromManifest() || versionFromPackageJson() || versionFromNpm();
+}
+
+// --- cache ---------------------------------------------------------------
+
+// Home-scoped, not per-repo: it describes the global install, so a per-repo
+// cache would make every repo fetch the same answer.
+function cachePath() {
+  return path.join(os.homedir(), CONFIG_DIR, `.${PKG}-version.json`);
+}
+
+function readCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+    if (typeof c.checked_at !== 'number' || typeof c.latest !== 'string') return null;
+    if (Date.now() - c.checked_at > TTL_MS) return null;
+    return c.latest;
+  } catch (e) { return null; }
+}
+
+// Best effort. An unwritable cache dir means we re-fetch next run, never that
+// we withhold the advice we already have.
+function writeCache(latest) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify({ checked_at: Date.now(), latest }));
+  } catch (e) { /* not worth a word */ }
+}
+
+// --- registry ------------------------------------------------------------
+
+function fetchLatest(cb) {
+  let base = process.env.npm_config_registry || 'https://registry.npmjs.org/';
+  if (!/\/$/.test(base)) base += '/';
+  const url = `${base}${PKG}/latest`;
+
+  let mod;
+  try { mod = url.startsWith('http://') ? require('http') : require('https'); }
+  catch (e) { return cb(null); }
+
+  let settled = false;
+  let req = null;
+  const finish = (v) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(deadline);
+    if (v === null && req) { try { req.destroy(); } catch (e) { /* */ } }
+    cb(v);
+  };
+
+  // The hard bound. req.setTimeout below does not cover connect time.
+  const deadline = setTimeout(() => finish(null), DEADLINE_MS);
+
+  try {
+    req = mod.get(url, { headers: { accept: 'application/json' } }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); return finish(null); }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => {
+        body += c;
+        if (body.length > 1e6) finish(null); // a packument this big is not ours
+      });
+      res.on('end', () => {
+        try {
+          const v = JSON.parse(body).version;
+          finish(typeof v === 'string' && v ? v : null);
+        } catch (e) { finish(null); }
+      });
+      res.on('error', () => finish(null));
+    });
+    req.setTimeout(DEADLINE_MS, () => finish(null));
+    req.on('error', () => finish(null));
+  } catch (e) { finish(null); }
+}
+
+// --- main ----------------------------------------------------------------
+
+function advise(installed, latest) {
+  if (!installed || !latest) return;            // never guess
+  if (!isNewer(installed, latest)) return;      // current, or ahead of the registry
+  process.stdout.write(
+    `liteagents ${installed} -> ${latest} available: `
+    + `npm i -g ${PKG}@latest && ${PKG}\n`
+  );
+}
+
+function main() {
+  const installed = installedVersion();
+
+  const cached = readCache();
+  if (cached) return advise(installed, cached);
+
+  fetchLatest((latest) => {
+    if (!latest) return;                        // offline, slow, or broken: silent
+    writeCache(latest);
+    advise(installed, latest);
+  });
+}
+
+if (require.main === module) {
+  // Every failure is silent by contract. This command is a passenger; it does
+  // not get to fail the run it is riding in.
+  try { main(); } catch (e) { /* silent */ }
+} 
+
+module.exports = { isNewer };

package/packages/opencode/command/remember.md

@@ -1,7 +1,5 @@
 ---
-name: remember
 description: Consolidate stashes + friction into project memory
-usage: /remember
 ---
 
 Run friction analysis, then consolidate session stashes + friction antigens into a single project-local MEMORY.md, and inject into AGENTS.md. Friction runs automatically (best-effort) — there is no separate `/friction` command. A docs reconcile check runs at the end, detect-only.
@@ -38,10 +36,31 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
    - **Locate `friction.cjs`** — it is bundled next to this command at `remember/friction.cjs`
      (the same directory as `remember.md`, whether installed or run from the package). If it
      exists nowhere, skip to step 1 (stash-only) and tell the user friction.cjs is missing.
+   - **Check for a newer liteagents** (best-effort, one line, never blocking) — bundled
+     beside `friction.cjs` as `remember/version-check.cjs`. Call it by its **absolute
+     path**, exactly as step 7 calls `docs-builder.cjs`: the cwd here is the target repo,
+     not this package, so a cwd-relative path fails everywhere except the liteagents repo
+     itself.
+     ```bash
+     node ~/.config/opencode/command/remember/version-check.cjs
+     ```
+     **If that path does not exist, use the directory you just resolved for
+     `friction.cjs`** — the two ship side by side, so that directory is correct for a
+     non-default install and when running from a checkout, where the path above would
+     point at the installed copy instead of the one under test.
+     It prints one advice line if the installed version is behind the registry, and prints
+     nothing otherwise. It exits 0 on every path, caches the registry answer for 24h, and
+     is bounded to ~2s, so it cannot stall this run. If it prints a line, relay it verbatim
+     in your final report; never act on it and never run the install yourself.
+   - **If the script is missing from both locations, say so** — one line, same rule as step
+     7's "applicable but could not run". A failed *check* (offline, registry down, timeout)
+     stays silent by design: it is a once-a-day nudge, not a result anyone is waiting on. A
+     missing *script* means the install is incomplete, which is worth a word.
    - **Resolve the global sessions root** — probe this list top-to-bottom, use the first that
      exists and contains `.jsonl` files directly, or one level down in per-project
      subdirectories (friction.cjs scans exactly those two levels, not a deep recursive walk).
      **Never prompt the user.**
+     <!-- mirror:literal:start — every tool's real path, identical in all four kits -->
      ```
      # ── Add your own global sessions root at the TOP so it is checked first ──
      ~/.claude/projects/                 # Claude Code
@@ -51,6 +70,7 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      ~/.codex/sessions/                  # Codex CLI  (use $CODEX_HOME/sessions/ if set)
      ~/.gemini/antigravity-cli/brain/    # Antigravity
      ```
+     <!-- mirror:literal:end -->
      > Note: `friction.cjs` parses Claude Code's session schema. The Codex/Antigravity roots
      > will resolve but yield no signals until friction learns their formats — open an issue
      > to request one: https://github.com/hamr0/liteagents/issues
@@ -72,11 +92,26 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      fresh output). **Move only those pipeline files** — anything else in `.opencode/memory/`
      (e.g. user-owned rule files) stays where it is. Remove the old dirs only if empty, update the managed MEMORY section in AGENTS.md to
      the new reference (step 5), and tell the user exactly what moved.
-   - **Bootstrap `AGENT_RULES.md` (one-time, silent-if-present).** If
-     `.opencode/remember/AGENT_RULES.md` does not exist, copy it from the bundled template next
-     to this command (`remember/AGENT_RULES.md`, same directory as `friction.cjs`). If it
-     already exists, leave it untouched — never overwrite, even if the bundled template
-     changes in a later version; it becomes user-owned the moment it lands in the project.
+   - **Sync `AGENT_RULES.md` from the installed template** — run the bundled script, which
+     does the whole decision itself. Call it by **absolute path**, for the same reason as
+     `version-check.cjs` in step 0: the cwd is the target repo, not this package.
+     ```bash
+     node ~/.config/opencode/command/remember/sync-rules.cjs
+     ```
+     It compares `.opencode/remember/AGENT_RULES.md` against the template shipped beside it
+     and takes one of three actions: **absent** — copies it in; **identical** — does
+     nothing at all, no write and no output; **differs** — moves the old body to
+     `AGENT_RULES.md.bak` and copies the new one in, reporting both. Relay whatever it
+     prints in the step-8 report; it is silent when nothing changed.
+
+     **This replaced a bootstrap-once rule that never refreshed**, which left a measured 35
+     repos many releases behind. The rules doc is a shipped standards document, so it is
+     kept current rather than frozen on first write — nothing is destroyed, because a
+     differing body is always preserved in the backup first.
+
+     The comparison is a byte compare done *by the script*, never by you: a model-performed
+     copy can re-wrap a line or drop a trailing newline, and the file would then differ
+     forever, backing up on every single run.
    - Read all `.opencode/stash/*.md` files in the current project
    - Read friction output written in step 0: `.opencode/remember/friction/antigen_clusters.json` (preferred) or `.opencode/remember/friction/antigen_review.md` (fallback). On the fallback path, step 4c does NO counting — merge quotes into
      matching entries only; never change `sessions`, `last_seen`, or `recurred_while_hot` (the
@@ -88,7 +123,11 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      length-gate debt on `.opencode/remember/MEMORY.md`. Steps 4-5 (friction → ledger count →
      Antigens render) are stash-independent and still run whenever friction produced output
      (see step 4's own guard). If there is also no friction
-     output, report "nothing to consolidate" and stop after step 1.
+     output, report "nothing to consolidate" and stop after step 1 — **but run
+     step 5's `stub-check.cjs` before you stop.** The stub shape does not depend on
+     there being anything to consolidate, and skipping it on quiet runs is exactly
+     how a repo with nothing to remember stays broken forever. `sync-rules.cjs`
+     already ran above, for the same reason.
 
 2. **Extract from unprocessed stashes** (up to 5 stashes per agent, as few agents as possible — see Guardrails)
    - Each agent reads its batch of stashes together and calls the mid-tier model (see Guardrails) to extract:
@@ -387,11 +426,32 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      Users trim this section deliberately (a pointer-only variant is common), and rewriting
      it silently re-adds text they removed, on every single run, forever. Observed in the
      field: a run restored the inline rules into a AGENTS.md whose owner had cut them, and
-     the edit had to be reverted by hand. This matches how `AGENT_RULES.md` itself is
-     handled — bootstrapped once, never overwritten after.
+     the edit had to be reverted by hand. Note this no longer matches how `AGENT_RULES.md`
+     itself is handled: `sync-rules.cjs` refreshes that file every run, because it is a
+     shipped standards document with a backup behind it. This section is prose the user
+     owns, with nothing behind it — so it stays bootstrap-once.
    - If an existing pair is present but its **path pointer** is missing or wrong, that is
      load-bearing: **report it and stop**, do not silently rewrite the section around it.
 
+   - **Then assert the stub SHAPE mechanically** — run the bundled script by **absolute
+     path**, for the same reason as steps 0 and 1:
+     ```bash
+     node ~/.config/opencode/command/remember/stub-check.cjs
+     ```
+     It edits only *inside* the marker pairs, and only the mechanism: a MEMORY include that
+     is not `@.opencode/remember/MEMORY.md` is repaired, and an `@`-include of
+     `AGENT_RULES.md` is demoted to a plain pointer. Prose inside the blocks is user-owned
+     and is never touched, which is why the bootstrap-once rule above still holds. It will
+     **not** repoint a MEMORY include at a file that does not exist — an un-migrated
+     `.opencode/memory/` repo has a live MEMORY.md at the old path, and breaking a working
+     include to satisfy a naming convention is worse than reporting it. Silent when the
+     shape is already current; relay whatever it prints in the step-8 report.
+
+     Measured 2026-09-03: 21 of 37 local repos still carried the pre-v2.19 `@`-include of
+     `AGENT_RULES.md`, hot-loading ~300 lines into every session. A shape rule checked by
+     asking you to look is a rule that drifts back; this one is a byte-level assertion done
+     by the script, never by you.
+
    ```markdown
    # Project Memory
    > Auto-generated by /remember. Do not edit manually.
@@ -452,8 +512,10 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
    `index-flat` script `/docs-builder` already uses, never a model call. Wrapped so any
    failure here can never block the memory write that already happened in steps 3-6.
 
-   - **Locate `docs-builder.cjs`** — bundled next to this command at
-     `docs-builder/docs-builder.cjs` (same convention as `remember/friction.cjs`). Call it by
+   - **Locate `docs-builder.cjs`** — it ships in the `docs-builder/` directory
+     that sits beside this one (under `skills/` on Claude Code and Amp, under
+     `commands/` on Droid and opencode), exactly as `friction.cjs` ships beside
+     this file. Call it by
      its **absolute path** in the command below — the cwd here is the target repo, not this
      package, so a cwd-relative path fails everywhere except the liteagents repo itself.
    - **Not applicable, stay silent:** if the project has no `docs/` directory, skip without
@@ -535,7 +597,14 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      ledger: ag-003 "don't commit per change"    RECURRED while hot (2/2) → rephrased, attempt 2
      ledger: ag-002 "literal scoped ask"         ESCALATED → Fact; 2 phrasings failed. Hook or accept?
      ```
-   - If AGENT_RULES.md was bootstrapped this run, say so (one line)
+   - Relay verbatim whatever `version-check.cjs` (step 0), `sync-rules.cjs` (step 1), and
+     `stub-check.cjs` (step 5) printed. Never re-word or summarize them: they are the
+     record of a file that was written or a version gap, and a paraphrase of "your body
+     was backed up to AGENT_RULES.md.bak" can lose the filename the user needs.
+   - Each is silent when nothing changed, so silence is the normal case and there is
+     nothing to invent — never report an action that produced no output.
+   - Never a silent write: if any of the three wrote or moved a file and you did not
+     relay its line, that is a defect.
    - If step 7 ran the auto re-index, say so and name the regenerated files
      (`docs/index.md`, plus `docs/log.md` if touched) so they are staged with this run
    - Confirm MEMORY.md and AGENTS.md updated
@@ -543,7 +612,8 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
 **File locations (all project-local — two dirs: `/stash` owns `.opencode/stash/`, `/remember` owns `.opencode/remember/`)**
 - Stash files: `.opencode/stash/*.md`
 - Memory file: `.opencode/remember/MEMORY.md` (single source of truth, referenced as `@.opencode/remember/MEMORY.md`)
-- Rules template: `.opencode/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced by a plain path pointer, not `@`-referenced — see step 5)
+- Rules template: `.opencode/remember/AGENT_RULES.md` (refreshed from the bundled package template every `/remember` run by `sync-rules.cjs`; a differing body is backed up first, not silently overwritten — referenced by a plain path pointer, not `@`-referenced — see step 5)
+- Rules backup: `.opencode/remember/AGENT_RULES.md.bak` (written by `sync-rules.cjs` only when the existing body differs from the template; a single file, overwritten each time it fires — not timestamped)
 - Antigen ledger: `.opencode/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.opencode/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.opencode/remember/.processed`