portable-agent-layer 0.47.0 → 0.48.0

package/README.md

@@ -86,6 +86,7 @@ pal cli status        # check your setup
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
+| `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 
 ### Target flags
 

package/assets/skills/create-skill/SKILL.md

@@ -57,7 +57,12 @@ The `description` should state **both what the skill does and when to invoke it*
    pal cli skill link <name>
    ```
    This creates the per-skill discovery symlink in each installed agent's skills directory (Claude Code, Cursor, Copilot, Codex); opencode discovers it automatically via `~/.pal/skills/`.
-6. Validate before declaring done:
+6. Run the doctor and resolve every error it reports:
+   ```bash
+   pal cli skill doctor <name>
+   ```
+   It checks the mechanical rules (folder/file-name match, name length/charset, description length, point-of-view, body length, reference depth). Fix all `✗` errors; weigh each `⚠` warning. A name/folder mismatch or a misnamed file makes the skill silently fail to load, so never skip this.
+7. Validate the rest by hand — the doctor can't judge these:
    - **Trigger clarity** — could a model decide *not* to invoke this from the description alone? If so, tighten it.
    - **Step concreteness** — every step has a verb and an object.
    - **Output specification** — the caller knows what they get back.

package/assets/templates/PAL/ALGORITHM.md

@@ -165,6 +165,18 @@ Refine criteria if the pressure test reveals gaps. Add criteria for uncovered fa
 - Decide execution order — what's serial, what can parallelize
 - **Extended+:** use EnterPlanMode for user alignment before executing
 
+**Grounding Gate — verify the premises before EXECUTE.**
+
+Don't just *list* what must be true — actively confirm the load-bearing facts the criteria rest on. For each premise (a reported behavior, a provider/API contract, an external tool's CLI, a file's contents, a claim about system state):
+- **Reproduce** the reported behavior before designing a fix — no fix on an unreproduced bug.
+- **Fetch the authoritative source** (live docs, the actual file, `gh api`) before asserting how something works.
+- **Probe the dependency/contract** (tool availability, MCP account, env var, DB connectivity, exact CLI) before building on it.
+- **Confirm one concrete artifact** (a commit, a shebang, a line of output) behind any external claim.
+
+No criterion may rest on an unverified premise. If a premise can't be verified now, mark it explicitly as an assumption and add a criterion to check it during EXECUTE. After 2 failed attempts at the same sub-problem, stop and re-ground — re-run OBSERVE rather than iterating on a bad premise.
+
+Output: `🧭 GROUNDING: [premises verified, or assumptions flagged]`
+
 ### ━━━ ⚡ EXECUTE ━━━ 3/5
 
 Do the work. Invoke selected capabilities via tool calls.
@@ -217,9 +229,11 @@ Focus: reasoning approach, problem decomposition, anticipation, blind spots.
 
 ```bash
 bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed N --failed N --sentiment 1-10 \
-  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection" --scope general
 ```
 
+Set `--scope task-specific` when the Q2 idea is bound to this one task (e.g. a criterion that only matters for the specific file, API, or dataset you were handling) and would not generalize to the algorithm; use `general` (the default) for reusable structural improvements. This keeps the algorithm-update synthesis focused on changes worth folding into ALGORITHM.md.
+
 **3. Relationship note** — write one Session entry capturing what was done this session:
 
 ```bash
@@ -316,6 +330,7 @@ Only write if the insight is **genuine and reusable** — not every session prod
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
 🧠 PREMORTEM: [failure modes]
+🧭 GROUNDING: [premises verified, or assumptions flagged]
 📐 APPROACH: [execution plan]
 
 ━━━ ⚡ EXECUTE ━━━ 3/5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -17,6 +17,7 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
+ *   skill doctor <name>               Evaluate a skill against the authoring best practices
  */
 
 import { spawnSync } from "node:child_process";
@@ -242,6 +243,7 @@ function showHelp() {
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
+    pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)

package/src/cli/skill.ts

@@ -1,15 +1,30 @@
 /**
  * pal cli skill — manage personal skills under ~/.pal/skills/.
  *
- *   pal cli skill link <name>   Link an existing ~/.pal/skills/<name>/ into
- *                               every installed agent so it is discoverable.
+ *   pal cli skill link <name>     Link an existing ~/.pal/skills/<name>/ into
+ *                                 every installed agent so it is discoverable.
+ *   pal cli skill doctor <name>   Evaluate ~/.pal/skills/<name>/ against the
+ *                                 skill-authoring best practices.
  */
 
+import { resolve } from "node:path";
+import { palHome } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
+import { formatReport, lintSkill } from "../tools/skill-doctor";
 
 export async function runSkill(args: string[]): Promise<number> {
   const [sub, name] = args;
 
+  if (sub === "doctor") {
+    if (!name) {
+      log.error("Usage: pal cli skill doctor <name>");
+      return 1;
+    }
+    const report = lintSkill(resolve(palHome(), "skills", name));
+    console.log(formatReport(report));
+    return report.errors > 0 ? 1 : 0;
+  }
+
   if (sub === "link") {
     if (!name) {
       log.error("Usage: pal cli skill link <name>");
@@ -35,6 +50,6 @@ export async function runSkill(args: string[]): Promise<number> {
     }
   }
 
-  log.error("Usage: pal cli skill link <name>");
+  log.error("Usage: pal cli skill <link|doctor> <name>");
   return 1;
 }

package/src/hooks/lib/algorithm-review.ts

@@ -0,0 +1,85 @@
+/**
+ * Algorithm-review cadence — decides when to nudge the MAINTAINER to run an
+ * `/algorithm-update` session (fold accumulated Q2 reflections into ALGORITHM.md).
+ *
+ * Maintainer-only by construction: the nudge fires solely in a PAL repo checkout,
+ * detected by the presence of the repo-only `.agents/skills/algorithm-update`
+ * skill. That path never ships to downstream installs — package.json `files`
+ * lists only `src/` and `assets/`, so `.agents/` is absent everywhere except a
+ * source checkout. Downstream users therefore never see this nudge.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { readReflections } from "./learning-store";
+import { palPkg, paths } from "./paths";
+
+const NUDGE_MIN_COUNT = 25;
+const NUDGE_MIN_DAYS = 7;
+const DAY_MS = 86_400_000;
+
+function markFile(): string {
+  return resolve(paths.state(), "algorithm-review.json");
+}
+
+export function readReviewMark(): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(markFile(), "utf-8"));
+    return typeof parsed.lastReviewedTs === "string" ? parsed.lastReviewedTs : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeReviewMark(ts: string): void {
+  writeFileSync(markFile(), `${JSON.stringify({ lastReviewedTs: ts }, null, 2)}\n`);
+}
+
+/** True only in a maintainer repo checkout — the repo-only update skill is present. */
+export function isMaintainerEnv(): boolean {
+  return existsSync(
+    resolve(palPkg(), ".agents", "skills", "algorithm-update", "SKILL.md")
+  );
+}
+
+/** Count reflections newer than the last review mark (all of them, if never reviewed). */
+export function countUnreviewed(mark: string | null = readReviewMark()): number {
+  const reflections = readReflections(paths.reflectionsFile());
+  if (!mark) return reflections.length;
+  const cutoff = new Date(mark).getTime();
+  return reflections.filter((r) => r.ts && new Date(r.ts).getTime() > cutoff).length;
+}
+
+export interface ReviewNudge {
+  count: number;
+  sinceDays: number;
+  since: string | null;
+}
+
+/**
+ * Nudge data when BOTH thresholds are met (≥25 new AND ≥7 days) in a maintainer
+ * env, else null. `now` is injected for testability.
+ */
+export function algorithmReviewNudge(now: Date): ReviewNudge | null {
+  if (!isMaintainerEnv()) return null;
+  const mark = readReviewMark();
+  const count = countUnreviewed(mark);
+  if (count < NUDGE_MIN_COUNT) return null;
+  const sinceDays = mark
+    ? Math.floor((now.getTime() - new Date(mark).getTime()) / DAY_MS)
+    : Number.POSITIVE_INFINITY;
+  if (sinceDays < NUDGE_MIN_DAYS) return null;
+  return { count, sinceDays, since: mark };
+}
+
+/** Formatted nudge section for the session reminder, or "" when it shouldn't fire. */
+export function loadAlgorithmReviewNudge(now: Date = new Date()): string {
+  const n = algorithmReviewNudge(now);
+  if (!n) return "";
+  const since = n.since ? new Date(n.since).toISOString().slice(0, 10) : "the start";
+  const age = Number.isFinite(n.sinceDays) ? `, ${n.sinceDays}d` : "";
+  return [
+    "## Algorithm Review Due",
+    `🔧 ${n.count} new algorithm reflections since ${since}${age} — run \`/algorithm-update\` to fold the recurring ones into ALGORITHM.md.`,
+  ].join("\n");
+}

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")),

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/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);

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

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+/**
+ * algorithm-synthesize — surface the Q2 field ("what a smarter algorithm would
+ * have done") across algorithm reflections, pre-sorted into candidate areas, to
+ * drive the periodic algorithm-update session: the loop from collected
+ * reflections back into ALGORITHM.md itself.
+ *
+ * IMPORTANT — the keyword BUCKETS are a *heuristic pre-sort hint only*, biased to
+ * the current model's English phrasing. They are NOT the clustering authority:
+ * another model wording the same idea differently ("double-check the assumption"
+ * vs "verify the premise") will not match. The real clustering is semantic, done
+ * by the model reading this report in the session. Therefore the tool NEVER drops
+ * data — every unmatched Q2 is surfaced in full under "Unbucketed", so nothing is
+ * invisible even when (especially when) the keyword sort misses or mis-sorts it.
+ *
+ * Library:  import { synthesizeAlgorithm, formatAlgorithmReport } from ".../algorithm-synthesize"
+ * Script:   bun src/tools/agent/algorithm-synthesize.ts [--since <ISO>] [--json]
+ */
+
+import { parseArgs } from "node:util";
+import { readReflections } from "../../hooks/lib/learning-store";
+import { paths } from "../../hooks/lib/paths";
+
+/** Algorithm areas a Q2 idea can target, mapped to ALGORITHM.md structure. */
+const BUCKETS: { key: string; label: string; patterns: RegExp }[] = [
+  {
+    key: "verify-gate",
+    label: "Establish grounding before acting (verify a fact / prerequisite first)",
+    patterns:
+      /pre-?check|pre-?mortem|premise|primary source|verif\w+|reproduce|before (writ|cod|propos|assert|implement|build|run|any|attempt|fetch|explor)|dependency scan|sanity-check|confirm .* before|prerequisite|gate (in|before)|trace .* first|check\w* .* before|anchor on|upfront|connectivity before|resolve .* before|triangulat|contradiction-detection|credibility gate|escalation|after \d+ (failed|iteration)/i,
+  },
+  {
+    key: "criteria",
+    label: "Criteria quality (atomicity, splitting, coverage, anti-criteria)",
+    patterns: /criteri|atomic|anti-criter|split .* criter|a .* criterion|enumerate/i,
+  },
+  {
+    key: "capability",
+    label: "Capability selection (plan mode, subagents, parallelism, research)",
+    patterns:
+      /capabilit|plan ?mode|askuser|sub-?agent|parallel|in one (agent|batch)|research|worktree/i,
+  },
+  {
+    key: "read-first",
+    label: "Read existing code/docs first (prior-artifact / context scan)",
+    patterns:
+      /read (the|existing|both)|inspect|prior-?artifact|existing (code|repo|hook|target)|grep|survey .* (before|first)/i,
+  },
+  {
+    key: "phase-structure",
+    label: "Phase structure (OBSERVE / PLAN / EXECUTE / VERIFY / LEARN ordering)",
+    patterns:
+      /observe|\bplan phase\b|execute|\bverify phase\b|\blearn phase\b|between (observe|plan|execute|verify)|new phase|a .* phase\b/i,
+  },
+  {
+    key: "scope",
+    label: "Scope & altitude (minimal change, avoid over-engineering)",
+    patterns: /scope|altitude|minimal|over-?eng|too (broad|wide|much)|narrow/i,
+  },
+];
+
+interface AlgorithmBucket {
+  key: string;
+  label: string;
+  count: number;
+  avgSentiment: number;
+  projects: number;
+  quotes: string[];
+}
+
+export interface AlgorithmSynthesis {
+  /** Count of general Q2s clustered (task-specific ones are surfaced separately). */
+  total: number;
+  since: string | null;
+  buckets: AlgorithmBucket[];
+  /** Count of general Q2s the keyword pre-sort matched no bucket for. */
+  unbucketed: number;
+  /** Full deduped text of every unbucketed general Q2 — the safety net, never just a count. */
+  unbucketedQuotes: string[];
+  /** Count of Q2s tagged task-specific (excluded from clustering, kept for review). */
+  taskSpecific: number;
+  /** Full deduped text of task-specific Q2s — surfaced, never dropped. */
+  taskSpecificQuotes: string[];
+}
+
+function projectOf(cwd: string): string {
+  return cwd.split("/").filter(Boolean).pop() ?? "";
+}
+
+/**
+ * Cluster Q2 reflections into candidate algorithm-improvement areas. A Q2 may
+ * land in multiple buckets (ideas often span areas); `unbucketed` counts Q2s
+ * that matched none, so blind spots in the bucket set stay visible.
+ */
+export function synthesizeAlgorithm(since?: Date): AlgorithmSynthesis {
+  const all = readReflections(paths.reflectionsFile());
+  const filtered = since ? all.filter((r) => r.ts && new Date(r.ts) >= since) : all;
+  const withQ2 = filtered.filter((r) => r.q2.trim());
+  // Cluster only general ideas; task-specific ones don't generalize to the
+  // algorithm, so surface them separately rather than polluting the buckets.
+  const q2s = withQ2.filter((r) => r.scope !== "task-specific");
+  const taskSpecificQuotes = [
+    ...new Set(withQ2.filter((r) => r.scope === "task-specific").map((r) => r.q2.trim())),
+  ];
+
+  const acc = new Map<
+    string,
+    { sentiments: number[]; projects: Set<string>; quotes: string[] }
+  >();
+  for (const b of BUCKETS) {
+    acc.set(b.key, { sentiments: [], projects: new Set(), quotes: [] });
+  }
+
+  let unbucketed = 0;
+  const unbucketedQuotes: string[] = [];
+  for (const r of q2s) {
+    const matched = BUCKETS.filter((b) => b.patterns.test(r.q2));
+    if (matched.length === 0) {
+      unbucketed += 1;
+      unbucketedQuotes.push(r.q2.trim());
+      continue;
+    }
+    for (const b of matched) {
+      const a = acc.get(b.key);
+      if (!a) continue;
+      a.sentiments.push(r.sentiment);
+      if (r.cwd) a.projects.add(projectOf(r.cwd));
+      a.quotes.push(r.q2.trim());
+    }
+  }
+
+  const buckets: AlgorithmBucket[] = BUCKETS.map((b) => {
+    const a = acc.get(b.key);
+    const sentiments = a?.sentiments ?? [];
+    const avg = sentiments.length
+      ? sentiments.reduce((s, n) => s + n, 0) / sentiments.length
+      : 0;
+    // Full deduped membership, longest (most specific) first. Not capped here —
+    // --json carries every member so nothing is lost; the human report caps the
+    // display per bucket. Zero-loss is the contract.
+    const quotes = [...new Set(a?.quotes ?? [])].sort((x, y) => y.length - x.length);
+    return {
+      key: b.key,
+      label: b.label,
+      count: sentiments.length,
+      avgSentiment: Math.round(avg * 10) / 10,
+      projects: a?.projects.size ?? 0,
+      quotes,
+    };
+  })
+    .filter((b) => b.count > 0)
+    .sort((x, y) => y.count - x.count);
+
+  return {
+    total: q2s.length,
+    since: since ? since.toISOString() : null,
+    buckets,
+    unbucketed,
+    unbucketedQuotes: [...new Set(unbucketedQuotes)],
+    taskSpecific: taskSpecificQuotes.length,
+    taskSpecificQuotes,
+  };
+}
+
+/** Render the synthesis as a markdown candidate-changes report. */
+export function formatAlgorithmReport(s: AlgorithmSynthesis): string {
+  const sinceLabel = s.since ? ` since ${s.since.slice(0, 10)}` : " (all time)";
+  const tsLabel = s.taskSpecific > 0 ? ` (+${s.taskSpecific} task-specific, below)` : "";
+  const lines = [
+    "# Algorithm Update — Candidate Changes",
+    `Source: ${s.total} general Q2 reflections${sinceLabel}${tsLabel}`,
+    "",
+    "> The buckets below are a keyword pre-sort hint (biased to current wording).",
+    "> Cluster semantically yourself — and read the Unbucketed section in full,",
+    "> since that is where wording the heuristic missed lands.",
+    "",
+    "## Pre-sorted candidate areas",
+  ];
+  s.buckets.forEach((b, i) => {
+    lines.push(
+      `### ${i + 1}. ${b.label}`,
+      `${b.count} reflections · avg sentiment ${b.avgSentiment}/10 · ${b.projects} project(s)`,
+      ""
+    );
+    for (const q of b.quotes.slice(0, 5)) lines.push(`- ${q}`);
+    if (b.quotes.length > 5) lines.push(`- _…+${b.quotes.length - 5} more (see --json)_`);
+    lines.push("");
+  });
+  lines.push(
+    `## Unbucketed — ${s.unbucketed} general Q2s the pre-sort missed (cluster these by hand)`,
+    ""
+  );
+  for (const q of s.unbucketedQuotes) lines.push(`- ${q}`);
+  if (s.taskSpecific > 0) {
+    lines.push(
+      "",
+      `## Task-specific — ${s.taskSpecific} Q2s tagged not-generalizable (review, don't fold into ALGORITHM.md)`,
+      ""
+    );
+    for (const q of s.taskSpecificQuotes) lines.push(`- ${q}`);
+  }
+  return lines.join("\n");
+}
+
+if (import.meta.main) {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      since: { type: "string" },
+      json: { type: "boolean", default: false },
+    },
+  });
+  const since = values.since ? new Date(values.since) : undefined;
+  const result = synthesizeAlgorithm(since);
+  console.log(
+    values.json ? JSON.stringify(result, null, 2) : formatAlgorithmReport(result)
+  );
+}

package/src/tools/skill-doctor.ts

@@ -0,0 +1,254 @@
+/**
+ * skill-doctor — static evaluator for a SKILL.md against Anthropic's
+ * skill-authoring best practices. Checks only what is mechanically verifiable:
+ * name/description constraints, body length, point-of-view, and reference depth.
+ *
+ * Library:  import { lintSkill, formatReport } from ".../skill-doctor"
+ * Script:   bun src/tools/skill-doctor.ts <skill-dir-or-name>
+ *           (resolves a path, or a name under ~/.pal/skills/)
+ * CLI:      pal cli skill doctor <name>   (see src/cli/skill.ts)
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { palHome } from "../hooks/lib/paths";
+
+type Level = "pass" | "warn" | "error";
+
+interface DoctorFinding {
+  level: Level;
+  check: string;
+  message: string;
+}
+
+export interface DoctorReport {
+  dir: string;
+  name: string | null;
+  findings: DoctorFinding[];
+  errors: number;
+  warnings: number;
+}
+
+interface ParsedSkill {
+  name: string | null;
+  description: string | null;
+  body: string;
+}
+
+const RESERVED_WORDS = ["anthropic", "claude"];
+const MAX_NAME = 64;
+const MAX_DESCRIPTION = 1024;
+const MAX_BODY_LINES = 500;
+
+/** Split a SKILL.md into frontmatter fields and body. */
+function parseSkill(content: string): ParsedSkill {
+  const parts = content.split(/^---\s*$/m);
+  if (parts.length < 3) {
+    return { name: null, description: null, body: content };
+  }
+  const frontmatter = parts[1];
+  const body = parts.slice(2).join("---");
+  const name = /^name:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
+  const description = /^description:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
+  return { name, description, body };
+}
+
+/** Remove fenced and inline code so prose checks don't trip on examples. */
+function stripCode(s: string): string {
+  return s.replace(/```[\s\S]*?```/g, "").replace(/`[^`]*`/g, "");
+}
+
+/**
+ * Evaluate the skill at `skillDir` (a folder containing SKILL.md) and return a
+ * structured report. Hard rules from Anthropic's validation surface as errors;
+ * best-practice nudges surface as warnings.
+ */
+export function lintSkill(skillDir: string): DoctorReport {
+  const findings: DoctorFinding[] = [];
+  const add = (level: Level, check: string, message: string) =>
+    findings.push({ level, check, message });
+
+  if (!existsSync(skillDir)) {
+    add("error", "structure", `No skill directory at ${skillDir}`);
+    return { dir: skillDir, name: null, findings, errors: 1, warnings: 0 };
+  }
+
+  // The runtime only loads a file named exactly `SKILL.md`. On case-insensitive
+  // filesystems (macOS, Windows) `existsSync` would accept `skill.md`, so match
+  // the real on-disk entry, not a case-folded path.
+  const skillFile = readdirSync(skillDir).find((e) => e.toLowerCase() === "skill.md");
+  if (!skillFile) {
+    add("error", "structure", `No SKILL.md found in ${skillDir}`);
+    return { dir: skillDir, name: null, findings, errors: 1, warnings: 0 };
+  }
+  skillFile === "SKILL.md"
+    ? add("pass", "file.name", "skill file is named SKILL.md")
+    : add(
+        "error",
+        "file.name",
+        `skill file is "${skillFile}" — must be exactly "SKILL.md" or the skill is silently ignored`
+      );
+
+  const { name, description, body } = parseSkill(
+    readFileSync(resolve(skillDir, skillFile), "utf-8")
+  );
+
+  // The runtime keys a skill by its folder name; a mismatched frontmatter `name`
+  // makes the skill silently fail to load.
+  const folder = basename(skillDir);
+  if (name) {
+    name === folder
+      ? add("pass", "name.folder", `matches folder "${folder}"`)
+      : add(
+          "error",
+          "name.folder",
+          `name "${name}" must equal the folder name "${folder}" verbatim — otherwise the skill is silently ignored`
+        );
+  }
+
+  // ── name ──
+  if (!name) {
+    add("error", "name", "Missing `name` in frontmatter");
+  } else {
+    name.length <= MAX_NAME
+      ? add("pass", "name.length", `${name.length}/${MAX_NAME} chars`)
+      : add("error", "name.length", `${name.length} chars exceeds ${MAX_NAME}`);
+    /^[a-z0-9-]+$/.test(name)
+      ? add("pass", "name.charset", "lowercase letters, numbers, hyphens only")
+      : add(
+          "error",
+          "name.charset",
+          `"${name}" must be lowercase a-z, 0-9, hyphens only`
+        );
+    const reserved = RESERVED_WORDS.find((w) => name.toLowerCase().includes(w));
+    reserved
+      ? add("error", "name.reserved", `contains reserved word "${reserved}"`)
+      : add("pass", "name.reserved", "no reserved words");
+  }
+
+  // ── description ──
+  if (!description) {
+    add("error", "description", "Missing `description` in frontmatter");
+  } else {
+    description.length <= MAX_DESCRIPTION
+      ? add(
+          "pass",
+          "description.length",
+          `${description.length}/${MAX_DESCRIPTION} chars`
+        )
+      : add(
+          "error",
+          "description.length",
+          `${description.length} chars exceeds ${MAX_DESCRIPTION}`
+        );
+    /<[^>]+>/.test(description)
+      ? add(
+          "warn",
+          "description.xml",
+          "contains angle-bracket content — Anthropic disallows XML tags; rephrase placeholders like <x> in prose"
+        )
+      : add("pass", "description.xml", "no XML tags");
+    /\bwhen/i.test(description)
+      ? add("pass", "description.trigger", "states when to use the skill")
+      : add(
+          "warn",
+          "description.trigger",
+          "no 'when to use' trigger — add 'Use when …' so the dispatcher can match it"
+        );
+    /\b(I can|I['’]ll|I will|I help|you can|you will|you could|you['’]ll)\b/i.test(
+      description
+    )
+      ? add(
+          "warn",
+          "description.pov",
+          "reads first/second person — write descriptions in third person (e.g. 'Processes…', 'Generates…')"
+        )
+      : add("pass", "description.pov", "third person");
+  }
+
+  // ── body ──
+  const bodyLines = body.split("\n").length;
+  bodyLines <= MAX_BODY_LINES
+    ? add("pass", "body.length", `${bodyLines}/${MAX_BODY_LINES} lines`)
+    : add(
+        "warn",
+        "body.length",
+        `${bodyLines} lines exceeds ${MAX_BODY_LINES} — split into reference files`
+      );
+
+  const prose = stripCode(body);
+  /\b(I['’]m|I will|I['’]ll|in my experience|my workflow|I wrote|I created)\b/i.test(
+    prose
+  )
+    ? add(
+        "warn",
+        "body.pov",
+        "body uses first-person author voice — write it as second-person instructions to the assistant"
+      )
+    : add("pass", "body.pov", "instructional voice");
+
+  // ── reference depth (one level deep) ──
+  const linkRe = /\[[^\]]+\]\(([^)]+\.md)\)/g;
+  const hasMdLink = /\[[^\]]+\]\([^)]+\.md\)/;
+  let nested = false;
+  for (const m of body.matchAll(linkRe)) {
+    const target = m[1];
+    if (/^https?:/.test(target)) continue;
+    const targetPath = resolve(skillDir, target);
+    if (!existsSync(targetPath)) continue;
+    const refContent = readFileSync(targetPath, "utf-8");
+    if (hasMdLink.test(refContent)) {
+      nested = true;
+      add(
+        "warn",
+        "references.depth",
+        `${target} links to further .md files — keep references one level deep from SKILL.md`
+      );
+    }
+  }
+  if (!nested) add("pass", "references.depth", "references are one level deep");
+
+  // ── windows-style paths ──
+  /\b[\w.-]+\\[\w.-]+\.(py|ts|js|sh|md|json)\b/.test(body)
+    ? add("warn", "paths", "Windows-style backslash path found — use forward slashes")
+    : add("pass", "paths", "forward-slash paths");
+
+  const errors = findings.filter((f) => f.level === "error").length;
+  const warnings = findings.filter((f) => f.level === "warn").length;
+  return { dir: skillDir, name, findings, errors, warnings };
+}
+
+/** Render a report as a human-readable string. */
+export function formatReport(r: DoctorReport): string {
+  const icon = { pass: "✓", warn: "⚠", error: "✗" } as const;
+  const lines = [`skill-doctor: ${r.name ?? "(unparsed)"}  —  ${r.dir}`];
+  for (const f of r.findings) {
+    lines.push(`  ${icon[f.level]} ${f.check}: ${f.message}`);
+  }
+  let verdict: string;
+  if (r.errors > 0) {
+    verdict = `FAIL — ${r.errors} error(s), ${r.warnings} warning(s)`;
+  } else if (r.warnings > 0) {
+    verdict = `OK with ${r.warnings} warning(s)`;
+  } else {
+    verdict = "PASS — all checks clean";
+  }
+  lines.push(`  ${verdict}`);
+  return lines.join("\n");
+}
+
+if (import.meta.main) {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.error("Usage: bun src/tools/skill-doctor.ts <skill-dir-or-name>");
+    process.exit(2);
+  }
+  let dir = resolve(arg);
+  if (!existsSync(resolve(dir, "SKILL.md"))) {
+    const byName = resolve(palHome(), "skills", arg);
+    if (existsSync(resolve(byName, "SKILL.md"))) dir = byName;
+  }
+  const report = lintSkill(dir);
+  console.log(formatReport(report));
+  process.exit(report.errors > 0 ? 1 : 0);
+}