portable-agent-layer 0.32.0 → 0.33.0

package/assets/skills/presentation/tools/lib/lint-types.ts

@@ -0,0 +1,40 @@
+// presentation skill — types shared across the lint pipeline.
+//
+// The doctor is structured as a rule registry: each rule is a small object
+// with a `check` function that emits Findings. Rules are either slide-scoped
+// (run once per slide) or deck-scoped (run once across the whole deck).
+
+export type Severity = "E" | "W";
+export type Finding = { rule: string; severity: Severity; msg: string };
+export type SlideReport = { name: string; layout: string; findings: Finding[] };
+
+export type SlideContext = {
+  name: string;
+  body: string; // raw markdown, includes Note: section
+  bodyNoNotes: string; // body with the Note: section stripped
+  layout: string;
+  deckDir: string;
+  heads1: string[];
+  heads2: string[];
+  index: number; // 0-based position in the deck
+};
+
+export type DeckContext = {
+  deckDir: string;
+  slides: SlideContext[];
+};
+
+export type SlideRule = {
+  name: string;
+  scope: "slide";
+  appliesTo?: (ctx: SlideContext) => boolean;
+  check: (ctx: SlideContext) => Promise<Finding[]> | Finding[];
+};
+
+export type DeckRule = {
+  name: string;
+  scope: "deck";
+  check: (ctx: DeckContext) => Promise<Finding[]> | Finding[];
+};
+
+export type Rule = SlideRule | DeckRule;

package/assets/skills/presentation/tools/new-deck.ts

@@ -84,13 +84,18 @@ lang: en
     await copyFile(join(sourceSlidesDir, f), join(slidesDir, f));
   }
 
-  // If the user happens to run build/present from inside this deck-dir, the output
-  // subdir lands here too. Pre-ignore it so it doesn't get accidentally committed.
+  // Build output lands in this deck-dir by default — flat (slug.html, slug.md)
+  // when --out defaults to the deck-dir, or under slug/ when --out is explicit.
+  // Pre-ignore both shapes.
   const slug =
     basename(target)
       .replace(/[^a-zA-Z0-9._-]+/g, "-")
       .replace(/^-+|-+$/g, "") || "deck";
-  await writeFile(join(target, ".gitignore"), `${slug}/\n`, "utf8");
+  await writeFile(
+    join(target, ".gitignore"),
+    `${slug}.html\n${slug}.md\n${slug}/\n`,
+    "utf8"
+  );
 
   console.log(`✓ deck scaffolded at ${target}`);
   console.log(`  template:   ${templateName}`);
@@ -99,7 +104,7 @@ lang: en
   console.log(`\nNext:`);
   console.log(`  $EDITOR ${slidesDir}/`);
   console.log(`  bun ~/.pal/skills/presentation/tools/build.ts ${target}`);
-  console.log(`  # output → <cwd>/${slug}/${slug}.html  (override with --out <dir>)`);
+  console.log(`  # output → ${target}/${slug}.html  (override with --out <dir>)`);
 }
 
 main().catch((e) => {

package/assets/skills/presentation/vendor/reveal/plugin/highlight/github-dark.css

@@ -0,0 +1,118 @@
+pre code.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 1em
+}
+code.hljs {
+  padding: 3px 5px
+}
+/*!
+  Theme: GitHub Dark
+  Description: Dark theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+
+  Outdated base version: https://github.com/primer/github-syntax-dark
+  Current colors taken from GitHub's CSS
+*/
+.hljs {
+  color: #c9d1d9;
+  background: #0d1117
+}
+.hljs-doctag,
+.hljs-keyword,
+.hljs-meta .hljs-keyword,
+.hljs-template-tag,
+.hljs-template-variable,
+.hljs-type,
+.hljs-variable.language_ {
+  /* prettylights-syntax-keyword */
+  color: #ff7b72
+}
+.hljs-title,
+.hljs-title.class_,
+.hljs-title.class_.inherited__,
+.hljs-title.function_ {
+  /* prettylights-syntax-entity */
+  color: #d2a8ff
+}
+.hljs-attr,
+.hljs-attribute,
+.hljs-literal,
+.hljs-meta,
+.hljs-number,
+.hljs-operator,
+.hljs-variable,
+.hljs-selector-attr,
+.hljs-selector-class,
+.hljs-selector-id {
+  /* prettylights-syntax-constant */
+  color: #79c0ff
+}
+.hljs-regexp,
+.hljs-string,
+.hljs-meta .hljs-string {
+  /* prettylights-syntax-string */
+  color: #a5d6ff
+}
+.hljs-built_in,
+.hljs-symbol {
+  /* prettylights-syntax-variable */
+  color: #ffa657
+}
+.hljs-comment,
+.hljs-code,
+.hljs-formula {
+  /* prettylights-syntax-comment */
+  color: #8b949e
+}
+.hljs-name,
+.hljs-quote,
+.hljs-selector-tag,
+.hljs-selector-pseudo {
+  /* prettylights-syntax-entity-tag */
+  color: #7ee787
+}
+.hljs-subst {
+  /* prettylights-syntax-storage-modifier-import */
+  color: #c9d1d9
+}
+.hljs-section {
+  /* prettylights-syntax-markup-heading */
+  color: #1f6feb;
+  font-weight: bold
+}
+.hljs-bullet {
+  /* prettylights-syntax-markup-list */
+  color: #f2cc60
+}
+.hljs-emphasis {
+  /* prettylights-syntax-markup-italic */
+  color: #c9d1d9;
+  font-style: italic
+}
+.hljs-strong {
+  /* prettylights-syntax-markup-bold */
+  color: #c9d1d9;
+  font-weight: bold
+}
+.hljs-addition {
+  /* prettylights-syntax-markup-inserted */
+  color: #aff5b4;
+  background-color: #033a16
+}
+.hljs-deletion {
+  /* prettylights-syntax-markup-deleted */
+  color: #ffdcd7;
+  background-color: #67060c
+}
+.hljs-char.escape_,
+.hljs-link,
+.hljs-params,
+.hljs-property,
+.hljs-punctuation,
+.hljs-tag {
+  /* purposely ignored */
+  
+}

package/assets/skills/projects/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: projects
+description: Project context management. PROACTIVE — use when the user references a project (by name or as "this repo", "current work"), asks to add/update/complete a project, says "store under <project>", "track this", "what am I working on", "my projects", "my priorities".
+argument-hint: [list | create | resume | add-fact | add-objective | add-next | add-blocker | add-decision | add-handoff | complete | archive | pause]
+---
+
+Manage the user's project registry. Each project has its own state file at `~/.pal/memory/state/progress/{slug}.json`. The Stop hook auto-touches `updated` whenever the cwd resolves into a registered project — so just *being* in the project keeps it warm.
+
+## CLI
+
+All operations go through the canonical CLI:
+
+```bash
+bun ~/.pal/tools/project.ts <command> [args]
+```
+
+Output is JSON.
+
+| Command | Purpose |
+|---------|---------|
+| `list` | All registered projects with status, path, updated, stale flag, and counts |
+| `create [name] [--path PATH] [--objectives "a;b;c"]` | Register a project. Defaults: name=basename(cwd), path=cwd. Slug must be `[a-z0-9_-]+` |
+| `resume <name>` | Print the full project JSON — facts, objectives, next steps, blockers, decisions, handoff |
+| `add-fact <name> "text"` | Append a stable fact / reference (e.g., "reference impl lives in this repo") |
+| `add-objective <name> "text"` | Append an objective |
+| `add-next <name> "text"` | Append a next step |
+| `add-blocker <name> "text"` | Append a blocker |
+| `add-decision <name> "decision" "rationale"` | Log a timestamped decision |
+| `add-handoff <name> "text"` | Overwrite the handoff field (single-value) |
+| `rm-fact \| rm-objective \| rm-next \| rm-blocker <name> <index>` | Remove an entry by zero-based index |
+| `complete <name>` / `archive <name>` / `pause <name>` / `unpause <name>` | Status transitions |
+| `rm <name>` | Delete the project state file entirely |
+
+## Routing
+
+| Intent | Action |
+|--------|--------|
+| "what am I working on", "my projects", "priorities" | `list` — summarize active and recently-touched projects |
+| "tell me about <project>" | `resume <name>` — present current state, highlight blockers and next steps |
+| "register this" / "track this" / cwd is unregistered work | `create` (default the name from cwd basename, confirm before writing) |
+| "store under <project>: X" / "note on <project>: X" | Pick the field — durable reference → `add-fact`, work item → `add-next`, obstacle → `add-blocker`. If unclear, ask. |
+| "we decided X because Y" | `add-decision <name> "X" "Y"` |
+| "handoff for <project>" / "next session pick up at X" | `add-handoff <name> "<text>"` |
+| "mark X complete" / "X is done" | `complete <name>` |
+| "park <project>" / "pause <project>" | `pause <name>` |
+| "archive <project>" | `archive <name>` |
+
+## Proactive registration
+
+When SessionStart context flags the current cwd as unregistered (e.g. `💡 cwd <path> is not yet registered; suggest registering if substantive work begins`) **and** the user starts substantive work (not just "hi"), surface the suggestion conversationally before the second tool call:
+
+> "I see we're in `<basename>` and it's not registered yet — want me to add it as a project?"
+
+- **Default name** = the FULL last path segment of cwd, lowercased. For `/repos/portable-agent-layer` → `portable-agent-layer`. Never split on `-`.
+- **Confirm before creating.** Never auto-create without explicit user approval ("yes", "do it", "register").
+- **Capture objectives in conversation.** If the user accepts but doesn't volunteer objectives, ask one short question, or infer from the last few messages and confirm.
+
+### When NOT to suggest registration
+
+- cwd has no project marker (`.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.) — it's a notes folder, not a project.
+- The user is clearly browsing or doing a one-off task.
+- An ancestor of multiple registered projects is the cwd (e.g. a generic dev root) — that's browse mode by design.
+- You're unsure. Err toward not registering.
+
+## Append-as-you-go
+
+When the user describes plans, blockers, or decisions during normal work, invoke the relevant subcommand to keep state current — that's the dynamism this system is built for. Don't invoke for fleeting comments, hypotheticals, or things the user is just thinking through. Wait for a clear declarative ("let's add X", "Z is blocking us"), not a question or musing.
+
+## Examples
+
+**Storing a reference under an existing project**
+```
+User: "store under <project> that a reference implementation exists in this repo"
+→ Identify the project from `list` (or by name)
+→ Durable reference, not a task → add-fact
+→ bun ~/.pal/tools/project.ts add-fact <slug> "Reference implementation lives in this repo"
+```
+
+**Registering the current repo**
+```
+User: "track this project"
+→ Default name from cwd basename, confirm with user
+→ bun ~/.pal/tools/project.ts create --path "$(pwd)" --objectives "first objective; second objective"
+```
+
+**Logging a decision**
+```
+User: "we decided <decision> because <reason>"
+→ bun ~/.pal/tools/project.ts add-decision <slug> "<decision>" "<reason>"
+```
+
+**Completing a project**
+```
+User: "mark <project> as complete"
+→ Confirm
+→ bun ~/.pal/tools/project.ts complete <slug>
+```
+
+## Anti-patterns
+
+- **Don't dump the full JSON.** Summarize. The user can ask for the raw payload.
+- **Don't write without confirming the field choice on ambiguous "store" requests.** A "fact" sticks forever; a "next step" implies follow-up — these are different commitments.
+- **Don't edit the JSON files directly.** Always use the CLI — it timestamps `updated` and keeps the schema valid.
+- **Don't re-introduce `~/.pal/telos/PROJECTS.md`.** That file and its `update-projects.ts` tool are deprecated. The legacy `telos` skill carries a deprecation notice for this reason.
+- **Don't confuse `add-fact` with the `telos` skill's `LEARNED.md` or `IDEAS.md`.** Project facts are scoped to one project; TELOS lessons are cross-cutting.
+
+## Rules
+
+- Always check `list` (or `resume <name>`) before writing — match an existing project rather than spawning a near-duplicate.
+- Slugs are `[a-z0-9_-]+`. Never rename a slug; if the display name needs to change, that's a code-side concern, not a slug change.
+- The Stop hook handles `updated` automatically when cwd matches `path` — no manual touch needed just to mark a project alive.

package/assets/skills/telos/SKILL.md

@@ -1,9 +1,12 @@
 ---
 name: telos
-description: Personal and project context management. Use when discussing goals, projects, beliefs, challenges, identity, updating telos, life context, what am I working on, adding a project, changing a goal, priorities, what do I believe, current obstacles, mission, or strategies.
+description: Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, priorities, what do I believe, current obstacles, mission, or strategies.
 argument-hint: [area to view or update]
 ---
 
+> ⚠️ **DEPRECATION NOTICE — Project management has moved.**
+> Project tracking is now handled by the `projects` skill, backed by `~/.pal/tools/project.ts` and per-project state in `~/.pal/memory/state/progress/`. **Do not use this skill for projects.** The `PROJECTS.md` references and `update-projects.ts` tool below are legacy and slated for removal — they remain only because the initial setup wizard (`src/cli/setup-telos.ts`) still depends on them. For anything project-related, invoke the `projects` skill.
+
 Manage the user's TELOS files — the persistent personal context that drives PAL.
 
 ## TELOS Files

package/assets/templates/AGENTS.md.template

@@ -60,10 +60,31 @@ Start your response with the following header in this mode:
 
 ## Context Routing
 
-When you need context about any of these topics, read `~/.pal/docs/CONTEXT_ROUTING.md` for the file path:
-
-- PAL internals
-- The user, their life and work, etc
-- Your own personality and rules
-- Any project referenced, any work, etc.
-- Basically anything that's specialized
+Load context on-demand by reading the file at the path listed. Only load what the current task requires.
+
+### PAL System
+
+| Topic | Path |
+|-------|------|
+| PAL system overview | `~/.pal/docs/README.md` |
+| System architecture | `~/.pal/docs/SYSTEM_ARCHITECTURE.md` |
+| Memory format & guidelines | `~/.pal/docs/MEMORY_SYSTEM.md` |
+| Work tracking (projects, sessions) | `~/.pal/docs/WORK_TRACKING.md` |
+| Opinion tracking | `~/.pal/docs/OPINION_TRACKING.md` |
+| Steering rules | `~/.pal/docs/STEERING_RULES.md` |
+| Algorithm (complex work phases) | `~/.pal/docs/ALGORITHM.md` |
+| Project lifecycle (when/how to register and manage user projects) | `~/.pal/skills/projects/SKILL.md` |
+
+### User Context (TELOS)
+
+| Topic | Path |
+|-------|------|
+| Goals (short/medium/long-term) | `~/.pal/telos/GOALS.md` |
+| Beliefs & principles | `~/.pal/telos/BELIEFS.md` |
+| Current challenges | `~/.pal/telos/CHALLENGES.md` |
+| Mission & direction | `~/.pal/telos/MISSION.md` |
+| Strategies & approaches | `~/.pal/telos/STRATEGIES.md` |
+| Ideas to explore | `~/.pal/telos/IDEAS.md` |
+| Key lessons learned | `~/.pal/telos/LEARNED.md` |
+| Mental models | `~/.pal/telos/MODELS.md` |
+| Narrative context | `~/.pal/telos/NARRATIVES.md` |

package/assets/templates/PAL/ALGORITHM.md

@@ -178,6 +178,8 @@ For EACH criterion:
 
 **Capability check:** Confirm every selected capability was actually invoked via tool call. Text output alone does not count.
 
+**Demonstrate, don't assert.** When verifying a new check / rule / behavior on a system that already passes, "existing inputs still pass" is not evidence the new logic works — the existing inputs would pass even if your code did nothing. Construct a deliberately-broken minimal example (a fake bad slide, a known-failing input, a unit test that should now fail without your change) and run it through to prove the new behavior actually fires. Show the failure happening in the verification output, not just the success case.
+
 If any criteria failed, fix and re-verify before completing.
 
 ### ━━━ 📚 LEARN ━━━ 5/5

package/assets/templates/PAL/README.md

@@ -14,7 +14,6 @@ PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows
 ~/.pal/                            # PAL home
   docs/                            # System documentation (engine-managed)
     ALGORITHM.md                   # The execution engine (4-phase)
-    CONTEXT_ROUTING.md             # On-demand context routing table
     MEMORY_SYSTEM.md               # Memory guidelines
     OPINION_TRACKING.md            # Opinion system reference
     STEERING_RULES.md              # Behavioral rules

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -475,4 +475,4 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 | Library files | kebab-case | `text-similarity.ts`, `signal-trends.ts` |
 | Tool files | kebab-case | `relationship-reflect.ts`, `token-cost.ts` |
 | Memory files | date-prefixed | `2026-03-24.md`, `2026-03-24_weekly.md` |
-| Template files | UPPER_SNAKE | `ALGORITHM.md`, `CONTEXT_ROUTING.md` |
+| Template files | UPPER_SNAKE | `ALGORITHM.md`, `MEMORY_SYSTEM.md` |

package/assets/templates/pal-settings.json

@@ -14,8 +14,7 @@
   "loadAtStartup": {
     "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
     "files": [
-      "~/.pal/docs/STEERING_RULES.md",
-      "~/.pal/telos/PROJECTS.md"
+      "~/.pal/docs/STEERING_RULES.md"
     ]
   },
   "dynamicContext": {
@@ -29,6 +28,7 @@
     "failurePatterns": true,
     "activeWork": true,
     "projectHistory": true,
+    "projects": true,
     "sessionIntelligence": true,
     "handoff": true,
     "selfModel": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/hooks/UserPromptOrchestrator.ts

@@ -7,6 +7,7 @@
  *  - session-name: generate 4-word session headline on first prompt
  */
 
+import { injectRetrieval } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
 import { logDebug, logError } from "./lib/log";
@@ -24,9 +25,10 @@ if (!input?.prompt) process.exit(0);
 const results = await Promise.allSettled([
   captureRating(input.prompt, input.session_id),
   captureSessionName(input.prompt, input.session_id ?? ""),
+  injectRetrieval(input.prompt),
 ]);
 
-const handlerNames = ["rating", "session-name"];
+const handlerNames = ["rating", "session-name", "inject-retrieval"];
 for (let i = 0; i < results.length; i++) {
   const r = results[i];
   if (r.status === "rejected") {

package/src/hooks/handlers/auto-graduate.ts

@@ -0,0 +1,169 @@
+/**
+ * Stop handler: promote graduated patterns into wisdom-frame CRYSTAL lines.
+ *
+ * Idempotency contract — N invocations in quick succession yield ≤1 promotion
+ * per pattern. Three layers:
+ *
+ *  1. TTL guard — skip if `graduated.json:lastRun` is younger than TTL_MS.
+ *     Catches accidental thrashing (Stop firing many times/min).
+ *
+ *  2. State-dedup — `state.graduated[]` tracks every pattern ever promoted.
+ *     A pattern with the same principle text never re-promotes, even after
+ *     the TTL window closes.
+ *
+ *  3. Content-dedup — `promoteCrystal` skips if any existing CRYSTAL line in
+ *     the target frame is Dice-similar (≥0.3) to the new principle. Last line
+ *     of defense against state corruption / manual edits / near-misses.
+ *
+ * Past attempt at auto-graduation failed precisely because of duplicate writes;
+ * this design is structured around that lesson. See feedback memory:
+ * `feedback_graduation_idempotency.md`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { analyze } from "../lib/graduation";
+import { logDebug, logError } from "../lib/log";
+import { ensureDir, paths } from "../lib/paths";
+import { promoteCrystal } from "../lib/wisdom";
+
+const TTL_MS = 24 * 60 * 60 * 1000; // 24h — matches synthesize.ts
+const CRYSTAL_FLOOR = 85;
+
+interface GraduatedEntry {
+  pattern: string;
+  domain: string;
+  confidence: number;
+  occurrences: number;
+  sources: string[];
+  graduatedAt: string;
+}
+
+interface GraduationState {
+  lastRun: string;
+  graduated: GraduatedEntry[];
+}
+
+function statePath(): string {
+  return resolve(ensureDir(paths.wisdomState()), "graduated.json");
+}
+
+function readState(): GraduationState {
+  const p = statePath();
+  if (!existsSync(p)) return { lastRun: "", graduated: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf-8")) as Partial<GraduationState>;
+    return {
+      lastRun: parsed.lastRun ?? "",
+      graduated: Array.isArray(parsed.graduated) ? parsed.graduated : [],
+    };
+  } catch {
+    return { lastRun: "", graduated: [] };
+  }
+}
+
+function writeState(state: GraduationState): void {
+  writeFileSync(statePath(), JSON.stringify(state, null, 2), "utf-8");
+}
+
+function withinTtl(state: GraduationState): boolean {
+  if (!state.lastRun) return false;
+  const last = new Date(state.lastRun).getTime();
+  if (!Number.isFinite(last)) return false;
+  return Date.now() - last < TTL_MS;
+}
+
+function alreadyPromoted(state: GraduationState, pattern: string): boolean {
+  return state.graduated.some((g) => g.pattern === pattern);
+}
+
+export interface AutoGraduateOptions {
+  /** Bypass the 24h TTL guard. State + content dedup still apply. */
+  force?: boolean;
+}
+
+export interface AutoGraduateResult {
+  ranAnalysis: boolean;
+  candidatesAtFloor: number;
+  promoted: number;
+  skippedByState: number;
+  skippedByContent: number;
+}
+
+/**
+ * Run auto-graduation. Safe to call as often as you like — see file header.
+ *
+ * Returns a summary of what happened so callers (handler, tests) can reason
+ * about the run without re-reading state.
+ */
+export async function autoGraduate(
+  opts: AutoGraduateOptions = {}
+): Promise<AutoGraduateResult> {
+  const result: AutoGraduateResult = {
+    ranAnalysis: false,
+    candidatesAtFloor: 0,
+    promoted: 0,
+    skippedByState: 0,
+    skippedByContent: 0,
+  };
+
+  const state = readState();
+  if (!opts.force && withinTtl(state)) {
+    logDebug("auto-graduate", `skip — within TTL (last ${state.lastRun})`);
+    return result;
+  }
+
+  let analysis: Awaited<ReturnType<typeof analyze>>;
+  try {
+    analysis = await analyze();
+    result.ranAnalysis = true;
+  } catch (err) {
+    logError("auto-graduate:analyze", err);
+    return result;
+  }
+
+  const eligible = analysis.graduated.filter((g) => g.confidence >= CRYSTAL_FLOOR);
+  result.candidatesAtFloor = eligible.length;
+
+  for (const g of eligible) {
+    if (alreadyPromoted(state, g.pattern)) {
+      result.skippedByState++;
+      continue;
+    }
+    const outcome = promoteCrystal(g.domain, g.pattern, g.confidence);
+    if (outcome.skipped === "duplicate") {
+      // Frame already had a Dice-similar CRYSTAL line — record in state so we
+      // don't re-attempt next run.
+      result.skippedByContent++;
+      state.graduated.push({
+        pattern: g.pattern,
+        domain: g.domain,
+        confidence: g.confidence,
+        occurrences: g.occurrences,
+        sources: g.sources,
+        graduatedAt: new Date().toISOString(),
+      });
+      continue;
+    }
+    result.promoted++;
+    state.graduated.push({
+      pattern: g.pattern,
+      domain: g.domain,
+      confidence: g.confidence,
+      occurrences: g.occurrences,
+      sources: g.sources,
+      graduatedAt: new Date().toISOString(),
+    });
+  }
+
+  state.lastRun = new Date().toISOString();
+  writeState(state);
+
+  if (result.promoted > 0 || result.skippedByState > 0 || result.skippedByContent > 0) {
+    logDebug(
+      "auto-graduate",
+      `promoted=${result.promoted} skipState=${result.skippedByState} skipContent=${result.skippedByContent} candidates=${result.candidatesAtFloor}`
+    );
+  }
+  return result;
+}

package/src/hooks/handlers/inject-retrieval.ts

@@ -0,0 +1,50 @@
+/**
+ * UserPromptSubmit handler: inject the top-N matching prior lessons into the prompt.
+ *
+ * Called from UserPromptOrchestrator. Reads the retrieval index, ranks the prompt
+ * against the corpus, prints a `<system-reminder>` block to stdout (Claude Code
+ * prepends UserPromptSubmit hook stdout to the prompt). Fail-closed: any error or
+ * timeout produces empty output, never blocks the prompt.
+ */
+
+import { logDebug, logError } from "../lib/log";
+import { runRetrieval } from "../lib/retrieval";
+import { ensureIndex } from "../lib/retrieval-index";
+import { isEnabled } from "../lib/settings";
+
+const TIMEOUT_MS = 250;
+
+function withTimeout<T>(work: () => T, ms: number): Promise<T | null> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(null), ms);
+    try {
+      const result = work();
+      clearTimeout(timer);
+      resolve(result);
+    } catch (err) {
+      clearTimeout(timer);
+      logError("inject-retrieval", err);
+      resolve(null);
+    }
+  });
+}
+
+export async function injectRetrieval(prompt: string): Promise<void> {
+  if (!prompt?.trim()) return;
+  if (!isEnabled("learningInjection")) return;
+
+  const result = await withTimeout(() => {
+    const index = ensureIndex();
+    if (index.corpusSize === 0) return null;
+    return runRetrieval(prompt, index, process.cwd());
+  }, TIMEOUT_MS);
+
+  if (!result?.reminder) return;
+
+  logDebug(
+    "inject-retrieval",
+    `injected ${result.matches.length} matches; top score=${result.matches[0]?.confidence.toFixed(3)}`
+  );
+
+  process.stdout.write(`${result.reminder}\n`);
+}