portable-agent-layer 0.61.3 → 0.62.0

package/assets/schema/pal-settings.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/assets/schema/pal-settings.schema.json",
+  "title": "PAL settings",
+  "description": "Configuration for the Portable Agent Layer. Lives at ~/.pal/memory/pal-settings.json. All sections are optional; PAL falls back to defaults for anything absent.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference — enables editor autocomplete, validation, and hover docs."
+    },
+    "identity": {
+      "type": "object",
+      "description": "Who the assistant is and who it serves.",
+      "additionalProperties": false,
+      "properties": {
+        "ai": {
+          "type": "object",
+          "description": "The assistant's persona.",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "description": "Short name (e.g. the name you call the assistant)." },
+            "fullName": { "type": "string", "description": "Full/formal name." },
+            "displayName": { "type": "string", "description": "Uppercase label used in headers." },
+            "catchphrase": { "type": "string", "description": "Greeting line. '{name}' is substituted with the ai.name value." }
+          }
+        },
+        "principal": {
+          "type": "object",
+          "description": "The human the assistant works for.",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "description": "The principal's name." },
+            "timezone": { "type": "string", "description": "IANA timezone (e.g. Europe/Budapest)." }
+          }
+        }
+      }
+    },
+    "loadAtStartup": {
+      "type": "object",
+      "description": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
+      "additionalProperties": false,
+      "properties": {
+        "files": {
+          "type": "array",
+          "description": "Absolute or PAL-relative file paths to inject at session start.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "dynamicContext": {
+      "type": "object",
+      "description": "Dynamic context sections injected at session start. Set any key to false to disable it; absent keys default to enabled.",
+      "additionalProperties": { "type": "boolean" },
+      "properties": {
+        "wisdom": { "type": "boolean", "description": "Crystallized wisdom principles." },
+        "opinions": { "type": "boolean", "description": "Tracked user opinions." },
+        "relationship": { "type": "boolean", "description": "Recent relationship notes." },
+        "learningDigest": { "type": "boolean", "description": "Lessons-from-failures digest." },
+        "failurePatterns": { "type": "boolean", "description": "Recurring failure patterns." },
+        "projectHistory": { "type": "boolean", "description": "Per-project session history." },
+        "projects": { "type": "boolean", "description": "Active projects list." },
+        "sessionIntelligence": { "type": "boolean", "description": "Rating trends and session signals." },
+        "handoff": { "type": "boolean", "description": "Handoff note from the previous session." },
+        "selfModel": { "type": "boolean", "description": "The assistant's self-model synthesis." },
+        "contextualSteering": { "type": "boolean", "description": "Prompt-time steering self-checks (see the steering section)." },
+        "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
+      }
+    },
+    "attribution": {
+      "type": "object",
+      "description": "Git co-author attribution opt-in.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Add the PAL co-author trailer to commits." },
+        "decided": { "type": "boolean", "description": "Gates the one-time attribution prompt." }
+      }
+    },
+    "steering": {
+      "type": "object",
+      "description": "Contextual steering: PAL injects a short self-check into your prompt when it matches a task type. Toggle the whole feature via dynamicContext.contextualSteering.",
+      "additionalProperties": false,
+      "properties": {
+        "disable": {
+          "type": "array",
+          "description": "Shipped steering rules to suppress, by tag.",
+          "items": {
+            "type": "string",
+            "enum": ["debugging", "destructive", "refactor", "planning", "testing", "committing", "secrets"]
+          },
+          "uniqueItems": true
+        },
+        "rules": {
+          "type": "array",
+          "description": "Personal steering rules appended to the shipped set. A malformed entry (missing field or bad regex) is skipped, never fatal.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["tag", "pattern", "snippet"],
+            "properties": {
+              "tag": { "type": "string", "description": "Short identifier for this rule (also used to dedupe matches)." },
+              "pattern": { "type": "string", "description": "JavaScript regex source, matched case-insensitively against the prompt." },
+              "snippet": { "type": "string", "description": "The self-check text injected when the pattern matches." }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/assets/skills/opinion/SKILL.md

@@ -7,7 +7,7 @@ description: "Opinion tracker for relationship notes. PROACTIVE: When the user c
 
 Tool: `tools/opinion.ts`
 
-Manage confidence-scored opinions about the user. Opinions are promoted from recurring relationship notes (the W/O/B observations captured at session end). This tool is the fast path to grow opinion confidence — relationship notes feed the slow path (+2% per reflect cycle), while explicit confirmations here jump +10%.
+Manage confidence-scored opinions about the user. Opinions are promoted from recurring relationship notes (the W/O/B observations captured at session end). This tool is the fast path to grow opinion confidence — relationship notes feed the slow path (+5% per reflect cycle), while explicit confirmations here jump +10%.
 
 Opinions at ≥85% confidence are automatically injected into every session context.
 
@@ -42,12 +42,12 @@ bun opinion.ts list
 # Show details for a specific opinion (fuzzy-matched)
 bun opinion.ts show "keywords"
 
-# Add a new opinion (starts at 50%)
+# Add a new opinion (starts at 60%)
 bun opinion.ts add "statement" [--category workflow]
 
 # Add evidence to an existing opinion
-bun opinion.ts evidence "keywords" --supporting "why"      # +2%
-bun opinion.ts evidence "keywords" --counter "why"         # -5%
+bun opinion.ts evidence "keywords" --supporting "why"      # +5%
+bun opinion.ts evidence "keywords" --counter "why"         # -10%
 bun opinion.ts evidence "keywords" --confirmation "why"    # +10%
 bun opinion.ts evidence "keywords" --contradiction "why"   # -20%
 ```
@@ -59,9 +59,9 @@ bun opinion.ts evidence "keywords" --contradiction "why"   # -20%
 ## Confidence Lifecycle
 
 ```
-New opinion (add) → 50%
-  ├── supporting evidence → +2% each
-  ├── counter evidence → -5% each
+New opinion (add) → 60%
+  ├── supporting evidence → +5% each
+  ├── counter evidence → -10% each
   ├── explicit confirmation → +10% each
   ├── explicit contradiction → -20% each
   └── at ≥85% → auto-injected into session context

package/assets/skills/opinion/tools/opinion.ts

@@ -147,7 +147,9 @@ switch (command) {
     const opinion = createOpinion(statement, "manual add");
     opinion.category = category;
     saveOpinion(opinion);
-    console.log(`  Added: "${statement}" [${category}] at 50%`);
+    console.log(
+      `  Added: "${statement}" [${category}] at ${Math.round(opinion.confidence * 100)}%`
+    );
     break;
   }
 
@@ -218,9 +220,9 @@ switch (command) {
   Commands:
     list                                      List all opinions with confidence bars
     show "keywords"                           Show opinion details + full evidence history
-    add "statement" [--category X]            Create new opinion (starts at 50%)
-    evidence "keywords" --supporting "why"    Supporting evidence (+2%)
-    evidence "keywords" --counter "why"       Counter evidence (-5%)
+    add "statement" [--category X]            Create new opinion (starts at 60%)
+    evidence "keywords" --supporting "why"    Supporting evidence (+5%)
+    evidence "keywords" --counter "why"       Counter evidence (-10%)
     evidence "keywords" --confirmation "why"  User explicitly confirmed (+10%)
     evidence "keywords" --contradiction "why" User explicitly contradicted (-20%)
 

package/assets/templates/hooks.copilot.json

@@ -21,6 +21,10 @@
       {
         "type": "command",
         "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      },
+      {
+        "type": "command",
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "agentStop": [

package/assets/templates/hooks.cursor.json

@@ -21,6 +21,10 @@
       {
         "type": "command",
         "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      },
+      {
+        "type": "command",
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "beforeShellExecution": [

package/assets/templates/pal-settings.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/assets/schema/pal-settings.schema.json",
   "identity": {
     "ai": {
       "name": "",
@@ -12,11 +13,9 @@
     }
   },
   "loadAtStartup": {
-    "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
     "files": []
   },
   "dynamicContext": {
-    "_docs": "Dynamic context sections injected at session start. Set to false to disable.",
     "wisdom": true,
     "opinions": true,
     "relationship": true,
@@ -26,6 +25,12 @@
     "projects": true,
     "sessionIntelligence": true,
     "handoff": true,
-    "selfModel": true
+    "selfModel": true,
+    "contextualSteering": true,
+    "steeringTestReport": false
+  },
+  "steering": {
+    "disable": [],
+    "rules": []
   }
 }

package/assets/templates/settings.claude.json

@@ -2,8 +2,6 @@
   "permissions": {
     "allow": [
       "Read(//*)",
-      "Grep(//*)",
-      "Glob(//*)",
       "WebFetch",
       "WebSearch",
       "Bash(cat //*)",
@@ -110,6 +108,15 @@
             "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

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

package/src/cli/index.ts

@@ -622,6 +622,13 @@ function nodeInstallHint(): string {
   return "install Node ≥ 22.6 (see https://nodejs.org or your package manager)";
 }
 
+function rtkInstallHint(): string {
+  if (process.platform === "win32")
+    return "download rtk.exe from https://github.com/rtk-ai/rtk/releases and add it to PATH";
+  if (process.platform === "darwin") return "`brew install rtk`";
+  return "`curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh`";
+}
+
 function checkHookHealth(home: string): HookHealth {
   const stateDir = resolve(home, "memory", "state");
   // Read current + all rotated logs (`.1`..`.5`) + legacy `.prev` so a recent
@@ -671,6 +678,7 @@ interface DoctorResult {
   cursor: ToolCheck;
   copilot: ToolCheck;
   codex: ToolCheck;
+  rtk: ToolCheck;
   hasAgent: boolean;
 }
 
@@ -684,6 +692,7 @@ function doctor(silent = false): DoctorResult {
       cursor: { name: "cursor", available: true },
       copilot: { name: "copilot", available: true },
       codex: { name: "codex", available: true },
+      rtk: { name: "rtk", available: true },
       hasAgent: true,
     };
   }
@@ -694,6 +703,7 @@ function doctor(silent = false): DoctorResult {
   const cursor = checkTool("cursor");
   const copilot = checkTool("copilot", ["version"]);
   const codex = checkTool("codex");
+  const rtk = checkTool("rtk");
   const hasAgent =
     claude.available ||
     opencode.available ||
@@ -751,6 +761,11 @@ function doctor(silent = false): DoctorResult {
       : fail(
           "Playwright Chromium — not found (run 'pal cli install' or 'bunx playwright install chromium')"
         );
+    rtk.available
+      ? ok(rtk.version || "rtk")
+      : info(
+          `rtk — not installed (optional; enables Bash output compression — ${rtkInstallHint()})`
+        );
 
     console.log("");
     log.info("PAL state");
@@ -1023,7 +1038,7 @@ function doctor(silent = false): DoctorResult {
     console.log("");
   }
 
-  return { bun, claude, opencode, cursor, copilot, codex, hasAgent };
+  return { bun, claude, opencode, cursor, copilot, codex, rtk, hasAgent };
 }
 
 // ── Commands ──

package/src/hooks/RtkWrap.ts

@@ -0,0 +1,52 @@
+/**
+ * Hook: PreToolUse — transparently wraps Bash commands in `rtk` to compress
+ * tool output before it reaches the model's context.
+ *
+ * PAL owns the wiring + presence-gating; rtk owns the rewrite. We do NOT
+ * reimplement rtk's selectivity or per-agent JSON shape — we forward the hook's
+ * stdin to `rtk hook <agent>` and pass its stdout straight back. rtk emits the
+ * correct rewrite object for each agent (Claude/Cursor/Copilot all differ), or
+ * nothing when a command isn't worth rewriting.
+ *
+ * Fail-open by construction: if rtk isn't installed, the agent can't rewrite,
+ * or anything throws, we emit nothing and exit 0 — the original command runs
+ * unchanged. rtk absent must never block or alter a Bash call.
+ *
+ * Codex (allow/deny only) and opencode (plugin path) have no `rtk hook`
+ * subcommand and are handled elsewhere — this hook no-ops for them.
+ */
+
+import { getActiveAgent } from "./lib/agent";
+import { findBinaryOnPath } from "./lib/which";
+
+const RTK_HOOK_SUBCOMMAND: Partial<Record<ReturnType<typeof getActiveAgent>, string>> = {
+  claude: "claude",
+  cursor: "cursor",
+  copilot: "copilot",
+};
+
+async function run(): Promise<void> {
+  const subcommand = RTK_HOOK_SUBCOMMAND[getActiveAgent()];
+  if (!subcommand) return; // codex/opencode — no rtk hook processor
+
+  const rtk = findBinaryOnPath("rtk");
+  if (!rtk) return; // fail-open: rtk not installed → command runs unchanged
+
+  const stdin = await Bun.stdin.text();
+  const proc = Bun.spawn([rtk, "hook", subcommand], {
+    stdin: Buffer.from(stdin),
+    stdout: "pipe",
+    stderr: "ignore", // drop rtk's "no hook installed" stderr nag
+  });
+  const out = await new Response(proc.stdout).text();
+  await proc.exited;
+  if (proc.exitCode === 0 && out) {
+    process.stdout.write(out);
+  }
+}
+
+try {
+  await run();
+} catch {
+  // Fail open — emit nothing, allow the original command.
+}

package/src/hooks/UserPromptOrchestrator.ts

@@ -7,7 +7,7 @@
  *  - session-name: generate 4-word session headline on first prompt
  */
 
-import { injectRetrieval } from "./handlers/inject-retrieval";
+import { injectPromptContext } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
 import { logDebug, logError, logPromptSnapshot } from "./lib/log";
@@ -30,8 +30,8 @@ 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 injected = await injectPromptContext(input.prompt);
+logPromptSnapshot(input.prompt, injected);
 
 const results = await Promise.allSettled([
   captureRating(input.prompt, sessionId),

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

@@ -60,7 +60,7 @@ async function processFailurePrinciple(
           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,
+          timeout: 90000,
           jsonSchema: {
             type: "object" as const,
             properties: {

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

@@ -12,6 +12,7 @@ import { logDebug, logError } from "../lib/log";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
+import { getSteeringReminder } from "../lib/steering";
 
 const TIMEOUT_MS = 250;
 
@@ -51,12 +52,11 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
   return result.reminder;
 }
 
-/** Write retrieval reminder to stdout in the correct format for the current agent.
+/** Write a reminder to stdout in the correct format for the current agent.
  *  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 null;
+ *  MUST be called at most once per hook run — Cursor/Codex expect a single JSON
+ *  object on stdout, so all prompt-time context is merged before this call. */
+function writeForAgent(reminder: string): void {
   if (isCursor()) {
     process.stdout.write(JSON.stringify({ additional_context: reminder }));
   } else if (isCodex()) {
@@ -71,5 +71,17 @@ export async function injectRetrieval(prompt: string): Promise<string | null> {
   } else {
     process.stdout.write(`${reminder}\n`);
   }
-  return reminder;
+}
+
+/** Gather all prompt-time context — prior-lesson retrieval + contextual steering —
+ *  merge into a single payload, and do the one per-agent write. Returns the combined
+ *  reminder that was injected, or null if there was nothing to inject. */
+export async function injectPromptContext(prompt: string): Promise<string | null> {
+  const retrieval = await getRetrievalReminder(prompt);
+  const steering = getSteeringReminder(prompt);
+  const parts = [steering, retrieval].filter((p): p is string => Boolean(p));
+  if (parts.length === 0) return null;
+  const combined = parts.join("\n\n");
+  writeForAgent(combined);
+  return combined;
 }

package/src/hooks/handlers/rating.ts

@@ -310,7 +310,7 @@ async function runSentimentInferenceAndStore(
       system: SENTIMENT_SYSTEM_PROMPT,
       user: contextBlock,
       maxTokens: 500,
-      timeout: 60000,
+      timeout: 90000,
       jsonSchema: SENTIMENT_SCHEMA,
       caller: "rating",
       sessionId,

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

@@ -178,7 +178,7 @@ async function captureSessionIntelligence(
       ].join("\n"),
       user: `User messages:\n${numberedMessages}\n\nLast AI response:\n${assistantWindow}`,
       maxTokens: 350,
-      timeout: 60000,
+      timeout: 90000,
       jsonSchema: INTELLIGENCE_SCHEMA,
       caller: "session-intelligence",
       sessionId,

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

@@ -70,7 +70,7 @@ async function upgradeWithInference(
       system: NAME_PROMPT,
       user: `Generate a 4-word title for: "${promptText}"`,
       maxTokens: 20,
-      timeout: 60000,
+      timeout: 90000,
       caller: "session-name",
       sessionId,
     });

package/src/hooks/handlers/update-check.ts

@@ -72,23 +72,26 @@ async function checkRepo(): Promise<UpdateCache> {
     });
     await fetch.exited;
 
-    const local = Bun.spawn(["git", "rev-parse", "HEAD"], {
+    const remote = Bun.spawn(["git", "rev-parse", "origin/main"], {
       cwd: repoDir,
       stdout: "pipe",
       stderr: "ignore",
       windowsHide: true,
     });
-    const localHash = (await new Response(local.stdout).text()).trim();
+    const remoteHash = (await new Response(remote.stdout).text()).trim();
 
-    const remote = Bun.spawn(["git", "rev-parse", "origin/main"], {
+    // "Ahead" (local unpushed commits) is not an update — only remote commits we
+    // lack are. Count HEAD..origin/main so being ahead or diverged never nags.
+    const behind = Bun.spawn(["git", "rev-list", "--count", "HEAD..origin/main"], {
       cwd: repoDir,
       stdout: "pipe",
       stderr: "ignore",
       windowsHide: true,
     });
-    const remoteHash = (await new Response(remote.stdout).text()).trim();
+    const behindCount =
+      Number.parseInt((await new Response(behind.stdout).text()).trim(), 10) || 0;
 
-    const available = localHash !== remoteHash && remoteHash.length > 0;
+    const available = behindCount > 0 && remoteHash.length > 0;
 
     // Get remote version from package.json on origin/main
     let latest = current;

package/src/hooks/lib/inference.ts

@@ -20,8 +20,7 @@
  * yet wired and currently fall through to the API path.
  */
 
-import { accessSync, constants, existsSync } from "node:fs";
-import { basename, delimiter, resolve as resolvePath } from "node:path";
+import { basename } from "node:path";
 import {
   getActiveAgent,
   isClaude,
@@ -33,6 +32,7 @@ import {
 import { logDebug } from "./log";
 import { HAIKU_MODEL } from "./models";
 import { buildSpawnGuardEnv, getInferenceDepth, SPAWN_GUARD_ENV } from "./spawn-guard";
+import { findBinaryOnPath } from "./which";
 
 export function hasApiKey(): boolean {
   return !!process.env.PAL_ANTHROPIC_API_KEY;
@@ -213,45 +213,6 @@ let opencodeBinaryCache: string | null | undefined;
 let copilotBinaryCache: string | null | undefined;
 let cursorBinaryCache: string | null | undefined;
 
-/**
- * Resolve a binary on PATH to its full absolute path.
- *
- * Manual PATH walk (instead of Bun.which / `which` subprocess) because:
- * 1. Ubuntu 24.04 dropped the `which` binary entirely.
- * 2. Windows has no `which` at all.
- * 3. Bun.which snapshots PATH at startup and ignores mid-test mutations.
- * 4. Bun.spawn on Windows is inconsistent at resolving PATHEXT for bare
- *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
- *
- * Returns the resolved absolute path or null.
- */
-function findBinaryOnPath(name: string): string | null {
-  const PATH = process.env.PATH;
-  if (!PATH) return null;
-  const exts =
-    process.platform === "win32"
-      ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
-      : [""];
-  for (const dir of PATH.split(delimiter)) {
-    if (!dir) continue;
-    for (const ext of exts) {
-      const candidate = resolvePath(dir, name + ext);
-      try {
-        if (process.platform === "win32") {
-          // Windows has no executable bit — existence in PATHEXT is enough.
-          if (existsSync(candidate)) return candidate;
-        } else {
-          accessSync(candidate, constants.X_OK);
-          return candidate;
-        }
-      } catch {
-        /* not here — try next */
-      }
-    }
-  }
-  return null;
-}
-
 function getClaudeBinary(): string | null {
   if (claudeBinaryCache !== undefined) return claudeBinaryCache;
   claudeBinaryCache = findBinaryOnPath("claude");

package/src/hooks/lib/opinions.ts

@@ -11,7 +11,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { paths } from "./paths";
-import { similarity } from "./text-similarity";
+import { containment, similarity } from "./text-similarity";
 
 // ── Types ──
 
@@ -118,16 +118,27 @@ function slugify(text: string): string {
     .join("-");
 }
 
-/** Find an existing opinion similar to the given text. Returns the opinion or null. */
+/** Find the best-matching opinion for the given text. Returns the opinion or null. */
 export function findSimilarOpinion(
   text: string,
   opinions: Opinion[],
   threshold = 0.3
 ): Opinion | null {
+  let best: Opinion | null = null;
+  let bestScore = 0;
   for (const op of opinions) {
-    if (similarity(text, op.statement) >= threshold) return op;
+    // Dice handles full-statement comparisons (dedup, reflect promotion);
+    // containment lets a short keyword query reach a long statement.
+    const score = Math.max(
+      similarity(text, op.statement),
+      containment(text, op.statement)
+    );
+    if (score >= threshold && score > bestScore) {
+      bestScore = score;
+      best = op;
+    }
   }
-  return null;
+  return best;
 }
 
 /** Create a new opinion from a recurring note. Starts at confidence 0.60. */

package/src/hooks/lib/settings.ts

@@ -25,6 +25,11 @@ export interface PalSettingsData {
   dynamicContext?: Record<string, boolean>;
   /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
   attribution?: { enabled?: boolean; decided?: boolean };
+  /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
+  steering?: {
+    disable?: string[];
+    rules?: Array<{ tag: string; pattern: string; snippet: string }>;
+  };
   [key: string]: unknown;
 }