@monotykamary/pi-vcc 0.3.16

package/src/core/settings.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+const SETTINGS_PATH_DEFAULT = join(homedir(), ".pi", "agent", "pi-vcc-config.json");
+const settingsPath = (): string => process.env.PI_VCC_CONFIG_PATH ?? SETTINGS_PATH_DEFAULT;
+/** Backwards-compat export. Resolves at access time, not import time. */
+const SETTINGS_PATH = settingsPath();
+
+/** Per-model or global compaction threshold. */
+export interface ModelThreshold {
+  /**
+   * Tokens to reserve for LLM response. Overrides pi-core's
+   * compaction.reserveTokens for matching models.
+   *
+   * This controls *when* compaction triggers:
+   *   contextTokens > contextWindow - reserveTokens
+   *
+   * A higher value compacts earlier (more conservative); a lower value
+   * lets context grow larger before compacting.
+   *
+   * Takes precedence over compactPercent when both are set.
+   */
+  reserveTokens?: number;
+  /**
+   * Compaction trigger as a percentage of context window (1–99).
+   * Compaction fires when: contextTokens > contextWindow × compactPercent / 100
+   *
+   * E.g. compactPercent: 65 means "compact when context is 65% full",
+   * equivalent to reserveTokens = 35% of contextWindow.
+   *
+   * Ignored when reserveTokens is also set.
+   */
+  compactPercent?: number;
+  /**
+   * Recent tokens to keep (not summarized) when pi-core handles compaction.
+   *
+   * Only affects pi-core's default compaction (when overrideDefaultCompaction
+   * is false). Pi-vcc's own buildOwnCut uses task-boundary heuristics instead
+   * of token budgets, so this value is advisory/forward-compat for now.
+   */
+  keepRecentTokens?: number;
+}
+
+export interface PiVccSettings {
+  /**
+   * When true, pi-vcc handles ALL compactions:
+   *   - /compact (no args)
+   *   - /compact <text>
+   *   - auto threshold / overflow
+   *   - /pi-vcc (always handled regardless)
+   *
+   * When false, pi-vcc only handles /pi-vcc; everything else
+   * falls back to pi core's default LLM-based compaction.
+   */
+  overrideDefaultCompaction: boolean;
+  /** Write debug snapshot to /tmp/pi-vcc-debug.json on each compaction. */
+  debug: boolean;
+  /**
+   * Per-model compaction thresholds. Keys are matched against
+   * "provider/modelId" (e.g., "neuralwatt/zai-org/GLM-5.1-FP8") or
+   * just "modelId" (e.g., "GLM-5.1-FP8").
+   *
+   * When a model matches, its reserveTokens/compactPercent overrides
+   * pi-core's global compaction.reserveTokens for the *when to compact*
+   * decision. This lets different models compact at different context
+   * fill levels.
+   */
+  modelThresholds?: Record<string, ModelThreshold>;
+  /**
+   * Global threshold applied to all models not matched by modelThresholds.
+   * Uses compactPercent or reserveTokens (compactPercent is easier — e.g.
+   * 65 means "compact at 65% full"). If omitted, pi-core's global
+   * compaction settings apply (no override).
+   */
+  globalThreshold?: ModelThreshold;
+  /**
+   * @deprecated Use globalThreshold instead.
+   */
+  defaultThreshold?: ModelThreshold;
+}
+
+const DEFAULT_SETTINGS: PiVccSettings = {
+  overrideDefaultCompaction: true,
+  debug: false,
+};
+
+/**
+ * Resolve the effective ModelThreshold for a given model.
+ *
+ * Lookup order:
+ *  1. Exact match on "provider/modelId" key
+ *  2. Exact match on "modelId" key
+ *  4. globalThreshold from settings
+ *  5. undefined (no override — pi-core's global settings apply)
+ */
+export function getModelThreshold(
+  settings: PiVccSettings,
+  model: { id: string; provider?: string } | undefined,
+): ModelThreshold | undefined {
+  if (!model) return settings.globalThreshold ?? settings.defaultThreshold;
+
+  const providerModelId = model.provider ? `${model.provider}/${model.id}` : undefined;
+
+  // Exact match on provider/modelId
+  if (providerModelId && settings.modelThresholds?.[providerModelId]) {
+    return settings.modelThresholds[providerModelId];
+  }
+
+  // Exact match on just modelId
+  if (settings.modelThresholds?.[model.id]) {
+    return settings.modelThresholds[model.id];
+  }
+
+  return settings.globalThreshold ?? settings.defaultThreshold;
+}
+
+/**
+ * Resolve the effective reserveTokens for a threshold, handling both
+ * absolute (reserveTokens) and percentage (compactPercent) modes.
+ *
+ * Returns the number of tokens to reserve, or undefined if the
+ * threshold is not usable (no reserveTokens, no compactPercent,
+ * or compactPercent out of range).
+ */
+export function resolveReserveTokens(
+  threshold: ModelThreshold,
+  contextWindow: number,
+): number | undefined {
+  if (threshold.reserveTokens != null) return threshold.reserveTokens;
+  if (threshold.compactPercent != null && contextWindow > 0) {
+    const pct = threshold.compactPercent;
+    if (pct < 1 || pct > 99) return undefined;
+    return Math.round(contextWindow * (1 - pct / 100));
+  }
+  return undefined;
+}
+
+const readJson = (path: string): Record<string, unknown> | null => {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+};
+
+export function loadSettings(): PiVccSettings {
+  const parsed = readJson(settingsPath());
+  if (!parsed || typeof parsed !== "object") return { ...DEFAULT_SETTINGS };
+  const loaded = { ...DEFAULT_SETTINGS, ...(parsed as Partial<PiVccSettings>) };
+  // Backward compat: defaultThreshold → globalThreshold
+  if (!loaded.globalThreshold && (parsed as any).defaultThreshold) {
+    loaded.globalThreshold = (parsed as any).defaultThreshold;
+  }
+  return loaded;
+}
+
+/**
+ * Ensure ~/.pi/agent/pi-vcc-config.json exists with default keys.
+ * - File missing → create with full default block.
+ * - File exists but invalid JSON → no-op (don't clobber user file).
+ * - File exists and valid → fill in missing default keys, preserve existing values.
+ */
+export function scaffoldSettings(): void {
+  try {
+    const path = settingsPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    if (!existsSync(path)) {
+      writeFileSync(path, `${JSON.stringify(DEFAULT_SETTINGS, null, 2)}\n`);
+      return;
+    }
+
+    const parsed = readJson(path);
+    if (!parsed || typeof parsed !== "object") return; // don't clobber
+
+    let changed = false;
+    const next: Record<string, unknown> = { ...parsed };
+    for (const [key, value] of Object.entries(DEFAULT_SETTINGS)) {
+      if (!(key in next)) {
+        next[key] = value;
+        changed = true;
+      }
+    }
+    if (changed) writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+  } catch {
+    // best-effort; never crash extension load
+  }
+}

package/src/core/skill-collapse.ts

@@ -0,0 +1,35 @@
+/** Shared skill-tag collapse utilities */
+
+const SKILL_TAG_RE = /^-?\s*<skill\s+name="([^"]+)"/;
+const SKILL_CLOSE_RE = /^-?\s*<\/skill>/;
+
+/** Collapse skill tags in an array of lines — dedup by name, drop all content inside block */
+export const collapseSkillLines = (lines: string[]): string[] => {
+  const result: string[] = [];
+  const seenSkills = new Set<string>();
+  let insideSkill = false;
+
+  for (const line of lines) {
+    const skillMatch = line.match(SKILL_TAG_RE);
+    if (skillMatch) {
+      insideSkill = true;
+      const name = skillMatch[1];
+      if (!seenSkills.has(name)) {
+        seenSkills.add(name);
+        result.push(`[skill: ${name}]`);
+      }
+      continue;
+    }
+    if (insideSkill) {
+      if (SKILL_CLOSE_RE.test(line)) insideSkill = false;
+      continue;
+    }
+    result.push(line);
+  }
+  return result;
+};
+
+/** Collapse <skill name="X" ...>...</skill> blocks in raw text */
+const SKILL_BLOCK_RE = /<skill\s+name="([^"]+)"[^>]*>[\s\S]*?(?:<\/skill>|$)/g;
+export const collapseSkillText = (text: string): string =>
+  text.replace(SKILL_BLOCK_RE, (_, name) => `[skill: ${name}]`);

package/src/core/summarize.ts

@@ -0,0 +1,179 @@
+import type { Message } from "@earendil-works/pi-ai";
+import type { FileOps } from "../types";
+import { normalize } from "./normalize";
+import { filterNoise } from "./filter-noise";
+import { buildSections } from "./build-sections";
+import { formatSummary, capBrief, RECALL_NOTE, wrapLongLines } from "./format";
+
+export interface CompileInput {
+  messages: Message[];
+  previousSummary?: string;
+  fileOps?: FileOps;
+}
+
+// Cache-friendly order: stable sections first, volatile sections last
+const HEADER_NAMES = [
+  "Session Goal",
+  "User Preferences",
+  "Files And Changes",
+  "Commits",
+  "Anchors",
+  "Type Catalog",
+  "Outstanding Context",
+  "Earlier Turns",
+  "Current Status",
+];
+
+const SEPARATOR = "\n\n---\n\n";
+
+/** Preamble prepended to every compaction summary. */
+const HANDFOFF_PREAMBLE =
+  "This summary captures work done before the most recent messages in this session. " +
+  "Read it to pick up context — this is work already in progress. " +
+  "Do not recap what was done, do not ask what to do next. " +
+  "Continue directly where you left off.";
+
+/** Extract a named section from summary text */
+const sectionOf = (text: string, header: string): string => {
+  const tag = `[${header}]`;
+  const start = text.indexOf(tag);
+  if (start < 0) return "";
+  const after = text.slice(start);
+  // Find next section header or separator
+  const nextSection = HEADER_NAMES
+    .filter((h) => h !== header)
+    .map((h) => after.indexOf(`[${h}]`))
+    .filter((n) => n > 0);
+  const nextSep = after.indexOf("\n\n---\n\n");
+  const candidates = [...nextSection, ...(nextSep > 0 ? [nextSep] : [])].sort((a, b) => a - b);
+  const end = candidates[0];
+  return (end ? after.slice(0, end) : after).trim();
+};
+
+/** Extract the brief transcript part (everything after ---) */
+const briefOf = (text: string): string => {
+  const idx = text.indexOf(SEPARATOR);
+  if (idx < 0) return "";
+  return text.slice(idx + SEPARATOR.length).trim();
+};
+
+/** Merge a header section */
+const mergeHeaderSection = (header: string, prev: string, fresh: string): string => {
+  // Outstanding Context, Type Catalog, and Current Status are volatile -- always use fresh only
+  if (header === "Outstanding Context" || header === "Type Catalog" || header === "Current Status" || header === "Anchors") return fresh;
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+
+  // Files And Changes: merge by category (Modified/Created/Read), dedup paths
+  if (header === "Files And Changes") {
+    return mergeFileLines(prev, fresh);
+  }
+
+  // Session Goal, User Preferences: line-level dedup, cap
+  const isClean = (l: string) => l.startsWith("- ") && !l.includes("<skill") && !l.includes("</skill");
+  const prevLines = prev.split("\n").filter(isClean);
+  const freshLines = fresh.split("\n").filter(isClean);
+  const combined = [...new Set([...prevLines, ...freshLines])];
+  const CAP = header === "Session Goal" ? 8 : header === "Commits" ? 8 : header === "Earlier Turns" ? 15 : 15;
+  const capped = combined.length > CAP ? combined.slice(-CAP) : combined;
+  if (capped.length === 0) return "";
+  return `[${header}]\n${capped.join("\n")}`;
+};
+
+/** Merge Files And Changes by category, dedup paths across compactions */
+const mergeFileLines = (prev: string, fresh: string): string => {
+  const categories = ["Modified", "Created", "Read"] as const;
+  const merged: Record<string, Set<string>> = {};
+  for (const cat of categories) merged[cat] = new Set();
+
+  // Parse "- Modified: a, b, c (+N more)" lines from both prev and fresh
+  // Also handle symbol-annotated format: "- Modified: a (fn1, fn2), b"
+  for (const text of [prev, fresh]) {
+    for (const line of text.split("\n")) {
+      for (const cat of categories) {
+        const prefix = `- ${cat}: `;
+        if (!line.startsWith(prefix)) continue;
+        let rest = line.slice(prefix.length);
+        // Strip symbol annotations like " (fn1, fn2)" from each path
+        rest = rest.replace(/\s*\([^)]*\)/g, "");
+        // Strip "(+N more)" suffix
+        rest = rest.replace(/\s*\(\+\d+ more\)\s*$/, "");
+        for (const p of rest.split(",")) {
+          const trimmed = p.trim();
+          if (trimmed) merged[cat].add(trimmed);
+        }
+      }
+    }
+  }
+
+  // Dedup: if already in Modified, drop from Created (file existed before)
+  for (const p of merged.Modified) merged.Created.delete(p);
+
+  const cap = (set: Set<string>, limit: number) => {
+    const arr = [...set];
+    if (arr.length <= limit) return arr.join(", ");
+    return arr.slice(0, limit).join(", ") + ` (+${arr.length - limit} more)`;
+  };
+
+  const lines: string[] = [];
+  if (merged.Modified.size > 0) lines.push(`- Modified: ${cap(merged.Modified, 10)}`);
+  if (merged.Created.size > 0) lines.push(`- Created: ${cap(merged.Created, 10)}`);
+  if (merged.Read.size > 0) lines.push(`- Read: ${cap(merged.Read, 10)}`);
+  if (lines.length === 0) return "";
+  return `[Files And Changes]\n${lines.join("\n")}`;
+};
+
+const mergeBriefTranscript = (prev: string, fresh: string): string => {
+  if (!prev) return fresh;
+  if (!fresh) return prev;
+  return prev + "\n\n" + fresh;
+};
+
+const mergePrevious = (prev: string, fresh: string): string => {
+  // Merge header sections
+  const headers = HEADER_NAMES
+    .map((header) => {
+      const freshSec = sectionOf(fresh, header);
+      const prevSec = sectionOf(prev, header);
+      return mergeHeaderSection(header, prevSec, freshSec);
+    })
+    .filter(Boolean);
+
+  // Merge brief transcript
+  const prevBrief = briefOf(prev);
+  const freshBrief = briefOf(fresh);
+  const mergedBrief = mergeBriefTranscript(prevBrief, freshBrief);
+
+  const parts: string[] = [];
+  if (headers.length > 0) {
+    parts.push(headers.join("\n\n"));
+  }
+  if (mergedBrief) {
+    parts.push(capBrief(mergedBrief));
+  }
+
+  return parts.join(SEPARATOR);
+};
+
+export const compile = (input: CompileInput): string => {
+  const blocks = filterNoise(normalize(input.messages));
+  const data = buildSections({ blocks });
+  const fresh = formatSummary(data);
+  // Strip any legacy RECALL_NOTE baked into prev summary (pre-fix format)
+  // so merge doesn't re-stack it inside the brief.
+  const prev = input.previousSummary
+    ? stripRecallNote(input.previousSummary)
+    : undefined;
+  const merged = prev ? mergePrevious(prev, fresh) : fresh;
+  if (!merged) return "";
+  const body = merged + SEPARATOR + RECALL_NOTE;
+  return wrapLongLines(HANDFOFF_PREAMBLE + "\n\n" + body);
+};
+
+const stripRecallNote = (text: string): string => {
+  // Remove trailing RECALL_NOTE (and any separators surrounding it) if present.
+  // Handles both current format (---\n\nNOTE) and bare trailing NOTE.
+  const idx = text.lastIndexOf(RECALL_NOTE);
+  if (idx < 0) return text;
+  return text.slice(0, idx).replace(/\s*(?:\n\n---\n\n)?\s*$/, "").trimEnd();
+};

package/src/core/tool-args.ts

@@ -0,0 +1,14 @@
+export const extractPath = (args: Record<string, unknown>): string | null => {
+  for (const key of ["path", "file_path", "filePath", "file"]) {
+    if (typeof args[key] === "string") return args[key] as string;
+  }
+  return null;
+};
+
+export const summarizeToolArgs = (args: Record<string, unknown>): string => {
+  const path = extractPath(args);
+  if (path) return `path=${path}`;
+  if (typeof args.command === "string") return `command=${args.command}`;
+  if (typeof args.query === "string") return `query=${args.query}`;
+  return Object.keys(args).join(", ");
+};

package/src/details.ts

@@ -0,0 +1,19 @@
+export interface PiVccCompactionDetails {
+  compactor: "pi-vcc";
+  version: number;
+  sections: string[];
+  sourceMessageCount: number;
+  previousSummaryUsed: boolean;
+  /** Entry IDs [firstSummarizedId, lastSummarizedId] that this compaction summarized */
+  messageRange?: [string, string];
+  /** Summarized-to-summary token ratio (rounded) */
+  compressionRatio?: number;
+  /** ISO-8601 timestamp of when this compaction ran */
+  timestamp?: string;
+  /** Token count before compaction */
+  tokensBefore?: number;
+  /** Number of messages kept in tail */
+  keptCount?: number;
+  /** Estimated token count of kept tail */
+  keptTokensEst?: number;
+}

package/src/extract/commits.ts

@@ -0,0 +1,69 @@
+import type { NormalizedBlock } from "../types";
+
+interface CommitInfo {
+  hash?: string;
+  message: string;
+}
+
+const COMMIT_MSG_RE = /git\s+commit[^\n]*?-m\s+(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|\$?'((?:[^'\\]|\\.)*)')/;
+// Match short hash from git output: "[branch hash]" or "main hash" or 7-12 hex
+const HASH_RE = /\b([0-9a-f]{7,12})\b/;
+
+const firstLineOf = (text: string): string => {
+  const line = text.split(/\\n|\n/)[0] ?? "";
+  return line.trim();
+};
+
+const cleanMessage = (msg: string): string =>
+  msg.replace(/\\"/g, '"').replace(/\\'/g, "'").trim();
+
+/**
+ * Extract git commits from bash tool calls (`git commit -m "..."`) and pair
+ * with hash from the immediately following tool_result.
+ */
+export const extractCommits = (blocks: NormalizedBlock[]): CommitInfo[] => {
+  const commits: CommitInfo[] = [];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b.kind !== "tool_call" || b.name !== "bash") continue;
+    const cmd = typeof b.args.command === "string" ? b.args.command : "";
+    if (!/\bgit\s+commit\b/.test(cmd)) continue;
+    const m = cmd.match(COMMIT_MSG_RE);
+    if (!m) continue;
+    const message = firstLineOf(cleanMessage(m[1] ?? m[2] ?? m[3] ?? ""));
+    if (!message) continue;
+
+    let hash: string | undefined;
+    // Look at next tool_result for hash
+    for (let j = i + 1; j < Math.min(blocks.length, i + 3); j++) {
+      const r = blocks[j];
+      if (r.kind !== "tool_result") continue;
+      // Common git commit output: `[branch <hash>] message` or `<branch> <hash>..<hash>`
+      const bracket = r.text.match(/\[\S+\s+([0-9a-f]{7,12})\]/);
+      if (bracket) { hash = bracket[1]; break; }
+      const range = r.text.match(/\b([0-9a-f]{7,12})\.\.([0-9a-f]{7,12})\b/);
+      if (range) { hash = range[2]; break; }
+      const plain = r.text.match(HASH_RE);
+      if (plain) { hash = plain[1]; break; }
+    }
+
+    // Dedup by message+hash
+    const key = `${hash ?? ""}::${message}`;
+    if (!commits.some((c) => `${c.hash ?? ""}::${c.message}` === key)) {
+      commits.push({ hash, message });
+    }
+  }
+
+  return commits;
+};
+
+export const formatCommits = (commits: CommitInfo[], limit = 8): string[] => {
+  const lines: string[] = [];
+  const items = commits.slice(-limit); // keep most recent
+  for (const c of items) {
+    const prefix = c.hash ? `${c.hash}: ` : "";
+    lines.push(`${prefix}${c.message}`);
+  }
+  return lines;
+};

package/src/extract/goals.ts

@@ -0,0 +1,79 @@
+import type { NormalizedBlock } from "../types";
+import { nonEmptyLines, clip } from "../core/content";
+import { collapseSkillLines } from "../core/skill-collapse";
+
+const SCOPE_CHANGE_RE =
+  /\b(instead|actually|change of plan|forget that|new task|switch to|now I want|pivot|let'?s do|stop .* and)\b/i;
+
+const TASK_RE =
+  /\b(fix|implement|add|create|build|refactor|debug|investigate|update|remove|delete|migrate|deploy|test|write|set up)\b/i;
+
+const NOISE_SHORT_RE = /^(ok|yes|no|sure|yeah|yep|go|hi|hey|thx|thanks|ok\b.*|y|n|k)\s*[.!?]*$/i;
+
+// Reject lines that are clearly not user goals (pasted output, code, paths, tool dumps)
+// or meta-prompt boilerplate (command templates like `/issues` that start with "For each issue:"
+// followed by numbered "Read the issue in full..." steps).
+const NON_GOAL_RE =
+  /^\s*[\[│├└─╭╰]|```|^\s*(=[A-Z]+\(|function |const |let |var |import |export |class )|^(https?:|file:|\/[A-Za-z])|\\n|^\s*For each\b|\bin full\b[^\n]*\b(comments|issue|issues|PRs?|linked)\b/;
+
+// Signals that the rest of the user message is a command template (e.g. /issues),
+// in which case we should stop collecting goals at the signal line.
+const TEMPLATE_SIGNAL_RE =
+  /^\s*(For each\b|Do NOT implement\b|Analyze and propose\b|If Task\/context\b|Output:\s*$)/i;
+
+const truncateAtTemplate = (lines: string[]): string[] => {
+  const idx = lines.findIndex((l) => TEMPLATE_SIGNAL_RE.test(l));
+  return idx >= 0 ? lines.slice(0, idx) : lines;
+};
+
+const stripLeadingBullet = (line: string): string =>
+  line.replace(/^\s*(?:[-*+]|\d+\.)\s+/, "").trim();
+
+const MAX_GOAL_CHARS = 200;
+
+const isSubstantiveGoal = (text: string): boolean => {
+  const t = text.trim();
+  if (t.length <= 5) return false;
+  if (t.length > MAX_GOAL_CHARS) return false;
+  if (NOISE_SHORT_RE.test(t)) return false;
+  if (NON_GOAL_RE.test(t)) return false;
+  return true;
+};
+
+// Test scope-change / task intent only on the leading portion of a user block
+// so that pasted outputs below the actual instruction do not trigger matches.
+const LEADING_CHARS = 200;
+
+export const extractGoals = (blocks: NormalizedBlock[]): string[] => {
+  const goals: string[] = [];
+  let latestScopeChange: string[] | null = null;
+
+  for (const b of blocks) {
+    if (b.kind !== "user") continue;
+    const rawLines = nonEmptyLines(b.text);
+    const truncated = truncateAtTemplate(rawLines);
+    const lines = collapseSkillLines(truncated.filter(isSubstantiveGoal))
+      .map(stripLeadingBullet)
+      .filter((l) => l.length > 5);
+    if (lines.length === 0) continue;
+
+    if (goals.length === 0) {
+      goals.push(...lines.slice(0, 6));
+      continue;
+    }
+
+    const leading = b.text.slice(0, LEADING_CHARS);
+    if (SCOPE_CHANGE_RE.test(leading)) {
+      latestScopeChange = lines.slice(0, 3).map((l) => clip(l, MAX_GOAL_CHARS));
+    } else if (TASK_RE.test(leading) && lines[0].length > 15) {
+      latestScopeChange = lines.slice(0, 2).map((l) => clip(l, MAX_GOAL_CHARS));
+    }
+  }
+
+  // Only emit the [Scope change] marker when we actually captured bullets.
+  if (latestScopeChange && latestScopeChange.length > 0) {
+    goals.push("[Scope change]", ...latestScopeChange);
+  }
+
+  return goals.slice(0, 8);
+};

package/src/extract/preferences.ts

@@ -0,0 +1,55 @@
+import type { NormalizedBlock } from "../types";
+import { clip, nonEmptyLines } from "../core/content";
+
+// Tightened patterns: require a clear preference construction, not bare keywords.
+const PREF_PATTERNS = [
+  /\bprefer(?:s|red|ring)?\s+\w/i,
+  /\bdon'?t want\b/i,
+  /\balways (?:use|do|run|prefer|keep|make|format|write|add|set|put|prefix|start|include|append)\b/i,
+  /\bnever (?:use|do|run|push|commit|write|ignore|add|set|put|remove|delete|include|deploy)\b/i,
+  /\bplease (?:use|avoid|keep|make|don'?t|do not|format|write)\b/i,
+  /\b(?:style|format|language|naming)\s*[:=]\s*\S/i,
+];
+
+export const extractPreferences = (blocks: NormalizedBlock[]): string[] => {
+  const prefs: string[] = [];
+  const seen = new Set<string>();
+
+  for (const b of blocks) {
+    if (b.kind !== "user") continue;
+
+    let perBlock = 0;
+    for (const line of nonEmptyLines(b.text)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.length < 5) continue;
+      if (trimmed.length > 200) continue;
+      // Reject questions.
+      if (trimmed.endsWith("?") || trimmed.includes("?...")) continue;
+      if (!PREF_PATTERNS.some((p) => p.test(trimmed))) continue;
+
+      const clipped = clip(trimmed, 200);
+      const key = clipped.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      prefs.push(clipped);
+
+      // Cap per user block to avoid pasting long rule lists as many prefs.
+      if (++perBlock >= 1) break;
+    }
+  }
+
+  return prefs.slice(0, 10);
+};
+
+/**
+ * Remove preferences that duplicate goals (case-insensitive, trimmed).
+ * Called by `buildSections` so that the two sections do not overlap.
+ */
+export const dedupPreferencesAgainstGoals = (
+  prefs: string[],
+  goals: string[],
+): string[] => {
+  const norm = (s: string) => s.trim().toLowerCase();
+  const goalSet = new Set(goals.map(norm));
+  return prefs.filter((p) => !goalSet.has(norm(p)));
+};