liteagents 2.24.1 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+## [3.0.0] - 2026-09-04
+
+### Breaking
+- **The `context-builder` subagent is removed — catalog goes 11 -> 10 agents.**
+  `docs-builder` supersedes its Tier 2/3 work (creating/splitting `docs/*.md`,
+  validated on real corpora; `docs/index.md` via `index-flat` is the sole index,
+  same reason `docs/wiki-index.md` was already deleted). Tier 1 (author
+  `CLAUDE.md`) was the only unique part, and its one load-bearing invariant —
+  `CLAUDE.md` must `@`-include `.claude/remember/MEMORY.md` and nothing else —
+  is now a mechanical gate in `stub-check.cjs`, run every `/remember`; a prose
+  rule inside a subagent was always the weaker enforcement. **Migration:** for
+  the doc-authoring work `context-builder` did, use `/docs-builder`; for a
+  cold-start `CLAUDE.md` on a brand-new project, use Claude Code's own `/init`.
+  Orchestrator routing's Brownfield workflow now starts at `system-architect`.
+
+### Security
+- **`sync-rules.cjs` and `stub-check.cjs` no longer write through a symlink out
+  of the repo they were invoked on.** `/remember` runs across a fleet of sibling
+  checkouts, so a relative link only has to reach a neighbor. Three routes were
+  reproduced and closed: a dangling link at the write target (followed by
+  `writeFileSync` as if the file were merely absent), a symlinked parent
+  directory (invisible to a leaf-only `lstat` guard), and a symlinked
+  `CLAUDE.md` that `stub-check.cjs` rewrote in place with no rename-away step.
+  `escapesRepo()` resolves the deepest existing ancestor with `realpath` and
+  confirms the write still lands inside the repo, `lstat`-ing the leaf for the
+  dangling case; refusal is loud (an `escapes` action / a skip message), never
+  silent. Mirrored to all four kits.
+
+### Added
+- **`AGENT_RULES.md` is now kept current in every repo, instead of written once and
+  forgotten.** `remember/sync-rules.cjs` byte-compares the repo copy against the
+  template shipped beside it on every `/remember` run: identical does nothing at all,
+  absent copies it in, and a differing body is moved to a single `AGENT_RULES.md.bak`
+  before the new one lands. The `.bak` is one file, deliberately — a customised body
+  survives exactly one release, so fold your changes in before the next update. This
+  replaced a bootstrap-once rule that had left a measured 35 local repos many releases
+  behind, after three hand sweeps failed to hold.
+- **`remember/stub-check.cjs` asserts the config stub's SHAPE and repairs it.** v2.19
+  demoted `AGENT_RULES.md` from an `@`-include to a plain pointer — an `@`-include
+  hot-loads ~300 lines into every session — but nothing enforced it, and 21 of 37
+  measured repos had drifted back. It also repairs a MEMORY include that is not
+  `@<dir>/remember/MEMORY.md`, since a bare `@MEMORY.md` resolves to a nonexistent
+  root file and hot memory then silently never loads. It edits only *inside* the
+  marker pairs and only the mechanism; the prose in those blocks stays user-owned.
+  It will **not** repoint a MEMORY include at a file that does not exist — a repo
+  still on the pre-rename `.claude/memory/` layout has a live file at the old path,
+  and breaking a working include to satisfy a naming convention is worse than saying
+  so.
+- **`remember/version-check.cjs` nudges when the installed liteagents is behind.**
+  One line in `/remember` step 0, advice only — it never installs. Any failure
+  (offline, DNS, timeout) is a silent skip, because a memory command that hangs on a
+  network call is worse than one that misses a nudge. The installer now stamps
+  `liteagents_version` into its manifest so the check does not shell out to
+  `npm ls -g` on every run (measured 502ms -> 113ms warm).
+- **The installer says where your backup went.** On a reinstall it now closes with the
+  path of every install it moved aside, and notes that an edited `AGENT_RULES.md` is
+  preserved in the backup's `remember/` folder. A fresh install's output is unchanged.
+
+### Changed
+- **`/remember` reports every write verbatim.** Step 8 relays exactly what
+  `version-check.cjs`, `sync-rules.cjs` and `stub-check.cjs` printed, and nothing when
+  they printed nothing. Paraphrasing could drop the `AGENT_RULES.md.bak` filename,
+  which is the one thing someone who just lost their edits needs.
+- **The stub check survives a quiet run.** Step 1's guard stops the run when there are
+  no unprocessed stashes and no friction output — which is exactly the state of a
+  stale, unattended repo. `stub-check.cjs` now runs before that stop; skipping it on
+  quiet runs is how a repo with nothing to remember stayed broken forever.
+- **`/refactor` hands the review back instead of chaining it.** Step 6's "commit, then
+  run `/branch-review`" read as a sequence to execute; a field run started the review
+  off the owner's "commit" and the owner objected. It now states that this is a
+  sentence to say, that both are the user's separate calls, and that "commit"/"yes"/"go"
+  authorizes the commit and nothing after it.
+
+### Fixed
+- Four places stated the memory-include mechanism using the broken bare `@MEMORY.md`
+  form, including an anti-pattern table an agent reads before writing the config.
+- `poc/friction-file-referents/README.md` claimed everything needed to audit it was in
+  the directory. `score.py` reproduces only the LLM-experiment table (Findings 4-6);
+  the mechanical-study numbers (Findings 2-3) come from a run whose script was never
+  committed. Now stated precisely.
+
+---
+
 ## [2.24.1] - 2026-09-03
 
 ### Changed

package/README.md

@@ -9,7 +9,7 @@
          ╚══════╝╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
 ```
 
-**AI development toolkit with 11 specialized agents and 18 commands per tool**
+**AI development toolkit with 10 specialized agents and 18 commands per tool**
 
 <p align="center">
   <img src="https://img.shields.io/github/package-json/v/hamr0/liteagents?label=version&color=2a4f8c" alt="version (auto from package.json)">
@@ -45,10 +45,10 @@ liteagents
 
 ### Supported Tools
 
-- **Claude Code** - 11 subagents + 8 skills + 10 commands (+ optional live-canvas channel plugin)
-- **Opencode** - 11 agent references + 18 commands
-- **Ampcode** - 11 subagents + 18 commands
-- **Droid** - 11 agent references + 18 commands
+- **Claude Code** - 10 subagents + 8 skills + 10 commands (+ optional live-canvas channel plugin)
+- **Opencode** - 10 agent references + 18 commands
+- **Ampcode** - 10 subagents + 18 commands
+- **Droid** - 10 agent references + 18 commands
 
 **Key Difference:**
 - **Claude Code**: Full subagent system with orchestrator + skills (auto-triggering)
@@ -73,7 +73,7 @@ liteagents
 
 ## Hot Memory — project-local learning from your own sessions
 
-Liteagents ships a two-command pipeline that turns Claude Code's session logs into project-local memory. No databases, no external services, just markdown files the assistant reads via `@MEMORY.md`.
+Liteagents ships a two-command pipeline that turns Claude Code's session logs into project-local memory. No databases, no external services, just markdown files the assistant reads via an `@.claude/remember/MEMORY.md` include.
 
 ```
 /stash  →  /remember
@@ -81,9 +81,23 @@ capture    analyze + consolidate
 ```
 
 - **`/stash`** — snapshot the current session's context before compaction or handoff; nudges you to consolidate once a few stashes pile up. The write-up runs on a mid-tier model, dispatched as a background subagent where your tool supports it, so the session isn't blocked on formatting/file I/O
-- **`/remember`** — runs friction analysis automatically (mining JSONL session logs across *all* your projects for frustration signals, failed flows, and abandonment patterns, clustered into antigen candidates), then consolidates stashes + friction antigens into `.claude/remember/MEMORY.md`; auto-injected into `CLAUDE.md` via `@MEMORY.md` so every future session benefits. Per-stash extraction runs as concurrent subagent calls on a mid-tier model — no model name hardcoded, so it works with whatever your tool has configured
+- **`/remember`** — runs friction analysis automatically (mining JSONL session logs across *all* your projects for frustration signals, failed flows, and abandonment patterns, clustered into antigen candidates), then consolidates stashes + friction antigens into `.claude/remember/MEMORY.md`; auto-injected into `CLAUDE.md` via an explicit `@.claude/remember/MEMORY.md` include so every future session benefits. Per-stash extraction runs as concurrent subagent calls on a mid-tier model — no model name hardcoded, so it works with whatever your tool has configured
 
-`/remember` also bootstraps a one-time `AGENT_RULES.md` coding-standards template into `.claude/remember/` on first run (never overwritten again after that), referenced separately in `CLAUDE.md` for the assistant to consult when building something new — a static guide, not something the pipeline learns or extracts.
+### `AGENT_RULES.md` — the standards doc that primes every session
+
+`/remember` installs an `AGENT_RULES.md` coding-standards template into `.claude/remember/` (`.factory/`, `.amp/`, `.opencode/` for the other tools) and references it from `CLAUDE.md` (`AGENT.md` / `AGENTS.md`) as a plain pointer, so the assistant consults it when building something new. It is a static guide — not something the pipeline learns or extracts.
+
+**It is kept current on every `/remember` run**, because a shipped standards doc that never updates is a stale one: 35 local repos were measured drifting many releases behind before this existed. Each run compares your copy against the template that came with your installed liteagents:
+
+| your copy | what happens |
+|---|---|
+| identical to the template | nothing at all — no write, no output |
+| missing | copied in |
+| **different** | moved to `AGENT_RULES.md.bak`, new template copied in, both reported |
+
+So **edits are never destroyed, but they are not preserved in place either.** If you have customised your rules, fold your changes into the new `AGENT_RULES.md` after an update — `AGENT_RULES.md.bak` is a *single* file that the next update overwrites, so a customised body survives one release, not two.
+
+To get a newer template in the first place, update the package: `/remember` tells you when your install is behind, and `npm i -g liteagents@latest && liteagents` refreshes it (your previous install is backed up automatically).
 
 What you get is a memory that *learns from your own mistakes and interventions*, grows quietly in your repo, and works anywhere Claude Code runs. The friction pass inside `/remember` scans all your projects and gives you a per-repo reliability verdict:
 
@@ -107,7 +121,7 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 
 ## What's Included
 
-### 11 Agents
+### 10 Agents
 
 **Workflow Agents (3):**
 - **1-create-prd** - Define scope with structured Product Requirement Documents
@@ -118,7 +132,6 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 - **orchestrator** - Analyze intent, coordinate workflows, route to optimal agent sequences
 - **code-developer** - Implementation, debugging, refactoring, code best practices
 - **quality-assurance** - Test architecture, quality gates, requirements traceability, risk assessment
-- **context-builder** - Initialize project context, discover documentation, create knowledge bases
 - **feature-planner** - Epics, user stories, prioritization, backlog management, retrospectives
 - **market-researcher** - Market analysis, competitive research, project discovery, brainstorming
 - **system-architect** - System design, technology selection, API design, scalability planning
@@ -167,6 +180,9 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 | **[remember-README.md](docs/product/remember-README.md)** | How hot memory works — the `/stash` → `/remember` pipeline, the friction sensor, and the antigen ledger |
 | **[docs-builder-README.md](docs/product/docs-builder-README.md)** | How `/docs-builder` works — the reorg/cleanup modes, what it measurably costs, and the ledger that tracks doc drift |
 | **[branch-review-README.md](docs/product/branch-review-README.md)** | How the pre-merge gate works — the three stages, what blocks a merge, and the `/branch-review` → fix ledger → `/refactor` loop |
+| **[live-canvas/README.md](packages/claude/skills/live-canvas/README.md)** | How `/live-canvas` works — the two modes, the click-to-annotate channel, and the Claude Code plugin setup |
+| **[docs/README.md](docs/README.md)** | Entry point for this repo’s own docs — what lives in `product/`, `archive/` and the operation log |
+| **[docs/index.md](docs/index.md)** | The generated index of every doc, with heading ranges. Rebuilt by `/docs-builder` on every reorg or split |
 
 ---
 
@@ -200,7 +216,7 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 
 ## Stats
 
-- **11** Specialized Agents
+- **10** Specialized Agents
 - **18** Workflow Commands & Skills
 - **4** Supported Tools (Claude, Opencode, Ampcode, Droid)
 - **Apache-2.0** License

package/installer/cli.js

@@ -13,12 +13,13 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const os = require('os');
 
 // Single source of truth for version; UPDATE_VERSION.sh bumps only package.json.
 const PACKAGE_JSON = require('../package.json');
 const PACKAGE_VERSION = PACKAGE_JSON.version;
 // Banner counts derived from the description field — same source as README.
-const AGENT_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+specialized agents/) || [, '11'])[1];
+const AGENT_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+specialized agents/) || [, '10'])[1];
 const COMMAND_COUNT = (PACKAGE_JSON.description.match(/(\d+)\s+commands/) || [, '18'])[1];
 
 // ANSI color codes
@@ -30,9 +31,35 @@ const colors = {
   yellow: '\x1b[33m',
   cyan: '\x1b[36m',
   magenta: '\x1b[35m',
-  red: '\x1b[31m'
+  red: '\x1b[31m',
+  dim: '\x1b[2m'
 };
 
+/**
+ * Render the closing note about backed-up installs, printed after `Done!`.
+ * Returns '' when backupLog is empty so a fresh install's output is
+ * unchanged. Never names `commands/` vs `command/` (opencode uses the
+ * singular form) — the note points at the shared `remember/` folder inside
+ * the backup, which is the same for every tool.
+ *
+ * @param {Array<{original: string, backup: string}>} backupLog
+ * @returns {string} Text to print (includes its own leading newline), or ''.
+ */
+function formatBackupClosingNote(backupLog) {
+  if (!backupLog || backupLog.length === 0) {
+    return '';
+  }
+
+  const lines = [`${colors.yellow}Previous install(s) backed up:${colors.reset}`];
+  for (const entry of backupLog) {
+    lines.push(`  ${entry.backup.replace(os.homedir(), '~')}`);
+  }
+  lines.push(`${colors.dim}If you had edited AGENT_RULES.md, your copy is preserved in`);
+  lines.push(`each backup's remember/ folder.${colors.reset}`);
+
+  return `\n${lines.join('\n')}`;
+}
+
 class InteractiveInstaller {
   constructor() {
     this.rl = readline.createInterface({
@@ -701,6 +728,11 @@ ${colors.bright}v${PACKAGE_VERSION} | ${AGENT_COUNT} agents + ${COMMAND_COUNT} c
     }
 
     console.log(`\n${colors.bright}${colors.green}Done!${colors.reset}`);
+
+    const closingNote = formatBackupClosingNote(installationEngine.backupLog);
+    if (closingNote) {
+      console.log(closingNote);
+    }
   }
 
   /**
@@ -765,4 +797,5 @@ if (require.main === module) {
   installer.run().catch(console.error);
 }
 
-module.exports = InteractiveInstaller;
+module.exports = InteractiveInstaller;
+module.exports.formatBackupClosingNote = formatBackupClosingNote;

package/installer/installation-engine.js

@@ -7,6 +7,11 @@
 const fs = require('fs');
 const path = require('path');
 
+// Same single source of truth as installer/cli.js: UPDATE_VERSION.sh bumps
+// only package.json. Stamped into every manifest so version-check.cjs can read
+// the installed version without shelling out to `npm ls -g` (~500ms per run).
+const LITEAGENTS_VERSION = require('../package.json').version;
+
 class InstallationEngine {
   constructor(pathManager, packageManager) {
     this.pathManager = pathManager;
@@ -448,7 +453,10 @@ class InstallationEngine {
     const manifest = {
       ...template,
       variant,
+      // `version` is the MANIFEST SCHEMA version and always has been; the
+      // liteagents release that wrote it is a separate field. Do not merge them.
       version: '1.1.0',
+      liteagents_version: LITEAGENTS_VERSION,
       installed_at: new Date().toISOString(),
       variantInfo: {
         name: variantMetadata.name,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "liteagents",
-  "version": "2.24.1",
-  "description": "AI development toolkit with 11 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
+  "version": "3.0.0",
+  "description": "AI development toolkit with 10 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {
     "liteagents": "./installer/cli.js",

package/packages/ampcode/AGENT.md

@@ -6,7 +6,7 @@ Ampcode is a lightweight CLI tool that provides workflow automation commands.
 
 These subagents are available when using Ampcode CLI.
 
-### Subagents (11 total)
+### Subagents (10 total)
 
 | ID | Title | When To Use |
 |---|---|---|
@@ -14,7 +14,6 @@ These subagents are available when using Ampcode CLI.
 | 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 AGENT.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/ampcode/agents/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/ampcode/commands/refactor.md

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

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stub-check.cjs — asserts the two managed blocks in the tool config carry the
+ * CURRENT stub shape, and repairs the shape when it is wrong.
+ *
+ * Shape, not content. The blocks' prose is user-owned — step 5 writes it once
+ * and never re-imposes it, because users trim it deliberately. What this script
+ * touches is only the mechanism:
+ *
+ *   MEMORY block       @<PROJECT_DIR>/remember/MEMORY.md   — an @-include.
+ *                      A bare `@MEMORY.md` resolves relative to the file that
+ *                      contains it, so in a repo root it names a file that does
+ *                      not exist and hot memory silently never loads.
+ *
+ *   AGENT_RULES block  <PROJECT_DIR>/remember/AGENT_RULES.md — a PLAIN pointer.
+ *                      v2.19 demoted it from an @-include on purpose: it is a
+ *                      standards guide to consult when building something new,
+ *                      not hot context, and @-including it loads ~300 lines into
+ *                      every session. Measured 2026-09-03: 21 of 37 local repos
+ *                      still carried the pre-v2.19 @-include.
+ *
+ * Two deliberate limits:
+ *
+ *   - It only edits INSIDE a marker pair. A pointer elsewhere in the config is
+ *     the user's prose and is left alone.
+ *   - It never repoints the MEMORY include at a file that does not exist. An
+ *     un-migrated `.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.
+ */
+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 };