portable-agent-layer 0.21.0 → 0.22.0

package/README.md

@@ -111,14 +111,15 @@ pal cli install               # all available (default)
 
 | Variable | Description |
 |----------|-------------|
-| `ANTHROPIC_API_KEY` | Required for PAL's hook inference (sentiment analysis, session naming). Uses Haiku for low-cost background calls. |
+| `PAL_ANTHROPIC_API_KEY` | Required for PAL's hook inference (sentiment analysis, session naming). Uses Haiku for low-cost background calls. |
 
 ### Optional
 
 | Variable | Description |
 |----------|-------------|
-| `PAL_GEMINI_API_KEY` | For YouTube video analysis skill |
+| `PAL_GEMINI_API_KEY` | For YouTube video analysis and web search skill  |
 | `PAL_XAI_API_KEY` | For Grok real-time research skill (X/web search) |
+| `PAL_PERPLEXITY_API_KEY` | For Perplexity deep research skill |
 | `PAL_HOME` | Override user state directory (default: `~/.pal` or repo root) |
 | `PAL_PKG` | Override package root |
 | `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |

package/assets/skills/fyzz-chat-api/SKILL.md

@@ -4,7 +4,7 @@ description: Query Fyzz Chat conversations and projects via the REST API. Use wh
 argument-hint: <conversations|projects> [options]
 ---
 
-When you need to access the user's Fyzz Chat conversations or projects, use the `fyzz-api` CLI tool. The tool reads the API key from the `FYZZ_API_KEY` environment variable automatically — never attempt to read, print, or reference the API key or the env var directly.
+When you need to access the user's Fyzz Chat conversations or projects, use the `fyzz-api` CLI tool. The tool reads the API key from the `PAL_FYZZ_API_KEY` environment variable automatically — never attempt to read, print, or reference the API key or the env var directly.
 
 ## Available commands
 
@@ -31,8 +31,8 @@ bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- projects
 If the tool reports a missing API key:
 
 1. Ask the user to create one in Fyzz Chat → Settings → API Keys
-2. They should set `FYZZ_API_KEY` in their shell profile or in PAL's `settings.json` env section
-3. Optionally set `FYZZ_BASE_URL` (defaults to `http://localhost:3000`)
+2. They should set `PAL_FYZZ_API_KEY` in their shell profile or in PAL's `settings.json` env section
+3. Optionally set `PAL_FYZZ_BASE_URL` (defaults to `http://localhost:3000`)
 
 ## Guidelines
 

package/assets/skills/fyzz-chat-api/tools/fyzz-api.ts

@@ -2,7 +2,7 @@
 /**
  * Fyzz Chat API — CLI wrapper for programmatic conversation access.
  *
- * Reads the API key from FYZZ_API_KEY env var (never printed to stdout).
+ * Reads the API key from PAL_FYZZ_API_KEY env var (never printed to stdout).
  * Returns JSON responses from the Fyzz Chat REST API.
  *
  * Usage:
@@ -14,9 +14,9 @@
 import { parseArgs } from "node:util";
 
 function loadApiKey(): string {
-  const key = process.env.FYZZ_API_KEY;
+  const key = process.env.PAL_FYZZ_API_KEY;
   if (!key) {
-    console.error("Error: FYZZ_API_KEY environment variable is not set.");
+    console.error("Error: PAL_FYZZ_API_KEY environment variable is not set.");
     console.error("Set it in your shell profile or PAL settings.json env section.");
     process.exit(1);
   }
@@ -25,7 +25,7 @@ function loadApiKey(): string {
 
 async function apiFetch(path: string, params?: Record<string, string>): Promise<unknown> {
   const apiKey = loadApiKey();
-  const baseUrl = process.env.FYZZ_BASE_URL ?? "http://localhost:3000";
+  const baseUrl = process.env.PAL_FYZZ_BASE_URL ?? "http://localhost:3000";
 
   const url = new URL(`/api/v1${path}`, baseUrl);
   if (params) {

package/assets/templates/PAL/ALGORITHM.md

@@ -35,13 +35,55 @@ Format:
 
 Include at least one anti-criterion (C-A prefix).
 
-**3. Select capabilities:**
+**3. Capability audit:**
 
-Scan the available skills listing. Select skills and tools you'll invoke during EXECUTE. Selecting a capability = commitment to invoke it via tool call. Don't select what you won't use.
+Scan ALL 14 capabilities below. For each, assign exactly one disposition:
+- **USE** — will invoke during a specific phase. State which.
+- **DECLINE** — would help but not worth it for this task's scope.
+- **N/A** — genuinely irrelevant to this task.
+
+**A: Foundation**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 1 | Task Tool | TaskCreate, TaskUpdate, TaskList |
+| 2 | AskUserQuestion | Built-in tool |
+| 3 | Skills (ACTIVE SCAN) | Read `skill-index.json`, match triggers against task |
+
+**B: Thinking & Analysis**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 4 | Think (analysis router) | `think` skill |
+| 5 | First Principles | `first-principles` skill |
+| 6 | Council (multi-perspective) | `council` skill |
+| 7 | Plan Mode | EnterPlanMode tool |
+
+**C: Agents & Research**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 8 | Research (multi-agent) | `research` skill |
+| 9 | Subagents | Agent tool (Explore, Plan, general-purpose) |
+| 10 | Background agents | Agent tool with `run_in_background: true` |
+
+**D: Execution & Verification**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 11 | Git worktree isolation | `isolation: "worktree"` on Agent |
+| 12 | Test runner | `bun test`, vitest, jest, pytest |
+| 13 | Static analysis | `tsc --noEmit`, biome, eslint |
+| 14 | CLI probes | curl, diff, jq, exit codes |
+
+**Capability #3 (Skills) requires active scanning.** Read `skill-index.json` and match the task against skill triggers. "Skills — N/A" without evidence of scanning is an error.
 
 Output:
 ```
-🏹 CAPABILITIES: [list each selected skill/tool and why]
+🏹 CAPABILITIES (14/14):
+USE: [#, #, #] — [reason (phase: WHICH)]
+DECLINE: [#, #] — [reason]
+N/A: [rest]
 ```
 
 ### ━━━ 🧠 PLAN ━━━ 2/5
@@ -92,11 +134,25 @@ If any criteria failed, fix and re-verify before completing.
 
 Reflect on the work and capture reusable knowledge. Skip this phase when the work was trivial or purely mechanical.
 
-**1. Reflection** (one sentence each):
-- What would I do differently next time?
-- What would a better algorithm have done differently?
+**1. Algorithm Reflection** (one sentence each — reflect on ALGORITHM PERFORMANCE, not task subject matter):
+
+**Q1 — Self:** "What would I have done differently in this Algorithm run?"
+Focus: phase execution, criteria quality, capability selection decisions.
+
+**Q2 — Algorithm:** "What would a smarter algorithm have done differently?"
+Focus: structural improvements — missing phases, better gating, capability triggers, ISC patterns.
+
+**Q3 — AI:** "What would a fundamentally smarter AI have done differently?"
+Focus: reasoning approach, problem decomposition, anticipation, blind spots.
+
+**2. Reflection Log** — record algorithm performance:
+
+```bash
+bun ~/.agents/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"
+```
 
-**2. Wisdom Frame** — if the session produced a genuine, reusable insight:
+**3. Wisdom Frame** — if the session produced a genuine, reusable insight:
 
 ```bash
 bun ~/.agents/PAL/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]
@@ -118,7 +174,10 @@ Only write if the insight is **genuine and reusable** — not every session prod
 📋 CRITERIA:
 [criteria checklist]
 
-🏹 CAPABILITIES: [selected capabilities]
+🏹 CAPABILITIES (14/14):
+USE: [#, #] — [reason]
+DECLINE: [#] — [reason]
+N/A: [rest]
 
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
@@ -136,6 +195,9 @@ Only write if the insight is **genuine and reusable** — not every session prod
 🗣️ {{IDENTITY_NAME}}: [summary]
 
 ━━━ 📚 LEARN ━━━ 5/5
-🪞 REFLECT: [what I'd do differently]
+🪞 Q1 — Self: [what I'd do differently]
+🪞 Q2 — Algorithm: [structural improvement]
+🪞 Q3 — AI: [reasoning blind spot]
+📊 REFLECTION LOG: [appended to algorithm-reflections.jsonl]
 📝 WISDOM: [frame update if genuine insight, or "No new insight"]
 ```

package/assets/templates/PAL/WORK_TRACKING.md

@@ -1,14 +1,7 @@
 # Work Tracking
 
-PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured) and `memory/state/projects.json` (AI-managed).
+PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured).
 
 ## 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.
+Projects are managed in `telos/PROJECTS.md` and force-loaded at session startup via `pal-settings.json → loadAtStartup.files`.

package/package.json

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

package/src/cli/index.ts

@@ -377,9 +377,9 @@ function doctor(silent = false): DoctorResult {
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
     // API key checks
-    process.env.ANTHROPIC_API_KEY
-      ? ok("ANTHROPIC_API_KEY is set")
-      : fail("ANTHROPIC_API_KEY — not set (hooks need it for inference)");
+    process.env.PAL_ANTHROPIC_API_KEY
+      ? ok("PAL_ANTHROPIC_API_KEY is set")
+      : fail("PAL_ANTHROPIC_API_KEY — not set (hooks need it for inference)");
     process.env.PAL_GEMINI_API_KEY
       ? ok("PAL_GEMINI_API_KEY is set")
       : warn("PAL_GEMINI_API_KEY — not set (optional, for YouTube analysis)");

package/src/hooks/handlers/rating.ts

@@ -358,6 +358,6 @@ export async function captureRating(message: string, sessionId?: string): Promis
     return;
   }
 
-  // Path 2: Implicit sentiment (requires ANTHROPIC_API_KEY — inference silently no-ops without it)
+  // Path 2: Implicit sentiment (requires PAL_ANTHROPIC_API_KEY — inference silently no-ops without it)
   await handleImplicitSentiment(cleaned, sessionId);
 }

package/src/hooks/handlers/relationship.ts

@@ -52,8 +52,8 @@ export async function captureRelationship(
     return;
   }
 
-  if (!process.env.ANTHROPIC_API_KEY) {
-    logDebug("relationship", "Skipped: no ANTHROPIC_API_KEY");
+  if (!process.env.PAL_ANTHROPIC_API_KEY) {
+    logDebug("relationship", "Skipped: no PAL_ANTHROPIC_API_KEY");
     return;
   }
 

package/src/hooks/handlers/session-name.ts

@@ -42,7 +42,7 @@ export async function captureSessionName(
   logDebug("session-name", `Named from prompt: "${name}"`);
 
   // Spawn detached background process to upgrade with Haiku inference
-  if (!process.env.ANTHROPIC_API_KEY) return;
+  if (!process.env.PAL_ANTHROPIC_API_KEY) return;
   try {
     const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
     const child = spawn(

package/src/hooks/lib/context.ts

@@ -15,13 +15,7 @@ import { readSessionNames } from "./session-names";
 import { buildSetupPrompt, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
 import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
-import {
-  activeProjects,
-  readProjectHistory,
-  readSessions,
-  recentSessions,
-  staleProjects,
-} from "./work-tracking";
+import { readProjectHistory, readSessions, recentSessions } from "./work-tracking";
 
 interface PalSettings {
   loadAtStartup?: { files?: string[] };
@@ -83,44 +77,16 @@ export function loadActiveWork(): { text: string; summary: string | null } | nul
   try {
     const cwd = process.cwd();
     const allRecent = recentSessions(48);
-    const projects = activeProjects();
-    const stale = staleProjects(7);
 
-    if (allRecent.length === 0 && projects.length === 0) return null;
+    if (allRecent.length === 0) return null;
 
     const lines: string[] = [];
 
-    if (allRecent.length > 0) {
-      lines.push("## Recent Work (last 48h)");
-      for (const s of allRecent.slice(-10).reverse()) {
-        const ago = formatAgo(s.ts);
-        const here = s.cwd === cwd ? " *" : "";
-        lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
-      }
-    }
-
-    if (projects.length > 0) {
-      lines.push("", "### Active Projects");
-      for (const p of projects) {
-        const sessionCount = p.sessions.length;
-        const ago = formatAgo(p.updated);
-        lines.push(`- **${p.name}** (${sessionCount} sessions, last: ${ago})`);
-        if (p.nextSteps.length > 0) {
-          lines.push(`  Next: ${p.nextSteps[0]}`);
-        }
-        if (p.blockers.length > 0) {
-          lines.push(`  Blockers: ${p.blockers.join(", ")}`);
-        } else {
-          lines.push("  Blockers: None");
-        }
-      }
-    }
-
-    if (stale.length > 0) {
-      lines.push("", "### Stale Projects (>7d inactive)");
-      for (const p of stale) {
-        lines.push(`- **${p.name}** — last active ${formatAgo(p.updated)}`);
-      }
+    lines.push("## Recent Work (last 48h)");
+    for (const s of allRecent.slice(-10).reverse()) {
+      const ago = formatAgo(s.ts);
+      const here = s.cwd === cwd ? " *" : "";
+      lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
     }
 
     // Summary from most recent session

package/src/hooks/lib/graduation.ts

@@ -214,7 +214,7 @@ async function generateRecommendations(
   ratings: RatingsSummary | null
 ): Promise<string[]> {
   if (candidates.length === 0 && !ratings) return [];
-  if (!process.env.ANTHROPIC_API_KEY) {
+  if (!process.env.PAL_ANTHROPIC_API_KEY) {
     return candidates
       .slice(0, 3)
       .map(

package/src/hooks/lib/inference.ts

@@ -21,7 +21,7 @@ export interface InferenceResult {
 }
 
 export async function inference(opts: InferenceOptions): Promise<InferenceResult> {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
+  const apiKey = process.env.PAL_ANTHROPIC_API_KEY;
   if (!apiKey) return { success: false };
 
   const {

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

@@ -58,12 +58,12 @@ function extractEnvVars(): string[] {
     }
   }
 
-  // ANTHROPIC_API_KEY from inference.ts
+  // PAL_ANTHROPIC_API_KEY from inference.ts
   const inferenceFile = resolve(pkg, "src", "hooks", "lib", "inference.ts");
   if (existsSync(inferenceFile)) {
     const content = readFileSync(inferenceFile, "utf-8");
-    if (content.includes("ANTHROPIC_API_KEY")) {
-      vars.add("ANTHROPIC_API_KEY");
+    if (content.includes("PAL_ANTHROPIC_API_KEY")) {
+      vars.add("PAL_ANTHROPIC_API_KEY");
     }
   }
 

package/src/hooks/lib/security.ts

@@ -34,6 +34,8 @@ export const HOOK_MANAGED_FILES = [
   "debug.log.prev",
   "opinions.json",
   "pal-settings.json",
+  "skill-index.json",
+  "algorithm-reflections.jsonl",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */
@@ -45,7 +47,8 @@ export const HOOK_MANAGED_DIRS = [
   "memory/relationship",
   "memory/wisdom/state",
   "memory/projects",
-  ".agents/PAL",
+  ".agents/PAL/memory",
+  ".agents/PAL/telos",
 ];
 
 /** Escape a string for use in a RegExp */

package/src/hooks/lib/work-tracking.ts

@@ -1,12 +1,11 @@
 /**
- * Structured work tracking: session history + persistent projects.
+ * Structured work tracking: session history + per-project history.
  * Used by both Claude Code (StopOrchestrator) and opencode (plugin).
  */
 
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
-import { now } from "./time";
 
 // ── Session Records ──────────────────────────────────────────────
 
@@ -179,52 +178,3 @@ export function readProjectHistory(cwd: string, limit = 15): ProjectHistoryEntry
     return [];
   }
 }
-
-// ── Persistent Projects ──────────────────────────────────────────
-
-export interface Project {
-  id: string;
-  name: string;
-  created: string;
-  updated: string;
-  status: "active" | "paused" | "completed";
-  objectives: string[];
-  decisions: string[];
-  completed: string[];
-  blockers: string[];
-  nextSteps: string[];
-  handoff: string;
-  sessions: string[];
-}
-
-function projectsPath(): string {
-  return resolve(ensureDir(paths.state()), "projects.json");
-}
-
-export function readProjects(): Record<string, Project> {
-  const p = projectsPath();
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-export function writeProject(project: Project): void {
-  const projects = readProjects();
-  project.updated = now();
-  projects[project.id] = project;
-  writeFileSync(projectsPath(), JSON.stringify(projects, null, 2), "utf-8");
-}
-
-export function activeProjects(): Project[] {
-  return Object.values(readProjects()).filter((p) => p.status === "active");
-}
-
-export function staleProjects(days = 7): Project[] {
-  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
-  return Object.values(readProjects()).filter(
-    (p) => p.status === "active" && new Date(p.updated).getTime() < cutoff
-  );
-}

package/src/targets/claude/install.ts

@@ -15,6 +15,7 @@ import {
   countAgents,
   countMd,
   countSkills,
+  generateSkillIndex,
   loadSettingsTemplate,
   log,
   mergeSettings,
@@ -50,6 +51,7 @@ log.success("Merged PAL settings into settings.json");
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
 copySkills(skillsDir);
+generateSkillIndex();
 
 // --- Copy agents ---
 copyAgents();

package/src/targets/cursor/install.ts

@@ -12,6 +12,7 @@ import {
   copyPalDocs,
   copySkills,
   countSkills,
+  generateSkillIndex,
   loadCursorHooksTemplate,
   log,
   mergeCursorHooks,
@@ -44,6 +45,7 @@ log.success("Merged PAL hooks into hooks.json");
 // --- Symlink skills to ~/.cursor/skills/ ---
 const cursorSkillsDir = resolve(CURSOR_DIR, "skills");
 copySkills(cursorSkillsDir);
+generateSkillIndex();
 
 // --- Copy PAL system docs ---
 const palDocsCount = copyPalDocs();

package/src/targets/lib.ts

@@ -536,6 +536,99 @@ export function removeAgentsFromOpencode(ocAgentsDir: string): string[] {
   return removed;
 }
 
+// --- Skill Index ---
+
+interface SkillIndexEntry {
+  name: string;
+  description: string;
+  triggers: string[];
+}
+
+interface SkillIndex {
+  generated: string;
+  totalSkills: number;
+  skills: Record<string, SkillIndexEntry>;
+}
+
+/** Extract trigger keywords from a skill description */
+function extractTriggers(description: string): string[] {
+  // Extract "Use when ..." phrases and key terms
+  const triggers = new Set<string>();
+
+  const useWhen = description.match(/Use when\s+(.+?)(?:\.|$)/i);
+  if (useWhen) {
+    const words = useWhen[1]
+      .toLowerCase()
+      .split(/[,\s]+/)
+      .filter(
+        (w) =>
+          w.length > 3 &&
+          !["when", "this", "that", "with", "from", "about", "your", "the"].includes(w)
+      );
+    for (const w of words) triggers.add(w);
+  }
+
+  // Extract domain terms from full description
+  const terms = description
+    .toLowerCase()
+    .match(
+      /\b(research|analyze|extract|summarize|review|debug|reflect|council|debate|brainstorm|first.principles|security|pdf|youtube|telos|goals|projects|beliefs|challenges|opinion|skill|create)\b/g
+    );
+  if (terms) for (const t of terms) triggers.add(t);
+
+  return [...triggers];
+}
+
+/**
+ * Generate skill-index.json from installed skills in ~/.agents/skills/.
+ * Called during install after skills are symlinked.
+ */
+export function generateSkillIndex(): number {
+  if (!existsSync(AGENTS_SKILLS_DIR)) return 0;
+
+  const index: SkillIndex = {
+    generated: new Date().toISOString(),
+    totalSkills: 0,
+    skills: {},
+  };
+
+  for (const name of readdirSync(AGENTS_SKILLS_DIR)) {
+    const skillMd = resolve(AGENTS_SKILLS_DIR, name, "SKILL.md");
+    if (!existsSync(skillMd)) continue;
+
+    try {
+      const content = readFileSync(skillMd, "utf-8");
+      const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+
+      const fm = fmMatch[1];
+      const nameMatch = fm.match(/^name:\s*(.+)$/m);
+      const descMatch = fm.match(/^description:\s*"?(.+?)"?\s*$/m);
+      if (!nameMatch) continue;
+
+      const skillName = nameMatch[1].trim();
+      const description = descMatch?.[1]?.trim() ?? "";
+
+      index.skills[skillName] = {
+        name: skillName,
+        description,
+        triggers: extractTriggers(description),
+      };
+      index.totalSkills++;
+    } catch {
+      /* skip unreadable skills */
+    }
+  }
+
+  // Write to state directory
+  const stateDir = resolve(palHome(), "memory", "state");
+  mkdirSync(stateDir, { recursive: true });
+  writeJson(resolve(stateDir, "skill-index.json"), index);
+  log.info(`Skill index: ${index.totalSkills} skills indexed`);
+
+  return index.totalSkills;
+}
+
 /** Count skill subdirectories in ~/.agents/skills/ */
 export function countSkills(): number {
   if (!existsSync(AGENTS_SKILLS_DIR)) return 0;

package/src/targets/opencode/install.ts

@@ -12,6 +12,7 @@ import {
   copyPalDocs,
   copySkills,
   countSkills,
+  generateSkillIndex,
   log,
   writeJson,
 } from "../lib";
@@ -54,6 +55,7 @@ try {
 // --- 3. Install skills into ~/.agents/skills/ ---
 const claudeSkillsDir = resolve(platform.claudeDir(), "skills");
 copySkills(claudeSkillsDir);
+generateSkillIndex();
 log.success("Installed skills to ~/.agents/skills/");
 
 // --- 4. Install agents into ~/.config/opencode/agents/ ---

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

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/**
+ * AlgorithmReflect — Append structured algorithm reflections to JSONL.
+ *
+ * Records algorithm performance data after each LEARN phase.
+ * Creates a queryable dataset for improving the algorithm over time.
+ *
+ * Usage:
+ *   bun run tool:algorithm-reflect --task "description" --criteria 5 --passed 4 --failed 1 --sentiment 7 \
+ *     --q1 "Should have read the file before planning" \
+ *     --q2 "Could have parallelized the explore agents" \
+ *     --q3 "Missed the implicit constraint about cross-platform"
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { paths } from "../../hooks/lib/paths";
+
+// ── Types ──
+
+interface AlgorithmReflection {
+  timestamp: string;
+  task: string;
+  criteria_count: number;
+  criteria_passed: number;
+  criteria_failed: number;
+  sentiment: number;
+  q1: string;
+  q2: string;
+  q3: string;
+}
+
+// ── Core ──
+
+function reflectionsPath(): string {
+  const dir = resolve(paths.learning(), "reflections");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return resolve(dir, "algorithm-reflections.jsonl");
+}
+
+export function appendReflection(reflection: AlgorithmReflection): {
+  success: boolean;
+  message: string;
+  path: string;
+} {
+  const p = reflectionsPath();
+  const line = `${JSON.stringify(reflection)}\n`;
+  appendFileSync(p, line, "utf-8");
+
+  return {
+    success: true,
+    message: `Reflection logged: ${reflection.criteria_passed}/${reflection.criteria_count} passed, sentiment ${reflection.sentiment}/10`,
+    path: p,
+  };
+}
+
+// ── CLI ──
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      task: { type: "string" },
+      criteria: { type: "string" },
+      passed: { type: "string" },
+      failed: { type: "string" },
+      sentiment: { type: "string" },
+      q1: { type: "string" },
+      q2: { type: "string" },
+      q3: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+AlgorithmReflect — Log algorithm performance after LEARN phase
+
+Usage:
+  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
+    --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+
+Arguments:
+  --task        Brief task description
+  --criteria    Total criteria count
+  --passed      Criteria passed
+  --failed      Criteria failed
+  --sentiment   Implied satisfaction 1-10
+  --q1          Q1 — Self: what I'd do differently
+  --q2          Q2 — Algorithm: structural improvement
+  --q3          Q3 — AI: reasoning blind spot
+
+Output: algorithm-reflections.jsonl in memory/learning/reflections/
+`);
+    process.exit(0);
+  }
+
+  if (!values.task || !values.q1 || !values.q2 || !values.q3) {
+    console.error("Required: --task, --q1, --q2, --q3");
+    process.exit(1);
+  }
+
+  const reflection: AlgorithmReflection = {
+    timestamp: new Date().toISOString(),
+    task: values.task,
+    criteria_count: parseInt(values.criteria || "0", 10),
+    criteria_passed: parseInt(values.passed || "0", 10),
+    criteria_failed: parseInt(values.failed || "0", 10),
+    sentiment: Math.max(1, Math.min(10, parseInt(values.sentiment || "5", 10))),
+    q1: values.q1,
+    q2: values.q2,
+    q3: values.q3,
+  };
+
+  const result = appendReflection(reflection);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (import.meta.main) run();