portable-agent-layer 0.47.0 → 0.49.0

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);
+}