review

# /review — the retention loop

Read `skills/_shared/dialogue-grammar.md` (hard rules, confidence integrity, park-and-resume, and the rating map apply here verbatim). Set:

```bash
# Resolve the engine. RUN THIS BLOCK VERBATIM — do not substitute a path you guessed.
# Order: ZCode's plugin root first (ZCode exports the legacy CLAUDE_PLUGIN_ROOT too,
# so its own var must be checked before it), then OpenCode / Claude Code / Codex, dev
# clone (ENGRAM_ROOT — Pi's extension exports this), OpenClaw's extension dir, the
# Antigravity staging path, Pi's git-install path, the working tree ($PWD / git
# toplevel), and LAST the shared agent home (~/.agents/engram — the clone route for
# platforms that read ~/.agents; last so it can shadow nothing). First one exists wins.
for d in "$ZCODE_PLUGIN_ROOT" "$OPENCODE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT" "$CODEX_PLUGIN_ROOT" "$ENGRAM_ROOT" \
         "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/extensions/engram" \
         "$HOME/.gemini/config/plugins/engram" \
         "$HOME/.pi/agent/git/github.com/nagisanzenin/engram" \
         "$PWD" "$(git rev-parse --show-toplevel 2>/dev/null)" \
         "$HOME/.agents/engram"; do
  [ -n "$d" ] && [ -f "$d/scripts/engram.py" ] && ENGRAM="$d/scripts/engram.py" && break
done
if [ -z "$ENGRAM" ]; then
  echo "engram: engine not found — set ENGRAM_ROOT to your engram checkout" >&2
  return 2 2>/dev/null || exit 2   # FAIL CLOSED: proceeding runs `python3 ""`,
fi                                  # which dumps a python usage error at the learner
```

If none are set, resolve the plugin root as the directory containing `.zcode-plugin/plugin.json`, `.claude-plugin/plugin.json`, or `.codex-plugin/plugin.json`. **Never inline a learner's answer into a shell command** — pass productions via `--production-file` (or `--production-file -` on stdin); a stray quote or `$(…)` in what they typed would otherwise execute.

**Spawning agents.** "Spawn **engram-…**" means a *fresh-context* child running that agent's definition — via your platform's subagent/Task tool (the type may be namespaced, e.g. `engram:engram-assessor`). **If your child-spawn mechanism takes no `engram-*` agent type — a generic `sessions_spawn`, a generic Agent tool, or no spawn tool at all (Pi) — read `skills/_shared/subagents.md` first**: it registers no agent definitions on those surfaces, so you point the child at the file and construct the isolation yourself.

## 1 · Load the queue

```bash
python3 "$ENGRAM" session-start   # what the ambient hook ALREADY told them (read-only)
python3 "$ENGRAM" stash count     # a previous session's ungraded work?
python3 "$ENGRAM" due --cap <cap>
```

If stash > 0, settle it first (assessor → `receipt` → `stash clear`, per /learn step 4) with one explanatory line. Caps: `quick` → 5 items; otherwise mode default (Standard ≈ 12). `--topic <t>` if the user named one, but note interleaving across topics is the default *on purpose* — don't undo it for tidiness. Open with the session ticket. Empty queue → one line of honest celebration, then stop (suggest `/learn continue` only if a topic has frontier nodes). Never invent reviews.

**`--cap` picks WHICH items, and it is not the order Engram used to serve (v1.3).** A capped session is a triage decision: with `--cap` the engine ranks by *expected 30-day retention saved per expected minute* and returns `{order, order_basis, items}` (the older `--limit` still returns a bare list in the old most-overdue-first order). Two things to carry into the session, both already in the payload:

- **Say nothing about the ordering unless asked** — it is plumbing, not a lesson. If asked, the honest line is in `order_basis`: it is *model-derived* (an FSRS projection), backed by one strong human RCT for the policy family and by simulations, and **no human RCT has ever ranked backlog orders**. Never present it as proven.
- **Never quote `expected_minutes` as a session estimate.** It is a ranking weight (a cold item is priced as slower), and it disagrees with the ~0.6 min/item the hook and `decay` use *on purpose*. When you need to say how long something takes, use `decay`'s `minutes` or the hook's — one figure to the learner, always. (Those two are the same estimate; `expected_minutes` is a per-item weight whose best-case rung happens to be 0.6.)
- **Items flagged `effectively_relearn: true` are functionally re-learns, not reviews.** They sort last on purpose and they lose almost nothing more by waiting. Name them once at the close rather than burning the cap on them: *"three of these are past the point of a quick review — they'd want a re-derivation. Want them in a longer session, or shall I retire any?"*

**Return-after-absence (the amnesty protocol — the highest-evidence Layer 2 move; `docs/05-affective-layers.md` P14).** Fires when `due > 2× the mode cap`, **or** when `adherence.return.days_since_last_session ≥ 7` (the engine's own constant — the same one the hook's amnesty and decay lines use; don't invent a different threshold), **or** when the loop has never closed. Then do **not** dump the debt.

> **The hook already spoke, and it spoke first.** On the same trigger, `session-start` has printed — in this order — amnesty, their plan, and the decay cost, *before the learner typed anything*. **Run `python3 "$ENGRAM" session-start` yourself in step 1** (it is read-only, stateless, and safe to re-run) so you can see what they already read, then **do not repeat any of those three lines.** Your amnesty is a re-frame only if they haven't just read one; repeated, it is padding, and repeating the plan line is exactly the "never twice, never as leverage" the protocol forbids. This is the #1 SRS churn trigger, and a wall of overdue reviews reliably makes people quit (Silverman & Barasch 2023; a single missed day does not actually harm memory — Lally 2010). Instead, one calm line of amnesty + load renegotiation, then a real choice:
- Frame it as normal, owed nothing: *"You've got 40 due after the break — tha