liteagents 2.24.1 → 3.5.0

package/packages/{claude/commands → ampcode/skills}/remember/AGENT_RULES.md

@@ -130,90 +130,50 @@ A problem you see and don't fix goes in the report, never in a comment. Comments
 
 ## Testing Standards
 
-### Rules
-
-**Test behavior, not implementation.** A test suite must give you confidence to refactor freely. If changing internal code (without changing behavior) breaks tests, those tests are liabilities, not assets.
-
-**Follow the Testing Trophy** (not the Testing Pyramid):
-- Few unit tests — only for pure logic, algorithms, and complex calculations
-- Many integration tests — the sweet spot; test real components working together
-- Some E2E tests — cover critical user journeys end-to-end
-- Static analysis — types and linters catch bugs cheaper than tests
-
-### When to Write Tests
-
-- **After the design stabilizes, not during exploration.** Do not TDD a prototype — you'll write 500 tests for code you delete tomorrow. First make it work (POC), then make it right (refactor + tests), then make it fast
-- **Write tests when the code has users.** If a function is called by other modules or exposed to users, it needs tests. Internal helpers that only serve one caller don't need their own test file
-- **Write tests for bugs.** Every bug fix must include a regression test that fails before the fix and passes after. This is the highest-value test you can write
-- **Write tests before refactoring.** Before changing working code, write characterization tests first to lock in current behavior, then refactor with confidence
-- **Do not write tests for glue code.** Code that just wires components together (calls A then B then C) is tested at the integration level, not unit level
-
-### TDD: When It Works and When It Doesn't
-
-- **TDD works for:** Pure functions, algorithms, parsers, validators, data transformations — anything with clear inputs and outputs
-- **TDD does not work for:** Exploring a design, building a POC, or unstable interfaces. Writing tests for unstable APIs creates churn and false confidence
-- **The rule:** You must understand what you're building before you TDD it. TDD is a design tool for known problems, not a discovery tool for unknown ones
-- **Red-green-refactor discipline:** If you do TDD, follow the cycle strictly. Write a failing test, write minimal code to pass, refactor. Do not write 20 tests then implement — that's front-loading waste
-
-### What Makes a Good Test
-
-- **Tests real behavior.** Call the public API, assert on observable output. Do not reach into internals
-- **Fails for the right reason.** A good test fails when the feature is broken, not when the implementation changes
-- **Reads like a spec.** Someone unfamiliar with the code must understand what the feature does by reading the test
-- **Self-contained.** Each test sets up its own state, runs, and cleans up. No ordering dependencies between tests
-- **Fast and deterministic.** Flaky tests erode trust. If a test depends on timing, network, or global state, fix that dependency
-
-### Anti-Patterns — Do Not Do These
-
-- **Mocking more than 60% of the test.** If most of the test is mock setup, you're testing mocks, not code. Use real implementations with `tmp_path`, `:memory:` SQLite, or test containers
-- **Smoke tests.** `assert result is not None` proves nothing. Assert on specific values, structure, or side effects
-- **Testing private methods.** If you need to test a private method, either it should be public or the public method's tests should cover it
-- **Mirroring implementation.** Tests that replicate the source code line-by-line break on every refactor and catch zero bugs
-- **Test-only production code.** Never add methods, flags, or branches to production code solely for testing. Use dependency injection instead
-
-### Test Organization
-
-- **Co-locate tests with packages:** `packages/<pkg>/tests/` not a root `tests/` directory. Each package owns its tests
-- **Separate by type:**
-  ```
-  packages/<pkg>/tests/
-    unit/           # Fast, isolated, mocked deps, <1s each
-    integration/    # Real DB, filesystem, multi-component, <10s each
-    e2e/            # Full workflows, subprocess calls, <60s each
-    conftest.py     # Shared fixtures for this package
-  ```
-- **One test file per module** (not per function). `test_auth.py` tests the auth module, not `test_login.py` + `test_logout.py` + `test_session.py`
-- **No duplicate test files.** Before creating a new test file, check if one already exists for that module
-
-### Markers and Signals
-
-| Marker | Purpose | CI Behavior |
-|--------|---------|-------------|
-| `@pytest.mark.slow` | Runtime > 5s | Run in full suite, skip in quick checks |
-| `@pytest.mark.ml` | Requires ML deps (torch, etc.) | Skip if deps not installed |
-| `@pytest.mark.real_api` | Calls external APIs | Skip in CI — run manually before release |
-
-**CI runs for fast signals:**
-- `pytest -m "not slow and not ml and not real_api"` — fast gate on every push (~30s)
-- `pytest` — full suite on PR merge or nightly
-- Package-level runs for targeted debugging: `pytest packages/core/tests/`
-
-### Coverage and Ratios
-
-- **Do not chase a coverage number.** 80% coverage with meaningless tests is worse than 40% with behavior-testing integration tests
-- **Cover the critical path first.** Data layer, auth, payment, core business logic — before helper utilities
-- **Coverage tells you what's NOT tested, not what IS tested.** High coverage with bad assertions is false confidence
-- **Delete tests that don't catch bugs.** If a test has never failed (or only fails on refactors), it's not providing value
-
-**Target ratio:** ~20% unit, ~60% integration, ~15% E2E, ~5% manual/exploratory
-
-### Test Tooling Standards
-
-- Use `tmp_path` for filesystem tests, `:memory:` or `tmp_path` SQLite for DB tests
-- Use dependency injection over `@patch` — it's more readable and survives refactors
-- Tests must be self-sufficient — no dependency on project directories, user config, or environment state
-- Use factories or builders for test data, not raw constructors with 15 arguments
-- Keep test fixtures close to where they're used. Shared fixtures in `conftest.py`, not a global test utilities package
+Principles, not a framework. Whatever the language, follow its ecosystem's conventions for
+runner, layout and fixtures — these rules govern what a test must *do*, never how a
+particular toolchain spells it.
+
+### What a test is for
+
+**Test behavior, not implementation.** A suite must give you confidence to refactor freely. If changing internal code without changing behavior breaks tests, those tests are liabilities, not assets.
+
+**Shape — the Testing Trophy, not the Pyramid:** static analysis catches the cheapest bugs; few unit tests, for pure logic and algorithms; many integration tests, the sweet spot, real components working together; some end-to-end tests over the critical journeys. Target roughly 20% unit, 60% integration, 15% E2E, 5% manual.
+
+### When to write them
+
+- **After the design stabilizes, not during exploration.** Do not test a prototype — you will write tests for code you delete tomorrow. First make it work (POC), then make it right (tests), then make it fast
+- **Tests first when you already know the contract.** Pure functions, algorithms, parsers, validators, data transformations — write the test, watch it fail, then implement. When you are still discovering the interface, that same discipline produces churn and false confidence
+- **Write tests for bugs.** Every fix ships a regression test that fails before the fix and passes after — the highest-value test there is
+- **Write tests before refactoring.** Characterization tests lock in current behavior first, then change the code
+- **Write tests when the code has users.** Called by other modules or exposed externally means it needs tests; a helper serving one caller does not need its own file
+- **Do not test glue code.** Something that only wires A to B to C is covered at the integration level
+
+### What makes a good test
+
+- **Tests real behavior.** Call the public interface, assert on observable output. Never reach into internals
+- **Fails for the right reason.** It breaks when the feature breaks, not when the implementation moves
+- **Reads like a spec.** Someone new to the code should learn what the feature does by reading it
+- **Self-contained.** Sets up its own state, runs, cleans up. No ordering dependencies, and no reliance on project directories, user config, or ambient environment
+- **Deterministic.** Flaky tests erode trust. A dependency on timing, network, or global state is a defect in the test
+- **Never sleep for a condition — poll for it.** Sleeping then asserting is wrong at every value: too short and it flakes under load, too long and the suite drags, and a real async bug looks identical to a guess that was too short. Wait on the condition itself, re-reading the state *inside* the loop, with a timeout that names what it was waiting for. A fixed delay is only correct once you have waited for the triggering condition, the delay comes from a documented interval rather than a guess, and a comment says why
+
+### Anti-patterns
+
+- **Mocking most of the test.** If mock setup outweighs the logic, you are testing mocks. Prefer the real thing against a temporary directory, an in-memory store, or a disposable container
+- **Partial mocks.** Mirror the complete structure the real thing returns, not only the fields this test reads. A mock missing a field downstream code consumes passes here and fails in production
+- **Smoke tests.** Asserting a result merely exists proves nothing. Assert on specific values, structure, or side effects
+- **Testing private internals.** If it needs its own test, it should be part of the public interface; otherwise the public tests should reach it
+- **Mirroring implementation.** A test that restates the source line by line breaks on every refactor and catches nothing
+- **Test-only production code.** Never add a method, flag, or branch to production solely for tests. Inject the dependency instead
+- **Chasing a coverage number.** 80% of meaningless tests is worse than 40% of behavioural ones. Coverage tells you what is *not* tested, never that what is covered is correct. Cover the critical path first — data, auth, money, core logic — before helpers
+
+### Organization
+
+- **Mirror the source structure**, at whatever level the ecosystem puts tests. One test file per module, not per function, and never a second file covering a module that already has one
+- **Separate by cost so CI gets a fast signal.** Keep quick isolated tests apart from ones needing real IO or a full workflow, and let the slow ones — long runtimes, heavy optional dependencies, live external APIs — be excluded from the gate that runs on every push and included in the full run
+- **Fixtures live near what uses them**, shared upward only when genuinely shared. Build test data with factories or builders, never a constructor taking fifteen positional arguments
+- **Delete tests that never catch anything.** A test that has only ever failed during refactors is a maintenance cost, not a safety net
 
 ---
 

package/packages/ampcode/{commands/remember.md → skills/remember/SKILL.md}

@@ -1,7 +1,8 @@
 ---
 name: remember
 description: Consolidate stashes + friction into project memory
-usage: /remember
+allowed-tools: Read, Grep, Glob
+disable-model-invocation: true
 ---
 
 Run friction analysis, then consolidate session stashes + friction antigens into a single project-local MEMORY.md, and inject into AGENT.md. Friction runs automatically (best-effort) — there is no separate `/friction` command. A docs reconcile check runs at the end, detect-only.
@@ -38,10 +39,31 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
    - **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/amp/skills/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 +73,7 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      ~/.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 +95,26 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      fresh output). **Move only those pipeline files** — anything else in `.amp/memory/`
      (e.g. user-owned rule files) stays where it is. Remove the old dirs only if empty, update the managed MEMORY section in AGENT.md to
      the new reference (step 5), and tell the user exactly what moved.
-   - **Bootstrap `AGENT_RULES.md` (one-time, silent-if-present).** If
-     `.amp/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/amp/skills/remember/sync-rules.cjs
+     ```
+     It compares `.amp/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 `.amp/stash/*.md` files in the current project
    - Read friction output written in step 0: `.amp/remember/friction/antigen_clusters.json` (preferred) or `.amp/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 +126,11 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      length-gate debt on `.amp/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 +429,32 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      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 AGENT.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/amp/skills/remember/stub-check.cjs
+     ```
+     It edits only *inside* the marker pairs, and only the mechanism: a MEMORY include that
+     is not `@.amp/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
+     `.amp/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 +515,10 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
    `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 +600,14 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      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 AGENT.md updated
@@ -543,7 +615,8 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
 **File locations (all project-local — two dirs: `/stash` owns `.amp/stash/`, `/remember` owns `.amp/remember/`)**
 - Stash files: `.amp/stash/*.md`
 - Memory file: `.amp/remember/MEMORY.md` (single source of truth, referenced as `@.amp/remember/MEMORY.md`)
-- Rules template: `.amp/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: `.amp/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: `.amp/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: `.amp/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.amp/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.amp/remember/.processed`

package/packages/ampcode/skills/remember/stub-check.cjs

@@ -0,0 +1,206 @@
+#!/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 `.amp/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 = '.amp';
+const CONFIG_FILE = 'AGENT.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.
+ *
+ * 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
+}
+
+/** 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 };