portable-agent-layer 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -48,6 +48,7 @@
     "ai:fyzz-api": "bun run src/tools/fyzz-api.ts",
     "ai:pdf-download": "bun run src/tools/pdf-download.ts",
     "ai:youtube-analyze": "bun run src/tools/youtube-analyze.ts",
+    "tool:eval": "bun run src/tools/eval-principles.ts",
     "tool:graduate": "bun run src/tools/graduate.ts",
     "tool:patterns": "bun run src/tools/pattern-synthesis.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",

package/src/cli/index.ts

@@ -21,7 +21,6 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
-import { getPendingSuggestions } from "../hooks/lib/tags";
 import { log } from "../targets/lib";
 
 const allArgs = process.argv.slice(2);
@@ -361,18 +360,6 @@ function doctor(silent = false): DoctorResult {
       }
     }
 
-    // Pending tag suggestions
-    const pending = getPendingSuggestions();
-    const pendingEntries = Object.entries(pending).sort((a, b) => b[1] - a[1]);
-    if (pendingEntries.length > 0) {
-      warn(`Tags: ${pendingEntries.length} pending suggestion(s)`);
-      for (const [tag, count] of pendingEntries.slice(0, 5)) {
-        log.info(`    "${tag}" (${count}/3 to promote)`);
-      }
-    } else {
-      ok("Tags: no pending suggestions");
-    }
-
     if (!hasAgent) {
       console.log("");
       log.error("No supported agent found. Install Claude Code or opencode.");

package/src/hooks/handlers/failure.ts

@@ -11,7 +11,7 @@ import { resolve } from "node:path";
 import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { ensureDir, paths } from "../lib/paths";
-import { getVocabulary, recordSuggestedTag } from "../lib/tags";
+import { FAILURE_PRINCIPLE_PROMPT } from "../lib/prompts";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -55,14 +55,13 @@ export async function captureFailure(
     resolve(paths.failures(), monthPath(), `${fileTimestamp()}_${slug}`)
   );
 
-  // Attempt inference to fill root cause analysis + tags
+  // Attempt inference to fill root cause analysis + candidate principle
   let whatWentWrong = "";
   let whatToDoDifferently = "";
-  let tags: string[] = [];
+  let principle = "";
   try {
-    const vocab = getVocabulary();
     const analysisResult = await inference({
-      system: `You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable. Also pick 1-3 tags from this list: [${vocab.join(", ")}]. If none fit, leave tags empty and put your suggested tag in suggested_tag.`,
+      system: `You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable. Also write a principle — ${FAILURE_PRINCIPLE_PROMPT}`,
       user: [
         `Rating: ${rating}/10`,
         `Context: ${context}`,
@@ -80,13 +79,9 @@ export async function captureFailure(
         properties: {
           what_went_wrong: { type: "string" as const },
           what_to_do_differently: { type: "string" as const },
-          tags: {
-            type: "array" as const,
-            items: { type: "string" as const },
-          },
-          suggested_tag: { type: "string" as const },
+          principle: { type: "string" as const },
         },
-        required: ["what_went_wrong", "what_to_do_differently", "tags"],
+        required: ["what_went_wrong", "what_to_do_differently", "principle"],
       },
     });
     if (analysisResult.usage) logTokenUsage("failure", analysisResult.usage);
@@ -94,13 +89,11 @@ export async function captureFailure(
       const parsed = JSON.parse(analysisResult.output) as {
         what_went_wrong?: string;
         what_to_do_differently?: string;
-        tags?: string[];
-        suggested_tag?: string;
+        principle?: string;
       };
       whatWentWrong = parsed.what_went_wrong ?? "";
       whatToDoDifferently = parsed.what_to_do_differently ?? "";
-      if (parsed.tags?.length) tags = parsed.tags;
-      if (parsed.suggested_tag) recordSuggestedTag(parsed.suggested_tag);
+      principle = parsed.principle ?? "";
     }
   } catch {
     // Graceful fallback — empty sections are still useful with the other context
@@ -113,7 +106,7 @@ export async function captureFailure(
     ts: new Date().toISOString(),
     slug,
   };
-  if (tags.length > 0) meta.tags = tags;
+  if (principle) meta.principle = principle;
 
   const body = [
     "## Last User Message",

package/src/hooks/handlers/work-learning.ts

@@ -11,7 +11,7 @@ import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { ensureDir, paths } from "../lib/paths";
-import { getVocabulary, recordSuggestedTag } from "../lib/tags";
+import { LEARNING_PRINCIPLE_PROMPT } from "../lib/prompts";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -108,16 +108,15 @@ export async function captureWorkLearning(
   let title = rawTitle;
   let summary = rawSummary;
   let insights = "";
-  let tags: string[] = [];
+  let principle = "";
   try {
-    const vocab = getVocabulary();
     const userMessages = messages
       .filter((m) => m.role === "user")
       .map((m) => extractContent(m).slice(0, 100))
       .slice(-8)
       .join("\n");
     const result = await inference({
-      system: `You summarize AI coding sessions between a human user and an AI assistant. The 'Human messages' are what the user said. The 'AI response' is what the assistant said. Produce: 1) a short title (5-10 words) describing what was accomplished, 2) a summary of what the AI assistant did for the user (2-4 sentences, write from the AI's perspective using 'we'), 3) insights — what worked well, what was surprising, or what should be done differently next time (2-3 bullet points, no markdown), 4) tags — pick 1-3 from this list: [${vocab.join(", ")}]. If none fit, leave tags empty and put your suggested tag in suggested_tag.`,
+      system: `You summarize AI coding sessions between a human user and an AI assistant. The 'Human messages' are what the user said. The 'AI response' is what the assistant said. Produce: 1) a short title (5-10 words) describing what was accomplished, 2) a summary of what the AI assistant did for the user (2-4 sentences, write from the AI's perspective using 'we'), 3) insights — what worked well, what was surprising, or what should be done differently next time (2-3 bullet points, no markdown), 4) principle — ${LEARNING_PRINCIPLE_PROMPT}`,
       user: `Human messages:\n${userMessages}\n\nAI response:\n${rawSummary.slice(0, 400)}`,
       maxTokens: 350,
       timeout: 15000,
@@ -128,13 +127,9 @@ export async function captureWorkLearning(
           title: { type: "string" as const },
           summary: { type: "string" as const },
           insights: { type: "string" as const },
-          tags: {
-            type: "array" as const,
-            items: { type: "string" as const },
-          },
-          suggested_tag: { type: "string" as const },
+          principle: { type: "string" as const },
         },
-        required: ["title", "summary", "insights", "tags"],
+        required: ["title", "summary", "insights", "principle"],
       },
     });
     if (result.usage) logTokenUsage("work-learning", result.usage);
@@ -143,14 +138,12 @@ export async function captureWorkLearning(
         title?: string;
         summary?: string;
         insights?: string;
-        tags?: string[];
-        suggested_tag?: string;
+        principle?: string;
       };
       if (parsed.title) title = parsed.title.slice(0, 100);
       if (parsed.summary) summary = parsed.summary;
       if (parsed.insights) insights = parsed.insights;
-      if (parsed.tags?.length) tags = parsed.tags;
-      if (parsed.suggested_tag) recordSuggestedTag(parsed.suggested_tag);
+      if (parsed.principle) principle = parsed.principle;
     }
   } catch {
     // Fallback to raw values
@@ -166,7 +159,7 @@ export async function captureWorkLearning(
     category,
     date: new Date().toISOString().slice(0, 10),
   };
-  if (tags.length > 0) meta.tags = tags;
+  if (principle) meta.principle = principle;
   if (sessionId) meta.session = sessionId;
 
   const body = [

package/src/hooks/lib/graduation.ts

@@ -21,7 +21,7 @@ interface LearningEntry {
   source: string; // "failure:{slug}" or "learning:{filename}"
   text: string; // context or title+insights
   date: string; // YYYY-MM-DD
-  tags: string[]; // semantic tags from inference
+  principle: string; // candidate principle from inference
 }
 
 interface PatternGroup {
@@ -46,6 +46,7 @@ interface GraduationState {
 
 export interface GraduationResult {
   candidates: PatternGroup[];
+  emerging: PatternGroup[];
   graduated: GraduatedEntry[];
   updated: GraduatedEntry[];
 }
@@ -171,7 +172,7 @@ function extractKeywords(text: string): Set<string> {
   );
 }
 
-function similarity(a: string, b: string): number {
+export function similarity(a: string, b: string): number {
   const ka = extractKeywords(a);
   const kb = extractKeywords(b);
   if (ka.size === 0 || kb.size === 0) return 0;
@@ -199,7 +200,7 @@ function collectFailures(): LearningEntry[] {
         for (const slug of readdirSync(monthDir)) {
           let context = "";
           let ts = "";
-          let entryTags: string[] = [];
+          let entryPrinciple = "";
 
           // Try capture.md (new format)
           const capturePath = resolve(monthDir, slug, "capture.md");
@@ -209,11 +210,11 @@ function collectFailures(): LearningEntry[] {
               const { meta } = parse<{
                 context?: string;
                 ts?: string;
-                tags?: string[];
+                principle?: string;
               }>(content);
               context = meta.context || "";
               ts = (meta.ts as string) || "";
-              if (Array.isArray(meta.tags)) entryTags = meta.tags;
+              entryPrinciple = meta.principle || "";
             } catch {
               /* fallback below */
             }
@@ -237,7 +238,7 @@ function collectFailures(): LearningEntry[] {
               source: `failure:${slug}`,
               text: context.slice(0, 300),
               date: ts.slice(0, 10),
-              tags: entryTags,
+              principle: entryPrinciple,
             });
           }
         }
@@ -265,16 +266,16 @@ function collectLearnings(): LearningEntry[] {
             const content = readFileSync(resolve(monthDir, file), "utf-8");
             let title = "";
             let insights = "";
-            let entryTags: string[] = [];
+            let entryPrinciple = "";
 
             if (hasFrontmatter(content)) {
               // New format
               const { meta, body } = parse<{
                 title?: string;
-                tags?: string[];
+                principle?: string;
               }>(content);
               title = meta.title || "";
-              if (Array.isArray(meta.tags)) entryTags = meta.tags;
+              entryPrinciple = meta.principle || "";
               const insightsMatch = body.match(/## Insights\n([\s\S]*?)(?=\n##|$)/);
               insights = insightsMatch?.[1]?.trim() || "";
             } else {
@@ -295,7 +296,7 @@ function collectLearnings(): LearningEntry[] {
                 source: `learning:${file}`,
                 text: text.slice(0, 300),
                 date,
-                tags: entryTags,
+                principle: entryPrinciple,
               });
             }
           } catch {
@@ -313,7 +314,7 @@ function collectLearnings(): LearningEntry[] {
 
 // ── Grouping ──
 
-const SIMILARITY_THRESHOLD = 0.35;
+export const SIMILARITY_THRESHOLD = 0.35;
 const MIN_OCCURRENCES = 3;
 const MIN_TEXT_LENGTH = 30;
 
@@ -329,33 +330,17 @@ function isActionable(text: string): boolean {
   return true;
 }
 
-/** Check if two entries share at least one tag. */
-function hasSharedTag(a: string[], b: string[]): boolean {
-  if (a.length === 0 || b.length === 0) return false;
-  return a.some((t) => b.includes(t));
-}
-
 function groupPatterns(entries: LearningEntry[]): PatternGroup[] {
   const groups: PatternGroup[] = [];
   const actionable = entries.filter((e) => isActionable(e.text));
 
   for (const entry of actionable) {
+    // Use principle for matching if available, fall back to raw text
+    const matchText = entry.principle || entry.text;
     let matched = false;
     for (const group of groups) {
-      // Tag-based matching (preferred — entries with shared tags)
-      if (
-        entry.tags.length > 0 &&
-        group.entries.some((e) => hasSharedTag(e.tags, entry.tags))
-      ) {
-        group.entries.push(entry);
-        matched = true;
-        break;
-      }
-      // Text similarity fallback (for untagged/legacy entries)
-      if (
-        entry.tags.length === 0 &&
-        similarity(entry.text, group.pattern) >= SIMILARITY_THRESHOLD
-      ) {
+      const groupText = group.entries[0]?.principle || group.pattern;
+      if (similarity(matchText, groupText) >= SIMILARITY_THRESHOLD) {
         group.entries.push(entry);
         matched = true;
         break;
@@ -370,7 +355,7 @@ function groupPatterns(entries: LearningEntry[]): PatternGroup[] {
     }
   }
 
-  return groups.filter((g) => g.entries.length >= MIN_OCCURRENCES);
+  return groups.filter((g) => g.entries.length >= 2);
 }
 
 // ── State Management ──
@@ -425,9 +410,12 @@ export function graduate(): GraduationResult {
     `Collected ${failures.length} failures, ${learnings.length} learnings`
   );
 
-  const candidates = groupPatterns(all);
+  const allGroups = groupPatterns(all);
+  const candidates = allGroups.filter((g) => g.entries.length >= MIN_OCCURRENCES);
+  const emerging = allGroups.filter((g) => g.entries.length === 2);
   const result: GraduationResult = {
     candidates,
+    emerging,
     graduated: [],
     updated: [],
   };

package/src/hooks/lib/prompts.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared prompt fragments — single source of truth for inference instructions.
+ */
+
+/** Principle extraction instruction for failed interactions. */
+export const FAILURE_PRINCIPLE_PROMPT =
+  "Write one actionable sentence that would prevent this issue from happening again. If no clear lesson, leave principle empty. Be concise.";
+
+/** Principle extraction instruction for session learnings. */
+export const LEARNING_PRINCIPLE_PROMPT =
+  "If this session taught a reusable lesson, write one actionable sentence that would prevent the same issue in the future. If no clear lesson, leave empty. Be concise.";

package/src/hooks/lib/security.ts

@@ -29,7 +29,6 @@ export const HOOK_MANAGED_FILES = [
   "signal-cache.json",
   "pending-failure.json",
   "token-usage.jsonl",
-  "tags.json",
   "graduated.json",
 ];
 

package/src/tools/eval-principles.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env bun
+/**
+ * Principle Evaluation — generate, regenerate, or compare candidate principles.
+ *
+ * Reads failures (capture.md) and learnings (frontmatter .md) and uses Haiku
+ * to generate candidate principles. Useful for tuning prompt quality.
+ *
+ * Modes:
+ *   --dry-run     Preview which files would be updated
+ *   --evaluate    Show current vs new principle for comparison (does not write)
+ *   --force       Regenerate principles even if one already exists
+ *   (default)     Generate missing principles only
+ *
+ * Usage:
+ *   bun run tool:eval                    # generate missing
+ *   bun run tool:eval -- --dry-run       # preview
+ *   bun run tool:eval -- --evaluate      # compare current vs new
+ *   bun run tool:eval -- --force         # regenerate all
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { hasFrontmatter, parse, stringify } from "../hooks/lib/frontmatter";
+import { inference } from "../hooks/lib/inference";
+import { palHome } from "../hooks/lib/paths";
+import {
+  FAILURE_PRINCIPLE_PROMPT,
+  LEARNING_PRINCIPLE_PROMPT,
+} from "../hooks/lib/prompts";
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const evaluate = args.includes("--evaluate");
+const force = args.includes("--force");
+
+const home = palHome();
+let processed = 0;
+let skipped = 0;
+let failed = 0;
+
+async function generatePrinciple(systemPrompt: string, context: string): Promise<string> {
+  const result = await inference({
+    system: systemPrompt,
+    user: context,
+    maxTokens: 100,
+    timeout: 10000,
+    jsonSchema: {
+      type: "object" as const,
+      additionalProperties: false,
+      properties: {
+        principle: { type: "string" as const },
+      },
+      required: ["principle"],
+    },
+  });
+
+  if (result.success && result.output) {
+    const parsed = JSON.parse(result.output) as { principle?: string };
+    const principle = parsed.principle?.trim() || "";
+    if (principle.length > 10) return principle;
+  }
+  return "";
+}
+
+// ── Failures ──
+
+async function processFailures() {
+  const failuresDir = resolve(home, "memory", "learning", "failures");
+  if (!existsSync(failuresDir)) return;
+
+  for (const year of readdirSync(failuresDir)) {
+    const yearDir = resolve(failuresDir, year);
+    for (const month of readdirSync(yearDir)) {
+      const monthDir = resolve(yearDir, month);
+      for (const slug of readdirSync(monthDir)) {
+        const capturePath = resolve(monthDir, slug, "capture.md");
+        if (!existsSync(capturePath)) continue;
+
+        const content = readFileSync(capturePath, "utf-8");
+        if (!hasFrontmatter(content)) continue;
+
+        const { meta, body } = parse<{
+          principle?: string;
+          context?: string;
+          rating?: number;
+        }>(content);
+
+        const hasPrinciple = !!meta.principle;
+        if (hasPrinciple && !force && !evaluate) {
+          skipped++;
+          continue;
+        }
+
+        const context = meta.context || "";
+        if (!context) {
+          skipped++;
+          continue;
+        }
+
+        const inputContext = `Rating: ${meta.rating}/10\nContext: ${context}\n\n${body.slice(0, 400)}`;
+
+        if (dryRun) {
+          console.log(`  [failure] ${slug.slice(0, 60)}`);
+          processed++;
+          continue;
+        }
+
+        try {
+          const newPrinciple = await generatePrinciple(
+            FAILURE_PRINCIPLE_PROMPT,
+            inputContext
+          );
+          if (!newPrinciple) {
+            skipped++;
+            continue;
+          }
+
+          if (evaluate) {
+            console.log(`  [failure] ${slug.slice(0, 50)}`);
+            if (hasPrinciple) {
+              console.log(`    OLD: ${meta.principle}`);
+            }
+            console.log(`    NEW: ${newPrinciple}`);
+            console.log("");
+            processed++;
+            continue;
+          }
+
+          const newMeta = { ...meta, principle: newPrinciple } as Record<string, unknown>;
+          writeFileSync(capturePath, stringify(newMeta, body), "utf-8");
+          console.log(`  [failure] ${slug.slice(0, 60)}`);
+          processed++;
+        } catch {
+          failed++;
+        }
+      }
+    }
+  }
+}
+
+// ── Learnings ──
+
+async function processLearnings() {
+  const learningDir = resolve(home, "memory", "learning", "session");
+  if (!existsSync(learningDir)) return;
+
+  for (const year of readdirSync(learningDir)) {
+    const yearDir = resolve(learningDir, year);
+    for (const month of readdirSync(yearDir)) {
+      const monthDir = resolve(yearDir, month);
+      for (const file of readdirSync(monthDir).filter((f) => f.endsWith(".md"))) {
+        const filepath = resolve(monthDir, file);
+        const content = readFileSync(filepath, "utf-8");
+
+        if (!hasFrontmatter(content)) {
+          skipped++;
+          continue;
+        }
+
+        const { meta, body } = parse<{
+          principle?: string;
+          title?: string;
+        }>(content);
+
+        const hasPrinciple = !!meta.principle;
+        if (hasPrinciple && !force && !evaluate) {
+          skipped++;
+          continue;
+        }
+
+        const title = meta.title || "";
+        if (!title) {
+          skipped++;
+          continue;
+        }
+
+        const inputContext = `Title: ${title}\n\n${body.slice(0, 400)}`;
+
+        if (dryRun) {
+          console.log(`  [learning] ${file.slice(0, 60)}`);
+          processed++;
+          continue;
+        }
+
+        try {
+          const newPrinciple = await generatePrinciple(
+            LEARNING_PRINCIPLE_PROMPT,
+            inputContext
+          );
+          if (!newPrinciple) {
+            skipped++;
+            continue;
+          }
+
+          if (evaluate) {
+            console.log(`  [learning] ${file.slice(0, 50)}`);
+            if (hasPrinciple) {
+              console.log(`    OLD: ${meta.principle}`);
+            }
+            console.log(`    NEW: ${newPrinciple}`);
+            console.log("");
+            processed++;
+            continue;
+          }
+
+          const newMeta = { ...meta, principle: newPrinciple } as Record<string, unknown>;
+          writeFileSync(filepath, stringify(newMeta, body), "utf-8");
+          console.log(`  [learning] ${file.slice(0, 60)}`);
+          processed++;
+        } catch {
+          failed++;
+        }
+      }
+    }
+  }
+}
+
+// ── Main ──
+
+const mode = evaluate
+  ? "evaluate"
+  : force
+    ? "force regenerate"
+    : dryRun
+      ? "dry run"
+      : "backfill";
+console.log(`\n  Principle ${mode}...\n`);
+
+await processFailures();
+await processLearnings();
+
+console.log(
+  `\n  Done: ${processed} ${evaluate ? "compared" : "processed"}, ${skipped} skipped, ${failed} failed\n`
+);

package/src/tools/graduate.ts

@@ -13,8 +13,8 @@ import { graduate } from "../hooks/lib/graduation";
 
 const result = graduate();
 
-if (result.candidates.length === 0) {
-  console.log("\n  No recurring patterns found (need 3+ similar entries).\n");
+if (result.candidates.length === 0 && result.emerging.length === 0) {
+  console.log("\n  No recurring patterns found.\n");
   process.exit(0);
 }
 
@@ -22,13 +22,12 @@ console.log(`\n  Graduation Report — ${result.candidates.length} pattern(s) de
 console.log("  ─────────────────────────────────────────────────\n");
 
 for (const candidate of result.candidates) {
-  // Collect unique tags across all entries
-  const allTags = [...new Set(candidate.entries.flatMap((e) => e.tags))];
+  // Collect unique candidate principles
+  const principles = [
+    ...new Set(candidate.entries.map((e) => e.principle).filter((p) => p.length > 0)),
+  ];
 
   console.log(`  [${candidate.domain}] ${candidate.entries.length}x occurrences`);
-  if (allTags.length > 0) {
-    console.log(`  Tags: ${allTags.join(", ")}`);
-  }
   console.log("");
 
   // Show each entry with date and source
@@ -39,13 +38,42 @@ for (const candidate of result.candidates) {
     );
   }
 
+  // Show candidate principles from Haiku
+  if (principles.length > 0) {
+    console.log("\n  Suggested principles:");
+    for (const p of principles) {
+      console.log(`    → ${p}`);
+    }
+  }
+
   console.log("");
-  console.log(
-    "  → Consider adding a principle to:",
-    `memory/wisdom/frames/${candidate.domain}.md`
-  );
+  console.log("  Target frame:", `memory/wisdom/frames/${candidate.domain}.md`);
   console.log("  ─────────────────────────────────────────────────\n");
 }
 
-console.log("  To crystallize: add a line to the wisdom frame file.");
-console.log("  Format: - Your principle here [CRYSTAL: 85%]\n");
+if (result.emerging.length > 0) {
+  console.log(`  Emerging (2x — one more to graduate)\n`);
+  for (const group of result.emerging) {
+    const principles = [
+      ...new Set(group.entries.map((e) => e.principle).filter((p) => p.length > 0)),
+    ];
+    console.log(`  [${group.domain}] ${group.entries.length}x`);
+    for (const entry of group.entries) {
+      const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+      console.log(
+        `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 80)}`
+      );
+    }
+    if (principles.length > 0) {
+      for (const p of principles) {
+        console.log(`    → ${p}`);
+      }
+    }
+    console.log("");
+  }
+}
+
+if (result.candidates.length > 0) {
+  console.log("  To crystallize: add a line to the wisdom frame file.");
+  console.log("  Format: - Your principle here [CRYSTAL: 85%]\n");
+}

package/src/hooks/lib/tags.ts

@@ -1,89 +0,0 @@
-/**
- * Tag vocabulary management for semantic grouping.
- *
- * Tags come from a fixed vocabulary. When Haiku suggests a tag not in the
- * vocabulary, it's tracked as "suggested". Suggested tags that recur 3+
- * times get auto-promoted to the vocabulary.
- */
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { ensureDir, paths } from "./paths";
-
-const DEFAULT_VOCABULARY = [
-  "versioning",
-  "testing",
-  "deployment",
-  "configuration",
-  "communication",
-  "documentation",
-  "architecture",
-  "debugging",
-  "performance",
-  "security",
-  "cross-platform",
-  "dependencies",
-  "incomplete-work",
-  "wrong-approach",
-  "tooling",
-];
-
-const PROMOTION_THRESHOLD = 3;
-
-export interface TagState {
-  vocabulary: string[];
-  suggested: Record<string, number>;
-}
-
-function stateFilePath(): string {
-  return resolve(ensureDir(paths.wisdomState()), "tags.json");
-}
-
-export function readTagState(): TagState {
-  const fp = stateFilePath();
-  if (!existsSync(fp)) {
-    return { vocabulary: [...DEFAULT_VOCABULARY], suggested: {} };
-  }
-  try {
-    return JSON.parse(readFileSync(fp, "utf-8"));
-  } catch {
-    return { vocabulary: [...DEFAULT_VOCABULARY], suggested: {} };
-  }
-}
-
-export function writeTagState(state: TagState): void {
-  writeFileSync(stateFilePath(), JSON.stringify(state, null, 2), "utf-8");
-}
-
-/** Get the current vocabulary (for injection into inference prompts). */
-export function getVocabulary(): string[] {
-  return readTagState().vocabulary;
-}
-
-/**
- * Record a suggested tag. If it reaches the promotion threshold,
- * move it to the vocabulary automatically.
- */
-export function recordSuggestedTag(tag: string): void {
-  const state = readTagState();
-  const normalized = tag.toLowerCase().trim();
-
-  // Already in vocabulary — nothing to do
-  if (state.vocabulary.includes(normalized)) return;
-
-  // Increment suggestion count
-  state.suggested[normalized] = (state.suggested[normalized] || 0) + 1;
-
-  // Promote if threshold reached
-  if (state.suggested[normalized] >= PROMOTION_THRESHOLD) {
-    state.vocabulary.push(normalized);
-    delete state.suggested[normalized];
-  }
-
-  writeTagState(state);
-}
-
-/** Get suggested tags and their counts (for reporting). */
-export function getPendingSuggestions(): Record<string, number> {
-  return readTagState().suggested;
-}