portable-agent-layer 0.51.2 → 0.53.0

package/README.md

@@ -83,6 +83,7 @@ pal cli status        # check your setup
 | `pal cli status` | Show current PAL configuration |
 | `pal cli doctor` | Check prerequisites and system health |
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
+| `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `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 |

package/assets/skills/analyze-pdf/SKILL.md

@@ -22,6 +22,18 @@ Use your native PDF reading capability (e.g. a Read tool or equivalent). Most mo
 
 Do NOT install PDF processing tools (poppler, pdftotext, etc.) unless the user explicitly asks. Native reading is sufficient.
 
+### Fallback: when native Read fails
+
+If the Read tool fails to open the PDF (e.g. error mentioning `pdftoppm`, missing renderer, or unsupported format), fall back to the text-extraction CLI:
+
+```bash
+bun ~/.pal/skills/analyze-pdf/tools/pdf-read.ts -- <path>
+```
+
+Use the stdout output as the document content and proceed with the user's request as normal.
+
+If `pdf-read.ts` also fails, stop completely — report the exact errors from both attempts and ask the user how to proceed. Never infer PDF content from filename, metadata, or assumptions.
+
 ## What to do with it
 
 Follow the user's request. Common tasks:

package/assets/skills/analyze-pdf/tools/pdf-read.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+
+/**
+ * PDF Read — Extracts text from a local PDF file, page by page.
+ *
+ * Usage:
+ *   bun pdf-read.ts -- <path/to/file.pdf>
+ *
+ * Prints each page's text to stdout separated by a page marker.
+ */
+
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { extractText, getDocumentProxy } from "unpdf";
+
+async function main() {
+  const { positionals } = parseArgs({ allowPositionals: true, options: {} });
+
+  const filePath = positionals[0];
+  if (!filePath) {
+    console.error("Usage: bun pdf-read.ts -- <path/to/file.pdf>");
+    process.exit(1);
+  }
+
+  const buffer = await readFile(filePath);
+  const pdf = await getDocumentProxy(new Uint8Array(buffer));
+  const { totalPages, text } = await extractText(pdf, { mergePages: false });
+
+  for (let i = 0; i < totalPages; i++) {
+    console.log(`--- Page ${i + 1} ---`);
+    console.log(text[i]);
+  }
+}
+
+void main();

package/assets/skills/pal-analyze/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: pal-analyze
+description: Run learning analysis — surface rating trends, recurring failure patterns, and graduation candidates. Use when learning analysis is due, or when the user asks about performance patterns, low ratings, or what to improve.
+argument-hint: [optional: --actionable for AI-generated recommendations]
+---
+
+When `/pal-analyze` is invoked (by you in response to a nudge, or by the user directly):
+
+## 1. Run the analyze tool
+
+```bash
+pal cli analyze
+```
+
+If the user passed `--actionable` or wants recommendations, append it: `pal cli analyze --actionable`
+
+## 2. Parse and present the output
+
+Read the console output and summarize the key signals. Focus on what's actionable, not exhaustive lists:
+
+**Ratings section:**
+- Lead with the average and trend direction
+- Call out any striking low-rating clusters (e.g. "47 low ratings, mostly around scope drift corrections")
+
+**Graduation candidates:**
+- Name the top 1-3 patterns ready to crystallize
+- Suggest the wisdom domain they'd live in
+
+**Emerging patterns:**
+- Name any 2-occurrence patterns worth watching
+
+Format example:
+```
+Analysis complete:
+
+Ratings: X.X/10 avg | N low (≤4) | N high (≥7)
+Top low-rating context: "[cluster description]"
+
+Ready to graduate (3+ occurrences):
+- "[pattern]" → suggest adding to wisdom/[domain].md
+
+Emerging (2 occurrences — one more to graduate):
+- "[pattern]"
+```
+
+## 3. Offer to act
+
+After showing results, ask:
+> "Want to crystallize any of these into a wisdom frame, or dig into the low-rating clusters?"
+
+If yes to crystallizing:
+```bash
+bun ~/.pal/tools/wisdom-frame.ts --domain <domain> --observation "<principle>"
+```

package/assets/skills/pal-reflect/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: pal-reflect
+description: Run relationship reflect — promote recurring behavioral observations into tracked opinions. Use when relationship reflect is due, or when the user asks to review what patterns have been observed.
+argument-hint: [optional: --dry-run to preview without writing]
+---
+
+When `/pal-reflect` is invoked (by you in response to a nudge, or by the user directly):
+
+## 1. Run the reflect tool
+
+```bash
+bun run tool:reflect
+```
+
+If the user passed `--dry-run`, append it: `bun run tool:reflect -- --dry-run`
+
+## 2. Parse and present the output
+
+Read the console output and present a concise summary:
+
+**If opinions were promoted or strengthened:**
+```
+Reflect complete — here's what changed:
+
+NEW opinions (confidence seeded from recurring observations):
+- [statement] (XX%)
+
+STRENGTHENED opinions (evidence accumulated):
+- [statement]: XX% → YY%
+```
+
+**If nothing changed:**
+```
+Reflect complete — no patterns strong enough yet.
+[N] observations loaded. An opinion promotes when the same pattern appears 2+ times.
+Most recent observations:
+- [list up to 3 recent O notes]
+```
+
+## 3. Offer a follow-up
+
+After showing results, say:
+> "Want to review the full opinions list, or is there a specific pattern you'd like to reinforce or correct?"
+
+If the user confirms or corrects something, use the opinion tool:
+```bash
+# Confirmed
+bun ~/.pal/skills/opinion/tools/opinion.ts evidence "keywords" --confirmation "what they confirmed"
+
+# Corrected
+bun ~/.pal/skills/opinion/tools/opinion.ts evidence "keywords" --contradiction "what they corrected"
+```

package/assets/statusline.ps1

@@ -29,7 +29,7 @@ $COST_STR = '$' + ([math]::Round($COST, 2)).ToString("0.00")
 
 # PAL: Hook health - count ERROR lines in debug.log from last 24h
 $HOOK_ERRORS = 0
-$debugLog = Join-Path $env:USERPROFILE ".pal\memory\state\debug.log"
+$debugLog = Join-Path $env:USERPROFILE ".pal\debug\debug.log"
 if (Test-Path $debugLog) {
   $cutoff = (Get-Date).AddHours(-24)
   try {
@@ -173,7 +173,7 @@ $QUOTES = @(
   "A person who never made a mistake never tried anything new.|Albert Einstein"
   "The journey of a thousand miles begins with one step.|Lao Tzu"
   "The obstacle is the way.|Marcus Aurelius"
-  "Whether you think you can or you think you can't — you are right.|Henry Ford"
+  "Whether you think you can or you think you can't - you are right.|Henry Ford"
   "Everything should be made as simple as possible, but not simpler.|Albert Einstein"
   "You miss 100% of the shots you don't take.|Wayne Gretzky"
 )

package/assets/statusline.sh

@@ -56,7 +56,7 @@ fi
 
 # PAL: Hook health — count ERROR lines in debug.log from last 24h
 HOOK_ERRORS=0
-DEBUG_LOG="$HOME/.pal/memory/state/debug.log"
+DEBUG_LOG="$HOME/.pal/debug/debug.log"
 if [ -f "$DEBUG_LOG" ]; then
   # Cross-platform 24h cutoff: macOS uses date -v, GNU Linux uses date -d
   CUTOFF=$(date -v-24H "+%Y-%m-%d %H:%M:%S" 2>/dev/null || date -d '24 hours ago' "+%Y-%m-%d %H:%M:%S" 2>/dev/null)
@@ -209,7 +209,7 @@ QUOTES=(
   "A person who never made a mistake never tried anything new.|Albert Einstein"
   "The journey of a thousand miles begins with one step.|Lao Tzu"
   "The obstacle is the way.|Marcus Aurelius"
-  "Whether you think you can or you think you can't — you are right.|Henry Ford"
+  "Whether you think you can or you think you can't - you are right.|Henry Ford"
   "Everything should be made as simple as possible, but not simpler.|Albert Einstein"
   "You miss 100% of the shots you don't take.|Wayne Gretzky"
 )

package/assets/templates/PAL/ALGORITHM.md

@@ -175,6 +175,8 @@ Don't just *list* what must be true — actively confirm the load-bearing facts
 
 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.
 
+**Retrieval failure is a hard block.** If a grounding tool call (Read, fetch, API, query) returns an error or no content, stop here — do not enter EXECUTE. Report the exact error, do not infer content from filename, metadata, or prior context, and ask the user for direction before proceeding.
+
 Output: `🧭 GROUNDING: [premises verified, or assumptions flagged]`
 
 ### ━━━ ⚡ EXECUTE ━━━ 3/5
@@ -234,16 +236,43 @@ bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed
 
 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:
+**3. Relationship note** — write behavioral observations (O, W) and a session diary entry (--b).
+
+The goal is behavioral intelligence about the user, not a session log. Session logs belong in handoff notes and project history. This step captures *who the user is* — observable patterns, preferences, world facts.
 
 ```bash
-bun ~/.pal/tools/relationship-note.ts --b "description"
+# Opinion — behavioral observation about the user (what you noticed about how they work):
+bun ~/.pal/tools/relationship-note.ts --o "User prefers reviewing existing code before adding anything new" --confidence 0.80
+
+# World fact — objective fact about the user's situation (tech stack, project state, context):
+bun ~/.pal/tools/relationship-note.ts --w "User is building a backend service in TypeScript with Bun"
+
+# Session diary — what the agent did this session (first-person, specific):
+bun ~/.pal/tools/relationship-note.ts --b "Refactored the auth middleware to support refresh token rotation"
+
+# Multiple notes in one call:
+bun ~/.pal/tools/relationship-note.ts --o "User prefers one verified change at a time, not batches" --confidence 0.80 --b "Fixed the path-normalization bug in the hook merge logic"
 ```
 
-- 1-2 sentences, first-person, specific — name the actual system/file/concept worked on
-- ✓ "Debugged the React Query cache split logic and resolved stuck message state in the onFinish callback"
-- ✗ "Helped with memory improvements" — too vague, no system named
-- Skip only if the session was a trivial lookup or typo fix (same rule as step 2)
+**O (Opinion) — what to write:**
+- Preference patterns: "User prefers short answers with a recommendation over exhaustive options"
+- Correction patterns: "User redirects scope drift immediately without elaborating on why"
+- Working style: "User verifies each change before asking for the next one"
+- Confidence guide: 0.70 = single observation, 0.80 = confirmed twice, 0.85+ = established pattern
+
+**W (World) — what to write:**
+- Tech stack facts: "User's current project uses PostgreSQL, tRPC, and Next.js"
+- Situation facts: "User is in the middle of a database migration with live traffic"
+
+**--b (Session diary) — keep it sharp:**
+- ✓ "Debugged the race condition in the message queue consumer and fixed the ack logic"
+- ✗ "Helped with backend improvements" — too vague, no system named
+
+**When to write O vs use the opinion tool (step 6):**
+- O notes → subtle patterns you observed, not yet confirmed → goes into daily file → synthesis promotes to opinions.json over time
+- Opinion tool → explicit user confirmation/correction → goes directly to opinions.json immediately
+
+Skip only if the session was a trivial lookup or typo fix (same rule as step 2).
 
 **4. Handoff note** — if work is unfinished, write what remains so the next session can pick up immediately:
 

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -111,14 +111,13 @@ Before any code, before any architecture — there must be clear thinking:
 - Each tool is a standalone CLI program
 - Each skill is a self-contained capability
 - Hooks compose via `Promise.allSettled` — independent, parallel, isolated failures
-- Tools compose via `bun run tool:<name>` — standard I/O, exit codes
+- Tools compose via `pal cli <name>` — standard I/O, exit codes
 
 ### 9. CLI as Interface
 
 **Every operation should be accessible via command line.**
 
-- `pal cli <command>` for system management
-- `bun run tool:<name>` for utilities
+- `pal cli <command>` for system management and user-facing utilities
 - Skills triggered via agent slash commands
 - No hidden operations — everything is scriptable and testable
 

package/assets/templates/pal-settings.json

@@ -21,10 +21,7 @@
     "opinions": true,
     "relationship": true,
     "learningDigest": true,
-    "synthesis": true,
-    "signalTrends": true,
     "failurePatterns": true,
-    "activeWork": true,
     "projectHistory": true,
     "projects": true,
     "sessionIntelligence": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.51.2",
+  "version": "0.53.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -50,9 +50,10 @@
     "uninstall": "bun run src/cli/index.ts cli uninstall",
     "tool:synthesize": "bun run src/tools/agent/synthesize.ts",
     "tool:thread": "bun run src/tools/agent/thread.ts",
-    "tool:analyze": "bun run src/tools/agent/analyze.ts",
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
-    "tool:reflect": "bun run src/tools/relationship-reflect.ts"
+    "tool:reflect": "bun run src/tools/relationship-reflect.ts",
+    "eval:sentiment": "bun eval/run.ts sentiment",
+    "eval:failure-principle": "bun eval/run.ts failure-principle"
   },
   "lint-staged": {
     "*.ts": [
@@ -75,6 +76,7 @@
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
     "lint-staged": "17.0.5",
+    "promptfoo": "0.121.14",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },
@@ -83,6 +85,7 @@
     "adm-zip": "^0.5.17",
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
-    "playwright": "^1.60.0"
+    "playwright": "^1.60.0",
+    "unpdf": "^0.12.0"
   }
 }

package/src/cli/index.ts

@@ -192,6 +192,11 @@ async function runCli(command: string | undefined, args: string[]) {
       runMigrate(args);
       break;
     }
+    case "analyze": {
+      const { run: runAnalyze } = await import("../tools/agent/analyze");
+      await runAnalyze(args);
+      break;
+    }
     case "usage": {
       const { usage } = await import("../tools/token-cost");
       usage();
@@ -251,6 +256,7 @@ function showHelp() {
     pal cli status                          Show PAL configuration
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
+    pal cli analyze [--actionable]          Learning analysis: ratings, failure patterns, graduation candidates
     pal cli usage                           Summarize token usage and cost
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)

package/src/hooks/LoadContext.ts

@@ -14,7 +14,7 @@ import { resolve } from "node:path";
 import { getActiveAgent, isCodex, isCopilot, isCursor } from "./lib/agent";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
-import { logDebug, logError } from "./lib/log";
+import { logContextSnapshot, logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 
@@ -48,6 +48,7 @@ try {
     active === "copilot" || active === "cursor" ? active : "claude";
   const reminder = buildSystemReminder({ agent });
   if (!reminder) process.exit(0);
+  logContextSnapshot(reminder);
 
   if (isCopilot()) {
     // Copilot: semi-static in ~/.copilot/instructions/pal-*.instructions.md (written at stop).

package/src/hooks/UserPromptOrchestrator.ts

@@ -10,7 +10,7 @@
 import { injectRetrieval } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
-import { logDebug, logError } from "./lib/log";
+import { logDebug, logError, logPromptSnapshot } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -30,13 +30,15 @@ logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)
 if (!input?.prompt) process.exit(0);
 
 const sessionId = input.session_id ?? input.sessionId ?? input.conversation_id;
+const retrieval = await injectRetrieval(input.prompt);
+logPromptSnapshot(input.prompt, retrieval);
+
 const results = await Promise.allSettled([
   captureRating(input.prompt, sessionId),
   captureSessionName(input.prompt, sessionId ?? ""),
-  injectRetrieval(input.prompt),
 ]);
 
-const handlerNames = ["rating", "session-name", "inject-retrieval"];
+const handlerNames = ["rating", "session-name"];
 for (let i = 0; i < results.length; i++) {
   const r = results[i];
   if (r.status === "rejected") {

package/src/hooks/handlers/failure-principle.ts

@@ -57,13 +57,7 @@ async function processFailurePrinciple(
           .join("\n\n");
 
         const result = await inference({
-          system: `Analyze this failed AI interaction. The user rated it ${pending.rating}/10.
-
-Return JSON:
-{
-  "principle": "<one actionable rule the AI should follow, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>",
-  "detailed_context": "<what went wrong and why, 50-150 words>"
-}`,
+          system: `Analyze this failed AI interaction (rated ${pending.rating}/10). Return JSON: {"principle": "<verb-first actionable rule, 10-20 words — write a full sentence, not a fragment>", "detailed_context": "<root cause and what to do differently, 50-150 words>"}.`,
           user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
           maxTokens: 400,
           timeout: 60000,

package/src/hooks/handlers/inject-retrieval.ts

@@ -52,10 +52,11 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
 }
 
 /** Write retrieval reminder to stdout in the correct format for the current agent.
- *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON. */
-export async function injectRetrieval(prompt: string): Promise<void> {
+ *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON.
+ *  Returns the reminder string that was injected, or null if nothing was injected. */
+export async function injectRetrieval(prompt: string): Promise<string | null> {
   const reminder = await getRetrievalReminder(prompt);
-  if (!reminder) return;
+  if (!reminder) return null;
   if (isCursor()) {
     process.stdout.write(JSON.stringify({ additional_context: reminder }));
   } else if (isCodex()) {
@@ -70,4 +71,5 @@ export async function injectRetrieval(prompt: string): Promise<void> {
   } else {
     process.stdout.write(`${reminder}\n`);
   }
+  return reminder;
 }

package/src/hooks/handlers/rating.ts

@@ -64,7 +64,7 @@ export function parseExplicitRating(
   // Reject if rest starts with words indicating a sentence, not a rating
   if (rest) {
     const sentenceStarters =
-      /^(items?|things?|steps?|files?|lines?|bugs?|issues?|errors?|times?|minutes?|hours?|days?|seconds?|percent|%|th\b|st\b|nd\b|rd\b|of\b|in\b|at\b|to\b|the\b|a\b|an\b)/i;
+      /^(items?|things?|steps?|files?|lines?|bugs?|issues?|errors?|times?|minutes?|hours?|days?|seconds?|percent|%|th\b|st\b|nd\b|rd\b|of\b|in\b|at\b|to\b|the\b|a\b|an\b|then\b|also\b|next\b)/i;
     if (sentenceStarters.test(rest)) return null;
 
     // Reject item selections: "1 and 2", "2 3 5", "1, 3, 5", "1-3"
@@ -196,51 +196,21 @@ OUTPUT FORMAT (JSON only):
   "rating": <1-10 or null>,
   "sentiment": "positive" | "negative" | "neutral",
   "confidence": <0.0-1.0>,
-  "summary": "<brief explanation, 10 words max>",
-  "detailed_context": "<comprehensive analysis, 50-150 words>",
-  "principle": "<one actionable rule the AI should follow to avoid this failure or repeat this success, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>"
+  "summary": "<10 words max>",
+  "detailed_context": "<what the user wanted, what the AI did or failed to do, root cause, and what to do differently — 50-150 words>",
+  "principle": "<one actionable rule, 10-20 words, start with a verb: Verify / Always / Never / Ask>"
 }
 
-DETAILED_CONTEXT REQUIREMENTS:
-1. What the user was trying to accomplish
-2. What the AI did (or failed to do)
-3. Why the user reacted this way (root cause)
-4. What specific behavior triggered this reaction
-5. What the AI should do differently (negative) or what worked (positive)
-
-RATING SCALE:
-- 1-2: Strong frustration, anger, disappointment
-- 3-4: Mild frustration, dissatisfaction
-- 5: Neutral
-- 6-7: Satisfaction, approval
-- 8-9: Strong approval, impressed
-- 10: Extraordinary enthusiasm
-
-CRITICAL DISTINCTIONS:
-- Profanity can indicate EITHER frustration OR excitement — use context
-- Sarcasm: "Oh great, another error" = negative despite "great"
-- Short praise ("great job", "nice") = STRONG APPROVAL (8-9), not mild
-
-IMPLIED SENTIMENT (most feedback is implied, not explicit):
-
-Implied NEGATIVE (rate 2-4):
-- CORRECTIONS: "No, I meant..." / "That's not what I said" -> 3-4
-- REPEATED REQUESTS: Having to ask the same thing twice -> 2-3
-- BEHAVIORAL CORRECTIONS: "Don't do that" / "Stop doing X" -> 3
-- EXASPERATED QUESTIONS: "Why is this still broken?" -> 2-3
-- SHORT DISMISSALS: "whatever" / "fine" / "just do it" -> 3-4
-- POINTING OUT OMISSIONS: "What about X?" (obviously required) -> 4
-
-Implied POSITIVE (rate 6-8):
-- TRUST SIGNALS: "Alright, fix all of it" / "Go ahead" -> 7
-- BUILDING ON WORK: "Now also add..." / "Next, do..." -> 6-7
-- ENGAGED FOLLOW-UPS: "What about X?" (exploring, not correcting) -> 6
-- MOVING FORWARD: Accepting output and giving next task -> 6
-
-WHEN TO RETURN null FOR RATING:
-- Neutral technical questions ("Can you check the logs?")
-- Simple commands ("Do it", "Yes", "Continue")
-- No emotional indicators present`;
+RATING SCALE: 1-2 strong frustration · 3-4 mild frustration · 5 neutral · 6-7 approval · 8-9 strong approval · 10 exceptional · null = no emotional signal
+Short praise ("great job", "nice") = STRONG APPROVAL (8-9), not mild.
+
+TASK DIRECTIVES — short imperatives with "pls" are approval or sequencing signals (null or 6-7, NOT negative):
+"write it pls" / "do it pls" / "step 3 pls" / "option 2 pls" = user directing or approving the AI's own proposal.
+EXCEPTION: "fix X pls" / "fix that pls" is always negative — "fix" implies a problem regardless of "pls".
+
+IMPLIED NEGATIVE (rate 2-4): corrections ("that's wrong", "I meant..."), repeats ("again pls", "still broken", "doesn't work again"), behavioral corrections ("don't do that"), exasperated questions ("why is this still broken?"), failure confirmations ("nothing is fixed").
+IMPLIED POSITIVE (rate 6-8): trust signals ("go ahead", "fix all of it"), continuation ("now also add X", "next do..."), moving forward with the next task.
+NULL rating: neutral questions, simple continuations ("yes", "continue"), task directives without failure context.`;
 
 const MIN_CONFIDENCE = 0.5;
 

package/src/hooks/handlers/reflect-trigger.ts

@@ -43,6 +43,21 @@ function countNotesSince(since: string): number {
   return count;
 }
 
+/**
+ * Session-start nudge: surfaces when ≥5 new O/W/B notes are pending review.
+ * Returns a formatted reminder string, or "" when nothing is due.
+ */
+export function loadReflectNudge(): string {
+  const lastReflect = getLastReflectDate();
+  const newNotes = countNotesSince(lastReflect || "2000-01-01");
+  if (newNotes < MIN_NEW_NOTES) return "";
+  const since = lastReflect || "the start";
+  return [
+    "## Relationship Reflect Due",
+    `🔄 ${newNotes} new relationship observations since ${since} — offer to run \`/pal-reflect\` to promote recurring patterns into tracked opinions.`,
+  ].join("\n");
+}
+
 export async function checkReflectTrigger(): Promise<void> {
   const lastReflect = getLastReflectDate();
   const now = new Date();

package/src/hooks/lib/analyze-nudge.ts

@@ -0,0 +1,47 @@
+/**
+ * Analyze nudge — surfaces a session-start reminder when the learning analysis
+ * is overdue (≥7 days since last run, or never run).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+const MAX_DAYS = 7;
+const DAY_MS = 86_400_000;
+
+function markFile(): string {
+  return resolve(paths.state(), "last-analyze.json");
+}
+
+function readLastAnalyzeDate(): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(markFile(), "utf-8"));
+    return typeof parsed.lastAnalyzedTs === "string" ? parsed.lastAnalyzedTs : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeLastAnalyzeDate(ts: string): void {
+  writeFileSync(markFile(), `${JSON.stringify({ lastAnalyzedTs: ts }, null, 2)}\n`);
+}
+
+export function loadAnalyzeNudge(now: Date = new Date()): string {
+  const last = readLastAnalyzeDate();
+  if (!last) {
+    return [
+      "## Learning Analysis Due",
+      "📊 Learning analysis has never been run — offer to run `/pal-analyze` (`pal cli analyze`) for a health check on ratings, failure patterns, and graduation candidates.",
+    ].join("\n");
+  }
+
+  const daysSince = (now.getTime() - new Date(last).getTime()) / DAY_MS;
+  if (daysSince < MAX_DAYS) return "";
+
+  const since = new Date(last).toISOString().slice(0, 10);
+  return [
+    "## Learning Analysis Due",
+    `📊 Learning analysis last run ${Math.floor(daysSince)}d ago (${since}) — offer to run \`/pal-analyze\` for a health check.`,
+  ].join("\n");
+}