portable-agent-layer 0.63.3 → 0.65.0

package/assets/skills/presentation/SKILL.md

@@ -1,7 +1,19 @@
 ---
 name: presentation
+license: MIT
 description: "Build branded HTML presentations from markdown using Reveal.js. Multi-template registry per user (each template = brand color, logo, fonts, footer, aspect). Per-deck workflow: scaffold → edit one markdown file per slide in slides/ → build → present. Output: a per-deck subdir with a self-contained HTML and a concatenated markdown sibling. 14 layouts including data-display patterns (big-stat, metric-grid). Use when creating slide decks, talks, workshop slides, lectures, or pitch decks."
 argument-hint: <deck-dir> to build, OR `setup-template` to add a brand template, OR `new <deck-dir> --template <name>` to scaffold a deck, OR `list-templates`
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "presentation"
+    - "slide deck"
+    - "slides"
+    - "pitch deck"
+    - "reveal.js"
+    - "workshop deck"
+    - "talk slides"
+    - "ppt"
 ---
 
 ## Overview

package/assets/skills/projects/SKILL.md

@@ -1,7 +1,26 @@
 ---
 name: projects
+license: MIT
 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 a named project\", \"track this\", \"what am I working on\", \"my projects\", \"my priorities\". Also triggered by ISC/ISA terminology — ISC stands for Ideal State Criteria, a project's verifiable done-conditions stored as `ISC-N:` lines in the Criteria section of its ISA.md spec. Phrases like \"ISC\", \"open/opening the ISC\", \"open ISCs\" (unfinished criteria), \"create/creating a ticket for a project\", \"new ticket\", or \"project ticket\" all map here: use `list-isc` to read them, `add-isc` to create one, `complete-isc`/`reopen-isc` to change status."
 argument-hint: [list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause]
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "projects"
+    - "isc"
+    - "isa"
+    - "my projects"
+    - "what am i working on"
+    - "my priorities"
+    - "track this"
+    - "resume the project"
+    - "resume project"
+    - "where are we"
+    - "open ticket"
+    - "open iscs"
+    - "file ticket"
+    - "file it as a ticket"
+    - "file a ticket"
 ---
 
 Manage the user's project registry. Each project lives at `~/.pal/memory/projects/{slug}/ISA.md`. Frontmatter holds operational state (next steps, blockers, handoff); the body holds ISA spec sections (Problem, Goal, Criteria, Context, Decisions, etc.). The Stop hook auto-touches `updated` whenever the cwd resolves into a registered project — just *being* in the project keeps it warm.
@@ -48,7 +67,7 @@ The body of each ISA.md holds spec sections. Use `update-section` to set them:
 | Decisions | `decisions` | Auto-managed by `add-decision`; dated bullet list |
 | Changelog | `changelog` | Archive of completed ISCs (`complete-isc` moves them here under a dated `### Archived` heading) plus any milestone notes |
 
-**ISC archive model.** `complete-isc` does not just check a box — it moves the ISC line out of Criteria and into the Changelog archive, so Criteria always reflects exactly the open work and never bloats the context loaded at session start. `list-isc <name>` shows open ISCs by default; pass `--closed` (archived only) or `--all` (open + archived) to read finished ones. `reopen-isc` pulls an archived ISC back into the open set. `prune-isc <name>` backfills legacy projects by sweeping any done ISCs still sitting in Criteria into the archive in one pass.
+**ISC archive model.** `complete-isc` does not just check a box — it moves the ISC line out of Criteria and into the Changelog archive, so Criteria always reflects exactly the open work and never bloats the context loaded at session start. `list-isc <name>` shows open ISCs by default; pass `--closed` (archived only) or `--all` (open + archived) to read finished ones. `reopen-isc` pulls an archived or retired ISC back into the open set. `edit-isc <name> <id> "new text"` rewrites an ISC's wording in place, keeping its id and state — use it to sharpen a vague criterion instead of closing and refiling. `retire-isc <name> <id> [--by <id>]` closes an ISC that stopped being valid: it files under a `### Retired` heading as `[~]` rather than claiming the work was done, and `--by` records the superseding ISC. A retired ISC counts as neither open nor done, is listed with `--retired`, and keeps its id reserved so no future ISC can reuse it. `prune-isc <name>` backfills legacy projects by sweeping any done ISCs still sitting in Criteria into the archive in one pass.
 
 ## Routing
 

package/assets/skills/reflect/SKILL.md

@@ -1,7 +1,20 @@
 ---
 name: reflect
+license: MIT
 description: "Diagnose why a PAL behavior did not trigger as expected — trace hooks, instructions, and logic to find the gap. Use when a hook, skill, or automation didn't fire or behaved unexpectedly."
 argument-hint: <what went wrong>
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "reflect"
+    - "didn't fire"
+    - "didn't trigger"
+    - "didn't run"
+    - "why didn't"
+    - "not triggering"
+    - "never fired"
+    - "should have fired"
+    - "behaved unexpectedly"
 ---
 
 When the user invokes `/reflect [optional: description of what didn't happen]`:

package/assets/skills/telos/SKILL.md

@@ -2,6 +2,18 @@
 name: telos
 description: "Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies."
 argument-hint: [area to view or update]
+metadata:
+  source: portable-agent-layer
+  derived-from: https://github.com/danielmiessler/LifeOS
+  triggers:
+    - "telos"
+    - "my goals"
+    - "my beliefs"
+    - "my mission"
+    - "life context"
+    - "current challenges"
+    - "what do i believe"
+    - "my strategies"
 ---
 
 Manage the user's TELOS files — from Greek τέλος (télos), meaning end/purpose/goal. The persistent personal context that orients PAL around who the user is and what they're working toward.

package/assets/skills/think/SKILL.md

@@ -2,6 +2,15 @@
 name: think
 description: "Thinking mode router — selects the right analytical approach for a question. Use when thinking through a problem, analyzing deeply, brainstorming ideas, debating options, decomposing to root cause, challenging assumptions, or exploring from multiple perspectives."
 argument-hint: <question or topic>
+metadata:
+  source: portable-agent-layer
+  derived-from: https://github.com/danielmiessler/LifeOS
+  triggers:
+    - "think"
+    - "brainstorm"
+    - "analyze deeply"
+    - "think about this"
+    - "mental model"
 ---
 
 Route $ARGUMENTS to the right thinking mode based on intent. Detect the mode from context — do NOT ask.

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -213,6 +213,9 @@ Brief description.
 
 ┌─────────────────────┐
 │  User Prompt Submit │──► UserPromptOrchestrator.ts
+│                     │    - Prompt context (one merged system-reminder):
+│                     │      contextual steering, skill trigger matches,
+│                     │      prior-lesson retrieval
 │                     │    - Rating capture (explicit/implicit)
 │                     │    - Session naming (first prompt)
 └─────────────────────┘

package/assets/templates/pal-settings.json

@@ -27,6 +27,7 @@
     "handoff": true,
     "selfModel": true,
     "contextualSteering": true,
+    "skillMatching": true,
     "steeringTestReport": false
   },
   "steering": {

package/assets/templates/settings.claude.json

@@ -45,7 +45,8 @@
   },
   "attribution": {
     "commit": "",
-    "pr": ""
+    "pr": "",
+    "sessionUrl": false
   },
   "showClearContextOnPlanAccept": true,
   "respectGitignore": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.63.3",
+  "version": "0.65.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "keywords": [
     "ai",
@@ -34,7 +34,9 @@
   },
   "scripts": {
     "type-check": "tsc --noEmit",
-    "test": "bun test",
+    "test": "bun test --randomize",
+    "test:mutate": "stryker run",
+    "test:mutate:diff": "bun .agents/scripts/mutate-diff.ts",
     "format": "biome format",
     "format-write": "biome format --write",
     "lint": "biome lint",
@@ -44,6 +46,10 @@
     "knip": "knip-bun",
     "klint": "klint",
     "jscpd": "jscpd --noTips",
+    "madge": "madge --circular --extensions ts --ts-config tsconfig.json src",
+    "lf": "bun .agents/scripts/check-lf.ts",
+    "lf:fix": "bun .agents/scripts/check-lf.ts --fix",
+    "secretlint": "secretlint \"**/*\"",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
     "build:skill-tools": "bun run scripts/build-skill-tools.ts",
@@ -66,11 +72,14 @@
     "@biomejs/biome": "2.4.15",
     "@commitlint/cli": "21.0.1",
     "@commitlint/config-conventional": "21.0.1",
-    "@konvert7/klint": "0.20.0",
+    "@hughescr/stryker-bun-runner": "1.3.8",
+    "@konvert7/klint": "0.34.0",
     "@opencode-ai/plugin": "latest",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.8",
+    "@stryker-mutator/core": "9.6.1",
     "@types/adm-zip": "^0.5.8",
     "@types/bun": "latest",
     "@types/node": "latest",
@@ -78,7 +87,9 @@
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
     "lint-staged": "17.0.5",
+    "madge": "8.0.0",
     "promptfoo": "0.121.14",
+    "secretlint": "13.0.2",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },

package/src/cli/index.ts

@@ -12,12 +12,12 @@
  *   uninstall [--claude] [--opencode] [--cursor] [--codex] Remove hooks/skills for targets
  *   update                             Update PAL (git pull or npm update)
  *   export [path] [--dry-run]         Export user state to zip
- *   import [path] [--dry-run]         Import user state from zip
+ *   import [path] [--dry-run] [--overwrite]  Merge user state from zip
  *   status                            Show current PAL configuration
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
- *   skill doctor <name>               Evaluate a skill against the authoring best practices
+ *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
  *   subagent doctor <name>           Evaluate a subagent against the authoring best practices
  *   debug [on|off]                    Enable / disable verbose hook debug logging
@@ -35,9 +35,17 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import {
+  appendImportLog,
+  mergeArchive,
+  readManifest,
+  summarize,
+} from "../hooks/lib/import-merge";
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
 import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
+import { ensureRegistered, writeRegistryEntry } from "../hooks/lib/machine";
 import { palHome, palPkg, paths, platform } from "../hooks/lib/paths";
+import { auditBindings, describeBindingIssue } from "../hooks/lib/projects";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
 import { checkPendingMigrations } from "./migrate";
@@ -274,7 +282,7 @@ function showHelp() {
     pal cli uninstall [--claude] [--opencode] [--cursor] [--codex] Remove hooks for targets
     pal cli update                          Update PAL (git pull or npm update)
     pal cli export [path] [--dry-run]       Export state to zip
-    pal cli import [path] [--dry-run]       Import state from zip
+    pal cli import [path] [--dry-run]       Merge state from zip (--overwrite to replace)
     pal cli status                          Show PAL configuration
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
@@ -283,7 +291,7 @@ function showHelp() {
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
-    pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
+    pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent
     pal cli subagent link <name>            Install a personal ~/.pal/agents/<name>.md into installed agents
     pal cli subagent doctor <name>          Evaluate a subagent against the authoring best practices
@@ -845,6 +853,16 @@ function doctor(silent = false): DoctorResult {
           );
     }
 
+    // Project bindings — where each project lives on THIS machine
+    {
+      const issues = auditBindings();
+      if (issues.length === 0) {
+        ok("Project bindings healthy");
+      } else {
+        for (const issue of issues) warn(`Binding: ${describeBindingIssue(issue)}`);
+      }
+    }
+
     // Dependencies (PAL's own npm packages)
     const nodeModulesPath = resolve(palPkg(), "node_modules");
     existsSync(nodeModulesPath)
@@ -1293,6 +1311,7 @@ async function importState(args: string[]) {
 
   const home = palHome();
   const dryRun = args.includes("--dry-run");
+  const overwrite = args.includes("--overwrite");
   const pathArg = args.find((a) => !a.startsWith("-"));
   logDebug("import", `start dryRun=${dryRun} pathArg=${pathArg ?? "(auto)"}`);
 
@@ -1369,16 +1388,83 @@ async function importState(args: string[]) {
     process.exit(0);
   }
 
-  logDebug("import", `zip=${zipPath} entries=${entries.length} dryRun=${dryRun}`);
+  logDebug(
+    "import",
+    `zip=${zipPath} entries=${entries.length} dryRun=${dryRun} overwrite=${overwrite}`
+  );
   if (dryRun) {
-    console.log(`Would import ${entries.length} files → ${home}\n`);
+    console.log(
+      `Would ${overwrite ? "overwrite with" : "merge"} ${entries.length} files → ${home}\n`
+    );
     for (const e of entries) console.log(`  ${e.entryName}`);
-  } else {
+    return;
+  }
+
+  if (overwrite) {
     zip.extractAllTo(home, true);
-    logDebug("import", `done extracted=${entries.length} to=${home}`);
-    console.log(`Imported ${entries.length} files → ${home}`);
+    logDebug("import", `done overwrote=${entries.length} to=${home}`);
+    console.log(`Imported ${entries.length} files → ${home} (overwrite)`);
+    appendImportLog(home, {
+      ts: new Date().toISOString(),
+      archive: zipPath,
+      mode: "overwrite",
+      created: 0,
+      merged: 0,
+      identical: 0,
+      conflicts: 0,
+      skipped: 0,
+      linesAdded: 0,
+      quarantineDir: null,
+    });
     log.info("Run 'pal cli install' to re-register hooks.");
+    return;
+  }
+
+  ensureRegistered(home);
+  const quarantineDir = resolve(
+    home,
+    "backups",
+    `import-conflicts-${new Date()
+      .toISOString()
+      .replace(/[-:T.]/g, "")
+      .slice(0, 14)}`
+  );
+  const result = mergeArchive(
+    entries.map((e) => ({ path: e.entryName, data: () => e.getData() })),
+    home,
+    quarantineDir
+  );
+  const source = readManifest(
+    entries.map((e) => ({ path: e.entryName, data: () => e.getData() }))
+  );
+  if (source) {
+    writeRegistryEntry({ id: source.machineId, label: source.label, os: source.os });
+    console.log(`Source machine: ${source.label} (${source.machineId})`);
+  }
+
+  appendImportLog(home, {
+    ts: new Date().toISOString(),
+    archive: zipPath,
+    mode: "merge",
+    created: result.created.length,
+    merged: result.merged.length,
+    identical: result.identical.length,
+    conflicts: result.conflicts.length,
+    skipped: result.skipped.length,
+    linesAdded: result.linesAdded,
+    quarantineDir: result.quarantineDir,
+    sourceMachineId: source?.machineId ?? null,
+  });
+
+  logDebug("import", `done merge ${summarize(result)} to=${home}`);
+  console.log(`Imported → ${home}: ${summarize(result)}`);
+  if (result.conflicts.length > 0) {
+    log.warn(
+      `${result.conflicts.length} file(s) diverged — local kept, incoming saved to ${result.quarantineDir}`
+    );
+    for (const c of result.conflicts) console.log(`  ${c}`);
   }
+  log.info("Run 'pal cli install' to re-register hooks.");
 }
 
 async function update() {

package/src/cli/migrate.ts

@@ -105,7 +105,7 @@ const v1Projects: Migration = {
 function nextIscId(criteria: string): number {
   const ids: number[] = [];
   for (const line of criteria.split("\n")) {
-    const m = new RegExp(/^-\s+\[[ x]\]\s+ISC-(\d+):/i).exec(line);
+    const m = new RegExp(/^-\s+\[[ x~]\]\s+ISC-(\d+):/i).exec(line);
     if (m) ids.push(Number(m[1]));
   }
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
@@ -117,7 +117,9 @@ function pendingThreadsForProjects(): { thread: Thread; project: ProjectProgress
   const projects = readAllProjects();
   const results: { thread: Thread; project: ProjectProgress }[] = [];
   for (const thread of threads) {
-    const project = projects.find((p) => resolve(p.path) === resolve(thread.cwd));
+    const project = projects.find(
+      (p) => p.path !== undefined && resolve(p.path) === resolve(thread.cwd)
+    );
     if (project) results.push({ thread, project });
   }
   return results;
@@ -362,7 +364,71 @@ const v3EntitiesToKnowledge: Migration = {
 
 // ── Registry ──────────────────────────────────────────────────────
 
-const MIGRATIONS: Migration[] = [v1Projects, v2ThreadsToIsc, v3EntitiesToKnowledge];
+// ── v4: project paths out of records, into machine-local bindings ──
+
+/** Records written before bindings existed carry their own `path:` in frontmatter. */
+function recordsCarryingAPath(): string[] {
+  const base = paths.projectHistory();
+  if (!existsSync(base)) return [];
+  const out: string[] = [];
+  for (const slug of readdirSync(base)) {
+    const file = resolve(base, slug, "ISA.md");
+    if (!existsSync(file)) continue;
+    const frontmatter = readFileSync(file, "utf-8").split("---")[1] ?? "";
+    if (/^path:/m.test(frontmatter)) out.push(slug);
+  }
+  return out;
+}
+
+const v4PathsToBindings: Migration = {
+  id: "v4-paths-to-bindings",
+  description: "Move project paths out of records into machine-local bindings",
+
+  check() {
+    const stale = recordsCarryingAPath();
+    return {
+      pending: stale.length > 0,
+      detail:
+        stale.length > 0 ? `${stale.length} record(s) still store a path` : undefined,
+    };
+  },
+
+  // Reading a record and writing it straight back is the whole migration: the
+  // writer already routes the path to a binding, drops the field, and picks up
+  // the git remote. Nothing here reimplements that, so the two cannot drift.
+  run(dryRun = false): MigrationResult {
+    const stale = recordsCarryingAPath();
+    const results: string[] = [];
+    let migrated = 0;
+    let skipped = 0;
+
+    for (const slug of stale) {
+      const project = readProject(slug);
+      if (!project) {
+        skipped++;
+        results.push(`${slug}: unreadable, left untouched`);
+        continue;
+      }
+      if (dryRun) {
+        migrated++;
+        results.push(`${slug}: would move ${project.path ?? "(no path)"} to a binding`);
+        continue;
+      }
+      writeProject(project);
+      migrated++;
+      results.push(`${slug}: path moved to a binding`);
+    }
+
+    return { migrated, skipped, results };
+  },
+};
+
+const MIGRATIONS: Migration[] = [
+  v1Projects,
+  v2ThreadsToIsc,
+  v3EntitiesToKnowledge,
+  v4PathsToBindings,
+];
 
 // ── Public API ────────────────────────────────────────────────────
 

package/src/cli/skill.ts

@@ -5,16 +5,59 @@
  *                                 every installed agent so it is discoverable.
  *   pal cli skill doctor <name>   Evaluate ~/.pal/skills/<name>/ against the
  *                                 skill-authoring best practices.
+ *   pal cli skill doctor --all    Evaluate every installed skill, one line each.
  *   pal cli skill author-model    Print the flagship model configured to author
  *                                 skills for the active agent (empty if none).
  */
 
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { getActiveAgent } from "../hooks/lib/agent";
 import { flagshipAuthorModel } from "../hooks/lib/models";
 import { palHome } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
-import { formatReport, lintSkill } from "../tools/skill-doctor";
+import { formatReport, formatSummary, lintSkill } from "../tools/skill-doctor";
+
+/** Entry names under ~/.pal/skills/, sorted; dangling links included. */
+function skillEntries(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).sort();
+}
+
+/** A listed entry that does not exist can only be a symlink whose target is gone. */
+function isDanglingLink(path: string): boolean {
+  return !existsSync(path);
+}
+
+/** Lint every installed skill, one summary line each. Exits 1 if any has errors. */
+function doctorAll(): number {
+  const dir = resolve(palHome(), "skills");
+  const entries = skillEntries(dir);
+
+  for (const name of entries.filter((n) => isDanglingLink(resolve(dir, n)))) {
+    log.warn(`Skipped ${name}: link target is gone — run 'pal cli install' to prune it`);
+  }
+
+  const names = entries.filter((n) => {
+    const path = resolve(dir, n);
+    return !isDanglingLink(path) && statSync(path).isDirectory();
+  });
+  if (names.length === 0) {
+    log.warn(`No skills found in ${dir}`);
+    return 0;
+  }
+
+  const reports = names.map((n) => lintSkill(resolve(dir, n)));
+  for (const report of reports) console.log(formatSummary(report));
+
+  const failing = reports.filter((r) => r.errors > 0).length;
+  const warning = reports.filter((r) => r.errors === 0 && r.warnings > 0).length;
+  const clean = reports.length - failing - warning;
+  console.log(
+    `\n${reports.length} skills — ${failing} failing, ${warning} with warnings, ${clean} clean`
+  );
+  return failing > 0 ? 1 : 0;
+}
 
 export async function runSkill(args: string[]): Promise<number> {
   const [sub, name] = args;
@@ -26,8 +69,9 @@ export async function runSkill(args: string[]): Promise<number> {
   }
 
   if (sub === "doctor") {
+    if (name === "--all") return doctorAll();
     if (!name) {
-      log.error("Usage: pal cli skill doctor <name>");
+      log.error("Usage: pal cli skill doctor <name|--all>");
       return 1;
     }
     const report = lintSkill(resolve(palHome(), "skills", name));
@@ -60,6 +104,6 @@ export async function runSkill(args: string[]): Promise<number> {
     }
   }
 
-  log.error("Usage: pal cli skill <link|doctor|author-model> [name]");
+  log.error("Usage: pal cli skill <link|doctor|author-model> [name|--all]");
   return 1;
 }

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

@@ -12,6 +12,7 @@ import { logDebug, logError } from "../lib/log";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
+import { getSkillReminder } from "../lib/skill-match";
 import { getSteeringReminder } from "../lib/steering";
 
 const BUDGET_MS = 250;
@@ -35,7 +36,8 @@ export function withinBudget<T>(work: () => T, ms: number): T | null {
   }
 }
 
-/** Returns the retrieval reminder string, or null if nothing to inject. @lintignore dynamically imported by opencode plugin */
+/** Returns the retrieval reminder string, or null if nothing to inject.
+ *  @lintignore exercised directly by test/inject-retrieval.test.ts */
 export async function getRetrievalReminder(prompt: string): Promise<string | null> {
   if (!prompt?.trim()) return null;
   if (!isEnabled("learningInjection")) return null;
@@ -77,15 +79,23 @@ function writeForAgent(reminder: string): void {
   }
 }
 
-/** Gather all prompt-time context — prior-lesson retrieval + contextual steering —
- *  merge into a single payload, and do the one per-agent write. Returns the combined
- *  reminder that was injected, or null if there was nothing to inject. */
+/** Merge every prompt-time source — contextual steering, skill matches, prior-lesson
+ *  retrieval — into one payload, or null when none of them produced anything.
+ *  @lintignore dynamically imported by opencode plugin */
+export async function getPromptContext(prompt: string): Promise<string | null> {
+  const parts = [
+    getSteeringReminder(prompt),
+    getSkillReminder(prompt),
+    await getRetrievalReminder(prompt),
+  ].filter((p): p is string => Boolean(p));
+
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}
+
+/** Gather all prompt-time context and do the one per-agent write. Returns the
+ *  combined reminder that was injected, or null if there was nothing to inject. */
 export async function injectPromptContext(prompt: string): Promise<string | null> {
-  const retrieval = await getRetrievalReminder(prompt);
-  const steering = getSteeringReminder(prompt);
-  const parts = [steering, retrieval].filter((p): p is string => Boolean(p));
-  if (parts.length === 0) return null;
-  const combined = parts.join("\n\n");
-  writeForAgent(combined);
+  const combined = await getPromptContext(prompt);
+  if (combined) writeForAgent(combined);
   return combined;
 }