portable-agent-layer 0.10.0 → 0.11.0

package/assets/templates/PAL/WORK_TRACKING.md

@@ -0,0 +1,14 @@
+# Work Tracking
+
+PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured) and `memory/state/projects.json` (AI-managed).
+
+## Projects
+
+Update `projects.json` via the work-tracking library when:
+- **Starting sustained multi-session work** → create a project with objectives and an id (slugified, e.g. "pdf-template-engine")
+- **Making a key decision** → add to the project's `decisions` array
+- **Completing a milestone** → add to `completed`, remove from `nextSteps`
+- **Session ends with open work** → update `nextSteps` and `handoff`
+- **Work is done** → set status to "completed"
+
+Do not create projects for one-off questions or quick fixes.

package/assets/templates/settings.claude.json

@@ -0,0 +1,80 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "WebFetch",
+      "WebSearch",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(ls *)",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(wc *)",
+      "Bash(diff *)",
+      "Bash(which *)",
+      "Bash(file *)",
+      "Bash(stat *)",
+      "Bash(readlink *)",
+      "Bash(bun ~/.agents/skills/*/tools/*.ts *)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -44,10 +44,6 @@
     "prepare": "husky",
     "install:all": "bun run src/cli/install.ts",
     "uninstall": "bun run src/cli/uninstall.ts",
-    "ai:entity-save": "bun run src/tools/entity-save.ts",
-    "ai:fyzz-api": "bun run src/tools/fyzz-api.ts",
-    "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",

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

@@ -17,8 +17,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import { loadTelos } from "./context";
-import { assets, ensureDir, palHome, paths, platform } from "./paths";
+import { assets, ensureDir, paths, platform } from "./paths";
 import { buildSetupPrompt, readSetupState } from "./setup";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
@@ -71,54 +70,30 @@ export function needsRebuild(): boolean {
 
   const outputMtime = statSync(outputPath).mtimeMs;
 
-  // Collect source files: template + setup.json + all telos/*.md
-  const sources: string[] = [
-    TEMPLATE_PATH,
-    resolve(dirname(TEMPLATE_PATH), "STEERING-RULES.md"),
-    resolve(paths.state(), "setup.json"),
-  ];
+  // Collect source files: template + setup.json + PAL docs
+  const sources: string[] = [TEMPLATE_PATH, resolve(paths.state(), "setup.json")];
 
-  const telosDir = paths.telos();
-  if (existsSync(telosDir)) {
-    for (const f of readdirSync(telosDir).filter((f) => f.endsWith(".md"))) {
-      sources.push(resolve(telosDir, f));
+  // Track PAL doc sources for rebuild detection
+  const palDocsDir = assets.palDocs();
+  if (existsSync(palDocsDir)) {
+    for (const f of readdirSync(palDocsDir).filter((f) => f.endsWith(".md"))) {
+      sources.push(resolve(palDocsDir, f));
     }
   }
 
   return latestMtime(...sources) > outputMtime;
 }
 
-function memoryPaths(): string {
-  const mem = resolve(palHome(), "memory");
-  return [
-    `- **Wisdom frames**: \`${resolve(mem, "wisdom", "frames")}/\` — crystallized principles per domain (loaded every session)`,
-    `- **Relationship notes**: \`${resolve(mem, "relationship")}/YYYY-MM/YYYY-MM-DD.md\` — daily interaction observations (loaded every session)`,
-    `- **Session learnings**: \`${resolve(mem, "learning", "session")}/YYYY-MM/*.md\` — reusable insights from sessions (loaded every session)`,
-    `- **Failure captures**: \`${resolve(mem, "learning", "failures")}/YYYY-MM/{timestamp}_{slug}/capture.md\` — what went wrong and why`,
-    `- **Signals**: \`${resolve(mem, "signals")}/ratings.jsonl\` — append-only rating signal log (do not edit directly)`,
-  ].join("\n");
-}
-
 /** Render AGENTS.md from the template using current state */
 export function buildClaudeMd(): string {
   const template = existsSync(TEMPLATE_PATH)
     ? readFileSync(TEMPLATE_PATH, "utf-8")
-    : "# PAL Context\n\n{{SETUP_PROMPT}}\n{{TELOS}}\n## Memory\n\n{{MEMORY_PATHS}}\n";
+    : "# PAL Context\n\n{{SETUP_PROMPT}}\n";
 
   const state = readSetupState();
   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("{{STEERING_RULES}}", steeringRules);
+  return template.replace("{{SETUP_PROMPT}}", setupPrompt ? `${setupPrompt}\n` : "");
 }
 
 /** 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

@@ -21,33 +21,6 @@ import {
   staleProjects,
 } from "./work-tracking";
 
-/** Load all populated TELOS files as a single markdown string */
-export function loadTelos(): string {
-  const telosDir = paths.telos();
-  if (!existsSync(telosDir)) return "";
-
-  const files = readdirSync(telosDir)
-    .filter((f) => f.endsWith(".md"))
-    .sort();
-
-  const sections: string[] = [];
-
-  for (const file of files) {
-    const content = readFileSync(resolve(telosDir, file), "utf-8").trim();
-    // Skip empty templates (only have a heading and comment)
-    const realLines = content
-      .split("\n")
-      .filter(
-        (l) =>
-          !l.startsWith("#") && !l.startsWith("<!--") && !l.startsWith("-->") && l.trim()
-      );
-    if (realLines.length === 0) continue;
-    sections.push(content);
-  }
-
-  return sections.join("\n\n---\n\n");
-}
-
 /** Count lines in a signals JSONL file */
 export function countSignals(filename: string): number {
   const filepath = resolve(paths.signals(), filename);

package/src/hooks/lib/paths.ts

@@ -77,4 +77,6 @@ export const assets = {
   hooks: () => pkg("src", "hooks"),
   telosTemplates: () => pkg("assets", "templates", "telos"),
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
+  claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
+  palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/hooks/lib/security.ts

@@ -43,6 +43,7 @@ export const HOOK_MANAGED_DIRS = [
   "memory/learning/synthesis",
   "memory/relationship",
   "memory/wisdom/state",
+  ".agents/PAL",
 ];
 
 /** Escape a string for use in a RegExp */

package/src/targets/claude/install.ts

@@ -1,20 +1,23 @@
 /**
  * PAL — Claude Code target installer (TypeScript)
- * Merges hooks into existing settings.json (never overwrites).
- * Copies skills additively. Generates CLAUDE.md from TELOS.
+ * Merges settings template into existing settings.json (never overwrites).
+ * Copies skills, agents, and PAL docs. Generates CLAUDE.md from TELOS.
  */
 
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
-import { palHome, palPkg, platform } from "../../hooks/lib/paths";
+import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
 import {
   copyAgents,
+  copyPalDocs,
   copySkills,
   countAgents,
   countMd,
   countSkills,
+  loadSettingsTemplate,
   log,
+  mergeSettings,
   readJson,
   writeJson,
 } from "../lib";
@@ -35,96 +38,13 @@ const backup = `${SETTINGS}.bak.${Date.now()}`;
 copyFileSync(SETTINGS, backup);
 log.info("Backed up settings.json");
 
-// --- Build hooks payload ---
-const hooksPayload = {
-  hooks: {
-    SessionStart: [
-      {
-        matcher: "",
-        hooks: [
-          { type: "command", command: `bun run ${PKG_ROOT}/src/hooks/LoadContext.ts` },
-        ],
-      },
-    ],
-    UserPromptSubmit: [
-      {
-        matcher: "",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/UserPromptOrchestrator.ts`,
-          },
-        ],
-      },
-    ],
-    PreToolUse: [
-      {
-        matcher: "Bash|Write|Edit",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/SecurityValidator.ts`,
-          },
-        ],
-      },
-      {
-        matcher: "Skill",
-        hooks: [
-          { type: "command", command: `bun run ${PKG_ROOT}/src/hooks/SkillGuard.ts` },
-        ],
-      },
-    ],
-    Stop: [
-      {
-        matcher: "",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/StopOrchestrator.ts`,
-          },
-        ],
-      },
-    ],
-  },
-};
+// --- 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);
 
-// --- Merge hooks additively (deduplicate by command) ---
-type HookEntry = { matcher: string; hooks: Array<{ type: string; command: string }> };
-type Settings = { hooks?: Record<string, HookEntry[]>; env?: Record<string, string> };
-
-const settings = readJson<Settings>(SETTINGS, {});
-if (!settings.hooks) settings.hooks = {};
-
-for (const [event, entries] of Object.entries(hooksPayload.hooks)) {
-  const existing = settings.hooks[event] ?? [];
-  for (const entry of entries) {
-    const cmd = entry.hooks[0]?.command;
-    const alreadyPresent = existing.some((e) => e.hooks?.[0]?.command === cmd);
-    if (!alreadyPresent) existing.push(entry);
-  }
-  settings.hooks[event] = existing;
-}
-
-// --- Add PAL tool permissions (auto-allow ai: scripts) ---
-type SettingsWithPermissions = Settings & { permissions?: { allow?: string[] } };
-const s = settings as SettingsWithPermissions;
-if (!s.permissions) s.permissions = {};
-if (!s.permissions.allow) s.permissions.allow = [];
-const aiTools = [
-  "ai:entity-save",
-  "ai:fyzz-api",
-  "ai:pdf-download",
-  "ai:youtube-analyze",
-];
-for (const tool of aiTools) {
-  const perm = `Bash(bun run ${tool} *)`;
-  if (!s.permissions.allow.includes(perm)) {
-    s.permissions.allow.push(perm);
-  }
-}
-
-writeJson(SETTINGS, settings);
-log.success("Merged hooks into settings.json");
+writeJson(SETTINGS, merged);
+log.success("Merged PAL settings into settings.json");
 
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
@@ -133,13 +53,16 @@ copySkills(skillsDir);
 // --- Copy agents ---
 copyAgents();
 
+// --- Copy PAL system docs ---
+const palDocsCount = copyPalDocs();
+log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+
 // --- Generate ~/.claude/AGENTS.md and symlink ~/.claude/CLAUDE.md → AGENTS.md ---
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md (→ ~/.claude/CLAUDE.md symlink)");
 
 log.success("Claude Code installation complete");
 console.log("");
-log.info(`Hooks: 5 (SessionStart, UserPromptSubmit, PreToolUse×2, Stop)`);
 log.info(`Skills: ${countSkills()}`);
 log.info(`Agents: ${countAgents()}`);
 log.info(`TELOS: ${countMd(resolve(palHome(), "telos"))} files`);

package/src/targets/claude/uninstall.ts

@@ -1,14 +1,23 @@
 /**
  * PAL — Claude Code uninstaller (TypeScript)
- * Removes PAL hooks, skills, and env from settings.json.
+ * Removes exactly what the settings template added, plus skills, agents, and PAL docs.
  */
 
 import { copyFileSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
-import { palPkg, platform } from "../../hooks/lib/paths";
-import { log, readJson, removeAgents, removeSkills, writeJson } from "../lib";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  loadSettingsTemplate,
+  log,
+  readJson,
+  removeAgents,
+  removePalDocs,
+  removeSkills,
+  unmergeSettings,
+  writeJson,
+} from "../lib";
 
-const PKG_ROOT = palPkg();
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CLAUDE_DIR = platform.claudeDir();
 const SETTINGS = resolve(CLAUDE_DIR, "settings.json");
 
@@ -21,50 +30,13 @@ if (!existsSync(SETTINGS)) {
 copyFileSync(SETTINGS, `${SETTINGS}.bak.${Date.now()}`);
 log.info("Backed up settings.json");
 
-// --- Remove PAL hooks ---
-type HookEntry = {
-  matcher?: string;
-  hooks?: Array<{ command?: string }>;
-  command?: string;
-};
-type Settings = { hooks?: Record<string, HookEntry[]>; env?: Record<string, string> };
+// --- 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);
 
-const settings = readJson<Settings>(SETTINGS, {});
-
-if (settings.hooks) {
-  for (const [event, entries] of Object.entries(settings.hooks)) {
-    settings.hooks[event] = entries.filter((entry) => {
-      // New format: { matcher, hooks: [{ command }] }
-      if (entry.hooks) return !entry.hooks.some((h) => h.command?.includes(PKG_ROOT));
-      // Old flat format: { type, command }
-      if (entry.command) return !entry.command.includes(PKG_ROOT);
-      return true;
-    });
-    if (settings.hooks[event].length === 0) delete settings.hooks[event];
-  }
-  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-}
-
-// --- Remove env ---
-if (settings.env) {
-  // Clean up env vars
-  delete settings.env.PAL_DIR;
-  if (Object.keys(settings.env).length === 0) delete settings.env;
-}
-
-// --- Remove PAL tool permissions ---
-type SettingsWithPermissions = Settings & { permissions?: { allow?: string[] } };
-const s = settings as SettingsWithPermissions;
-if (s.permissions?.allow) {
-  s.permissions.allow = s.permissions.allow.filter(
-    (p) => !p.includes(PKG_ROOT) && !p.startsWith("Bash(bun run ai:")
-  );
-  if (s.permissions.allow.length === 0) delete s.permissions.allow;
-  if (Object.keys(s.permissions).length === 0) delete s.permissions;
-}
-
-writeJson(SETTINGS, settings);
-log.success("Removed PAL hooks and env from settings.json");
+writeJson(SETTINGS, cleaned);
+log.success("Removed PAL settings from settings.json");
 
 // --- Remove PAL skills ---
 const removed = removeSkills(resolve(CLAUDE_DIR, "skills"));
@@ -82,6 +54,9 @@ if (removedAgents.length > 0) {
   log.info("No PAL agents found");
 }
 
+// --- Remove PAL system docs ---
+removePalDocs();
+
 // --- Remove AGENTS.md and CLAUDE.md symlink ---
 const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
 const claudeMd = resolve(CLAUDE_DIR, "CLAUDE.md");