portable-agent-layer 0.36.0 → 0.37.0

package/src/hooks/lib/projects.ts

@@ -1,12 +1,10 @@
 /**
- * Projects — registry of user-curated projects with auto-managed state.
+ * Projects — registry of user-curated projects backed by ISA.md files.
  *
- * Each project lives in `~/.pal/memory/state/progress/{slug}.json`. The CLI
- * (`src/tools/agent/project.ts`) is the user/AI-facing writer; the Stop hook
+ * Each project lives in `~/.pal/memory/projects/{slug}/ISA.md`. Frontmatter
+ * holds operational state; the body holds ISA spec sections. The CLI
+ * (`src/tools/agent/project.ts`) is the primary writer; the Stop hook
  * auto-touches `updated` when cwd resolves into a registered project.
- *
- * Replaces the hand-edited `~/.pal/telos/PROJECTS.md` — see plan
- * `~/.claude/plans/clever-frolicking-harp.md` for context.
  */
 
 import {
@@ -14,35 +12,38 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmdirSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, parse as parsePath, resolve, sep } from "node:path";
+import { parse, stringify } from "./frontmatter";
 import { paths } from "./paths";
 
 export type ProjectStatus = "active" | "paused" | "complete" | "archived";
 
-export interface Decision {
-  ts: string;
-  decision: string;
-  rationale: string;
-}
-
 export interface ProjectProgress {
   name: string;
   path: string;
   status: ProjectStatus;
   created: string;
   updated: string;
-  facts?: string[];
-  objectives?: string[];
-  next_steps?: string[];
+  next?: string[];
   blockers?: string[];
   handoff?: string;
-  decisions?: Decision[];
+  // ISA body sections
+  problem?: string;
+  goal?: string;
+  criteria?: string;
+  vision?: string;
+  constraints?: string;
+  out_of_scope?: string;
+  context?: string;
+  decisions?: string;
+  changelog?: string;
 }
 
-export const PROJECT_STALE_DAYS_DEFAULT = 14;
+const PROJECT_STALE_DAYS_DEFAULT = 14;
 
 const PROJECT_MARKERS = [
   ".git",
@@ -54,23 +55,69 @@ const PROJECT_MARKERS = [
   "Gemfile",
 ];
 
-function progressDir(): string {
-  const dir = paths.progress();
-  mkdirSync(dir, { recursive: true });
-  return dir;
+type IsaMeta = {
+  name: string;
+  path: string;
+  status: ProjectStatus;
+  created: string;
+  updated: string;
+  next?: string[];
+  blockers?: string[];
+  handoff?: string;
+};
+
+const BODY_SECTIONS: Array<[string, keyof ProjectProgress]> = [
+  ["Problem", "problem"],
+  ["Goal", "goal"],
+  ["Criteria", "criteria"],
+  ["Vision", "vision"],
+  ["Constraints", "constraints"],
+  ["Out of Scope", "out_of_scope"],
+  ["Context", "context"],
+  ["Decisions", "decisions"],
+  ["Changelog", "changelog"],
+];
+
+const HEADER_TO_FIELD: Record<string, keyof ProjectProgress> = Object.fromEntries(
+  BODY_SECTIONS.map(([h, k]) => [h.toLowerCase(), k])
+);
+
+function buildBody(p: ProjectProgress): string {
+  return BODY_SECTIONS.filter(([, k]) => (p[k] as string | undefined)?.trim())
+    .map(([h, k]) => `## ${h}\n\n${(p[k] as string).trim()}`)
+    .join("\n\n");
 }
 
-function progressFile(slug: string): string {
-  return resolve(progressDir(), `${slug}.json`);
+function extractSections(body: string): Partial<ProjectProgress> {
+  const out: Partial<ProjectProgress> = {};
+  for (const part of body.split(/^## /m).slice(1)) {
+    const nl = part.indexOf("\n");
+    if (nl === -1) continue;
+    const header = part.slice(0, nl).trim().toLowerCase();
+    const content = part.slice(nl + 1).trim();
+    if (!content) continue;
+    const field = HEADER_TO_FIELD[header];
+    if (field) (out as Record<string, string>)[field as string] = content;
+  }
+  return out;
+}
+
+function isaFilePath(slug: string): string {
+  return resolve(paths.projectHistory(), slug, "ISA.md");
+}
+
+function ensureAndGetIsaFile(slug: string): string {
+  const dir = resolve(paths.projectHistory(), slug);
+  mkdirSync(dir, { recursive: true });
+  return resolve(dir, "ISA.md");
 }
 
 /**
  * Compute the default project slug from a cwd.
  *
  * Returns the FULL last path segment, lowercased, with non-[a-z0-9_-] chars
- * collapsed to a single hyphen. Critically: never split on `-` or any
- * separator within the basename. `/repos/portable-agent-layer` →
- * `portable-agent-layer`, NOT `layer`.
+ * collapsed to a single hyphen. Never splits on `-`. `/repos/portable-agent-layer`
+ * → `portable-agent-layer`, NOT `layer`.
  */
 export function defaultSlug(cwd: string): string {
   const base = basename(resolve(cwd));
@@ -83,8 +130,6 @@ export function defaultSlug(cwd: string): string {
 
 /**
  * Heuristic: does this directory look like a project root (has a project marker)?
- * Used by the SessionStart loader to hint the AI when an unregistered cwd is
- * project-shaped, so registration can be suggested in conversation.
  */
 export function looksLikeProjectRoot(cwd: string): boolean {
   const cwdAbs = resolve(cwd);
@@ -92,56 +137,62 @@ export function looksLikeProjectRoot(cwd: string): boolean {
 }
 
 export function readAllProjects(): ProjectProgress[] {
-  const dir = progressDir();
-  if (!existsSync(dir)) return [];
+  const base = paths.projectHistory();
+  if (!existsSync(base)) return [];
   const out: ProjectProgress[] = [];
-  for (const file of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
-    try {
-      const parsed = JSON.parse(
-        readFileSync(resolve(dir, file), "utf-8")
-      ) as ProjectProgress;
-      if (parsed?.name && parsed?.path && parsed?.status) out.push(parsed);
-    } catch {
-      /* skip malformed */
-    }
+  for (const slug of readdirSync(base)) {
+    const file = resolve(base, slug, "ISA.md");
+    if (!existsSync(file)) continue;
+    const p = readProject(slug);
+    if (p) out.push(p);
   }
   return out;
 }
 
 export function readProject(name: string): ProjectProgress | null {
-  const file = progressFile(name);
+  const file = isaFilePath(name);
   if (!existsSync(file)) return null;
   try {
-    return JSON.parse(readFileSync(file, "utf-8")) as ProjectProgress;
+    const content = readFileSync(file, "utf-8");
+    const { meta, body } = parse<IsaMeta>(content);
+    if (!meta?.name || !meta?.path || !meta?.status) return null;
+    return { ...meta, ...extractSections(body) };
   } catch {
     return null;
   }
 }
 
 export function writeProject(p: ProjectProgress): void {
-  writeFileSync(progressFile(p.name), `${JSON.stringify(p, null, 2)}\n`, "utf-8");
+  const meta: Record<string, unknown> = {
+    name: p.name,
+    path: p.path,
+    status: p.status,
+    created: p.created,
+    updated: p.updated,
+  };
+  if (p.next?.length) meta.next = p.next;
+  if (p.blockers?.length) meta.blockers = p.blockers;
+  if (p.handoff) meta.handoff = p.handoff;
+  writeFileSync(ensureAndGetIsaFile(p.name), stringify(meta, buildBody(p)), "utf-8");
 }
 
 export function deleteProject(name: string): boolean {
-  const file = progressFile(name);
+  const file = isaFilePath(name);
   if (!existsSync(file)) return false;
   unlinkSync(file);
+  try {
+    rmdirSync(resolve(paths.projectHistory(), name));
+  } catch {
+    /* dir not empty or already gone */
+  }
   return true;
 }
 
 /**
  * Resolve `cwd` to the registered project that contains it, if any.
  *
- * Rules:
- *  - Exact-match registered path → that project.
- *  - Descendant of exactly one registered path → that project.
- *  - Descendant of multiple (nested) → longest registered path wins.
- *  - Ancestor of registered project (parent-dir browse mode) → null.
- *  - Unrelated cwd → null.
- *
- * The parent-dir case is the load-bearing one: opening `/repos/` (an ancestor
- * of multiple registered repos) MUST return null so the Stop-hook auto-write
- * doesn't ambiguously bump one of N children.
+ * Parent-dir browse mode (cwd is an ancestor of a registered project) → null.
+ * Multiple nested projects → longest registered path wins.
  */
 export function resolveProjectFromCwd(
   cwd: string,
@@ -171,7 +222,7 @@ export function isStale(
  * Walk up from `cwd` looking for the nearest dir with a project marker.
  * Returns absolute path or null. Bounded at 12 levels to avoid runaway walks.
  */
-export function findProjectRoot(cwd: string): string | null {
+function findProjectRoot(cwd: string): string | null {
   let dir = resolve(cwd);
   const fsRoot = parsePath(dir).root;
   for (let i = 0; i < 12; i++) {
@@ -199,15 +250,9 @@ const MAX_INLINE_BULLETS = 3;
 /**
  * Format the SessionStart "Active Projects" section.
  *
- * Output is empty when there's nothing to say (no active/paused projects AND
- * no project-shaped unregistered cwd). When non-empty, includes:
- *  - A `## Active Projects` block listing every active/paused project
- *  - Full Objectives / Next / Blockers detail ONLY for the cwd-resolved project
- *    (`→ here`); every other project renders as a one-liner with next/blocker
- *    counts, to keep the section bounded as the project corpus grows
- *  - A `⚠ stale` flag for projects updated > threshold days ago
- *  - A trailing AI-visible hint when cwd resolves to no project but
- *    `findProjectRoot(cwd)` reveals a project-shaped ancestor
+ * For the cwd-resolved project (`→ here`): full detail with Context, Objectives
+ * (from goal section), Next, and Blockers. For all others: compact one-liner with
+ * next/blocker counts only. Stale flag (>14d) and browse-mode hint included.
  */
 export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
   const all = readAllProjects();
@@ -223,8 +268,7 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
   const lines: string[] = [];
 
   if (visible.length > 0) {
-    lines.push("## Active Projects");
-    lines.push("");
+    lines.push("## Active Projects", "");
     const sorted = [...visible].sort((a, b) => b.updated.localeCompare(a.updated));
     for (const p of sorted) {
       const ago = formatAgo(p.updated);
@@ -235,23 +279,47 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
 
       if (isResolved) {
         lines.push(`- **${p.name}** (${statusPrefix}${ago})${stale}${here}`);
-        if (p.facts?.length) {
-          lines.push(`  Facts: ${p.facts.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
+        if (p.context) {
+          const bullets = p.context
+            .split("\n")
+            .map((l) => l.replace(/^[-*]\s*/, "").trim())
+            .filter(Boolean);
+          lines.push(`  Facts: ${bullets.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
+        }
+        if (p.goal) {
+          const bullets = p.goal
+            .split("\n")
+            .map((l) => l.replace(/^[-*]\s*/, "").trim())
+            .filter(Boolean);
+          lines.push(`  Objectives: ${bullets.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
         }
-        if (p.objectives?.length) {
-          lines.push(
-            `  Objectives: ${p.objectives.slice(0, MAX_INLINE_BULLETS).join("; ")}`
-          );
+        if (p.constraints) {
+          const bullets = p.constraints
+            .split("\n")
+            .map((l) => l.replace(/^[-*]\s*/, "").trim())
+            .filter(Boolean);
+          lines.push(`  Constraints: ${bullets.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
         }
-        if (p.next_steps?.length) {
-          lines.push(`  Next: ${p.next_steps.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
+        if (p.next?.length) {
+          lines.push(`  Next: ${p.next.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
         }
         if (p.blockers?.length) {
           lines.push(`  Blockers: ${p.blockers.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
         }
+        if (p.criteria) {
+          const openIscs = p.criteria
+            .split("\n")
+            .filter((l) => /^-\s+\[ \]\s+ISC-\d+:/i.test(l))
+            .map((l) => l.replace(/^-\s+\[ \]\s+/, "").trim());
+          if (openIscs.length > 0) {
+            lines.push(
+              `  Open ISCs (${openIscs.length}): ${openIscs.slice(0, MAX_INLINE_BULLETS).join("; ")}`
+            );
+          }
+        }
       } else {
         const counts: string[] = [];
-        if (p.next_steps?.length) counts.push(`${p.next_steps.length} next`);
+        if (p.next?.length) counts.push(`${p.next.length} next`);
         if (p.blockers?.length) counts.push(`${p.blockers.length} blockers`);
         const countsSuffix = counts.length > 0 ? ` — ${counts.join(", ")}` : "";
         lines.push(`- **${p.name}** (${statusPrefix}${ago})${countsSuffix}${stale}`);

package/src/hooks/lib/readme-sync.ts

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { palPkg } from "./paths";
 
-export interface SyncResult {
+interface SyncResult {
   ok: boolean;
   issues: string[];
 }

package/src/hooks/lib/relationship.ts

@@ -15,9 +15,9 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
 
-export type NoteType = "W" | "O" | "Session";
+type NoteType = "W" | "O" | "Session";
 
-export interface RelationshipNote {
+interface RelationshipNote {
   type: NoteType;
   text: string;
   confidence?: number;
@@ -31,18 +31,6 @@ function dailyFilePath(date: Date): string {
   return resolve(monthDir, `${yyyy}-${mm}-${dd}.md`);
 }
 
-/** @deprecated No longer called — relationship notes are written in ALGORITHM LEARN phase */
-export function hasSessionNotes(sessionId: string): boolean {
-  const filepath = dailyFilePath(new Date());
-  if (!existsSync(filepath)) return false;
-  try {
-    const content = readFileSync(filepath, "utf-8");
-    return content.includes(`<!-- session:${sessionId} -->`);
-  } catch {
-    return false;
-  }
-}
-
 /** Deduplicate notes against what's already in today's file */
 function dedup(notes: RelationshipNote[], filepath: string): RelationshipNote[] {
   if (!existsSync(filepath)) return notes;
@@ -77,7 +65,7 @@ export function appendNotes(notes: RelationshipNote[], sessionId?: string): void
 
   const timestamp = new Date().toTimeString().slice(0, 5);
   lines.push(`## ${timestamp}`);
-  if (sessionId) lines.push(`<!-- session:${sessionId} -->`);
+  if (sessionId) lines.push(`<!-- session:${sessionId} cwd:${process.cwd()} -->`);
 
   for (const note of fresh) {
     if (note.type === "O" && note.confidence !== undefined) {

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

@@ -17,7 +17,7 @@ import { palPkg, paths } from "./paths";
 import { similarity, tokenize } from "./text-similarity";
 import { readFramesForRetrieval } from "./wisdom";
 
-export const INDEX_VERSION = 1;
+const INDEX_VERSION = 1;
 
 export interface IndexedDoc {
   id: string;
@@ -29,6 +29,7 @@ export interface IndexedDoc {
   len: number;
   displayPrinciple: string;
   displayContext: string;
+  cwd?: string;
 }
 
 export interface RetrievalIndex {
@@ -116,6 +117,7 @@ export function buildIndex(): RetrievalIndex {
       len,
       displayPrinciple: f.principle,
       displayContext: f.context,
+      cwd: f.cwd || undefined,
     });
   }
 
@@ -151,7 +153,7 @@ export function buildIndex(): RetrievalIndex {
   };
 }
 
-export function writeIndex(index: RetrievalIndex): void {
+function writeIndex(index: RetrievalIndex): void {
   writeFileSync(paths.retrievalIndex(), JSON.stringify(index));
 }
 
@@ -182,7 +184,7 @@ export function isStale(index: RetrievalIndex): boolean {
 }
 
 /** Detached background rebuild — fire and forget, never throws. */
-export function spawnBackgroundRebuild(): void {
+function spawnBackgroundRebuild(): void {
   try {
     const script = resolve(palPkg(), "src", "hooks", "lib", "retrieval-index.ts");
     const child = spawn("bun", ["run", script, "--rebuild"], {

package/src/hooks/lib/retrieval.ts

@@ -18,7 +18,7 @@ const MAX_MATCHES = 2;
 const MAX_REMINDER_BYTES = 500;
 const PRINCIPLE_TRUNC = 200;
 
-export interface ScoredDoc {
+interface ScoredDoc {
   doc: IndexedDoc;
   score: number;
   confidence: number;
@@ -38,7 +38,7 @@ function ageDecay(ts: string): number {
 }
 
 /** Raw IDF-weighted overlap score, capped tf, sqrt-length-normalized. */
-export function scoreDoc(
+function scoreDoc(
   queryTerms: Set<string>,
   doc: IndexedDoc,
   df: Record<string, number>,
@@ -56,7 +56,7 @@ export function scoreDoc(
 }
 
 /** Upper bound: query treated as a doc with tf=1 per unique term. */
-export function selfScore(
+function selfScore(
   queryTerms: Set<string>,
   df: Record<string, number>,
   N: number
@@ -75,7 +75,7 @@ function scopeMatches(doc: IndexedDoc, scopeKey: string): boolean {
 
 /** Rank the index against `query`. Returns docs above the confidence threshold,
  *  scope-boosted and age-decayed, sorted high-to-low, capped at MAX_MATCHES. */
-export function rank(query: string, index: RetrievalIndex, cwd: string): ScoredDoc[] {
+function rank(query: string, index: RetrievalIndex, cwd: string): ScoredDoc[] {
   const queryTerms = extractKeywords(query);
   if (queryTerms.size === 0) return [];
 
@@ -92,7 +92,10 @@ export function rank(query: string, index: RetrievalIndex, cwd: string): ScoredD
   for (const doc of index.docs) {
     const raw = scoreDoc(queryTerms, doc, index.df, N);
     if (raw === 0) continue;
-    const scopeMatch = [...scopeTokens].some((t) => scopeMatches(doc, t));
+    // Exact cwd match when available; fingerprint heuristic for older captures.
+    const scopeMatch = doc.cwd
+      ? doc.cwd === cwd
+      : [...scopeTokens].some((t) => scopeMatches(doc, t));
     const boosted = raw * (scopeMatch ? SCOPE_BOOST : 1) * ageDecay(doc.ts);
     const confidence = boosted / self;
     if (confidence < CONFIDENCE_THRESHOLD) continue;
@@ -120,12 +123,8 @@ function formatAgo(ts: string): string {
 }
 
 function formatLine(s: ScoredDoc): string {
-  const tag =
-    s.doc.source === "wisdom"
-      ? `[${s.doc.displayContext}]`
-      : s.scopeMatch
-        ? "[project]"
-        : "[global]";
+  const scopeTag = s.scopeMatch ? "[project]" : "[global]";
+  const tag = s.doc.source === "wisdom" ? `[${s.doc.displayContext}]` : scopeTag;
   const text = s.doc.displayPrinciple || s.doc.displayContext || "";
   const principle = truncate(text, PRINCIPLE_TRUNC);
   if (s.doc.source === "wisdom") {
@@ -137,7 +136,7 @@ function formatLine(s: ScoredDoc): string {
 }
 
 /** Build the `<system-reminder>` block. Drops lowest-ranked lines until ≤500 bytes. */
-export function formatReminder(matches: ScoredDoc[]): string {
+function formatReminder(matches: ScoredDoc[]): string {
   if (matches.length === 0) return "";
   let lines = matches.map(formatLine);
 

package/src/hooks/lib/security.ts

@@ -4,7 +4,7 @@
  */
 
 /** Dangerous command patterns — always blocked */
-export const BLOCKED_COMMANDS: [RegExp, string][] = [
+const BLOCKED_COMMANDS: [RegExp, string][] = [
   [/rm\s+-rf\s+[/~]/, "Recursive delete of root or home"],
   [/mkfs\./, "Filesystem format"],
   [/dd\s+if=.*of=\/dev\//, "Raw disk write"],
@@ -16,7 +16,7 @@ export const BLOCKED_COMMANDS: [RegExp, string][] = [
 ];
 
 /** Hook-managed files — single source of truth */
-export const HOOK_MANAGED_FILES = [
+const HOOK_MANAGED_FILES = [
   "CLAUDE.md",
   "AGENTS.md",
   "ratings.jsonl",
@@ -40,7 +40,7 @@ export const HOOK_MANAGED_FILES = [
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */
-export const HOOK_MANAGED_DIRS = [
+const HOOK_MANAGED_DIRS = [
   "memory/signals",
   "memory/learning/failures",
   "memory/learning/session",
@@ -56,8 +56,11 @@ function escapeRegExp(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/** PAL-deployed dirs — engine-managed, overwritten on every `pal install` */
+const PAL_INSTALLED_DIRS_RE = /[/\\]\.pal[/\\](?:docs|skills|tools)[/\\]/;
+
 /** Paths that should never be written to */
-export const PROTECTED_PATHS: RegExp[] = [
+const PROTECTED_PATHS: RegExp[] = [
   /^\/etc\//,
   /^\/boot\//,
   /^\/System\//,
@@ -65,26 +68,21 @@ export const PROTECTED_PATHS: RegExp[] = [
   /\.gnupg\//,
   // Claude Code auto-memory — PAL owns memory; writes here indicate wrong system is being used
   /\.claude\/projects\/[^/]+\/memory\//,
+  PAL_INSTALLED_DIRS_RE,
   // Derived from HOOK_MANAGED_FILES — scoped to managed roots only
   ...HOOK_MANAGED_FILES.map(
     (name) =>
-      new RegExp(`[/\\\\]\\.(?:pal|claude|agents|cursor)[/\\\\].*${escapeRegExp(name)}$`)
+      new RegExp(
+        String.raw`[/\\]\.(?:pal|claude|agents|cursor)[/\\].*${escapeRegExp(name)}$`
+      )
   ),
 ];
 
-/** Patterns that warrant a warning (logged but not blocked) */
-export const WARN_COMMANDS: RegExp[] = [
-  /git\s+push\s+.*--force/,
-  /git\s+reset\s+--hard/,
-  /drop\s+(?:table|database)/i,
-  /truncate\s+table/i,
-];
-
 /** Roots where managed files/dirs are protected (user state, not repo templates) */
 const MANAGED_ROOTS = [".pal/", ".claude/", ".agents/", ".config/opencode/", ".cursor/"];
 
 function isUnderManagedRoot(path: string): boolean {
-  const normalized = path.replace(/\\/g, "/");
+  const normalized = path.replaceAll("\\", "/");
   return MANAGED_ROOTS.some(
     (root) => normalized.includes(`/${root}`) || normalized.includes(`\\.${root}`)
   );
@@ -104,7 +102,7 @@ export function checkBashCommand(cmd: string): string | null {
   const segments = cmd.split(/[|;&&]/).map((s) => s.trim());
   for (const name of HOOK_MANAGED_FILES) {
     const pattern = new RegExp(
-      `\\.(?:pal|claude|agents|cursor|config/opencode)[/\\\\]\\S*${escapeRegExp(name)}`
+      String.raw`\.(?:pal|claude|agents|cursor|config/opencode)[/\\]\S*${escapeRegExp(name)}`
     );
     const managed = segments.filter((s) => pattern.test(s));
     if (managed.length > 0 && !managed.every((s) => READ_ONLY_COMMANDS.test(s))) {
@@ -113,7 +111,7 @@ export function checkBashCommand(cmd: string): string | null {
   }
   for (const dir of HOOK_MANAGED_DIRS) {
     const pattern = new RegExp(
-      `\\.(?:pal|claude|agents|cursor|config/opencode)[/\\\\]\\S*${escapeRegExp(dir)}`
+      String.raw`\.(?:pal|claude|agents|cursor|config/opencode)[/\\]\S*${escapeRegExp(dir)}`
     );
     const managed = segments.filter((s) => pattern.test(s));
     if (managed.length > 0 && !managed.every((s) => READ_ONLY_COMMANDS.test(s))) {
@@ -125,7 +123,7 @@ export function checkBashCommand(cmd: string): string | null {
 
 /** Check a file path against protected patterns. Returns a reason string or null. */
 export function checkFilePath(filePath: string): string | null {
-  const normalized = filePath.replace(/\\/g, "/");
+  const normalized = filePath.replaceAll("\\", "/");
   // Check hook-managed files — only under managed roots (not repo templates)
   if (isUnderManagedRoot(normalized)) {
     const matchedFile = HOOK_MANAGED_FILES.find((name) =>
@@ -140,7 +138,13 @@ export function checkFilePath(filePath: string): string | null {
   if (matchedDir) {
     return `${matchedDir}/ is managed automatically by hooks — do not edit directly`;
   }
-  // Check system-protected paths
+  // PAL-deployed dirs — edit source in the PAL repo, not the installed copy
+  if (PAL_INSTALLED_DIRS_RE.test(normalized)) {
+    const match = new RegExp(/\.pal[/\\](docs|skills|tools)/).exec(normalized);
+    const dir = match ? match[1] : "docs/skills/tools";
+    return `~/.pal/${dir}/ is managed by 'pal install' — edit the source in the PAL repo instead`;
+  }
+  // Check remaining system-protected paths
   if (PROTECTED_PATHS.some((pattern) => pattern.test(filePath))) {
     return `Protected path: ${filePath}`;
   }

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

@@ -15,7 +15,7 @@ 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 {
+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. */
@@ -65,7 +65,9 @@ export function loadSynthesisRecommendations(): string {
 
         const content = readFileSync(resolve(monthDir, files[0]), "utf-8");
 
-        const recMatch = content.match(/## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/);
+        const recMatch = new RegExp(
+          /## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/
+        ).exec(content);
         if (!recMatch?.[1]?.trim()) continue;
 
         const recs = recMatch[1]

package/src/hooks/lib/session-names.ts

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { paths } from "./paths";
 
-export interface SessionNames {
+interface SessionNames {
   [sessionId: string]: string;
 }
 

package/src/hooks/lib/settings.ts

@@ -11,7 +11,7 @@ import { paths } from "./paths";
 
 // ── Types ──
 
-export interface Identity {
+interface Identity {
   ai: { name: string; fullName: string; displayName: string; catchphrase: string };
   principal: { name: string; timezone: string };
 }