liteagents 2.24.1 → 3.0.0

package/packages/droid/commands/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 = '.factory';
+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 ~/.factory, 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>/<commands|command>/remember/, so the root is
+// 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/droid/commands/remember.md

@@ -38,6 +38,26 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
    - **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 ~/.factory/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 (`.factory/stash/*.md` + `.factory/remember/friction/anti
      fresh output). **Move only those pipeline files** — anything else in `.factory/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
-     `.factory/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 ~/.factory/commands/remember/sync-rules.cjs
+     ```
+     It compares `.factory/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 `.factory/stash/*.md` files in the current project
    - Read friction output written in step 0: `.factory/remember/friction/antigen_clusters.json` (preferred) or `.factory/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 (`.factory/stash/*.md` + `.factory/remember/friction/anti
      length-gate debt on `.factory/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 (`.factory/stash/*.md` + `.factory/remember/friction/anti
      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 ~/.factory/commands/remember/stub-check.cjs
+     ```
+     It edits only *inside* the marker pairs, and only the mechanism: a MEMORY include that
+     is not `@.factory/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
+     `.factory/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 (`.factory/stash/*.md` + `.factory/remember/friction/anti
      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 +610,8 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
 **File locations (all project-local — two dirs: `/stash` owns `.factory/stash/`, `/remember` owns `.factory/remember/`)**
 - Stash files: `.factory/stash/*.md`
 - Memory file: `.factory/remember/MEMORY.md` (single source of truth, referenced as `@.factory/remember/MEMORY.md`)
-- Rules template: `.factory/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: `.factory/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: `.factory/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: `.factory/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.factory/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.factory/remember/.processed`

package/packages/droid/droids/orchestrator.md

@@ -77,7 +77,7 @@ Predefined multi-agent sequences:
 | Workflow | Sequence | When |
 |----------|----------|------|
 | **Greenfield** | market-researcher → feature-planner → 1-create-prd → 2-generate-tasks → 3-process-task-list | New product/feature from scratch |
-| **Brownfield** | context-builder → system-architect → feature-planner | Understand existing codebase |
+| **Brownfield** | system-architect → feature-planner | Understand existing codebase |
 | **Feature** | feature-planner → 1-create-prd → 2-generate-tasks → 3-process-task-list | Add feature to existing product |
 | **Bug Fix** | code-developer → quality-assurance | Fix and verify |
 | **Sprint** | feature-planner (*sprint-plan) → 2-generate-tasks | Plan sprint from backlog |
@@ -96,7 +96,7 @@ Quick routing when user has clear intent:
 | review, quality, test | quality-assurance |
 | design, UI, wireframe | ui-designer |
 | architecture, tech, design doc | system-architect |
-| understand, document, brownfield | context-builder |
+| understand, brownfield, existing codebase | system-architect |
 
 ## Commands
 

package/packages/opencode/AGENTS.md

@@ -6,7 +6,7 @@ Opencode is a lightweight CLI tool that provides workflow automation commands.
 
 These subagents are available when using Claude Code CLI. Opencode 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. Opencode can reference
 | 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/opencode/agent/orchestrator.md

@@ -81,7 +81,7 @@ Predefined multi-agent sequences:
 | Workflow | Sequence | When |
 |----------|----------|------|
 | **Greenfield** | market-researcher → feature-planner → 1-create-prd → 2-generate-tasks → 3-process-task-list | New product/feature from scratch |
-| **Brownfield** | context-builder → system-architect → feature-planner | Understand existing codebase |
+| **Brownfield** | system-architect → feature-planner | Understand existing codebase |
 | **Feature** | feature-planner → 1-create-prd → 2-generate-tasks → 3-process-task-list | Add feature to existing product |
 | **Bug Fix** | code-developer → quality-assurance | Fix and verify |
 | **Sprint** | feature-planner (*sprint-plan) → 2-generate-tasks | Plan sprint from backlog |
@@ -100,7 +100,7 @@ Quick routing when user has clear intent:
 | review, quality, test | quality-assurance |
 | design, UI, wireframe | ui-designer |
 | architecture, tech, design doc | system-architect |
-| understand, document, brownfield | context-builder |
+| understand, brownfield, existing codebase | system-architect |
 
 ## Commands
 

package/packages/opencode/command/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/opencode/command/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 `.opencode/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 = '.opencode';
+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 };