@lorekit/cli 1.15.0 → 1.16.0

package/README.md

@@ -483,6 +483,16 @@ Both files share this schema — all fields optional:
                            // values: "claude" | "cursor" | "codex"
                            // repo wins over user
 
+  "hooks.instructions": {
+    "SessionStart":        "Focus on migration safety. Treat any lesson tagged 'migration' as high-priority.",
+    "PostToolUseFailure":  "When recording a failure, always include the exact command and exit code.",
+    "Stop":                null
+  },
+                           // per-event custom text appended to the hook output.
+                           // both layers merged: repo instructions first, then user.
+                           // null (or absent key) means no extra instruction for that event.
+                           // values: string | null  (keys: "SessionStart" | "PostToolUseFailure" | "Stop")
+
   // ── Telemetry ──────────────────────────────────────────────────────────────
   "telemetry.disabled": true,
                            // team-level opt-out for orgs with a no-telemetry policy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/control.mjs

@@ -137,6 +137,27 @@ export function resolveControl({
     (typeof userConfig['hooks.adapter'] === 'string' && userConfig['hooks.adapter'].trim()) ||
     null;
 
+  // `hooks.instructions` — per-event custom text appended to the hook output so
+  // teams can embed project-specific guidance directly into the injected context.
+  // Both layers contribute: repo instructions come first, user instructions follow
+  // (same direction as `tags.default` — repo supplements, user personalises).
+  // null for a given event means "no custom instruction for that event".
+  const HOOK_EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
+  const hooksInstructions = {};
+  {
+    const repoInstr =
+      (repoConfig['hooks.instructions'] && typeof repoConfig['hooks.instructions'] === 'object')
+        ? repoConfig['hooks.instructions'] : {};
+    const userInstr =
+      (userConfig['hooks.instructions'] && typeof userConfig['hooks.instructions'] === 'object')
+        ? userConfig['hooks.instructions'] : {};
+    for (const ev of HOOK_EVENTS) {
+      const parts = [repoInstr[ev], userInstr[ev]]
+        .filter((v) => typeof v === 'string' && v.trim().length > 0);
+      hooksInstructions[ev] = parts.length > 0 ? parts.join('\n') : null;
+    }
+  }
+
   return {
     mode: chosen.mode,
     storeTarget,
@@ -147,6 +168,7 @@ export function resolveControl({
     scopeDefaults,
     hooksDisabled,
     hooksAdapter,
+    hooksInstructions,
   };
 }
 

package/src/core/lessons.mjs

@@ -51,19 +51,56 @@ export async function fetchLessons(store, cwd) {
   return { scope, lessons: lessons.slice(0, MAX_LESSONS) };
 }
 
-// Render lessons as a compact markdown block, or null when there are none.
-export function formatLessons(lessons, scope) {
-  if (!lessons || lessons.length === 0) return null;
+// Cap on a lesson's one-line hook in the injected index. Long enough to jog
+// recognition, short enough that N lessons stay a scannable list, not a wall —
+// the full text is always one `memory.read` away.
+const HOOK_LEN = 80;
+
+// A lesson's first meaningful line, cleaned into a short recognisable hook:
+// skips leading HTML-comment metadata (`<!-- ... -->`) and markdown heading
+// marks, collapses whitespace, and truncates on a word boundary with an
+// ellipsis — so nothing is ever cut mid-word into noise like "cascades to GE".
+function lessonHook(value, max = HOOK_LEN) {
+  let first = '';
+  for (const raw of String(value || '').split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('<!--')) continue; // skip blanks + meta comments
+    first = line.replace(/^#+\s*/, '');              // strip markdown heading marks
+    if (first) break;
+  }
+  first = first.replace(/\s+/g, ' ').trim();
+  if (first.length <= max) return first;
+  const clipped = first.slice(0, max);
+  const lastSpace = clipped.lastIndexOf(' ');
+  return `${(lastSpace > max * 0.6 ? clipped.slice(0, lastSpace) : clipped).trimEnd()}…`;
+}
+
+// Render the SessionStart block as a compact INDEX — one terse line per lesson
+// (scope, key, and a short hook), never the full bodies. This mirrors the
+// lorekit-memory intake rule ("report briefly") and the MEMORY.md index pattern:
+// surface WHAT is known so the agent can `memory.read` the one lesson that turns
+// out to matter, instead of paying for every body up front. Null when empty.
+// `instruction` — an optional extra line appended after the index, sourced from
+// `hooks.instructions.SessionStart` in the control config. Lets teams inject
+// project-specific guidance (e.g. "focus on migration safety") without touching
+// the hook internals. Visible even when there are no lessons.
+export function formatLessons(lessons, scope, { instruction = null } = {}) {
+  const noun = lessons && lessons.length === 1 ? 'memory' : 'memories';
+  if (!lessons || lessons.length === 0) {
+    // No lessons — only emit if there is a custom instruction to show.
+    if (!instruction) return null;
+    return (
+      `LoreKit: 0 ${noun} loaded · ${scope.repoScope || 'this workspace'} ` +
+      `— considerations, not rules; read any in full with memory.read.\n\n` +
+      `Project instruction: ${instruction}`
+    );
+  }
   const header =
-    `LoreKit — ${lessons.length} shared ${lessons.length === 1 ? 'memory' : 'memories'} for ${scope.repoScope || 'this workspace'}. ` +
-    `Treat as considerations, not rules; trust the current code if they conflict.`;
-  const body = lessons
-    .map((l) => {
-      const first = String(l.value || '').split('\n')[0].slice(0, 300);
-      return `- (${l.scope}) ${l.key}: ${first}`;
-    })
-    .join('\n');
-  return `${header}\n${body}`;
+    `LoreKit: ${lessons.length} ${noun} loaded · ${scope.repoScope || 'this workspace'} ` +
+    `— considerations, not rules; read any in full with memory.read.`;
+  const body = lessons.map((l) => `- (${l.scope}) ${l.key} — ${lessonHook(l.value)}`).join('\n');
+  const instructionBlock = instruction ? `\n\nProject instruction: ${instruction}` : '';
+  return `${header}\n${body}${instructionBlock}`;
 }
 
 // Distil a small set of significant, lowercased search TERMS from a tool
@@ -104,19 +141,16 @@ export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
 }
 
 // Render the relevant-lessons block injected alongside the failure nudge, or
-// null when nothing matched. Framed as prior art, not a directive — same
-// "considerations, not rules" stance as `formatLessons`.
+// null when nothing matched. Same compact-index shape as `formatLessons`, with a
+// touch more hook per line (there are at most MAX_RELEVANT and they're directly
+// actionable). Framed as prior art, not a directive.
 export function formatRelevantLessons(lessons) {
   if (!lessons || lessons.length === 0) return null;
+  const noun = lessons.length === 1 ? 'memory' : 'memories';
   const header =
-    `LoreKit — you've hit something like this before. ${lessons.length} related ` +
-    `${lessons.length === 1 ? 'memory' : 'memories'} (considerations, not rules; trust the current code if they conflict):`;
-  const body = lessons
-    .map((l) => {
-      const first = String(l.value || '').split('\n')[0].slice(0, 300);
-      return `- (${l.scope}) ${l.key}: ${first}`;
-    })
-    .join('\n');
+    `LoreKit: ${lessons.length} related ${noun} — you've hit something like this before ` +
+    `(considerations, not rules; read in full with memory.read):`;
+  const body = lessons.map((l) => `- (${l.scope}) ${l.key} — ${lessonHook(l.value, 140)}`).join('\n');
   return `${header}\n${body}`;
 }
 
@@ -146,12 +180,12 @@ function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
 export function retrospectiveNudge(scope, control) {
   const writeScope = scope.repoScope || 'global';
   const hint = tagsHint(writeScope, control);
+  const instruction = control && control.hooksInstructions && control.hooksInstructions.Stop
+    ? `\n\nProject instruction: ${control.hooksInstructions.Stop}` : '';
   return (
-    'LoreKit retrospective: if this session hit a stuck loop, a repeated ' +
-    'command failure, a surprising gotcha, a near-miss, or a wrong assumption ' +
-    'that cost time, record it now via the lorekit-memory skill ' +
-    `(memory.write to ${writeScope}, phrased as an observation).${hint} ` +
-    'If nothing was durable, do nothing.'
+    `LoreKit: hit any friction worth remembering — a stuck loop, a repeated ` +
+    `failure, a gotcha, a wrong assumption? If so, memory.write to ${writeScope} ` +
+    `as an observation; else skip.${hint}${instruction}`
   );
 }
 
@@ -161,11 +195,11 @@ export function retrospectiveNudge(scope, control) {
 export function failureNudge(toolName, scope, control) {
   const writeScope = scope.repoScope || 'global';
   const hint = tagsHint(writeScope, control);
-  const suffix = hint ? `${hint} So the next run avoids it.` : 'so the next run avoids it.';
+  const instruction = control && control.hooksInstructions && control.hooksInstructions.PostToolUseFailure
+    ? `\n\nProject instruction: ${control.hooksInstructions.PostToolUseFailure}` : '';
   return (
-    `LoreKit: the last ${toolName} call failed. If this is a recurring or ` +
-    'non-obvious failure, consider recording the fix as a memory via ' +
-    `lorekit-memory (memory.write to ${writeScope}) — ${suffix}`
+    `LoreKit: the last ${toolName} call failed. If it's recurring or non-obvious, ` +
+    `memory.write to ${writeScope} with the fix so the next run avoids it.${hint}${instruction}`
   );
 }
 

package/src/doctor.mjs

@@ -88,7 +88,24 @@ export async function doctor(args) {
     record('warn', 'scope', 'no git remote here — memories fall back to global');
   }
 
-  // 6. doctor.require — committed list of checks that MUST pass.
+  // 6. Hook instructions — show resolved per-event custom instructions when any are set.
+  {
+    const instr = control.hooksInstructions || {};
+    const EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
+    const configured = EVENTS.filter((ev) => instr[ev]);
+    if (configured.length > 0) {
+      for (const ev of EVENTS) {
+        const text = instr[ev];
+        if (text) {
+          record('info', `hooks.instructions.${ev}`, c.dim(text.length > 80 ? text.slice(0, 77) + '…' : text));
+        } else {
+          record('info', `hooks.instructions.${ev}`, c.dim('(not set)'));
+        }
+      }
+    }
+  }
+
+  // 7. doctor.require — committed list of checks that MUST pass.
   //    Useful as a CI gate: any check in the list that did not pass causes a failure.
   const lorekitJson = readLorekitJson(root);
   const required = (Array.isArray(lorekitJson['doctor.require']) ? lorekitJson['doctor.require'] : [])

package/src/hook.mjs

@@ -93,9 +93,19 @@ async function run(args) {
   if (intent === 'read') {
     if (!firstTimeThisSession(parsed.sessionId, 'read')) return 0;
     const store = createStore(control);
-    if (!store) return 0; // unconfigured/unusable — stay silent
+    // When there is no usable store, we still want to emit a custom instruction
+    // if one is configured — so we don't bail out entirely on a missing store.
+    const sessionInstruction = control.hooksInstructions && control.hooksInstructions.SessionStart
+      ? control.hooksInstructions.SessionStart : null;
+    if (!store) {
+      // No store: emit a minimal header + instruction when present, then return.
+      if (sessionInstruction) {
+        emit(formatLessons(null, { repoScope: null }, { instruction: sessionInstruction }));
+      }
+      return 0;
+    }
     const { scope: readScope, lessons } = await fetchLessons(store, root);
-    emit(formatLessons(lessons, readScope));
+    emit(formatLessons(lessons, readScope, { instruction: sessionInstruction }));
     return 0;
   }