portable-agent-layer 0.47.0 → 0.49.0

package/src/hooks/lib/context.ts

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { readLearnings } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { paths } from "./paths";
@@ -312,9 +313,12 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
     ? loadSessionIntelligence()
     : "";
   const handoff = settings.isEnabled("handoff") ? loadHandoff() : "";
+  // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
+  const algoReview = loadAlgorithmReviewNudge();
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
+  if (algoReview) parts.push(algoReview);
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);

package/src/hooks/lib/learning-store.ts

@@ -158,3 +158,48 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
   return entries;
 }
+
+// ── Reflections ──
+
+export interface ReflectionEntry {
+  ts: string;
+  cwd: string;
+  task: string;
+  sentiment: number;
+  q1: string;
+  q2: string;
+  q3: string;
+  /** Whether the improvement ideas generalize to the algorithm, or are task-bound. */
+  scope: "general" | "task-specific";
+}
+
+/**
+ * Read algorithm reflections from the JSONL store, newest first. Each line is one
+ * reflection produced at the end of an Algorithm run (q1 = what I'd do differently,
+ * q2 = algorithm improvement, q3 = AI-level insight).
+ */
+export function readReflections(file: string, limit?: number): ReflectionEntry[] {
+  if (!existsSync(file)) return [];
+  const entries: ReflectionEntry[] = [];
+  for (const line of readFileSync(file, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      entries.push({
+        ts: o.timestamp || "",
+        cwd: o.cwd || "",
+        task: o.task || "",
+        sentiment: typeof o.sentiment === "number" ? o.sentiment : 0,
+        q1: o.q1 || "",
+        q2: o.q2 || "",
+        q3: o.q3 || "",
+        // Untagged (e.g. the existing backlog) defaults to general — the common case.
+        scope: o.scope === "task-specific" ? "task-specific" : "general",
+      });
+    } catch {
+      /* skip malformed line */
+    }
+  }
+  entries.reverse(); // JSONL is appended chronologically → newest first
+  return limit ? entries.slice(0, limit) : entries;
+}

package/src/hooks/lib/paths.ts

@@ -50,6 +50,9 @@ export const paths = {
   knowledge: () => ensureDir(home("memory", "knowledge")),
   knowledgeDomain: (d: string) => ensureDir(home("memory", "knowledge", d)),
   failures: () => ensureDir(home("memory", "learning", "failures")),
+  reflections: () => ensureDir(home("memory", "learning", "reflections")),
+  reflectionsFile: () =>
+    home("memory", "learning", "reflections", "algorithm-reflections.jsonl"),
   retrievalIndex: () => home("memory", "learning", ".retrieval-index.json"),
   progress: () => ensureDir(home("memory", "state", "progress")),
   projectHistory: () => ensureDir(home("memory", "projects")),
@@ -82,6 +85,8 @@ export const assets = {
   copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
   codexHooksTemplate: () => pkg("assets", "templates", "hooks.codex.json"),
   codexRulesTemplate: () => pkg("assets", "templates", "rules.codex.rules"),
+  statuslineScriptBash: () => pkg("assets", "statusline.sh"),
+  statuslineScriptPs1: () => pkg("assets", "statusline.ps1"),
   agentTools: () => pkg("src", "tools", "agent"),
   tools: () => pkg("src", "tools"),
   palDocs: () => pkg("assets", "templates", "PAL"),

package/src/hooks/lib/retrieval-index.ts

@@ -1,6 +1,6 @@
 /**
  * Retrieval index — single JSON file with per-doc term-frequency vectors and a global
- * document-frequency table over the failures + wisdom-frames corpus.
+ * document-frequency table over the failures + wisdom-frames + reflections corpus.
  *
  * Built once on first read, rebuilt in the background when source dirs change.
  * Read by the UserPromptSubmit retrieval handler; written by ensureIndex (sync bootstrap)
@@ -11,17 +11,18 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { SIMILARITY_THRESHOLD } from "./graduation";
-import { readFailures } from "./learning-store";
+import { readFailures, readReflections } from "./learning-store";
 import { logDebug, logError } from "./log";
 import { palPkg, paths } from "./paths";
 import { similarity, tokenize } from "./text-similarity";
 import { readFramesForRetrieval } from "./wisdom";
 
-const INDEX_VERSION = 1;
+// v2: added "reflection" source — bump invalidates v1 caches so they rebuild with it.
+const INDEX_VERSION = 2;
 
 export interface IndexedDoc {
   id: string;
-  source: "failure" | "wisdom";
+  source: "failure" | "wisdom" | "reflection";
   path: string;
   rating: number;
   ts: string;
@@ -144,6 +145,32 @@ export function buildIndex(): RetrievalIndex {
     });
   }
 
+  // Reflections — each Algorithm run's self-observations. q1 ("what I'd do
+  // differently") is the actionable lesson; q2/q3 add process and reasoning signal.
+  for (const r of readReflections(paths.reflectionsFile())) {
+    const tokens = buildDocTokens([
+      { text: r.q1, weight: 3 },
+      { text: r.task, weight: 2 },
+      { text: r.q2, weight: 2 },
+      { text: r.q3, weight: 1 },
+    ]);
+    if (tokens.length === 0) continue;
+    const { tf, len } = buildTermFreq(tokens);
+    for (const term of Object.keys(tf)) df[term] = (df[term] ?? 0) + 1;
+    docs.push({
+      id: `reflect:${r.ts}`,
+      source: "reflection",
+      path: paths.reflectionsFile(),
+      rating: r.sentiment,
+      ts: r.ts,
+      tf,
+      len,
+      displayPrinciple: r.q1,
+      displayContext: r.task,
+      cwd: r.cwd || undefined,
+    });
+  }
+
   return {
     version: INDEX_VERSION,
     builtAt: new Date().toISOString(),
@@ -173,7 +200,7 @@ export function readIndex(): RetrievalIndex | null {
 export function isStale(index: RetrievalIndex): boolean {
   try {
     const builtMs = new Date(index.builtAt).getTime();
-    for (const dir of [paths.failures(), paths.wisdom()]) {
+    for (const dir of [paths.failures(), paths.wisdom(), paths.reflections()]) {
       if (!existsSync(dir)) continue;
       if (statSync(dir).mtimeMs > builtMs) return true;
     }

package/src/hooks/lib/retrieval.ts

@@ -131,7 +131,8 @@ function formatLine(s: ScoredDoc): string {
     return `- ${tag} ${principle} (CRYSTAL ${s.doc.rating}%)`;
   }
   const ago = formatAgo(s.doc.ts);
-  const meta = ago ? `rating ${s.doc.rating}/10, ${ago}` : `rating ${s.doc.rating}/10`;
+  const kind = s.doc.source === "reflection" ? "reflection" : "rating";
+  const meta = ago ? `${kind} ${s.doc.rating}/10, ${ago}` : `${kind} ${s.doc.rating}/10`;
   return `- ${tag} ${principle} (${meta})`;
 }
 

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

@@ -9,7 +9,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parse } from "./frontmatter";
-import { readFailures } from "./learning-store";
+import { type FailureEntry, readFailures } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { palHome, paths } from "./paths";
 import { readFramePrinciples } from "./wisdom";
@@ -100,16 +100,39 @@ export function loadSynthesisRecommendations(): string {
   }
 }
 
-/** Build the 5 most recent failure lessons as an avoid-list. */
+/**
+ * Rank failures for injection: same-project (cwd match) first, then by recency.
+ * Project-relevant lessons are never crowded out by more-recent other-project
+ * ones — fixing the case where (e.g.) a web-app's cache lessons dominate a CLI
+ * session purely because they were logged last. Returns the top `limit`.
+ */
+export function rankFailures(
+  entries: FailureEntry[],
+  cwd: string,
+  limit = 5
+): FailureEntry[] {
+  return [...entries]
+    .sort((a, b) => {
+      const am = a.cwd === cwd;
+      const bm = b.cwd === cwd;
+      if (am !== bm) return am ? -1 : 1;
+      return (b.ts || "").localeCompare(a.ts || ""); // recency desc within a group
+    })
+    .slice(0, limit);
+}
+
+/** Build the failure avoid-list, prioritized by relevance to the current project. */
 export function loadFailurePatterns(): string {
   try {
-    const entries = readFailures(paths.failures(), 5);
-    if (entries.length === 0) return "";
+    const cwd = process.cwd();
+    const all = readFailures(paths.failures());
+    if (all.length === 0) return "";
 
-    const lines = entries.map((e) => {
+    const lines = rankFailures(all, cwd).map((e) => {
       const label = e.rating ? `[${e.rating}/10]` : "";
+      const tag = e.cwd === cwd ? "[project]" : "[other]";
       const text = e.principle || e.context;
-      return `- ${label} ${text}`.trim();
+      return `- ${label} ${tag} ${text}`.trim();
     });
 
     return ["## Lessons from Recent Failures — Apply These Now", ...lines].join("\n");

package/src/targets/claude/install.ts

@@ -9,9 +9,11 @@ import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
 import {
+  addStatuslineConfig,
   copyAgents,
   copyPalDocs,
   copySkills,
+  copyStatusline,
   countAgents,
   countMd,
   countSkills,
@@ -43,7 +45,10 @@ log.info("Backed up settings.json");
 // --- Load template and merge into existing settings ---
 const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
 const existing = readJson<Record<string, unknown>>(SETTINGS, {});
-const merged = mergeSettings(existing, template);
+let merged = mergeSettings(existing, template);
+
+// Add platform-specific statusLine config
+merged = addStatuslineConfig(merged);
 
 writeJson(SETTINGS, merged);
 log.success("Merged PAL settings into settings.json");
@@ -56,6 +61,9 @@ generateSkillIndex();
 // --- Copy agents ---
 copyAgents();
 
+// --- Copy statusline script ---
+copyStatusline();
+
 // --- Copy PAL system docs ---
 const palDocsCount = copyPalDocs();
 log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);

package/src/targets/claude/uninstall.ts

@@ -13,6 +13,8 @@ import {
   removeAgents,
   removePalDocs,
   removeSkills,
+  removeStatusline,
+  removeStatuslineConfig,
   unmergeSettings,
   writeJson,
 } from "../lib";
@@ -33,7 +35,10 @@ log.info("Backed up settings.json");
 // --- Load template and unmerge from existing settings ---
 const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
 const existing = readJson<Record<string, unknown>>(SETTINGS, {});
-const cleaned = unmergeSettings(existing, template);
+let cleaned = unmergeSettings(existing, template);
+
+// Remove statusLine config
+cleaned = removeStatuslineConfig(cleaned);
 
 writeJson(SETTINGS, cleaned);
 log.success("Removed PAL settings from settings.json");
@@ -54,6 +59,9 @@ if (removedAgents.length > 0) {
   log.info("No PAL agents found");
 }
 
+// --- Remove statusline script ---
+removeStatusline();
+
 // --- Remove PAL system docs ---
 removePalDocs();
 

package/src/targets/lib.ts

@@ -3,6 +3,7 @@
  */
 
 import {
+  chmodSync,
   copyFileSync,
   existsSync,
   lstatSync,
@@ -123,6 +124,65 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
     }
   }
 
+  // Merge skillOverrides (object with skill name keys, add if not present)
+  if (template.skillOverrides && typeof template.skillOverrides === "object") {
+    result.skillOverrides ??= {};
+    const resultOverrides = result.skillOverrides as Record<string, unknown>;
+    for (const [skill, value] of Object.entries(template.skillOverrides)) {
+      if (!(skill in resultOverrides)) {
+        resultOverrides[skill] = value;
+      }
+    }
+  }
+
+  // Merge attribution (object with commit/pr keys, add if not present)
+  if (template.attribution && typeof template.attribution === "object") {
+    if (!("attribution" in result)) {
+      result.attribution = template.attribution;
+    }
+  }
+
+  // Merge showClearContextOnPlanAccept (boolean, add if not present)
+  if ("showClearContextOnPlanAccept" in template) {
+    if (!("showClearContextOnPlanAccept" in result)) {
+      result.showClearContextOnPlanAccept = template.showClearContextOnPlanAccept;
+    }
+  }
+
+  // Merge respectGitignore (boolean, add if not present)
+  if ("respectGitignore" in template) {
+    if (!("respectGitignore" in result)) {
+      result.respectGitignore = template.respectGitignore;
+    }
+  }
+
+  // Merge spinnerTipsEnabled (boolean, add if not present)
+  if ("spinnerTipsEnabled" in template) {
+    if (!("spinnerTipsEnabled" in result)) {
+      result.spinnerTipsEnabled = template.spinnerTipsEnabled;
+    }
+  }
+
+  // Merge spinnerTipsOverride (merge tips array, deduplicate by content)
+  if (
+    template.spinnerTipsOverride &&
+    typeof template.spinnerTipsOverride === "object" &&
+    "tips" in template.spinnerTipsOverride &&
+    Array.isArray((template.spinnerTipsOverride as Record<string, unknown>).tips)
+  ) {
+    result.spinnerTipsOverride ??= { tips: [] };
+    const resultOverride = result.spinnerTipsOverride as Record<string, unknown>;
+    resultOverride.tips ??= [];
+    const tips = resultOverride.tips as string[];
+    const templateTips = (template.spinnerTipsOverride as Record<string, unknown>)
+      .tips as string[];
+    for (const tip of templateTips) {
+      if (typeof tip === "string" && !tips.includes(tip)) {
+        tips.push(tip);
+      }
+    }
+  }
+
   return result;
 }
 
@@ -163,6 +223,68 @@ export function unmergeSettings(existing: Settings, template: Settings): Setting
     if (Object.keys(result.permissions).length === 0) delete result.permissions;
   }
 
+  // Remove PAL skillOverrides (remove keys that appear in template)
+  if (
+    template.skillOverrides &&
+    typeof template.skillOverrides === "object" &&
+    result.skillOverrides &&
+    typeof result.skillOverrides === "object"
+  ) {
+    const palSkills = new Set(Object.keys(template.skillOverrides));
+    for (const skill of palSkills) {
+      delete (result.skillOverrides as Record<string, unknown>)[skill];
+    }
+    if (Object.keys(result.skillOverrides).length === 0) delete result.skillOverrides;
+  }
+
+  // Remove PAL attribution if it matches template structure
+  if (template.attribution && "attribution" in result) {
+    delete result.attribution;
+  }
+
+  // Remove PAL showClearContextOnPlanAccept
+  if (
+    "showClearContextOnPlanAccept" in template &&
+    "showClearContextOnPlanAccept" in result
+  ) {
+    delete result.showClearContextOnPlanAccept;
+  }
+
+  // Remove PAL respectGitignore
+  if ("respectGitignore" in template && "respectGitignore" in result) {
+    delete result.respectGitignore;
+  }
+
+  // Remove PAL spinnerTipsEnabled
+  if ("spinnerTipsEnabled" in template && "spinnerTipsEnabled" in result) {
+    delete result.spinnerTipsEnabled;
+  }
+
+  // Remove PAL spinnerTipsOverride (remove only template tips, preserve user tips)
+  if (
+    template.spinnerTipsOverride &&
+    typeof template.spinnerTipsOverride === "object" &&
+    "tips" in template.spinnerTipsOverride &&
+    Array.isArray((template.spinnerTipsOverride as Record<string, unknown>).tips) &&
+    result.spinnerTipsOverride &&
+    typeof result.spinnerTipsOverride === "object" &&
+    "tips" in result.spinnerTipsOverride &&
+    Array.isArray((result.spinnerTipsOverride as Record<string, unknown>).tips)
+  ) {
+    const templateTipsArray = (template.spinnerTipsOverride as Record<string, unknown>)
+      .tips as string[];
+    const templateTips = new Set(templateTipsArray);
+    const resultOverride = result.spinnerTipsOverride as Record<string, unknown>;
+    const tips = resultOverride.tips as string[];
+    resultOverride.tips = tips.filter((tip) => !templateTips.has(tip));
+    if (
+      (resultOverride.tips as string[]).length === 0 &&
+      Object.keys(resultOverride).length === 1
+    ) {
+      delete result.spinnerTipsOverride;
+    }
+  }
+
   return result;
 }
 
@@ -768,6 +890,100 @@ export function loadCopilotHooksTemplate(templatePath: string, pkgRoot: string):
   }
 }
 
+// --- Statusline ---
+
+/** Copy statusline script to ~/.claude/ for the current platform */
+export function copyStatusline(): boolean {
+  const claudeDir = platform.claudeDir();
+  mkdirSync(claudeDir, { recursive: true });
+
+  const isPlatformWin32 = process.platform === "win32";
+  const sourcePath = isPlatformWin32
+    ? assets.statuslineScriptPs1()
+    : assets.statuslineScriptBash();
+  const scriptName = isPlatformWin32 ? "statusline.ps1" : "statusline.sh";
+  const destPath = resolve(claudeDir, scriptName);
+
+  if (!existsSync(sourcePath)) {
+    log.warn(`Statusline script not found at ${sourcePath}`);
+    return false;
+  }
+
+  try {
+    copyFileSync(sourcePath, destPath);
+
+    // Make executable on Unix
+    if (process.platform !== "win32") {
+      chmodSync(destPath, 0o755);
+    }
+
+    log.success(`Statusline installed to ${destPath}`);
+    return true;
+  } catch (e) {
+    log.warn(`Failed to copy statusline script: ${e}`);
+    return false;
+  }
+}
+
+/** Remove statusline script from ~/.claude/ */
+export function removeStatusline(): boolean {
+  const claudeDir = platform.claudeDir();
+  const isPlatformWin32 = process.platform === "win32";
+  const scriptName = isPlatformWin32 ? "statusline.ps1" : "statusline.sh";
+  const scriptPath = resolve(claudeDir, scriptName);
+
+  if (!existsSync(scriptPath)) {
+    log.info("Statusline script not found, nothing to remove");
+    return true;
+  }
+
+  try {
+    unlinkSync(scriptPath);
+    log.success(`Removed statusline script from ${scriptPath}`);
+    return true;
+  } catch (e) {
+    log.warn(`Failed to remove statusline script: ${e}`);
+    return false;
+  }
+}
+
+/** Add statusLine config to settings if not already present or if using old broken command */
+export function addStatuslineConfig(
+  settings: Record<string, unknown>
+): Record<string, unknown> {
+  const statusLine = settings.statusLine as Record<string, unknown> | undefined;
+
+  // Check if already configured with a valid command (not the old broken one)
+  if (statusLine && typeof statusLine === "object" && statusLine.command) {
+    const cmd = statusLine.command as string;
+    // Keep existing config unless it's the old broken Get-Content pattern
+    if (!cmd.includes("Get-Content -Raw")) {
+      return settings;
+    }
+  }
+
+  const isPlatformWin32 = process.platform === "win32";
+  const command = isPlatformWin32
+    ? "powershell -NoProfile -File ~/.claude/statusline.ps1"
+    : "~/.claude/statusline.sh";
+
+  settings.statusLine = {
+    type: "command",
+    command,
+    padding: 2,
+  };
+
+  return settings;
+}
+
+/** Remove statusLine config from settings */
+export function removeStatuslineConfig(
+  settings: Record<string, unknown>
+): Record<string, unknown> {
+  delete settings.statusLine;
+  return settings;
+}
+
 // --- Skill Index ---
 
 interface SkillIndexEntry {

package/src/tools/agent/algorithm-reflect.ts

@@ -12,8 +12,7 @@
  *     --q3 "Missed the implicit constraint about cross-platform"
  */
 
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
 
@@ -30,14 +29,15 @@ interface AlgorithmReflection {
   q1: string;
   q2: string;
   q3: string;
+  /** general = the improvement ideas generalize to the algorithm; task-specific = bound to this task. */
+  scope: "general" | "task-specific";
 }
 
 // ── Core ──
 
 function reflectionsPath(): string {
-  const dir = resolve(paths.learning(), "reflections");
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  return resolve(dir, "algorithm-reflections.jsonl");
+  paths.reflections(); // ensures the directory exists
+  return paths.reflectionsFile();
 }
 
 function appendReflection(reflection: AlgorithmReflection): {
@@ -70,6 +70,7 @@ function run() {
       q1: { type: "string" },
       q2: { type: "string" },
       q3: { type: "string" },
+      scope: { type: "string" },
       help: { type: "boolean", short: "h" },
     },
   });
@@ -91,6 +92,7 @@ Arguments:
   --q1          Q1 — Self: what I'd do differently
   --q2          Q2 — Algorithm: structural improvement
   --q3          Q3 — AI: reasoning blind spot
+  --scope       general (default) | task-specific — is the algorithm idea reusable or task-bound?
 
 Output: algorithm-reflections.jsonl in memory/learning/reflections/
 `);
@@ -113,6 +115,9 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
     q1: values.q1,
     q2: values.q2,
     q3: values.q3,
+    // Default to general (the ~94% case); only "task-specific" suppresses it
+    // from algorithm-update clustering.
+    scope: values.scope === "task-specific" ? "task-specific" : "general",
   };
 
   const result = appendReflection(reflection);