portable-agent-layer 0.9.0 → 0.10.0

package/assets/templates/AGENTS.md.template

@@ -43,3 +43,9 @@ Do not create projects for one-off questions or quick fixes.
 - When a session produces reusable insights → session learning
 - When something fails significantly (rating < 6) → failure capture
 - Do NOT write memories about trivial exchanges or things already captured in TELOS.
+
+## Opinion Tracking
+
+PAL tracks confidence-scored opinions about the user. When you notice the user confirming or contradicting a behavioral pattern, update it via `bun run tool:opinion`. Run `bun run tool:opinion -- --help` for full usage and examples. Opinions at ≥85% confidence are automatically injected into every session context.
+
+{{STEERING_RULES}}

package/assets/templates/STEERING-RULES.md

@@ -0,0 +1,23 @@
+## Steering Rules
+
+Behavioral directives — act on these, don't just know them.
+
+**Surgical fixes only.** When debugging, make precise corrections to the broken behavior. Never delete or rearchitect components as a fix. If you believe a component is the root cause, explain your reasoning and ask before removing it.
+
+**Never assert without verification.** Don't say something "is" a certain way unless you've verified it with your tools. After making changes, verify the result before claiming success. Evidence required — tests, diffs, tool output. Never "Done!" without proof.
+
+**First principles over bolt-ons.** Most problems are symptoms. Understand → Simplify → Reduce → Add (last resort). Don't accrue technical debt through band-aid solutions.
+
+**Read before modifying.** Understand existing code, imports, and patterns before suggesting changes.
+
+**One change when debugging.** Isolate, verify, proceed. Don't change multiple things at once.
+
+**Minimal scope.** Only change what was asked. No bonus refactoring, no extra cleanup, no unsolicited improvements.
+
+**Ask before destructive actions.** Deletes, force pushes, production deploys — always ask first.
+
+**Plan means stop.** "Create a plan" = present and STOP. No execution without approval.
+
+**Error recovery.** When told you did something wrong — review the session, identify the violation, fix it, then explain what happened and capture the learning. Don't ask "What did I do wrong?"
+
+**Act on what you know.** When tracked opinions or relationship notes reveal user preferences, apply them to your behavior. If you know the user prefers concise responses, be concise. If they prefer manual commits, never offer to commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -49,6 +49,7 @@
     "ai:pdf-download": "bun run src/tools/pdf-download.ts",
     "ai:youtube-analyze": "bun run src/tools/youtube-analyze.ts",
     "tool:analyze": "bun run src/tools/analyze.ts",
+    "tool:opinion": "bun run src/tools/opinion.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
     "tool:export": "bun run src/tools/export.ts",
     "tool:import": "bun run src/tools/import.ts",

package/src/hooks/handlers/rating.ts

@@ -10,12 +10,10 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
-import { categorizeLearning } from "../lib/learning-category";
-import { ensureDir, paths } from "../lib/paths";
+import { paths } from "../lib/paths";
 import { emitRating } from "../lib/signals";
-import { fileTimestamp, monthPath, now } from "../lib/time";
+import { now } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 
 /** Read cached last assistant response (written by StopOrchestrator), looked up by session */
@@ -237,37 +235,6 @@ const MIN_CONFIDENCE = 0.5;
 
 // ── Rating Handling ──
 
-function writeLearningMarkdown(
-  rating: number,
-  source: string,
-  context: string,
-  detailedContext: string,
-  responsePreview: string
-): void {
-  const category = categorizeLearning(context, detailedContext);
-  const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
-  const filename = `${fileTimestamp()}_${source}-rating-${rating}_${category}.md`;
-
-  const meta: Record<string, unknown> = {
-    title: context.slice(0, 100) || "(low rating)",
-    category,
-    date: new Date().toISOString().slice(0, 10),
-    rating,
-    source,
-  };
-
-  const body = [
-    "## Context",
-    context || "*(unavailable)*",
-    "",
-    ...(detailedContext ? ["## Analysis", detailedContext, ""] : []),
-    "## Last Response",
-    responsePreview || "*(unavailable)*",
-  ].join("\n");
-
-  writeFileSync(resolve(dir, filename), stringify(meta, body), "utf-8");
-}
-
 function handleRating(
   rating: number,
   context: string,
@@ -279,8 +246,8 @@ function handleRating(
   const responsePreview = getLastResponse(sessionId).slice(0, 500);
   emitRating(rating, context, source, responsePreview);
 
-  if (rating <= 3) {
-    // Deep failure — write pending file for Stop handler with full transcript
+  if (rating <= 4) {
+    // Low rating — write pending file for Stop handler with full transcript
     const userPreview = userMessage?.slice(0, 400);
     writeFileSync(
       resolve(paths.state(), "pending-failure.json"),
@@ -299,16 +266,6 @@ function handleRating(
       ),
       "utf-8"
     );
-    // No learning markdown for ≤3 — failure capture covers it with richer analysis + tags
-  } else if (rating < 5) {
-    // Low but not critical — write learning markdown
-    writeLearningMarkdown(
-      rating,
-      source,
-      context,
-      detailedContext ?? "",
-      responsePreview
-    );
   }
 }
 

package/src/hooks/handlers/reflect-trigger.ts

@@ -0,0 +1,83 @@
+/**
+ * Auto-trigger for relationship reflect — runs when conditions are met:
+ * - 7+ days since last reflect
+ * - 10+ new relationship notes since last reflect
+ *
+ * Spawns `bun run tool:reflect` as a detached background process.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logDebug } from "../lib/log";
+import { getLastReflectDate } from "../lib/opinions";
+import { palPkg, paths } from "../lib/paths";
+
+const MIN_DAYS_BETWEEN = 7;
+const MIN_NEW_NOTES = 10;
+
+function countNotesSince(since: string): number {
+  const relDir = paths.relationship();
+  if (!existsSync(relDir)) return 0;
+
+  let count = 0;
+  try {
+    for (const monthDir of readdirSync(relDir)) {
+      if (!/^\d{4}-\d{2}$/.test(monthDir)) continue;
+      const monthPath = resolve(relDir, monthDir);
+      try {
+        for (const file of readdirSync(monthPath)) {
+          if (!file.endsWith(".md")) continue;
+          const dateStr = file.replace(".md", "");
+          if (dateStr > since) {
+            const content = readFileSync(resolve(monthPath, file), "utf-8");
+            count += (content.match(/^- [OBW]/gm) || []).length;
+          }
+        }
+      } catch {
+        /* skip */
+      }
+    }
+  } catch {
+    /* non-critical */
+  }
+  return count;
+}
+
+export async function checkReflectTrigger(): Promise<void> {
+  const lastReflect = getLastReflectDate();
+  const now = new Date();
+
+  // Trigger if either condition is met (OR logic)
+  let timeThreshold = !lastReflect;
+  if (lastReflect) {
+    const daysSince =
+      (now.getTime() - new Date(lastReflect).getTime()) / (1000 * 60 * 60 * 24);
+    timeThreshold = daysSince >= MIN_DAYS_BETWEEN;
+  }
+
+  const newNotes = countNotesSince(lastReflect || "2000-01-01");
+  const volumeThreshold = newNotes >= MIN_NEW_NOTES;
+
+  if (!timeThreshold && !volumeThreshold) {
+    logDebug("reflect-trigger", `Skipping: ${newNotes} notes, time threshold not met`);
+    return;
+  }
+
+  logDebug(
+    "reflect-trigger",
+    `Triggering: ${newNotes} new notes, last: ${lastReflect || "never"}`
+  );
+
+  try {
+    const proc = Bun.spawn(["bun", "run", "tool:reflect"], {
+      cwd: palPkg(),
+      stdout: "ignore",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    proc.unref();
+    logDebug("reflect-trigger", "Spawned reflect in background");
+  } catch (err) {
+    logDebug("reflect-trigger", `Failed to spawn: ${err}`);
+  }
+}

package/src/hooks/handlers/relationship.ts

@@ -20,8 +20,9 @@ const OBSERVATION_SCHEMA = {
         properties: {
           type: {
             type: "string",
-            enum: ["O", "W"],
-            description: "O=opinion/preference, W=factual observation",
+            enum: ["O", "W", "B"],
+            description:
+              "O=opinion/preference, W=factual observation, B=belief/behavioral pattern",
           },
           text: { type: "string" },
           confidence: { type: "number" },
@@ -74,8 +75,10 @@ export async function captureRelationship(
   const result = await inference({
     system:
       "You analyze user messages from an AI coding session to extract relationship observations. " +
-      "Focus on: preferences (how they like to work), corrections (what they pushed back on), " +
-      "frustrations, positive reactions, communication style patterns. " +
+      "Types: O=opinions/preferences (how they like to work, what they want), " +
+      "B=beliefs/behavioral patterns (how they approach problems, decision-making style, recurring habits), " +
+      "W=world facts (their situation, projects, tools they use). " +
+      "Focus on: preferences, corrections, frustrations, positive reactions, communication style, problem-solving approach. " +
       "Return 0-3 observations. If nothing notable, return empty observations array. Be concise.",
     user: `User messages from this session:\n${userMessages.map((m, i) => `${i + 1}. ${m}`).join("\n")}`,
     maxTokens: 300,
@@ -93,7 +96,7 @@ export async function captureRelationship(
 
   try {
     const parsed = JSON.parse(result.output) as {
-      observations: Array<{ type: "O" | "W"; text: string; confidence: number }>;
+      observations: Array<{ type: "O" | "W" | "B"; text: string; confidence: number }>;
     };
 
     logDebug("relationship", `Parsed ${parsed.observations?.length ?? 0} observations`);

package/src/hooks/handlers/session-name.ts

@@ -30,14 +30,16 @@ export async function captureSessionName(
 ): Promise<void> {
   if (!sessionId) return;
 
-  // Skip if this session is already named
+  // Skip if this session is already named (non-untitled)
   const names = readSessionNames();
-  if (names[sessionId]) return;
+  const existing = names[sessionId];
+  if (existing && existing !== "untitled session") return;
 
-  // 1. Instant deterministic name from keywords
-  const fallback = extractFallbackName(message);
-  writeSessionName(sessionId, fallback);
-  logDebug("session-name", `Deterministic name: "${fallback}"`);
+  // Try deterministic name from this message's keywords
+  const name = extractFallbackName(message);
+  if (name === "untitled session") return; // not enough keywords yet
+  writeSessionName(sessionId, name);
+  logDebug("session-name", `Named from prompt: "${name}"`);
 
   // TODO: re-enable when a consumer exists (tab titles, dashboard)
   // // 2. Spawn detached background process to upgrade with inference

package/src/hooks/handlers/work-learning.ts

@@ -154,6 +154,7 @@ export async function captureWorkLearning(
     title,
     category,
     date: new Date().toISOString().slice(0, 10),
+    cwd: process.cwd(),
   };
   if (sessionId) meta.session = sessionId;
 

package/src/hooks/handlers/work-session.ts

@@ -3,7 +3,11 @@
  * Replaces the old work.ts handler.
  */
 
-import { readSessionNames } from "../lib/session-names";
+import {
+  extractFallbackName,
+  readSessionNames,
+  writeSessionName,
+} from "../lib/session-names";
 import { now } from "../lib/time";
 import {
   extractContent,
@@ -29,9 +33,18 @@ export async function captureWorkSession(
 
     const id = sessionId || `session-${Date.now()}`;
 
-    // Look up session name
+    // Name the session if still untitled and enough messages
     const names = readSessionNames();
-    const name = names[id] || "untitled session";
+    let name = names[id] || "";
+    if ((!name || name === "untitled session") && messages.length >= 6) {
+      const userTexts = messages
+        .filter((m) => m.role === "user")
+        .map((m) => extractContent(m))
+        .join(" ");
+      name = extractFallbackName(userTexts);
+      if (name !== "untitled session") writeSessionName(id, name);
+    }
+    if (!name || name === "untitled session") name = "untitled session";
 
     // Extract content
     const lastUser = extractLastUser(messages);

package/src/hooks/lib/claude-md.ts

@@ -72,7 +72,11 @@ export function needsRebuild(): boolean {
   const outputMtime = statSync(outputPath).mtimeMs;
 
   // Collect source files: template + setup.json + all telos/*.md
-  const sources: string[] = [TEMPLATE_PATH, resolve(paths.state(), "setup.json")];
+  const sources: string[] = [
+    TEMPLATE_PATH,
+    resolve(dirname(TEMPLATE_PATH), "STEERING-RULES.md"),
+    resolve(paths.state(), "setup.json"),
+  ];
 
   const telosDir = paths.telos();
   if (existsSync(telosDir)) {
@@ -105,10 +109,16 @@ export function buildClaudeMd(): string {
   const setupPrompt = state ? buildSetupPrompt(state) : null;
   const telos = loadTelos();
 
+  const steeringPath = resolve(dirname(TEMPLATE_PATH), "STEERING-RULES.md");
+  const steeringRules = existsSync(steeringPath)
+    ? readFileSync(steeringPath, "utf-8").trim()
+    : "";
+
   return template
     .replace("{{SETUP_PROMPT}}", setupPrompt ? `${setupPrompt}\n` : "")
     .replace("{{TELOS}}", telos ? `${telos}\n` : "")
-    .replace("{{MEMORY_PATHS}}", memoryPaths());
+    .replace("{{MEMORY_PATHS}}", memoryPaths())
+    .replace("{{STEERING_RULES}}", steeringRules);
 }
 
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */

package/src/hooks/lib/context.ts

@@ -7,6 +7,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parse } from "./frontmatter";
 import { readFailures, readLearnings } from "./learning-store";
+import { loadOpinionContext } from "./opinions";
 import { paths } from "./paths";
 import { loadRecentNotes } from "./relationship";
 import { readSessionNames } from "./session-names";
@@ -62,22 +63,21 @@ export function countSignals(filename: string): number {
 /** Load structured session history + project dashboard */
 export function loadActiveWork(): { text: string; summary: string | null } | null {
   try {
-    const recent = recentSessions(48);
+    const cwd = process.cwd();
+    const allRecent = recentSessions(48);
     const projects = activeProjects();
     const stale = staleProjects(7);
 
-    if (recent.length === 0 && projects.length === 0) return null;
+    if (allRecent.length === 0 && projects.length === 0) return null;
 
     const lines: string[] = [];
 
-    if (recent.length > 0) {
+    if (allRecent.length > 0) {
       lines.push("## Recent Work (last 48h)");
-      for (const s of recent.slice(-10).reverse()) {
+      for (const s of allRecent.slice(-10).reverse()) {
         const ago = formatAgo(s.ts);
-        lines.push(`- [${s.status}] ${s.name} — ${ago}`);
-        if (s.handoff) {
-          lines.push(`  Handoff: ${s.handoff.split("\n")[0].slice(0, 120)}`);
-        }
+        const here = s.cwd === cwd ? " *" : "";
+        lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
       }
     }
 
@@ -106,7 +106,8 @@ export function loadActiveWork(): { text: string; summary: string | null } | nul
     }
 
     // Summary from most recent session
-    const last = recent.length > 0 ? recent[recent.length - 1] : null;
+    const cwdSessions = allRecent.filter((s) => s.cwd === cwd);
+    const last = cwdSessions.length > 0 ? cwdSessions[cwdSessions.length - 1] : null;
     const summary = last?.summary?.slice(0, 60) || null;
 
     return {
@@ -215,26 +216,33 @@ export function loadWisdomContext(): string {
   }
 }
 
-/** Load recent session learning files as digest, split by category */
+/** Load recent session learning files as digest, with detail for current project */
 export function loadLearningDigest(): string {
   try {
-    const entries = readLearnings(paths.sessionLearning(), 6);
+    const cwd = process.cwd();
+    const entries = readLearnings(paths.sessionLearning(), 10);
     if (entries.length === 0) return "";
 
-    const approach = entries.filter((e) => e.category !== "system").slice(0, 2);
-    const system = entries.filter((e) => e.category === "system").slice(0, 2);
+    const thisProject = entries.filter((e) => e.cwd === cwd).slice(0, 4);
+    const other = entries.filter((e) => e.cwd !== cwd).slice(0, 3);
+
+    if (thisProject.length === 0 && other.length === 0) return "";
 
-    if (approach.length === 0 && system.length === 0) return "";
+    const lines: string[] = [];
 
-    const lines: string[] = ["## Recent Session Learnings"];
-    if (approach.length > 0) {
-      lines.push("### Approach");
-      for (const e of approach) lines.push(`- **Title:** ${e.title}`);
+    if (thisProject.length > 0) {
+      lines.push("## This Project — Recent Sessions");
+      for (const e of thisProject) {
+        lines.push(`- **${e.title}**`);
+        if (e.insights) lines.push(`  ${e.insights.split("\n")[0].slice(0, 150)}`);
+      }
     }
-    if (system.length > 0) {
-      lines.push("### System");
-      for (const e of system) lines.push(`- **Title:** ${e.title}`);
+
+    if (other.length > 0) {
+      lines.push(thisProject.length > 0 ? "" : "", "## Other Recent Learnings");
+      for (const e of other) lines.push(`- ${e.title}`);
     }
+
     return lines.join("\n");
   } catch {
     return "";
@@ -347,8 +355,10 @@ export function buildSystemReminder(): string {
   const trends = loadSignalTrends();
   const failures = loadFailurePatterns();
   const synthesis = loadSynthesisRecommendations();
+  const opinions = loadOpinionContext();
   const parts: string[] = [];
   if (wisdom) parts.push(wisdom);
+  if (opinions) parts.push(opinions);
   if (relationship) parts.push(relationship);
   if (digest) parts.push(digest);
   if (synthesis) parts.push(synthesis);

package/src/hooks/lib/graduation.ts

@@ -2,7 +2,7 @@
  * Unified Learning Analysis — graduation + ratings summary in one pipeline.
  *
  * Reads failures and session learnings via learning-store, detects recurring
- * patterns via Jaccard similarity on context text, and generates a ratings summary
+ * patterns via Dice similarity on context text, and generates a ratings summary
  * with recommendations via Haiku inference.
  *
  * A pattern qualifies for graduation when it appears 3+ times across different sessions.
@@ -13,20 +13,20 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import {
-  extractKeywords,
   type FailureEntry,
   type LearningEntry,
   readFailures,
   readLearnings,
-  similarity,
 } from "./learning-store";
 import { logDebug } from "./log";
 import { ensureDir, paths } from "./paths";
+import { extractKeywords, similarity } from "./text-similarity";
 
 // ── Types ──
 
 export interface AnalysisEntry {
   source: string;
+  path: string;
   text: string;
   date: string;
 }
@@ -86,7 +86,7 @@ function classifyDomain(text: string): string {
 // ── Data Collection ──
 
 const MIN_TEXT_LENGTH = 30;
-export const SIMILARITY_THRESHOLD = 0.35;
+export const SIMILARITY_THRESHOLD = 0.3;
 const MIN_OCCURRENCES = 3;
 
 function toAnalysisEntries(
@@ -99,6 +99,7 @@ function toAnalysisEntries(
     if (f.context.length >= MIN_TEXT_LENGTH) {
       entries.push({
         source: `failure:${f.slug}`,
+        path: f.path,
         text: f.context.slice(0, 300),
         date: f.date,
       });
@@ -110,6 +111,7 @@ function toAnalysisEntries(
     if (text.length >= MIN_TEXT_LENGTH) {
       entries.push({
         source: `learning:${l.filename}`,
+        path: l.path,
         text: text.slice(0, 300),
         date: l.date,
       });

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

@@ -13,6 +13,7 @@ import { parse } from "./frontmatter";
 
 export interface FailureEntry {
   slug: string;
+  path: string;
   rating: number;
   context: string;
   principle: string;
@@ -22,11 +23,13 @@ export interface FailureEntry {
 
 export interface LearningEntry {
   filename: string;
+  path: string;
   title: string;
   category: string;
   principle: string;
   date: string;
   insights: string;
+  cwd: string;
 }
 
 // ── Shared Directory Walker ──
@@ -79,6 +82,7 @@ export function readFailures(baseDir: string, limit?: number): FailureEntry[] {
 
           entries.push({
             slug: meta.slug || slug,
+            path: capturePath,
             rating: meta.rating ?? 0,
             context: meta.context,
             principle: meta.principle || "",
@@ -119,6 +123,7 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
             category?: string;
             principle?: string;
             date?: string;
+            cwd?: string;
           }>(content);
 
           if (!meta.title) continue;
@@ -127,11 +132,13 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
           entries.push({
             filename: file,
+            path: resolve(monthDir, file),
             title: meta.title,
             category: meta.category || "algorithm",
             principle: meta.principle || "",
             date: meta.date || "",
             insights: insightsMatch?.[1]?.trim() || "",
+            cwd: meta.cwd || "",
           });
 
           if (limit && entries.length >= limit) return entries;
@@ -146,120 +153,3 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
   return entries;
 }
-
-// ── Text Similarity (Jaccard on keywords) ──
-
-const STOP_WORDS = new Set([
-  "the",
-  "a",
-  "an",
-  "is",
-  "was",
-  "are",
-  "were",
-  "be",
-  "been",
-  "being",
-  "have",
-  "has",
-  "had",
-  "do",
-  "does",
-  "did",
-  "will",
-  "would",
-  "could",
-  "should",
-  "may",
-  "might",
-  "can",
-  "shall",
-  "to",
-  "of",
-  "in",
-  "for",
-  "on",
-  "with",
-  "at",
-  "by",
-  "from",
-  "as",
-  "into",
-  "through",
-  "during",
-  "before",
-  "after",
-  "and",
-  "but",
-  "or",
-  "nor",
-  "not",
-  "no",
-  "so",
-  "if",
-  "then",
-  "than",
-  "that",
-  "this",
-  "it",
-  "its",
-  "i",
-  "you",
-  "he",
-  "she",
-  "we",
-  "they",
-  "my",
-  "your",
-  "his",
-  "her",
-  "our",
-  "their",
-  "what",
-  "which",
-  "who",
-  "when",
-  "where",
-  "how",
-  "all",
-  "each",
-  "both",
-  "few",
-  "more",
-  "most",
-  "other",
-  "some",
-  "such",
-  "up",
-  "out",
-  "about",
-  "just",
-  "also",
-  "very",
-  "too",
-  "only",
-  "own",
-]);
-
-export function extractKeywords(text: string): Set<string> {
-  return new Set(
-    text
-      .toLowerCase()
-      .replace(/[^a-z0-9\s-]/g, " ")
-      .split(/\s+/)
-      .filter((w) => w.length > 2 && !STOP_WORDS.has(w))
-  );
-}
-
-export function similarity(a: string, b: string): number {
-  const ka = extractKeywords(a);
-  const kb = extractKeywords(b);
-  if (ka.size === 0 || kb.size === 0) return 0;
-
-  let intersection = 0;
-  for (const w of ka) {
-    if (kb.has(w)) intersection++;
-  }
-  const union = new Set([...ka, ...kb]).size;
-  return union > 0 ? intersection / union : 0;
-}