portable-agent-layer 0.35.0 → 0.36.0

package/src/hooks/lib/semi-static.ts

@@ -0,0 +1,186 @@
+/**
+ * Semi-static context source registry.
+ *
+ * One entry here = the only change needed to add a new source across all consumers:
+ * CLAUDE.md @imports, opencode instructions[], Cursor .mdc, Copilot .instructions.md,
+ * and the session-stop digest writer.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "./frontmatter";
+import { readFailures } from "./learning-store";
+import { loadOpinionContext } from "./opinions";
+import { palHome, paths } from "./paths";
+import { readFramePrinciples } from "./wisdom";
+
+/** A single semi-static context source — built at session stop, loaded natively at session start. */
+export interface SemiStaticSource {
+  /** Absolute path used in @imports (CLAUDE.md), instructions[] (opencode), and digest writes. */
+  readonly path: string;
+  /** When true, session-stop handler writes build result to path. */
+  readonly writesDigest: boolean;
+  /** Returns current content — builds fresh when writesDigest is true, reads the file otherwise. */
+  load(): string;
+  /** Slug for ~/.cursor/rules/pal-${slug}.mdc and ~/.copilot/instructions/pal-${slug}.instructions.md */
+  readonly slug: string;
+  /** Human-readable description for Cursor .mdc frontmatter. */
+  readonly description: string;
+}
+
+/** Returns the Cursor rules filename for a source. */
+export function cursorFilename(src: SemiStaticSource): string {
+  return `pal-${src.slug}.mdc`;
+}
+
+/** Returns the Copilot instructions filename for a source. */
+export function copilotFilename(src: SemiStaticSource): string {
+  return `pal-${src.slug}.instructions.md`;
+}
+
+function readFileSafe(path: string): string {
+  try {
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Build recommendations from the most recent synthesis report. */
+export function loadSynthesisRecommendations(): string {
+  try {
+    const synthDir = paths.synthesis();
+    if (!existsSync(synthDir)) return "";
+
+    const months = readdirSync(synthDir).sort().reverse();
+    for (const month of months) {
+      const monthDir = resolve(synthDir, month);
+      try {
+        const files = readdirSync(monthDir)
+          .filter((f) => f.endsWith(".md"))
+          .sort()
+          .reverse();
+        if (files.length === 0) continue;
+
+        const content = readFileSync(resolve(monthDir, files[0]), "utf-8");
+
+        const recMatch = content.match(/## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/);
+        if (!recMatch?.[1]?.trim()) continue;
+
+        const recs = recMatch[1]
+          .trim()
+          .split("\n")
+          .filter((l) => l.trim())
+          .slice(0, 4);
+
+        if (recs.length === 0) continue;
+
+        const { meta } = parse<{ period?: string; average_rating?: string }>(content);
+        const period = meta.period ?? "";
+        const avgRating = meta.average_rating ? `${meta.average_rating}/10` : "";
+
+        const header = [
+          "## Pattern Synthesis",
+          period ? `*${period} — ${avgRating}*` : "",
+        ]
+          .filter(Boolean)
+          .join("\n");
+
+        return [header, ...recs].join("\n");
+      } catch {
+        /* try next month */
+      }
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/** Build the 5 most recent failure lessons as an avoid-list. */
+export function loadFailurePatterns(): string {
+  try {
+    const entries = readFailures(paths.failures(), 5);
+    if (entries.length === 0) return "";
+
+    const lines = entries.map((e) => {
+      const label = e.rating ? `[${e.rating}/10]` : "";
+      const text = e.principle || e.context;
+      return `- ${label} ${text}`.trim();
+    });
+
+    return ["## Lessons from Recent Failures — Apply These Now", ...lines].join("\n");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * All semi-static context sources in load order.
+ * Adding one entry here is the only change needed to extend coverage to all consumers.
+ */
+export function getSemiStaticSources(): SemiStaticSource[] {
+  const memory = paths.memory();
+  const home = palHome();
+  return [
+    {
+      path: resolve(memory, "self-model", "current.md"),
+      writesDigest: false,
+      load: () => readFileSafe(resolve(memory, "self-model", "current.md")),
+      slug: "self-model",
+      description: "PAL self-model",
+    },
+    {
+      path: resolve(memory, "wisdom", "context.md"),
+      writesDigest: true,
+      load: () => {
+        try {
+          const principles = readFramePrinciples();
+          if (principles.length === 0) return "";
+          return ["## Crystallized Principles", ...principles.map((p) => `- ${p}`)].join(
+            "\n"
+          );
+        } catch {
+          return "";
+        }
+      },
+      slug: "wisdom",
+      description: "PAL wisdom",
+    },
+    {
+      path: resolve(memory, "relationship", "opinions-context.md"),
+      writesDigest: true,
+      load: () => {
+        try {
+          return loadOpinionContext();
+        } catch {
+          return "";
+        }
+      },
+      slug: "opinions",
+      description: "PAL opinions",
+    },
+    {
+      path: resolve(memory, "learning", "synthesis-digest.md"),
+      writesDigest: true,
+      load: loadSynthesisRecommendations,
+      slug: "synthesis",
+      description: "PAL pattern synthesis",
+    },
+    {
+      path: resolve(memory, "learning", "failures-digest.md"),
+      writesDigest: true,
+      load: loadFailurePatterns,
+      slug: "failures",
+      description: "PAL recent failure lessons",
+    },
+    {
+      path: resolve(home, "docs", "STEERING_RULES.md"),
+      writesDigest: false,
+      load: () => readFileSafe(resolve(home, "docs", "STEERING_RULES.md")),
+      slug: "steering",
+      description: "PAL steering rules",
+    },
+  ];
+}

package/src/hooks/lib/setup.ts

@@ -36,11 +36,6 @@ export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
       "What are your current goals? (short-term, medium-term, long-term) (~/.pal/telos/GOALS.md)",
     hint: "e.g. Ship v2 by Q3, learn Rust, get promoted to staff engineer",
   },
-  projects: {
-    file: "telos/PROJECTS.md",
-    question: "What projects are you currently working on? (~/.pal/telos/PROJECTS.md)",
-    hint: "e.g. PAL (active, high priority), personal blog (paused), side SaaS (early stage)",
-  },
   beliefs: {
     file: "telos/BELIEFS.md",
     question: "What principles or values guide your work? (~/.pal/telos/BELIEFS.md)",

package/src/hooks/lib/stop.ts

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { autoGraduate } from "../handlers/auto-graduate";
 import { autoBackup } from "../handlers/backup";
+import { writeContextDigests } from "../handlers/context-digests";
 import { notifyDesktop } from "../handlers/desktop-notify";
 import { captureFailure } from "../handlers/failure";
 import { projectTouch } from "../handlers/project-touch";
@@ -56,6 +57,7 @@ export async function runStopHandlers(
     autoGraduate(),
     projectTouch(options.lastAssistantMessage),
     notifyDesktop(options.sessionId),
+    Promise.resolve(writeContextDigests()),
   ]);
 
   const handlerNames = [
@@ -71,6 +73,7 @@ export async function runStopHandlers(
     "auto-graduate",
     "project-touch",
     "desktop-notify",
+    "context-digests",
   ];
   for (let i = 0; i < results.length; i++) {
     const r = results[i];

package/src/targets/claude/uninstall.ts

@@ -57,7 +57,7 @@ if (removedAgents.length > 0) {
 // --- Remove PAL system docs ---
 removePalDocs();
 
-// --- Remove AGENTS.md and CLAUDE.md symlink ---
+// --- Remove AGENTS.md and CLAUDE.md ---
 const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
 const claudeMd = resolve(CLAUDE_DIR, "CLAUDE.md");
 try {

package/src/targets/copilot/install.ts

@@ -1,11 +1,13 @@
 /**
  * PAL — Copilot target installer
  * Writes hooks to ~/.copilot/hooks/pal-hooks.json.
- * Copies skills and agents. Symlinks copilot-instructions.md to AGENTS.md.
+ * Copies skills and agents. Writes ~/.copilot/instructions/pal-*.instructions.md.
+ * Enables ~/.copilot/instructions in VS Code chat.instructionsFilesLocations.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { writeContextDigests } from "../../hooks/handlers/context-digests";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -16,7 +18,10 @@ import {
   generateSkillIndex,
   loadCopilotHooksTemplate,
   log,
+  readJson,
   scaffoldPalSettings,
+  vscodeSettingsFile,
+  writeJson,
 } from "../lib";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
@@ -50,16 +55,42 @@ log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
 // --- Scaffold PAL settings ---
 scaffoldPalSettings();
 
-// --- Generate AGENTS.md + copilot-instructions.md symlink ---
-// ensureSymlinks() inside regenerateIfNeeded() handles the symlink once ~/.copilot/ exists
+// --- Generate AGENTS.md ---
 regenerateIfNeeded();
-const instructionsPath = resolve(COPILOT_DIR, "copilot-instructions.md");
+log.success("Generated AGENTS.md");
+
+// --- Write ~/.copilot/instructions/pal-*.instructions.md ---
+mkdirSync(resolve(COPILOT_DIR, "instructions"), { recursive: true });
+writeContextDigests();
 log.success(
-  existsSync(instructionsPath)
-    ? "copilot-instructions.md symlink present"
-    : "Generated AGENTS.md (copilot-instructions.md symlink will be created on next session)"
+  "Written ~/.copilot/instructions/pal-self-model + pal-wisdom + pal-opinions.instructions.md"
 );
 
+// --- Enable ~/.copilot/instructions in VS Code settings ---
+const vsSettingsPath = vscodeSettingsFile();
+const manualHint =
+  'Add manually: { "chat.instructionsFilesLocations": { "~/.copilot/instructions": true } }';
+if (vsSettingsPath) {
+  try {
+    const settings = readJson<Record<string, unknown>>(vsSettingsPath, {});
+    const existing =
+      typeof settings["chat.instructionsFilesLocations"] === "object" &&
+      settings["chat.instructionsFilesLocations"] !== null
+        ? (settings["chat.instructionsFilesLocations"] as Record<string, unknown>)
+        : {};
+    settings["chat.instructionsFilesLocations"] = {
+      ...existing,
+      "~/.copilot/instructions": true,
+    };
+    writeJson(vsSettingsPath, settings);
+    log.success("Enabled ~/.copilot/instructions in VS Code settings");
+  } catch {
+    log.warn(`Could not update VS Code settings — ${manualHint}`);
+  }
+} else {
+  log.warn(`Could not detect VS Code settings path — ${manualHint}`);
+}
+
 log.success("Copilot installation complete");
 console.log("");
 log.info(`Skills: ${countSkills()}`);

package/src/targets/copilot/uninstall.ts

@@ -1,12 +1,22 @@
 /**
  * PAL — Copilot uninstaller
- * Removes pal-hooks.json, skill symlinks, agents, and copilot-instructions.md symlink.
+ * Removes pal-hooks.json, skill symlinks, agents, instruction files,
+ * and the VS Code chat.instructionsFilesLocations entry.
  */
 
 import { copyFileSync, existsSync, lstatSync, readlinkSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { platform } from "../../hooks/lib/paths";
-import { log, removeAgentsFromCopilot, removePalDocs, removeSkills } from "../lib";
+import { copilotFilename, getSemiStaticSources } from "../../hooks/lib/semi-static";
+import {
+  log,
+  readJson,
+  removeAgentsFromCopilot,
+  removePalDocs,
+  removeSkills,
+  vscodeSettingsFile,
+  writeJson,
+} from "../lib";
 
 const COPILOT_DIR = platform.copilotDir();
 const HOOKS_FILE = resolve(COPILOT_DIR, "hooks", "pal-hooks.json");
@@ -35,26 +45,57 @@ if (removedAgents.length > 0) {
   log.success(`Removed ${removedAgents.length} agent(s): ${removedAgents.join(", ")}`);
 }
 
-// --- Remove copilot-instructions.md symlink (only if it points to AGENTS.md) ---
-const instructionsPath = resolve(COPILOT_DIR, "copilot-instructions.md");
-if (existsSync(instructionsPath)) {
+// --- Remove PAL docs ---
+removePalDocs();
+
+// --- Remove ~/.copilot/instructions/pal-*.instructions.md ---
+for (const src of getSemiStaticSources()) {
+  try {
+    unlinkSync(resolve(COPILOT_DIR, "instructions", copilotFilename(src)));
+  } catch {
+    /* gone */
+  }
+}
+// pal-session.instructions.md is written by LoadContext (not a semi-static source)
+try {
+  unlinkSync(resolve(COPILOT_DIR, "instructions", "pal-session.instructions.md"));
+} catch {
+  /* gone */
+}
+log.success("Removed ~/.copilot/instructions/pal-*.instructions.md");
+
+// --- Backward compat: remove old copilot-instructions.md symlink if present ---
+const legacyPath = resolve(COPILOT_DIR, "copilot-instructions.md");
+if (existsSync(legacyPath)) {
   try {
-    const stat = lstatSync(instructionsPath);
-    if (stat.isSymbolicLink()) {
-      const target = readlinkSync(instructionsPath);
-      if (target.includes("AGENTS.md")) {
-        unlinkSync(instructionsPath);
-        log.success("Removed copilot-instructions.md symlink");
-      } else {
-        log.info("copilot-instructions.md is not a PAL symlink — leaving it");
-      }
+    if (
+      lstatSync(legacyPath).isSymbolicLink() &&
+      readlinkSync(legacyPath).includes("AGENTS.md")
+    ) {
+      unlinkSync(legacyPath);
+      log.success("Removed legacy copilot-instructions.md symlink");
     }
   } catch {
-    // ignore
+    /* ignore */
   }
 }
 
-// --- Remove PAL docs ---
-removePalDocs();
+// --- Remove ~/.copilot/instructions entry from VS Code settings ---
+const vsSettingsPath = vscodeSettingsFile();
+if (vsSettingsPath && existsSync(vsSettingsPath)) {
+  const settings = readJson<Record<string, unknown>>(vsSettingsPath, {});
+  const locs = settings["chat.instructionsFilesLocations"];
+  if (typeof locs === "object" && locs !== null) {
+    const obj = locs as Record<string, unknown>;
+    delete obj["~/.copilot/instructions"];
+    if (Object.keys(obj).length === 0) {
+      delete settings["chat.instructionsFilesLocations"];
+    } else {
+      settings["chat.instructionsFilesLocations"] = obj;
+    }
+    writeJson(vsSettingsPath, settings);
+    log.success("Removed ~/.copilot/instructions from VS Code settings");
+  }
+}
 
 log.success("Copilot uninstall complete");

package/src/targets/cursor/install.ts

@@ -6,6 +6,7 @@
 
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
+import { writeContextDigests } from "../../hooks/handlers/context-digests";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -64,6 +65,13 @@ scaffoldPalSettings();
 regenerateIfNeeded();
 log.success("Generated AGENTS.md");
 
+// --- Write ~/.cursor/rules/pal-*.mdc ---
+mkdirSync(resolve(CURSOR_DIR, "rules"), { recursive: true });
+writeContextDigests();
+log.success(
+  "Written ~/.cursor/rules/pal-self-model.mdc + pal-wisdom.mdc + pal-opinions.mdc"
+);
+
 log.success("Cursor installation complete");
 console.log("");
 log.info(`Skills: ${countSkills()}`);

package/src/targets/cursor/uninstall.ts

@@ -4,9 +4,10 @@
  * Removes PAL skill symlinks.
  */
 
-import { copyFileSync, existsSync } from "node:fs";
+import { copyFileSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import { cursorFilename, getSemiStaticSources } from "../../hooks/lib/semi-static";
 import {
   loadCursorHooksTemplate,
   log,
@@ -56,4 +57,20 @@ if (removedAgents.length > 0) {
 // --- Remove PAL system docs ---
 removePalDocs();
 
+// --- Remove ~/.cursor/rules/pal-*.mdc ---
+for (const src of getSemiStaticSources()) {
+  try {
+    unlinkSync(resolve(CURSOR_DIR, "rules", cursorFilename(src)));
+  } catch {
+    /* gone */
+  }
+}
+// Backward compat: remove legacy merged file if present
+try {
+  unlinkSync(resolve(CURSOR_DIR, "rules", "pal-context.mdc"));
+} catch {
+  /* gone */
+}
+log.success("Removed ~/.cursor/rules/pal-*.mdc");
+
 log.success("Cursor uninstall complete");

package/src/targets/lib.ts

@@ -14,6 +14,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { assets, palHome, platform } from "../hooks/lib/paths";
 
@@ -41,6 +42,31 @@ export function writeJson(path: string, data: unknown): void {
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 }
 
+/** Resolve the VS Code user settings.json path cross-platform. Returns null on unknown platforms. */
+export function vscodeSettingsFile(): string | null {
+  const h = homedir();
+  if (process.platform === "darwin") {
+    return resolve(h, "Library", "Application Support", "Code", "User", "settings.json");
+  }
+  if (process.platform === "linux") {
+    return resolve(
+      process.env.XDG_CONFIG_HOME ?? resolve(h, ".config"),
+      "Code",
+      "User",
+      "settings.json"
+    );
+  }
+  if (process.platform === "win32") {
+    return resolve(
+      process.env.APPDATA ?? resolve(h, "AppData", "Roaming"),
+      "Code",
+      "User",
+      "settings.json"
+    );
+  }
+  return null;
+}
+
 // --- Settings template merge/unmerge ---
 
 type HookEntry = { matcher?: string; hooks?: Array<{ type: string; command: string }> };

package/src/targets/opencode/install.ts

@@ -3,10 +3,18 @@
  * Deploys plugin, installs skills, generates AGENTS.md.
  */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { palPkg, platform } from "../../hooks/lib/paths";
+import { getSemiStaticSources } from "../../hooks/lib/semi-static";
 import {
   copyAgentsForOpencode,
   copyPalDocs,
@@ -70,6 +78,26 @@ log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md");
 
+// --- 7. Add semi-static digest files to instructions[] in config.json ---
+const configPath = resolve(OC_GLOBAL_DIR, "config.json");
+const staticFiles = getSemiStaticSources().map((s) => s.path);
+let ocConfig: Record<string, unknown> = {};
+if (existsSync(configPath) && statSync(configPath).size > 0) {
+  try {
+    ocConfig = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    /* start fresh */
+  }
+}
+const existingInstructions = Array.isArray(ocConfig.instructions)
+  ? (ocConfig.instructions as string[])
+  : [];
+ocConfig.instructions = [...new Set([...existingInstructions, ...staticFiles])];
+writeFileSync(configPath, `${JSON.stringify(ocConfig, null, 2)}\n`, "utf-8");
+log.success(
+  `Updated config.json: ${(ocConfig.instructions as string[]).length} instructions`
+);
+
 log.success("opencode installation complete");
 console.log("");
 log.info(`Plugin: ${pluginDst}`);

package/src/targets/opencode/plugin.ts

@@ -74,7 +74,7 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
   return {
     // --- Per-message: Inject dynamic system reminder ---
     "experimental.chat.system.transform": async (_input, output) => {
-      const reminder = buildSystemReminder();
+      const reminder = buildSystemReminder({ agent: "opencode" });
       if (reminder) output.system.push(reminder);
     },
 

package/src/targets/opencode/uninstall.ts

@@ -1,11 +1,12 @@
 /**
  * PAL — opencode uninstaller (TypeScript)
- * Removes plugin and AGENTS.md.
+ * Removes plugin, AGENTS.md, and PAL entries from config.json.
  */
 
-import { unlinkSync } from "node:fs";
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { platform } from "../../hooks/lib/paths";
+import { getSemiStaticSources } from "../../hooks/lib/semi-static";
 import { log, removeAgentsFromOpencode, removePalDocs, removeSkills } from "../lib";
 
 const OC_GLOBAL_DIR = platform.opencodeDir() || "";
@@ -41,7 +42,7 @@ if (removedAgents.length > 0)
 // --- Remove PAL system docs ---
 removePalDocs();
 
-// --- Remove AGENTS.md and CLAUDE.md symlink ---
+// --- Remove AGENTS.md and CLAUDE.md ---
 const agentsMd = resolve(OC_GLOBAL_DIR, "AGENTS.md");
 const claudeMd = resolve(PAL_CLAUDE_DIR, "CLAUDE.md");
 try {
@@ -57,4 +58,30 @@ try {
   /* gone */
 }
 
+// --- Remove PAL entries from config.json instructions[] ---
+const configPath = resolve(OC_GLOBAL_DIR, "config.json");
+if (existsSync(configPath) && statSync(configPath).size > 0) {
+  try {
+    const ocConfig = JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+    if (Array.isArray(ocConfig.instructions)) {
+      const palFiles = new Set(getSemiStaticSources().map((s) => s.path));
+      const filtered = (ocConfig.instructions as string[]).filter(
+        (p) => !palFiles.has(p)
+      );
+      if (filtered.length === 0) {
+        delete ocConfig.instructions;
+      } else {
+        ocConfig.instructions = filtered;
+      }
+      writeFileSync(configPath, `${JSON.stringify(ocConfig, null, 2)}\n`, "utf-8");
+      log.success("Removed PAL entries from config.json instructions[]");
+    }
+  } catch {
+    log.warn("Could not clean config.json instructions[] — check manually");
+  }
+}
+
 log.success("opencode uninstall complete");