liteagents 2.24.1 → 3.5.0

package/packages/opencode/command/refactor.md

@@ -1,11 +1,8 @@
 ---
-name: refactor
-description: Refactor [code]
-usage: /refactor <code-section> | /refactor (no args = fix-ledger mode)
-argument-hint: [file-or-function, or empty for the fix ledger]
-allowed-tools: Read, Edit, Grep, Glob, Bash(npm test *), Bash(npx jest *), Bash(npx vitest *), Bash(pnpm test *), Bash(yarn test *), Bash(pytest *), Bash(python *), Bash(go test *), Bash(cargo test *), Bash(make test *), Bash(git diff *), Bash(git grep *), Bash(git status *), Bash(git rev-parse *), Bash(git switch *)
+description: Refactor and optimize [code]
 ---
-Refactor $ARGUMENTS.
+Refactor $ARGUMENTS. A targeted refactor includes the performance pass
+below — it is on by default, not a separate command.
 
 ## Guardrails
 - **Spawn a worker and explicitly select your tool's mid tier.** State the
@@ -44,15 +41,15 @@ Refactor $ARGUMENTS.
   other does.** `git status --porcelain` at exit must list only files a
   surviving bullet named — that is this command's scope guarantee, and unlike
   `/branch-review` it is not expected to be empty. It cannot police the
-  memory directory: `.claude/` is normally gitignored, so porcelain stays
+  memory directory: `.opencode/` is normally gitignored, so porcelain stays
   empty whether you deleted a fixed bullet, wrote nothing, or overwrote
-  `MEMORY.md`. So also take `md5sum .claude/remember/*` before you start and
+  `MEMORY.md`. So also take `md5sum .opencode/remember/*` before you start and
   again before you report, and show the comparison: only `fix-ledger.md` may
   differ. `last-review.md` in particular is `/branch-review`'s to write —
   a fixer that touches it forges the gate that judges its own work.
 
 ## Ledger mode — `$ARGUMENTS` empty
-Work through `.claude/remember/fix-ledger.md`, the non-blocking findings
+Work through `.opencode/remember/fix-ledger.md`, the non-blocking findings
 `/branch-review` has accumulated. Everything below (goals, constraints,
 verification, HITL gates) still applies; this section only says what to
 refactor and how to close each item.
@@ -72,8 +69,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
@@ -81,6 +84,35 @@ refactor and how to close each item.
 - Apply DRY
 - Better naming
 - Smaller functions (single responsibility)
+- Remove needless work — the performance pass below
+
+## Performance — part of every targeted refactor
+When `$ARGUMENTS` names a target, look for wasted work as well as messy
+work: time and space complexity, N+1 queries, I/O inside a loop, needless
+allocations, the same value recomputed repeatedly.
+
+**Ground every finding before you touch it.** Performance claims are easy
+to invent. A finding counts as **confirmed** only with at least one of:
+- a profile, benchmark or log line showing call frequency or duration,
+- the path sits on an obvious hot loop or per-request handler with real
+  volume,
+- the user supplied evidence in the request.
+
+Without one of those it is **uncertain — report it, do not optimise it.**
+Speculative optimisation is scope creep with a stopwatch.
+
+Fix confirmed findings under the same constraints as any other refactor:
+minimal change, one obvious shape, no behaviour change, no API change.
+After each such edit, re-read the changed region and confirm it still
+computes the same answer — a perf change that quietly alters semantics is
+the worst kind. Report per finding: **location** (`file:line`), **cost**
+(concrete — "N+1 over ~1k rows on every page load", not "could be
+faster"), **change**, **expected improvement**, **trade-off**
+(readability / memory / consistency).
+
+In ledger mode the surviving bullets are the whole scope — do not add
+perf findings of your own. One you notice goes back to the orchestrator
+as a new bullet, like any other side finding.
 
 ## Constraints
 - **NO behavior changes**
@@ -114,8 +146,20 @@ honest way to know is to run them.
 - the change is **bigger than the user asked for** (scope creep —
   unrelated cleanups, formatting, comment edits). Confirm before
   applying.
+- a perf fix has **multiple reasonable shapes** (cache vs precompute vs
+  batch vs paginate vs index) — present the options with trade-offs, not
+  a chosen path.
+- a perf fix trades **correctness for speed** (lossy approximation,
+  weaker or eventual consistency) — even when it is "obviously" faster.
+- a perf fix touches **concurrency primitives** (locks, atomics,
+  ordering) — easy to introduce a race.
+- a perf fix changes a **DB schema, response shape or caller contract**.
 
 Final report:
 - **refactor done, tests N pass / 0 fail** — ready, OR
 - **refactor done, but K tests fail** — awaiting direction (revert /
   patch / update test).
+
+Plus the performance pass: **confirmed-and-fixed** · **confirmed-but-asking**
+(why + options) · **uncertain** (what profiling or data would settle it) ·
+**none found**.

package/packages/opencode/command/release.md

@@ -1,8 +1,5 @@
 ---
-name: release
 description: Verify, sweep docs, cut a version — then hand the release sequence back
-usage: /release
-allowed-tools: Read, Grep, Glob, Edit, Write, Agent, Bash(git status *), Bash(git diff *), Bash(git log *), Bash(git show *), Bash(git fetch *), Bash(git add *), Bash(git commit *), Bash(git rev-parse *), Bash(git merge-base *), Bash(npm *), Bash(pnpm *), Bash(yarn *), Bash(pytest *), Bash(python *), Bash(go *), Bash(cargo *), Bash(make *)
 ---
 Release **preparation** orchestrator for the **current branch**. It runs your
 existing pre-deploy gate, sweeps the docs, bumps the version and commits —
@@ -57,7 +54,7 @@ A review must have run on this branch **at the current HEAD SHA**.
 
 **Compare the SHAs yourself; do not settle for an answer.** Run `git rev-parse
 HEAD` and compare it against the `sha:` line in
-`.claude/remember/last-review.md`, which `/branch-review` writes. Asking the
+`.opencode/remember/last-review.md`, which `/branch-review` writes. Asking the
 orchestrator "did a review run?" puts the question to the one party with an
 incentive to say yes, so its word is not evidence — and neither is a SHA
 quoted from a chat message, which is the same claim in another costume and is
@@ -72,7 +69,7 @@ that predates this file's introduction has no record, so it does not count.
   is what makes "all findings fixed" checkable instead of promised.
   **No exceptions — including the fix ledger.** It is normally gitignored, so
   appending to it moves nothing and this never comes up. A repo that tracks
-  `.claude/` instead will see a ledger commit land after the review and make
+  `.opencode/` instead will see a ledger commit land after the review and make
   it stale. That is the rule working, not a case to carve out: re-review, or
   leave the ledger uncommitted until after the release.
 - **`coverage:` naming any stage `NOT RUN`** → **stop**. A `ready` from a run

package/packages/opencode/command/remember/AGENT_RULES.md

@@ -9,7 +9,7 @@
 6. [Environment](#environment)
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
-9. [AGENTS.md Stub](#agentsmd-stub)
+9. [CLAUDE.md Stub](#claudemd-stub)
 
 ---
 
@@ -59,7 +59,7 @@ Every task runs through three layers. Do not skip ahead to code.
 Not courtesies. These bind you as written, whether or not your tool enforces them.
 
 - **Always** identify affected files before making changes, and explain what will change and why
-- **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.opencode/settings.json`
+- **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.claude/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
 - **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/branch-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
@@ -130,90 +130,50 @@ A problem you see and don't fix goes in the report, never in a comment. Comments
 
 ## Testing Standards
 
-### Rules
+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.
 
-**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.
+### What a test is for
 
-**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
+**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.
 
-### When to Write Tests
+**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.
 
-- **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
+### When to write them
 
-### TDD: When It Works and When It Doesn't
+- **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
 
-- **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
 
-### 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
 
-- **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
 
-### Anti-Patterns — Do Not Do These
+- **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
 
-- **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
+### Organization
 
-### 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
+- **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
 
 ---
 
@@ -281,9 +241,9 @@ The [Twelve-Factor App](https://12factor.net) methodology for modern, scalable a
 
 ---
 
-## AGENTS.md Stub
+## CLAUDE.md Stub
 
-Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions.
+Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions.
 
 ```markdown
 ## Dev Rules
@@ -304,5 +264,5 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 
 **Responsive web UI is mandatory.** Any web UI must work on mobile by default — fluid layouts, viewport meta, breakpoints, no horizontal scroll. Verify in DevTools device emulation before claiming a UI task is done. POCs exempt; real projects are not.
 
-For full development and testing standards, see `.opencode/remember/AGENT_RULES.md`.
+For full development and testing standards, see `.claude/remember/AGENT_RULES.md`.
 ```

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