liteagents 2.24.0 → 3.0.0

package/packages/claude/commands/remember.md

@@ -38,6 +38,26 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
    - **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 ~/.claude/commands/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).
@@ -72,11 +92,26 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
      fresh output). **Move only those pipeline files** — anything else in `.claude/memory/`
      (e.g. user-owned rule files) stays where it is. Remove the old dirs only if empty, update the managed MEMORY section in CLAUDE.md to
      the new reference (step 5), and tell the user exactly what moved.
-   - **Bootstrap `AGENT_RULES.md` (one-time, silent-if-present).** If
-     `.claude/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 ~/.claude/commands/remember/sync-rules.cjs
+     ```
+     It compares `.claude/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 `.claude/stash/*.md` files in the current project
    - Read friction output written in step 0: `.claude/remember/friction/antigen_clusters.json` (preferred) or `.claude/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 (`.claude/stash/*.md` + `.claude/remember/friction/antige
      length-gate debt on `.claude/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 (`.claude/stash/*.md` + `.claude/remember/friction/antige
      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 CLAUDE.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 ~/.claude/commands/remember/stub-check.cjs
+     ```
+     It edits only *inside* the marker pairs, and only the mechanism: a MEMORY include that
+     is not `@.claude/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
+     `.claude/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.
@@ -535,7 +595,14 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
      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 CLAUDE.md updated
@@ -543,7 +610,8 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
 **File locations (all project-local — two dirs: `/stash` owns `.claude/stash/`, `/remember` owns `.claude/remember/`)**
 - Stash files: `.claude/stash/*.md`
 - Memory file: `.claude/remember/MEMORY.md` (single source of truth, referenced as `@.claude/remember/MEMORY.md`)
-- Rules template: `.claude/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: `.claude/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: `.claude/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: `.claude/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.claude/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.claude/remember/.processed`

package/packages/droid/AGENTS.md

@@ -6,7 +6,7 @@ Droid is a lightweight CLI tool that provides workflow automation commands.
 
 These subagents are available when using Claude Code CLI. Droid can reference them but doesn't implement them directly.
 
-### Subagents (11 total)
+### Subagents (10 total)
 
 | ID | Title | When To Use |
 |---|---|---|
@@ -14,7 +14,6 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | 2-generate-tasks | 2-Generate Tasks | Detailed Planning - use to break down the PRD into a granular, actionable task list |
 | 3-process-task-list | 3-Process Task List | Iterative Implementation - use to guide the AI to tackle one task at a time, allowing you to review and approve each change |
 | code-developer | Full Stack Developer | Use for code implementation, debugging, refactoring, and development best practices |
-| context-builder | Context Initializer | Use to initialize project context for new/existing projects, discover and organize documentation, create AGENTS.md and KNOWLEDGE_BASE.md for optimal token-efficient memory |
 | feature-planner | Product Manager | Use for creating epics and user stories, prioritization, backlog navigation, story refinement, and retrospectives |
 | market-researcher | Business Analyst | Use for market research, brainstorming, competitive analysis, project briefs, and initial project discovery |
 | orchestrator | Master Orchestrator | Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult |

package/packages/droid/commands/refactor.md

@@ -72,8 +72,14 @@ refactor and how to close each item.
    behaviour change is not a refactor — leave the bullet, note it in the report.
 5. Run the tests as described below. Then report: **fixed / dropped / left**
    with the reason per left item, and the remaining bullet count.
-6. Say plainly: **commit, then run `/branch-review`** on this branch — ledger
-   mode is a fixer, not a review, and its diff gets the ordinary gate.
+6. **Hand it back; do not chain it.** Say plainly: **commit, then run
+   `/branch-review`** on this branch — ledger mode is a fixer, not a review,
+   and its diff gets the ordinary gate. That is a sentence you *say*, not a
+   sequence you *run*. They are two separate calls and both are the user's:
+   an answer of "commit", "yes" or "go" authorizes the commit and nothing
+   after it. Never start `/branch-review` off the back of it. Observed in the
+   field: a run chained the review onto the owner's "commit" and the owner
+   objected.
 
 ## Goals
 - Reduce complexity

package/packages/droid/commands/remember/stub-check.cjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stub-check.cjs — asserts the two managed blocks in the tool config carry the
+ * CURRENT stub shape, and repairs the shape when it is wrong.
+ *
+ * Shape, not content. The blocks' prose is user-owned — step 5 writes it once
+ * and never re-imposes it, because users trim it deliberately. What this script
+ * touches is only the mechanism:
+ *
+ *   MEMORY block       @<PROJECT_DIR>/remember/MEMORY.md   — an @-include.
+ *                      A bare `@MEMORY.md` resolves relative to the file that
+ *                      contains it, so in a repo root it names a file that does
+ *                      not exist and hot memory silently never loads.
+ *
+ *   AGENT_RULES block  <PROJECT_DIR>/remember/AGENT_RULES.md — a PLAIN pointer.
+ *                      v2.19 demoted it from an @-include on purpose: it is a
+ *                      standards guide to consult when building something new,
+ *                      not hot context, and @-including it loads ~300 lines into
+ *                      every session. Measured 2026-09-03: 21 of 37 local repos
+ *                      still carried the pre-v2.19 @-include.
+ *
+ * Two deliberate limits:
+ *
+ *   - It only edits INSIDE a marker pair. A pointer elsewhere in the config is
+ *     the user's prose and is left alone.
+ *   - It never repoints the MEMORY include at a file that does not exist. An
+ *     un-migrated `.factory/memory/` repo has a live MEMORY.md at the old path;
+ *     rewriting it to the new one would break a working include to satisfy a
+ *     naming convention. That case is reported, not repaired.
+ *
+ * Missing marker pairs are not this script's business — step 5 creates them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// The ONE pair of lines that differs across packages.
+const PROJECT_DIR = '.factory';
+const CONFIG_FILE = 'AGENTS.md';
+
+const MEM = { start: '<!-- MEMORY:START -->', end: '<!-- MEMORY:END -->' };
+const RULES = { start: '<!-- AGENT_RULES:START -->', end: '<!-- AGENT_RULES:END -->' };
+
+const MEMORY_REL = `${PROJECT_DIR}/remember/MEMORY.md`;
+const RULES_REL = `${PROJECT_DIR}/remember/AGENT_RULES.md`;
+
+/** 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.
+ */
+function escapesRepo(repo, target) {
+  let root;
+  try { root = fs.realpathSync(repo); } catch (e) { return true; }
+
+  // Walk up to the deepest ancestor that exists; anything below it cannot be
+  // a link yet, so only the existing part needs resolving.
+  const tail = [];
+  let dir = path.dirname(target);
+  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;
+  }
+
+  let resolved;
+  try { resolved = path.join(fs.realpathSync(dir), ...tail, path.basename(target)); }
+  catch (e) { return true; }                      // an ancestor is a dangling link
+
+  // The last component can be a link even when every directory above it is
+  // clean — that is the dangling-file case.
+  try { if (fs.lstatSync(resolved).isSymbolicLink()) return true; } catch (e) { /* absent: fine */ }
+
+  return resolved !== root && !resolved.startsWith(root + path.sep);
+}
+
+/** Index range of the lines strictly between a marker pair, or null. */
+function blockRange(lines, markers) {
+  const s = lines.findIndex((l) => l.trim() === markers.start);
+  if (s === -1) return null;
+  const e = lines.findIndex((l, i) => i > s && l.trim() === markers.end);
+  if (e === -1) return null;
+  return { from: s + 1, to: e };            // [from, to)
+}
+
+/**
+ * @returns {{fixes:string[], notes:string[], changed:boolean}}
+ *   fixes  — repairs written to disk
+ *   notes  — wrong shapes deliberately left alone, with the reason
+ */
+function check(repo) {
+  const config = path.join(repo, CONFIG_FILE);
+  const fixes = [];
+  const notes = [];
+
+  // Checked before the read, not just before the write: a repair decided
+  // from a followed link is already the wrong decision.
+  if (escapesRepo(repo, config)) {
+    return { fixes, notes: [`${CONFIG_FILE} not checked: it leaves the repo via a symlink`], changed: false };
+  }
+
+  let text;
+  try { text = fs.readFileSync(config, 'utf8'); } catch (e) {
+    return { fixes, notes, changed: false };  // no config: step 5 will create one
+  }
+
+  const lines = text.split('\n');
+  let changed = false;
+
+  // ── MEMORY block: must be an @-include naming the explicit path ────────────
+  const mem = blockRange(lines, MEM);
+  if (mem) {
+    const i = lines.findIndex(
+      (l, n) => n >= mem.from && n < mem.to && /^@\S*MEMORY\.md\s*$/.test(l.trim()));
+    if (i === -1) {
+      notes.push(`${CONFIG_FILE}: MEMORY block has no @-include — hot memory does not load`);
+    } else {
+      const want = `@${MEMORY_REL}`;
+      const have = lines[i].trim();
+      if (have !== want) {
+        if (fs.existsSync(path.join(repo, MEMORY_REL))) {
+          lines[i] = want;
+          changed = true;
+          fixes.push(`${CONFIG_FILE}: MEMORY include repaired, ${have} → ${want}`);
+        } else {
+          // The old path may be the only one with a file behind it.
+          notes.push(
+            `${CONFIG_FILE}: MEMORY include is ${have}, not ${want} — left as is, `
+            + `${MEMORY_REL} does not exist yet`);
+        }
+      }
+    }
+  }
+
+  // ── AGENT_RULES block: must be a PLAIN pointer, never an @-include ─────────
+  const rules = blockRange(lines, RULES);
+  if (rules) {
+    const i = lines.findIndex(
+      (l, n) => n >= rules.from && n < rules.to && /^@\S*AGENT_RULES\.md\s*$/.test(l.trim()));
+    if (i !== -1) {
+      // Demote in place. The path is kept as written — only the @ is dropped,
+      // because the @ is the defect and the path may be a deliberate variant.
+      const had = lines[i].trim();
+      lines[i] = had.slice(1);
+      changed = true;
+      fixes.push(
+        `${CONFIG_FILE}: AGENT_RULES pointer demoted from an @-include (${had} → ${had.slice(1)}) `
+        + `— it is a standards guide, not hot context`);
+    } else {
+      const hasPointer = lines
+        .slice(rules.from, rules.to)
+        .some((l) => /AGENT_RULES\.md/.test(l));
+      if (!hasPointer) {
+        notes.push(`${CONFIG_FILE}: AGENT_RULES block has no path pointer — nothing points at the rules`);
+      }
+    }
+  }
+
+  if (changed) {
+    try {
+      fs.writeFileSync(config, lines.join('\n'));
+    } catch (e) {
+      return { fixes: [], notes: [`${CONFIG_FILE} not repaired: ${e.message}`], changed: false };
+    }
+  }
+
+  return { fixes, notes, changed };
+}
+
+function main() {
+  const repo = process.argv[2] || process.cwd();
+  const r = check(repo);
+  for (const line of r.fixes) process.stdout.write(`${line}\n`);
+  for (const line of r.notes) process.stdout.write(`${line}\n`);
+  // Silent when the shape is already current — the common case.
+}
+
+if (require.main === module) {
+  // A passenger on /remember, like version-check.cjs and sync-rules.cjs: it
+  // never gets to fail the run it rides in.
+  try { main(); } catch (e) { /* silent */ }
+}
+
+module.exports = { check, PROJECT_DIR, CONFIG_FILE, MEMORY_REL, RULES_REL };

package/packages/droid/commands/remember/sync-rules.cjs

@@ -0,0 +1,169 @@
+#!/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 = '.factory';
+
+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.
+ */
+function escapesRepo(repo, target) {
+  let root;
+  try { root = fs.realpathSync(repo); } catch (e) { return true; }
+
+  // Walk up to the deepest ancestor that exists; anything below it cannot be
+  // a link yet, so only the existing part needs resolving.
+  const tail = [];
+  let dir = path.dirname(target);
+  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;
+  }
+
+  let resolved;
+  try { resolved = path.join(fs.realpathSync(dir), ...tail, path.basename(target)); }
+  catch (e) { return true; }                      // an ancestor is a dangling link
+
+  // The last component can be a link even when every directory above it is
+  // clean — that is the dangling-file case.
+  try { if (fs.lstatSync(resolved).isSymbolicLink()) return true; } catch (e) { /* absent: fine */ }
+
+  return resolved !== root && !resolved.startsWith(root + path.sep);
+}
+
+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 };