portable-agent-layer 0.17.0 → 0.18.0

package/assets/templates/PAL/ALGORITHM.md

@@ -2,11 +2,11 @@
 
 Core: transition from CURRENT STATE to IDEAL STATE using verifiable criteria. Every criterion is atomic, binary testable, and checked off with evidence.
 
-## The Four Phases
+## The Five Phases
 
 All work happens inside these phases. No work outside the phase structure until the Algorithm completes.
 
-### ━━━ 👁️ OBSERVE ━━━ 1/4
+### ━━━ 👁️ OBSERVE ━━━ 1/5
 
 Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 
@@ -44,7 +44,7 @@ Output:
 🏹 CAPABILITIES: [list each selected skill/tool and why]
 ```
 
-### ━━━ 🧠 PLAN ━━━ 2/4
+### ━━━ 🧠 PLAN ━━━ 2/5
 
 **Pressure test the criteria:**
 
@@ -59,7 +59,7 @@ Refine criteria if the pressure test reveals gaps. Add criteria for uncovered fa
 - Decide execution order — what's serial, what can parallelize
 - If Advanced+ complexity, use EnterPlanMode for user alignment
 
-### ━━━ ⚡ EXECUTE ━━━ 3/4
+### ━━━ ⚡ EXECUTE ━━━ 3/5
 
 Do the work. Invoke selected capabilities via tool calls.
 
@@ -67,7 +67,7 @@ Do the work. Invoke selected capabilities via tool calls.
 - If a criterion can't be met, flag it immediately — don't defer to VERIFY
 - Make decisions explicit — state why you chose approach A over B
 
-### ━━━ ✅ VERIFY ━━━ 4/4
+### ━━━ ✅ VERIFY ━━━ 4/5
 
 No rubber-stamping. Each criterion needs specific evidence.
 
@@ -88,13 +88,30 @@ For EACH criterion:
 
 If any criteria failed, fix and re-verify before completing.
 
+### ━━━ 📚 LEARN ━━━ 5/5
+
+Reflect on the work and capture reusable knowledge. Skip this phase when the work was trivial or purely mechanical.
+
+**1. Reflection** (one sentence each):
+- What would I do differently next time?
+- What would a better algorithm have done differently?
+
+**2. Wisdom Frame** — if the session produced a genuine, reusable insight:
+
+```bash
+bun ~/.agents/PAL/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]
+```
+
+Domains: `development`, `workflow`, `communication`, `infrastructure`, `integration`, or any fitting domain.
+Only write if the insight is **genuine and reusable** — not every session produces one. When in doubt, skip.
+
 ## Output Format
 
 ```
 ♻️ ALGORITHM ═══════════════════════════
 🗒️ TASK: [brief description]
 
-━━━ 👁️ OBSERVE ━━━ 1/4
+━━━ 👁️ OBSERVE ━━━ 1/5
 🔎 REVERSE ENGINEERING:
 [reverse engineering output]
 
@@ -103,18 +120,22 @@ If any criteria failed, fix and re-verify before completing.
 
 🏹 CAPABILITIES: [selected capabilities]
 
-━━━ 🧠 PLAN ━━━ 2/4
+━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
 🧠 PREMORTEM: [failure modes]
 📐 APPROACH: [execution plan]
 
-━━━ ⚡ EXECUTE ━━━ 3/4
+━━━ ⚡ EXECUTE ━━━ 3/5
 [work happens here]
 
-━━━ ✅ VERIFY ━━━ 4/4
+━━━ ✅ VERIFY ━━━ 4/5
 ✅ VERIFICATION:
 [criterion-by-criterion evidence]
 
 🔧 CHANGE: [what changed]
 🗣️ {{IDENTITY_NAME}}: [summary]
+
+━━━ 📚 LEARN ━━━ 5/5
+🪞 REFLECT: [what I'd do differently]
+📝 WISDOM: [frame update if genuine insight, or "No new insight"]
 ```

package/assets/templates/settings.claude.json

@@ -19,7 +19,8 @@
       "Bash(file //*)",
       "Bash(stat //*)",
       "Bash(readlink //*)",
-      "Bash(bun ~/.agents/skills/*/tools/*.ts *)"
+      "Bash(bun ~/.agents/skills/*/tools/*.ts *)",
+      "Bash(bun run tool:wisdom-frame *)"
     ]
   },
   "hooks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -44,7 +44,8 @@
     "prepare": "husky",
     "install:all": "bun run src/cli/index.ts cli install",
     "uninstall": "bun run src/cli/index.ts cli uninstall",
-    "tool:analyze": "bun run src/tools/analyze.ts",
+    "tool:analyze": "bun run src/tools/agent/analyze.ts",
+    "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.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/lib/paths.ts

@@ -81,5 +81,6 @@ export const assets = {
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
   claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
   cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
+  agentTools: () => pkg("src", "tools", "agent"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/targets/lib.ts

@@ -273,10 +273,11 @@ export function copyPalDocs(): number {
     count++;
   }
 
-  // Symlink ~/.agents/PAL/telos and ~/.agents/PAL/memory → <palHome>/...
+  // Symlink ~/.agents/PAL/{telos,memory,tools} → source locations
   const linkType = process.platform === "win32" ? "junction" : "dir";
   ensureSymlink(resolve(PAL_DOCS_DIR, "telos"), resolve(palHome(), "telos"), linkType);
   ensureSymlink(resolve(PAL_DOCS_DIR, "memory"), resolve(palHome(), "memory"), linkType);
+  ensureSymlink(resolve(PAL_DOCS_DIR, "tools"), assets.agentTools(), linkType);
 
   return count;
 }

package/src/tools/agent/analyze.ts

@@ -0,0 +1,157 @@
+#!/usr/bin/env bun
+/**
+ * Unified Learning Analysis — graduation patterns + ratings summary.
+ *
+ * Reads failures and session learnings, finds recurring patterns,
+ * summarizes ratings, and generates recommendations.
+ *
+ * Usage: bun run tool:analyze
+ */
+
+import { parseArgs } from "node:util";
+import { type AnalysisResult, analyze } from "../../hooks/lib/graduation";
+
+// ── ANSI Colors ──
+
+const c = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+};
+
+export function printReport(result: AnalysisResult): void {
+  const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
+  const hasRatings = result.ratings !== null;
+
+  if (!hasPatterns && !hasRatings) {
+    console.log("\n  No patterns or ratings data found.\n");
+    return;
+  }
+
+  if (result.ratings) {
+    const r = result.ratings;
+    const avgColor = r.average >= 7 ? c.green : r.average <= 4 ? c.red : c.yellow;
+    console.log(
+      `\n  ${c.bold("Ratings:")} ${avgColor(`${r.average.toFixed(1)}/10`)} avg (${r.total} total)`
+    );
+    console.log(
+      `  ${c.red(`Low (≤4): ${r.low.count}`)} | ${c.green(`High (≥7): ${r.high.count}`)}`
+    );
+  }
+
+  if (result.candidates.length > 0) {
+    console.log(
+      `\n  ${c.bold(c.green(`Graduation Report — ${result.candidates.length} pattern(s) detected`))}\n`
+    );
+    console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
+
+    for (const candidate of result.candidates) {
+      console.log(
+        `  ${c.cyan(`[${candidate.domain}]`)} ${c.bold(`${candidate.entries.length}x`)} occurrences`
+      );
+      console.log("");
+
+      for (const entry of candidate.entries) {
+        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+        const tag =
+          sourceType === "failure"
+            ? c.red(`[${sourceType}]`)
+            : c.yellow(`[${sourceType}]`);
+        console.log(
+          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 100)}`
+        );
+      }
+
+      console.log(`\n  ${c.dim("Files:")}`);
+      for (const entry of candidate.entries) {
+        console.log(`    ${c.dim(entry.path)}`);
+      }
+
+      console.log("");
+      console.log(
+        `  Target frame: ${c.magenta(`memory/wisdom/frames/${candidate.domain}.md`)}`
+      );
+      console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
+    }
+  }
+
+  if (result.emerging.length > 0) {
+    console.log(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
+    for (const group of result.emerging) {
+      console.log(
+        `  ${c.cyan(`[${group.domain}]`)} ${c.bold(`${group.entries.length}x`)}`
+      );
+      for (const entry of group.entries) {
+        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+        const tag =
+          sourceType === "failure"
+            ? c.red(`[${sourceType}]`)
+            : c.yellow(`[${sourceType}]`);
+        console.log(
+          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 80)}`
+        );
+      }
+      console.log("  Files:");
+      for (const entry of group.entries) {
+        console.log(`    ${c.dim(entry.path)}`);
+      }
+      console.log("");
+    }
+  }
+
+  if (result.recommendations.length > 0) {
+    console.log(`  ${c.bold("Recommendations:")}\n`);
+    for (const rec of result.recommendations) {
+      console.log(`    ${rec}`);
+    }
+    console.log("");
+  }
+
+  if (result.candidates.length > 0) {
+    console.log(`  To crystallize: add a line to the wisdom frame file.`);
+    console.log(`  Format: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`);
+  }
+}
+
+async function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      help: { type: "boolean", short: "h" },
+      actionable: { type: "boolean", short: "a" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+  PAL Learning Analysis — unified graduation + ratings report
+
+  Reads all captured failures (rating ≤3) and session learnings,
+  groups recurring patterns via Dice similarity on context text,
+  and summarizes rating trends.
+
+  Sections:
+    Ratings       Overall average, low/high counts
+    Graduation    Patterns with 3+ occurrences → ready to crystallize
+    Emerging      Patterns with 2 occurrences → one more to graduate
+
+  Flags:
+    --actionable, -a  Generate actionable recommendations via Haiku inference
+
+  To crystallize a graduated pattern, add it to the target wisdom frame:
+    - Your principle here [CRYSTAL: 85%]
+
+  Usage: bun run tool:analyze [--actionable] [--help]
+`);
+    process.exit(0);
+  }
+
+  const result = await analyze({ actionable: values.actionable });
+  printReport(result);
+}
+
+if (import.meta.main) run();

package/src/tools/agent/wisdom-frame.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env bun
+/**
+ * WisdomFrameUpdater — Update wisdom frames with new observations.
+ *
+ * Takes a domain and observation, updates the appropriate frame file.
+ * Creates the frame if it doesn't exist. Tracks observation count and
+ * evolution log. Principles are marked [CRYSTAL: N%] manually when
+ * confidence is high enough.
+ *
+ * Usage:
+ *   bun run tool:wisdom-frame --domain communication --observation "prefers bullet points"
+ *   bun run tool:wisdom-frame --domain development --observation "refactoring without tests caused regressions" --type anti-pattern
+ *   bun run tool:wisdom-frame --domain workflow --observation "always run type-check after edits" --type principle
+ *
+ * Types: principle, contextual-rule, anti-pattern, evolution (default)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { paths } from "../../hooks/lib/paths";
+
+// ── Types ──
+
+type ObservationType = "principle" | "contextual-rule" | "anti-pattern" | "evolution";
+
+interface UpdateResult {
+  success: boolean;
+  domain: string;
+  type: ObservationType;
+  message: string;
+  framePath: string;
+}
+
+// ── Helpers ──
+
+function date(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function parseObservationCount(content: string): number {
+  const match = content.match(/\*\*Observation Count:\*\*\s*(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+function incrementCount(content: string): string {
+  const current = parseObservationCount(content);
+  return content.replace(/(\*\*Observation Count:\*\*\s*)\d+/, `$1${current + 1}`);
+}
+
+function updateDate(content: string): string {
+  return content.replace(/(\*\*Last Updated:\*\*\s*)\S+/, `$1${date()}`);
+}
+
+function appendToSection(
+  content: string,
+  sectionHeader: string,
+  entry: string,
+  fallbackBefore?: string
+): string {
+  const idx = content.indexOf(sectionHeader);
+
+  if (idx === -1) {
+    // Section doesn't exist — insert before fallback or at end
+    const insertAt = fallbackBefore ? content.indexOf(fallbackBefore) : -1;
+    const pos = insertAt !== -1 ? insertAt : content.length;
+    return `${content.slice(0, pos)}${sectionHeader}\n\n${entry}\n\n${content.slice(pos)}`;
+  }
+
+  // Find end of section (next ## or EOF)
+  const afterSection = content.slice(idx + sectionHeader.length);
+  const nextSection = afterSection.indexOf("\n## ");
+  const insertPoint =
+    nextSection === -1 ? content.length : idx + sectionHeader.length + nextSection;
+
+  return `${content.slice(0, insertPoint)}\n${entry}${content.slice(insertPoint)}`;
+}
+
+// ── Core Update ──
+
+export function updateFrame(
+  domain: string,
+  observation: string,
+  type: ObservationType = "evolution"
+): UpdateResult {
+  const framesDir = paths.wisdom();
+  const framePath = resolve(framesDir, `${domain}.md`);
+
+  // Create frame if it doesn't exist
+  if (!existsSync(framePath)) {
+    mkdirSync(framesDir, { recursive: true });
+
+    const content = `# Frame: ${domain.charAt(0).toUpperCase() + domain.slice(1)}
+
+## Meta
+- **Domain:** ${domain}
+- **Observation Count:** 1
+- **Last Updated:** ${date()}
+
+---
+
+## Core Principles
+
+*No crystallized principles yet. Observations accumulating.*
+
+---
+
+## Contextual Rules
+
+${type === "contextual-rule" ? `- ${observation} (${date()})` : "*None yet.*"}
+
+---
+
+## Anti-Patterns
+
+${type === "anti-pattern" ? `### ${observation}\n- **Severity:** Medium\n- **Frequency:** Observed` : "*None yet.*"}
+
+---
+
+## Evolution Log
+- ${date()}: Frame created — ${observation}
+`;
+
+    writeFileSync(framePath, content);
+    return {
+      success: true,
+      domain,
+      type,
+      message: `Created new frame "${domain}" with initial observation`,
+      framePath,
+    };
+  }
+
+  // Update existing frame
+  let content = readFileSync(framePath, "utf-8");
+  content = incrementCount(content);
+  content = updateDate(content);
+
+  const evolutionEntry = `- ${date()}: ${observation}`;
+
+  switch (type) {
+    case "anti-pattern":
+      content = appendToSection(
+        content,
+        "## Anti-Patterns",
+        `\n### ${observation}\n- **Severity:** Medium\n- **Frequency:** Observed`,
+        "## Evolution Log"
+      );
+      content = appendToSection(content, "## Evolution Log", evolutionEntry);
+      break;
+
+    case "contextual-rule":
+      content = appendToSection(
+        content,
+        "## Contextual Rules",
+        `- ${observation} (${date()})`,
+        "## Anti-Patterns"
+      );
+      content = appendToSection(content, "## Evolution Log", evolutionEntry);
+      break;
+
+    case "principle":
+      // Principles logged for manual crystallization — don't auto-add to Core Principles
+      content = appendToSection(
+        content,
+        "## Evolution Log",
+        `- ${date()}: Principle candidate — ${observation}`
+      );
+      break;
+
+    case "evolution":
+    default:
+      content = appendToSection(content, "## Evolution Log", evolutionEntry);
+      break;
+  }
+
+  writeFileSync(framePath, content);
+
+  return {
+    success: true,
+    domain,
+    type,
+    message: `Updated "${domain}" frame with ${type}: ${observation}`,
+    framePath,
+  };
+}
+
+// ── CLI ──
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      domain: { type: "string", short: "d" },
+      observation: { type: "string", short: "o" },
+      type: { type: "string", short: "t" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+WisdomFrameUpdater — Update wisdom frames with observations
+
+Usage:
+  bun run tool:wisdom-frame --domain <domain> --observation "text" [--type <type>]
+
+Domains:
+  development, workflow, communication, infrastructure, integration, or any custom domain
+
+Types:
+  principle        High-confidence pattern (logged for manual crystallization)
+  contextual-rule  Context-specific behavioral rule
+  anti-pattern     Something to avoid
+  evolution        General observation (default)
+
+Examples:
+  bun run tool:wisdom-frame -d workflow -o "always run type-check after edits"
+  bun run tool:wisdom-frame -d development -o "mocking DB hides migration bugs" -t anti-pattern
+  bun run tool:wisdom-frame -d communication -o "user prefers terse summaries" -t principle
+`);
+    process.exit(0);
+  }
+
+  if (!values.domain || !values.observation) {
+    console.error("Required: --domain and --observation");
+    process.exit(1);
+  }
+
+  const cliType = (values.type || "evolution") as ObservationType;
+  const result = updateFrame(values.domain, values.observation, cliType);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (import.meta.main) run();

package/src/tools/export.ts

@@ -10,25 +10,31 @@ import { resolve } from "node:path";
 import { collectExportFiles, exportZip, timestamp } from "../hooks/lib/export";
 import { palHome } from "../hooks/lib/paths";
 
-const args = process.argv.slice(2);
-const dryRun = args.includes("--dry-run");
-const pathArg = args.find((a) => a !== "--dry-run");
+export { collectExportFiles, exportZip };
 
-const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
+function run() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const pathArg = args.find((a) => a !== "--dry-run");
 
-if (dryRun) {
-  const files = collectExportFiles();
-  if (files.length === 0) {
-    console.log("Nothing to export — no gitignored personal files found.");
-  } else {
-    console.log(`Would export ${files.length} files → ${outputPath}\n`);
-    for (const f of files) console.log(`  ${f}`);
-  }
-} else {
-  const count = exportZip(outputPath);
-  if (count === 0) {
-    console.log("Nothing to export — no gitignored personal files found.");
+  const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
+
+  if (dryRun) {
+    const files = collectExportFiles();
+    if (files.length === 0) {
+      console.log("Nothing to export — no gitignored personal files found.");
+    } else {
+      console.log(`Would export ${files.length} files → ${outputPath}\n`);
+      for (const f of files) console.log(`  ${f}`);
+    }
   } else {
-    console.log(`Exported ${count} files → ${outputPath}`);
+    const count = exportZip(outputPath);
+    if (count === 0) {
+      console.log("Nothing to export — no gitignored personal files found.");
+    } else {
+      console.log(`Exported ${count} files → ${outputPath}`);
+    }
   }
 }
+
+if (import.meta.main) run();