greprag 5.49.8 → 5.49.9

package/dist/commands/memory-reflex.js

@@ -1,226 +1,34 @@
 "use strict";
-/** memory-reflex — greprag episodic memory as a context-fill reflex (the first
- *  "greprag service as a reminder-interrupt module" beyond the harness's own arm/mechanic).
- *  docs/reminder-interrupt.md §Registry spec + the announce-featureset discussion (2026-06-20).
+/** memory-primer — the SessionStart announce that teaches greprag's episodic memory
+ *  as a capability the agent operates on its OWN judgment (`greprag memory search` /
+ *  `recap`). A PRIMER (full doctrine inline), nothing else.
  *
- *  THE IDEA: when the agent is about to answer without context it could have, surface the
- *  relevant project memory inline — seamlessly, no tool call. Two trigger layers feed ONE
- *  reminder: keyword (user signals recall, this file's `hasRecallIntent`) · nano (implicit
- *  gap). P1 = keyword + the announce that teaches the capability; nano lands next. (The
- *  self-report `[[recall:]]` marker was removed 2026-06-22 — a dumb surface; direct
- *  `greprag memory search` covers the explicit-gap case.)
- *
- *  SEARCH-THEN-INJECT, not nudge: a trigger fires a memory search in the hook; only a hit
- *  ABOVE the confidence gate is injected (top 1-2, capped). A miss = silence — so the search
- *  result is its own precision filter and the reflex never becomes wallpaper (the
- *  banner-blindness failure mode, fix `16a29a8b`). PURE module: the hook owns the search
- *  (I/O) + frames the hit via `buildMemoryInjection`, then routes the string through env —
- *  exactly the front-desk module's shape.
- *
- *  EXCESSIVENESS is the watched risk (operator's call 2026-06-20): two filters bound it —
- *  high-precision keyword phrases (low fire rate) + the confidence gate (low inject rate) —
- *  and every fire is tallied (`MemoryReflexStats`) so /mechanic can monitor the rate and the
- *  inject/fire ratio, and auto-quiet if it turns noisy. adr: adr/memory-reflex.md */
+ *  HISTORY: this module once also did per-turn AUTO-INJECTION — recall-intent keyword
+ *  match → inline memory search → surface a hit. That was DROPPED 2026-06-22. Two
+ *  reasons: (1) it was knowledge injection, NOT a behavioral reminder — a different,
+ *  undeveloped system that was jammed into the reminder registry for lack of a slot;
+ *  (2) it collided with the agent's own, better-targeted `greprag memory search` (the
+ *  auto-search just threw the raw prompt at the index). Same call that retired the
+ *  `[[recall:]]` self-report marker: prefer a strong primer + agent judgment over a
+ *  passive auto-surface. If a real "knowledge injection" system is built later, it gets
+ *  its own home — it is not a reminder. docs/reminder-interrupt.md (the landed map). */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryReflexModule = exports.MEMORY_QUIET_CACHE_TTL_MS = exports.MEMORY_CONFIDENCE_GATE = void 0;
-exports.hasRecallIntent = hasRecallIntent;
-exports.selectGatedHits = selectGatedHits;
-exports.gatedHitText = gatedHitText;
-exports.buildMemoryInjection = buildMemoryInjection;
+exports.memoryPrimerModule = void 0;
 exports.buildMemoryAnnounce = buildMemoryAnnounce;
-exports.injectionWasUsed = injectionWasUsed;
-exports.tallyMemoryFire = tallyMemoryFire;
-exports.tallyMemoryUsed = tallyMemoryUsed;
-exports.quietCacheSaysSilent = quietCacheSaysSilent;
-// ---------- Layer 1: keyword trigger (free, same-turn) -----------------------
-/** High-precision recall-intent phrases — MULTI-WORD by design (a single word like
- *  "previously" over-fires). Each strongly implies the agent needs recalled project
- *  context it may not hold. Tuned conservatively; the /mechanic monitor reports the
- *  false-fire rate and this list is where we'd loosen/tighten. */
-const RECALL_PHRASES = [
-    'last time', 'we decided', 'we agreed', 'we chose', 'we discussed',
-    'we talked about', 'you said', 'you mentioned', 'you told me',
-    'remember when', 'remember that', 'what did we', 'what was our',
-    'as we discussed', 'as i mentioned', 'earlier you', 'earlier we',
-    'refresh my memory', 'catch me up', 'where did we leave',
-    'the bug we', 'that bug we', 'the plan we', 'did we ever', 'how did we',
-];
-const RECALL_RE = new RegExp(`\\b(${RECALL_PHRASES.join('|').replace(/ /g, '\\s+')})\\b`, 'i');
-/** Does this prompt signal a recall need? Pure, total — the hook gates the inline search
- *  on it. The query handed to the search is the prompt itself (the search is built for
- *  natural queries; fragile noun-extraction buys nothing). */
-function hasRecallIntent(prompt) {
-    return !!prompt && RECALL_RE.test(prompt);
-}
-/** Confidence gate — a hit must clear this to be injected. Below it, the reflex stays
- *  silent (the search result IS the precision filter). Reranked hits carry a calibrated
- *  `confidence` (0-1); unreranked hits fall back to a raw-score floor. */
-exports.MEMORY_CONFIDENCE_GATE = 0.5;
-const RAW_SCORE_FLOOR = 0.15;
-/** Hard cap — never inject more than this many hits (context-bloat discipline; we just
- *  spent a session draining the heap). */
-const MAX_INJECTED = 2;
-/** Per-hit trim — keep each injected snippet tight. */
-const HIT_TRIM = 280;
-function passesGate(h) {
-    return typeof h.confidence === 'number'
-        ? h.confidence >= exports.MEMORY_CONFIDENCE_GATE
-        : h.score >= RAW_SCORE_FLOOR;
-}
-/** The hits that clear the gate, capped — the SINGLE source of "what gets shown", shared by the
- *  injection framing AND the efficacy capture, so the overlap is scored against exactly what
- *  was injected. */
-function selectGatedHits(hits) {
-    return (hits || []).filter(passesGate).slice(0, MAX_INJECTED);
-}
-/** Raw content of the gated hits (no framing boilerplate) — stashed at inject-time so the
- *  Stop-hook overlap scores the response against the actual memory, not the frame. */
-function gatedHitText(hits) {
-    return selectGatedHits(hits).map(h => h.content || '').join('\n');
-}
-function trim(s, n) {
-    const t = (s || '').replace(/\s+/g, ' ').trim();
-    return t.length > n ? t.slice(0, n - 1) + '…' : t;
-}
-/** Frame the gated top hits into the inline injection block; null when nothing clears the
- *  gate (→ the module stays silent that turn). Tier is ambient (soft context, never a
- *  forced-decision directive). Tight + capped by design. */
-function buildMemoryInjection(hits) {
-    const passing = selectGatedHits(hits);
-    if (passing.length === 0)
-        return null;
-    const lines = ['[📁 greprag memory — possibly relevant, auto-surfaced (pull more: `greprag memory search`):'];
-    for (const h of passing) {
-        const meta = [h.shape, h.createdAt ? h.createdAt.slice(0, 10) : null, h.projectName]
-            .filter(Boolean).join(', ');
-        lines.push(`  · ${trim(h.content, HIT_TRIM)}${meta ? `  (${meta})` : ''}`);
-    }
-    lines.push(']');
-    return lines.join('\n');
-}
-// ---------- SessionStart announce (teach the capability once) -----------------
-/** The business card, loaded once. Teaches the auto-surface AND the on-demand pull.
- *  Action-first, token-minimal, per the reminder-interrupt authoring rules. */
+/** The business card, loaded once. Teaches the on-demand search/recap reflex —
+ *  action-first, token-minimal, per the reminder-interrupt authoring rules. */
 function buildMemoryAnnounce() {
     return [
         '[greprag memory — this project remembers. Every past session (decisions, bugs, what was discussed, who did what) is captured and searchable.]',
-        'Auto-surface: when THIS turn leans on earlier work, the relevant memory is injected inline for you — trust it and use it.',
-        'On demand, any time you need more than surfaced: `greprag memory search "<topic>"` (semantic — ask in natural language), `greprag memory recap` to catch up on the session, `greprag memory recap --last N` for deeper history. Reach for it the moment you suspect this project knows something you don\'t — searching is cheap.',
+        'On demand, the moment you suspect this project knows something you don\'t: `greprag memory search "<topic>"` (semantic — ask in natural language), `greprag memory recap` to catch up on the session, `greprag memory recap --last N` for deeper history. Searching is cheap — reach for it rather than guessing or asking the operator to re-explain.',
     ].join('\n');
 }
-// ---------- Efficacy: did the injection get USED (the overlap proxy) ----------
-/** Free overlap proxy for "did the response draw on the injected memory" — the efficacy
- *  numerator's cheap first rung. (The Flash-Lite judge calibrates/replaces it later,
- *  server-side; greprag's judge model is Gemini Flash-Lite, never nano.) Distinctive CONTENT
- *  terms the injection introduced — in the hit, NOT already in the prompt, not stopwords /
- *  frame boilerplate — that reappear in the response. ≥ USED_MIN_TERMS reused → used.
- *  Imperfect (paraphrase escapes it, coincidence trips it) but a real aggregate signal at
- *  zero cost + zero latency. */
-const USED_MIN_TERMS = 2;
-const MIN_TERM_LEN = 4;
-const TERM_STOPWORDS = new Set([
-    'this', 'that', 'with', 'from', 'have', 'were', 'your', 'they', 'them', 'then', 'than',
-    'will', 'would', 'could', 'should', 'about', 'there', 'their', 'what', 'when', 'which',
-    'into', 'over', 'also', 'been', 'more', 'most', 'some', 'such', 'only', 'just', 'like',
-    'here', 'where', 'these', 'those', 'them', 'because',
-    // injection-frame boilerplate — never count these as "used":
-    'greprag', 'memory', 'relevant', 'surfaced', 'auto', 'session', 'project', 'search', 'recap', 'pull',
-]);
-function contentTerms(text) {
-    const out = new Set();
-    for (const raw of (text || '').toLowerCase().split(/[^a-z0-9]+/)) {
-        if (raw.length >= MIN_TERM_LEN && !TERM_STOPWORDS.has(raw))
-            out.add(raw);
-    }
-    return out;
-}
-/** Did the agent's response reuse distinctive content from the injection? Pure, total. */
-function injectionWasUsed(hitText, prompt, response) {
-    const hitTerms = contentTerms(hitText);
-    if (hitTerms.size === 0)
-        return false;
-    const promptTerms = contentTerms(prompt);
-    const respTerms = contentTerms(response);
-    let used = 0;
-    for (const t of hitTerms) {
-        if (promptTerms.has(t))
-            continue; // not distinctive — already in the prompt
-        if (respTerms.has(t) && ++used >= USED_MIN_TERMS)
-            return true;
-    }
-    return false;
-}
-function normalizeStats(prior) {
-    const p = (prior && typeof prior === 'object') ? prior : {};
-    const bt = (p.byTrigger && typeof p.byTrigger === 'object') ? p.byTrigger : {};
-    return {
-        fires: Number.isFinite(p.fires) ? p.fires : 0,
-        injected: Number.isFinite(p.injected) ? p.injected : 0,
-        silent: Number.isFinite(p.silent) ? p.silent : 0,
-        used: Number.isFinite(p.used) ? p.used : 0,
-        byTrigger: {
-            keyword: Number.isFinite(bt.keyword) ? bt.keyword : 0,
-            flash: Number.isFinite(bt.flash) ? bt.flash : 0,
-        },
-        firstFiredAt: p.firstFiredAt,
-        lastFiredAt: p.lastFiredAt,
-        lastTurnCount: p.lastTurnCount,
-    };
-}
-/** Tally one fire — PURE (the hook supplies the clock). `didInject` splits the
- *  fire into injected vs silent so the monitor can read the inject/fire ratio. */
-function tallyMemoryFire(prior, trigger, didInject, turnCount, nowIso) {
-    const s = normalizeStats(prior);
-    s.fires += 1;
-    if (didInject)
-        s.injected += 1;
-    else
-        s.silent += 1;
-    s.byTrigger[trigger] += 1;
-    s.firstFiredAt = s.firstFiredAt || nowIso;
-    s.lastFiredAt = nowIso;
-    if (Number.isFinite(turnCount))
-        s.lastTurnCount = turnCount;
-    return s;
-}
-/** Record that an injection was USED (the efficacy numerator) — PURE; bumped at Stop when the
- *  overlap proxy (or, later, the Flash-Lite judge) finds the response drew on the injection.
- *  Never decrements; `used ≤ injected` by construction of the call sites. */
-function tallyMemoryUsed(prior) {
-    const s = normalizeStats(prior);
-    s.used += 1;
-    return s;
-}
-// ---------- Auto-quiet (server efficacy verdict, cached locally) --------------
-/** The server (the Flash-Lite judge, `@greprag/core` memory-efficacy) owns the
- *  auto-quiet THRESHOLD and ships its verdict on the /v1/memory/query response.
- *  The hook caches that boolean and honors it with a TTL — how long to trust a
- *  cached verdict before re-probing. While quiet the reflex skips the search, so
- *  no fresh verdict arrives and the cache ages; once stale the reflex fires again
- *  to re-probe and the server re-judges. That gives auto-quiet TEETH (a real
- *  silent window) while staying self-healing — a reflex that recovers is never
- *  permanently silenced (unlike the hard, manual mechanicKilled() switch). */
-exports.MEMORY_QUIET_CACHE_TTL_MS = 12 * 60 * 60 * 1000; // 12h
-/** Does the locally-cached server verdict say "stay silent THIS turn"? PURE +
- *  total. Silent only when the cache is present, says quiet, and is still fresh.
- *  Fail-open everywhere else (missing / malformed / stale → NOT silent) so a bad
- *  cache can never permanently kill the reflex. */
-function quietCacheSaysSilent(cache, nowMs) {
-    if (!cache || cache.quiet !== true || typeof cache.cachedAt !== 'string')
-        return false;
-    const t = Date.parse(cache.cachedAt);
-    if (!Number.isFinite(t))
-        return false;
-    return (nowMs - t) < exports.MEMORY_QUIET_CACHE_TTL_MS;
-}
-// ---------- The registry module ----------------------------------------------
-/** memory-reflex as a reminder-interrupt module. announce teaches memory once; reminder
- *  routes the hook-supplied injection (env.memoryHit); detect gates on its presence. PURE —
- *  the hook owns the keyword gate + the search + the framing + the tally. */
-exports.memoryReflexModule = {
-    id: 'memory-reflex',
-    detect: (env) => (env.memoryHit ? { tier: 'ambient' } : { tier: 'silent' }),
-    announce: () => buildMemoryAnnounce(),
-    reminder: (_d, env) => env.memoryHit ?? null,
+/** memory-primer as a reminder-interrupt module: announce-only (a PRIMER). detect →
+ *  silent, reminder → null. PURE. */
+exports.memoryPrimerModule = {
+    id: 'memory-primer',
+    detect: (_env) => ({ tier: 'silent' }),
+    announce: (_env) => buildMemoryAnnounce(),
+    reminder: () => null,
 };
 //# sourceMappingURL=memory-reflex.js.map

package/dist/commands/memory-reflex.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-reflex.js","sourceRoot":"","sources":["../../src/commands/memory-reflex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;qFAqBqF;;;AAuBrF,0CAEC;AAmCD,0CAEC;AAID,oCAEC;AAUD,oDAWC;AAMD,kDAMC;AA+BD,4CAWC;AA4CD,0CAYC;AAKD,0CAIC;AAuBD,oDAKC;AAxOD,gFAAgF;AAEhF;;;kEAGkE;AAClE,MAAM,cAAc,GAAG;IACrB,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc;IAClE,iBAAiB,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa;IAC7D,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc;IAC/D,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY;IAChE,mBAAmB,EAAE,aAAa,EAAE,oBAAoB;IACxD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY;CACxE,CAAC;AACF,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE/F;;8DAE8D;AAC9D,SAAgB,eAAe,CAAC,MAAiC;IAC/D,OAAO,CAAC,CAAC,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5C,CAAC;AAeD;;0EAE0E;AAC7D,QAAA,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B;0CAC0C;AAC1C,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,uDAAuD;AACvD,MAAM,QAAQ,GAAG,GAAG,CAAC;AAErB,SAAS,UAAU,CAAC,CAAY;IAC9B,OAAO,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;QACrC,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,8BAAsB;QACxC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,eAAe,CAAC;AACjC,CAAC;AAED;;oBAEoB;AACpB,SAAgB,eAAe,CAAC,IAAiB;IAC/C,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;AAChE,CAAC;AAED;sFACsF;AACtF,SAAgB,YAAY,CAAC,IAAiB;IAC5C,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,IAAI,CAAC,CAAS,EAAE,CAAS;IAChC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;4DAE4D;AAC5D,SAAgB,oBAAoB,CAAC,IAAiB;IACpD,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,KAAK,GAAa,CAAC,6FAA6F,CAAC,CAAC;IACxH,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC;aACjF,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,iFAAiF;AAEjF;+EAC+E;AAC/E,SAAgB,mBAAmB;IACjC,OAAO;QACL,+IAA+I;QAC/I,2HAA2H;QAC3H,mUAAmU;KACpU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,iFAAiF;AAEjF;;;;;;gCAMgC;AAChC,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IACtF,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IACtF,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IACtF,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS;IACpD,6DAA6D;IAC7D,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM;CACrG,CAAC,CAAC;AAEH,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACjE,IAAI,GAAG,CAAC,MAAM,IAAI,YAAY,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0FAA0F;AAC1F,SAAgB,gBAAgB,CAAC,OAAe,EAAE,MAAc,EAAE,QAAgB;IAChF,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS,CAAkB,0CAA0C;QAC7F,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,cAAc;YAAE,OAAO,IAAI,CAAC;IAChE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAwBD,SAAS,cAAc,CAAC,KAA2C;IACjE,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,EAAwB,CAAC;IACnF,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,EAAqC,CAAC;IACnH,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC7C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtD,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1C,SAAS,EAAE;YACT,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACrD,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAChD;QACD,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,aAAa,EAAE,CAAC,CAAC,aAAa;KAC/B,CAAC;AACJ,CAAC;AAED;kFACkF;AAClF,SAAgB,eAAe,CAC7B,KAA+B,EAAE,OAAsB,EAAE,SAAkB,EAC3E,SAAiB,EAAE,MAAc;IAEjC,MAAM,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IACb,IAAI,SAAS;QAAE,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;;QAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;IACnD,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC;IAC1C,CAAC,CAAC,WAAW,GAAG,MAAM,CAAC;IACvB,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,CAAC,CAAC,aAAa,GAAG,SAAS,CAAC;IAC5D,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;6EAE6E;AAC7E,SAAgB,eAAe,CAAC,KAA+B;IAC7D,MAAM,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;IACZ,OAAO,CAAC,CAAC;AACX,CAAC;AAED,iFAAiF;AAEjF;;;;;;;8EAO8E;AACjE,QAAA,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAG,MAAM;AAOtE;;;mDAGmD;AACnD,SAAgB,oBAAoB,CAAC,KAA0C,EAAE,KAAa;IAC5F,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvF,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,iCAAyB,CAAC;AACjD,CAAC;AAED,gFAAgF;AAEhF;;6EAE6E;AAChE,QAAA,kBAAkB,GAAmB;IAChD,EAAE,EAAE,eAAe;IACnB,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAc;IACxF,QAAQ,EAAE,GAAG,EAAE,CAAC,mBAAmB,EAAE;IACrC,QAAQ,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI;CAC7C,CAAC"}
+{"version":3,"file":"memory-reflex.js","sourceRoot":"","sources":["../../src/commands/memory-reflex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;wFAYwF;;;AAMxF,kDAKC;AAPD;+EAC+E;AAC/E,SAAgB,mBAAmB;IACjC,OAAO;QACL,+IAA+I;QAC/I,wVAAwV;KACzV,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;qCACqC;AACxB,QAAA,kBAAkB,GAAmB;IAChD,EAAE,EAAE,eAAe;IACnB,MAAM,EAAE,CAAC,IAAiB,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC9D,QAAQ,EAAE,CAAC,IAAiB,EAAiB,EAAE,CAAC,mBAAmB,EAAE;IACrE,QAAQ,EAAE,GAAkB,EAAE,CAAC,IAAI;CACpC,CAAC"}

package/dist/commands/reminder-registry.d.ts

@@ -11,6 +11,11 @@ import { ReminderEnv, ReminderModule, Detection } from './reminder-types';
  *  loud, action-first modules last (watcher-arm → mechanic) so they read most-recent at
  *  SessionStart. Add a module here to wire it into BOTH surfaces at once. */
 export declare const REGISTRY: ReminderModule[];
+/** Split the registry by READ surface (docs/reminder-interrupt.md). UserPromptSubmit
+ *  evaluates `prompt`-source modules (the default); PreToolUse evaluates `command`-source
+ *  modules (they read env.toolCommand). Announces are always prompt-side (SessionStart). */
+export declare const promptModules: (registry?: ReminderModule[]) => ReminderModule[];
+export declare const commandModules: (registry?: ReminderModule[]) => ReminderModule[];
 export interface FiredReminder {
     id: string;
     tier: Detection['tier'];
@@ -20,5 +25,11 @@ export interface FiredReminder {
  *  Stacking — a turn may carry several. A detector or reminder that throws drops that
  *  module for the turn; it never blocks the others or the turn. */
 export declare function collectReminders(env: ReminderEnv, registry?: ReminderModule[]): FiredReminder[];
-/** SessionStart: every module's announce (skipping null), in registry order. */
+/** Boot-sequence sort: a STABLE topological order over `dependsOn` (docs/load-system.md).
+ *  Registry array order is the tie-breaker, so a dependency-free registry is emitted
+ *  verbatim; declared deps only ever pull a module EARLIER. A missing/cyclic dep degrades
+ *  gracefully to array order (never throws — a boot order is not worth crashing a turn). */
+export declare function bootOrder(registry: ReminderModule[]): ReminderModule[];
+/** SessionStart: every module's announce (skipping null), in BOOT-SEQUENCE order
+ *  (dependsOn topo-sort, array order as tie-breaker). */
 export declare function collectAnnounces(env: ReminderEnv, registry?: ReminderModule[]): string[];

package/dist/commands/reminder-registry.js

@@ -5,10 +5,12 @@
  *  PURE over ReminderEnv — the hook assembles env (i/o) and emits the returned lines;
  *  a broken module never blocks a turn (fail-open per module). */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REGISTRY = void 0;
+exports.commandModules = exports.promptModules = exports.REGISTRY = void 0;
 exports.collectReminders = collectReminders;
+exports.bootOrder = bootOrder;
 exports.collectAnnounces = collectAnnounces;
 const inbox_primer_reminder_1 = require("./inbox-primer-reminder");
+const load_primer_reminder_1 = require("./load-primer-reminder");
 const corpus_reminder_1 = require("./corpus-reminder");
 const setup_reminder_1 = require("./setup-reminder");
 const frontdesk_reminder_1 = require("./frontdesk-reminder");
@@ -17,6 +19,8 @@ const assistant_reminder_1 = require("./assistant-reminder");
 const memory_reflex_1 = require("./memory-reflex");
 const arm_reminder_1 = require("./arm-reminder");
 const friction_reminder_1 = require("./friction-reminder");
+const collision_reminder_1 = require("./collision-reminder");
+const version_reminder_1 = require("./version-reminder");
 /** Registry order = display order. THE single agent-facing announce/reminder assembly:
  *  the hook does I/O → fills ReminderEnv → collectAnnounces (SessionStart) / collectReminders
  *  (per turn) render every module here in this order. Order preserves the historical recap
@@ -25,15 +29,26 @@ const friction_reminder_1 = require("./friction-reminder");
  *  SessionStart. Add a module here to wire it into BOTH surfaces at once. */
 exports.REGISTRY = [
     inbox_primer_reminder_1.inboxPrimerModule,
+    load_primer_reminder_1.loadPrimerModule,
+    load_primer_reminder_1.chipSpawnPointerModule,
     corpus_reminder_1.corpusAnnounceModule,
     setup_reminder_1.setupWarningModule,
+    version_reminder_1.versionUpgradeModule, // Deficiency-gated announce — silent unless a newer release exists
     frontdesk_reminder_1.frontDeskModule,
     checkpoint_reminder_1.checkpointModule,
     assistant_reminder_1.assistantDoctrineModule,
-    memory_reflex_1.memoryReflexModule,
+    memory_reflex_1.memoryPrimerModule,
     arm_reminder_1.watcherArmModule,
     friction_reminder_1.mechanicFrictionModule,
+    collision_reminder_1.collisionMatchModule, // source: 'command' — evaluated at PreToolUse, not UserPromptSubmit
 ];
+/** Split the registry by READ surface (docs/reminder-interrupt.md). UserPromptSubmit
+ *  evaluates `prompt`-source modules (the default); PreToolUse evaluates `command`-source
+ *  modules (they read env.toolCommand). Announces are always prompt-side (SessionStart). */
+const promptModules = (registry = exports.REGISTRY) => registry.filter((m) => (m.source ?? 'prompt') === 'prompt');
+exports.promptModules = promptModules;
+const commandModules = (registry = exports.REGISTRY) => registry.filter((m) => m.source === 'command');
+exports.commandModules = commandModules;
 /** Per-turn: every module's live reminder line (skipping silent), in registry order.
  *  Stacking — a turn may carry several. A detector or reminder that throws drops that
  *  module for the turn; it never blocks the others or the turn. */
@@ -61,10 +76,37 @@ function collectReminders(env, registry = exports.REGISTRY) {
     }
     return out;
 }
-/** SessionStart: every module's announce (skipping null), in registry order. */
+/** Boot-sequence sort: a STABLE topological order over `dependsOn` (docs/load-system.md).
+ *  Registry array order is the tie-breaker, so a dependency-free registry is emitted
+ *  verbatim; declared deps only ever pull a module EARLIER. A missing/cyclic dep degrades
+ *  gracefully to array order (never throws — a boot order is not worth crashing a turn). */
+function bootOrder(registry) {
+    const byId = new Map(registry.map((m) => [m.id, m]));
+    const ordered = [];
+    const placed = new Set();
+    const visiting = new Set();
+    const visit = (m) => {
+        if (placed.has(m.id) || visiting.has(m.id))
+            return; // placed, or a cycle → bail
+        visiting.add(m.id);
+        for (const dep of m.dependsOn ?? []) {
+            const d = byId.get(dep);
+            if (d)
+                visit(d); // unknown dep id → ignored (graceful)
+        }
+        visiting.delete(m.id);
+        placed.add(m.id);
+        ordered.push(m);
+    };
+    for (const m of registry)
+        visit(m);
+    return ordered;
+}
+/** SessionStart: every module's announce (skipping null), in BOOT-SEQUENCE order
+ *  (dependsOn topo-sort, array order as tie-breaker). */
 function collectAnnounces(env, registry = exports.REGISTRY) {
     const out = [];
-    for (const m of registry) {
+    for (const m of bootOrder(registry)) {
         let a = null;
         try {
             a = m.announce(env);

package/dist/commands/reminder-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"reminder-registry.js","sourceRoot":"","sources":["../../src/commands/reminder-registry.ts"],"names":[],"mappings":";AAAA;;;;kEAIkE;;;AAwClE,4CAaC;AAGD,4CAUC;AA/DD,mEAA4D;AAC5D,uDAAyD;AACzD,qDAAsD;AACtD,6DAAuD;AACvD,+DAAyD;AACzD,6DAA+D;AAC/D,mDAAqD;AACrD,iDAAkD;AAClD,2DAA6D;AAE7D;;;;;6EAK6E;AAChE,QAAA,QAAQ,GAAqB;IACxC,yCAAiB;IACjB,sCAAoB;IACpB,mCAAkB;IAClB,oCAAe;IACf,sCAAgB;IAChB,4CAAuB;IACvB,kCAAkB;IAClB,+BAAgB;IAChB,0CAAsB;CACvB,CAAC;AAQF;;mEAEmE;AACnE,SAAgB,gBAAgB,CAC9B,GAAgB,EAAE,WAA6B,gBAAQ;IAEvD,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAY,CAAC;QACjB,IAAI,CAAC;YAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACxC,IAAI,IAAI,GAAkB,IAAI,CAAC;QAC/B,IAAI,CAAC;YAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QACtD,IAAI,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gFAAgF;AAChF,SAAgB,gBAAgB,CAC9B,GAAgB,EAAE,WAA6B,gBAAQ;IAEvD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,GAAkB,IAAI,CAAC;QAC5B,IAAI,CAAC;YAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAChD,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"reminder-registry.js","sourceRoot":"","sources":["../../src/commands/reminder-registry.ts"],"names":[],"mappings":";AAAA;;;;kEAIkE;;;AAuDlE,4CAaC;AAMD,8BAkBC;AAID,4CAUC;AAvGD,mEAA4D;AAC5D,iEAAkF;AAClF,uDAAyD;AACzD,qDAAsD;AACtD,6DAAuD;AACvD,+DAAyD;AACzD,6DAA+D;AAC/D,mDAAqD;AACrD,iDAAkD;AAClD,2DAA6D;AAC7D,6DAA4D;AAC5D,yDAA0D;AAE1D;;;;;6EAK6E;AAChE,QAAA,QAAQ,GAAqB;IACxC,yCAAiB;IACjB,uCAAgB;IAChB,6CAAsB;IACtB,sCAAoB;IACpB,mCAAkB;IAClB,uCAAoB,EAAI,mEAAmE;IAC3F,oCAAe;IACf,sCAAgB;IAChB,4CAAuB;IACvB,kCAAkB;IAClB,+BAAgB;IAChB,0CAAsB;IACtB,yCAAoB,EAAI,oEAAoE;CAC7F,CAAC;AAEF;;4FAE4F;AACrF,MAAM,aAAa,GAAG,CAAC,WAA6B,gBAAQ,EAAoB,EAAE,CACvF,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC;AADjD,QAAA,aAAa,iBACoC;AACvD,MAAM,cAAc,GAAG,CAAC,WAA6B,gBAAQ,EAAoB,EAAE,CACxF,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;AADpC,QAAA,cAAc,kBACsB;AAQjD;;mEAEmE;AACnE,SAAgB,gBAAgB,CAC9B,GAAgB,EAAE,WAA6B,gBAAQ;IAEvD,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAY,CAAC;QACjB,IAAI,CAAC;YAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACxC,IAAI,IAAI,GAAkB,IAAI,CAAC;QAC/B,IAAI,CAAC;YAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QACtD,IAAI,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;4FAG4F;AAC5F,SAAgB,SAAS,CAAC,QAA0B;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,CAAiB,EAAQ,EAAE;QACxC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,4BAA4B;QAChF,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACnB,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;YACpC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,CAAC;gBAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,sCAAsC;QACzD,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;yDACyD;AACzD,SAAgB,gBAAgB,CAC9B,GAAgB,EAAE,WAA6B,gBAAQ;IAEvD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,GAAkB,IAAI,CAAC;QAC5B,IAAI,CAAC;YAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAChD,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/commands/reminder-types.d.ts

@@ -40,6 +40,14 @@ export interface ReminderEnv {
     /** Precomputed assistant-doctrine context — the hook owns the doctrine-file read, so
      *  this module half is a pass-through. Null for any non-assistant project. */
     assistantDoctrine?: string | null;
+    /** Deficiency-gated announce signal: the installed greprag is behind the latest
+     *  published version. Set by the hook (daily-cached npm-registry check); null/undefined
+     *  when current. Drives the version-upgrade announce — "new release, upgrade with X".
+     *  docs/reminder-interrupt.md (a Deficiency-gated announce, not a new type). */
+    updateAvailable?: {
+        current: string;
+        latest: string;
+    } | null;
     /** Names of the api-docs-tagged corpus stores (the hook lists `?tag=api-docs`).
      *  Drives the corpus announce: name the on-tap reference banks so an agent
      *  searches them before answering from training data. Empty/undefined → the
@@ -52,6 +60,14 @@ export interface ReminderEnv {
      *  the search + the confidence gate + framing; the memory-reflex module routes the
      *  framed string as its per-turn reminder. Null = nothing cleared the gate this turn. */
     memoryHit?: string | null;
+    /** The Bash command about to run (the `command` read surface for a Match trigger).
+     *  Present only on the PreToolUse env; undefined at UserPromptSubmit. */
+    toolCommand?: string | null;
+    /** Same-repo peers live right now (the hook does the fresh watcher read off the
+     *  hot path and passes the result; the collision module detects purely on it). */
+    collisionPeers?: {
+        short: string;
+    }[];
 }
 /** Slim open-checkpoint row (the SessionStart landmark announce, checkpoint module).
  *  Lives here — not in checkpoint-reminder.ts — because ReminderEnv references it and a
@@ -72,6 +88,18 @@ export interface Detection {
  *  unit-testable regression-lock. */
 export interface ReminderModule {
     id: string;
+    /** Which READ surface this module fires on (docs/reminder-interrupt.md — the landed
+     *  map). `prompt` (default) modules run at UserPromptSubmit; `command` modules run at
+     *  PreToolUse, reading `env.toolCommand`. The call site filters the registry by source
+     *  so each hook event evaluates only its own modules. */
+    source?: 'prompt' | 'command';
+    /** Boot-sequence dependencies (docs/load-system.md §boot sequence): module ids whose
+     *  announce MUST be emitted before this one's. A primer that references a concept an
+     *  earlier primer establishes declares it here (e.g. the mechanic primer references chip
+     *  vehicles → `dependsOn: ['chip-spawn-pointer']`; every pointer that says "greprag load"
+     *  → `dependsOn: ['load-primer']`). collectAnnounces topologically sorts on this, so the
+     *  boot order is a declared graph, not fragile array position. Omit = no dependency. */
+    dependsOn?: string[];
     /** Read the live deficiency. The gate: `silent` ⇒ the module is quiet this turn. */
     detect: (env: ReminderEnv) => Detection;
     /** SessionStart schema, loaded once (teach method + why). null = nothing to announce. */

package/dist/commands/version-reminder.d.ts

@@ -0,0 +1,15 @@
+/** version-reminder — the release-upgrade announce. A DEFICIENCY-gated announce
+ *  (docs/reminder-interrupt.md): the Deficiency trigger ("a required state is missing")
+ *  applied to the ANNOUNCE surface — the required state is "running the latest greprag,"
+ *  the deficiency is "installed < latest published." When behind, the SessionStart announce
+ *  tells the user a new release is out + how to upgrade; it auto-clears once they upgrade.
+ *
+ *  This is what makes a release PROPAGATE — without it, users never learn to upgrade.
+ *  NOT a new announce kind: it is a primer gated by Deficiency, exactly like setup-warning
+ *  (which announces only when there's a drift gap). The hook does the I/O (the daily-cached
+ *  npm-registry version check) and passes the verdict as env.updateAvailable; this module
+ *  is PURE — announce-only (detect → silent, reminder → null). */
+import { ReminderModule } from './reminder-types';
+/** The upgrade announce — null unless the hook detected a newer published version. */
+export declare function buildVersionAnnounce(current: string, latest: string): string;
+export declare const versionUpgradeModule: ReminderModule;

package/dist/commands/version-reminder.js

@@ -0,0 +1,34 @@
+"use strict";
+/** version-reminder — the release-upgrade announce. A DEFICIENCY-gated announce
+ *  (docs/reminder-interrupt.md): the Deficiency trigger ("a required state is missing")
+ *  applied to the ANNOUNCE surface — the required state is "running the latest greprag,"
+ *  the deficiency is "installed < latest published." When behind, the SessionStart announce
+ *  tells the user a new release is out + how to upgrade; it auto-clears once they upgrade.
+ *
+ *  This is what makes a release PROPAGATE — without it, users never learn to upgrade.
+ *  NOT a new announce kind: it is a primer gated by Deficiency, exactly like setup-warning
+ *  (which announces only when there's a drift gap). The hook does the I/O (the daily-cached
+ *  npm-registry version check) and passes the verdict as env.updateAvailable; this module
+ *  is PURE — announce-only (detect → silent, reminder → null). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.versionUpgradeModule = void 0;
+exports.buildVersionAnnounce = buildVersionAnnounce;
+/** The upgrade announce — null unless the hook detected a newer published version. */
+function buildVersionAnnounce(current, latest) {
+    return [
+        `[greprag — a new release is out: v${latest} (you are on v${current}).]`,
+        `Upgrade: \`npm i -g greprag@latest\`. New behavior + fixes land on your next session.`,
+    ].join('\n');
+}
+exports.versionUpgradeModule = {
+    id: 'version-upgrade',
+    detect: (_env) => ({ tier: 'silent' }), // announce-only
+    announce: (env) => {
+        const u = env.updateAvailable;
+        if (!u || !u.current || !u.latest)
+            return null;
+        return buildVersionAnnounce(u.current, u.latest);
+    },
+    reminder: () => null,
+};
+//# sourceMappingURL=version-reminder.js.map

package/dist/commands/version-reminder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-reminder.js","sourceRoot":"","sources":["../../src/commands/version-reminder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;kEAUkE;;;AAKlE,oDAKC;AAND,sFAAsF;AACtF,SAAgB,oBAAoB,CAAC,OAAe,EAAE,MAAc;IAClE,OAAO;QACL,qCAAqC,MAAM,iBAAiB,OAAO,KAAK;QACxE,uFAAuF;KACxF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAEY,QAAA,oBAAoB,GAAmB;IAClD,EAAE,EAAE,iBAAiB;IACrB,MAAM,EAAE,CAAC,IAAiB,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,gBAAgB;IAChF,QAAQ,EAAE,CAAC,GAAgB,EAAiB,EAAE;QAC5C,MAAM,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC;QAC9B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAC/C,OAAO,oBAAoB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IACD,QAAQ,EAAE,GAAkB,EAAE,CAAC,IAAI;CACpC,CAAC"}