pi-continuous-learning 0.6.0 → 0.8.0

package/dist/skill-scaffold.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Skill scaffolding from instinct clusters.
+ *
+ * When 3+ related instincts in the same domain form a cohesive topic,
+ * generates a SKILL.md file that can be installed as a Pi skill.
+ */
+import type { DomainCluster } from "./graduation.js";
+export interface SkillScaffold {
+    name: string;
+    description: string;
+    domain: string;
+    content: string;
+    sourceInstinctIds: string[];
+}
+/**
+ * Generates a SKILL.md scaffold from a domain cluster of instincts.
+ */
+export declare function generateSkillScaffold(cluster: DomainCluster): SkillScaffold;
+/**
+ * Generates skill scaffolds for all qualifying clusters.
+ */
+export declare function generateAllSkillScaffolds(clusters: DomainCluster[]): SkillScaffold[];
+//# sourceMappingURL=skill-scaffold.d.ts.map

package/dist/skill-scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-scaffold.d.ts","sourceRoot":"","sources":["../src/skill-scaffold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAyBD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAgC3E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,EAAE,GACxB,aAAa,EAAE,CAEjB"}

package/dist/skill-scaffold.js

@@ -0,0 +1,62 @@
+/**
+ * Skill scaffolding from instinct clusters.
+ *
+ * When 3+ related instincts in the same domain form a cohesive topic,
+ * generates a SKILL.md file that can be installed as a Pi skill.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function toSkillName(domain) {
+    return domain.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function formatInstinctAsSection(instinct, index) {
+    return [
+        `### ${index + 1}. ${instinct.title}`,
+        "",
+        `**When:** ${instinct.trigger}`,
+        "",
+        instinct.action,
+        "",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generates a SKILL.md scaffold from a domain cluster of instincts.
+ */
+export function generateSkillScaffold(cluster) {
+    const name = toSkillName(cluster.domain);
+    const sortedInstincts = [...cluster.instincts].sort((a, b) => b.confidence - a.confidence);
+    const description = `Learned ${cluster.domain} patterns from coding sessions. ` +
+        `Covers ${sortedInstincts.length} practices distilled from instinct observations.`;
+    const sections = sortedInstincts.map((inst, i) => formatInstinctAsSection(inst, i));
+    const content = [
+        `# ${cluster.domain} Skill`,
+        "",
+        `> Auto-generated from ${sortedInstincts.length} graduated instincts in the "${cluster.domain}" domain.`,
+        "",
+        `## Description`,
+        "",
+        description,
+        "",
+        `## Practices`,
+        "",
+        ...sections,
+    ].join("\n");
+    return {
+        name,
+        description,
+        domain: cluster.domain,
+        content,
+        sourceInstinctIds: sortedInstincts.map((i) => i.id),
+    };
+}
+/**
+ * Generates skill scaffolds for all qualifying clusters.
+ */
+export function generateAllSkillScaffolds(clusters) {
+    return clusters.map(generateSkillScaffold);
+}
+//# sourceMappingURL=skill-scaffold.js.map

package/dist/skill-scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-scaffold.js","sourceRoot":"","sources":["../src/skill-scaffold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,uBAAuB,CAAC,QAAkB,EAAE,KAAa;IAChE,OAAO;QACL,OAAO,KAAK,GAAG,CAAC,KAAK,QAAQ,CAAC,KAAK,EAAE;QACrC,EAAE;QACF,aAAa,QAAQ,CAAC,OAAO,EAAE;QAC/B,EAAE;QACF,QAAQ,CAAC,MAAM;QACf,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAsB;IAC1D,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CACjD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CACtC,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,OAAO,CAAC,MAAM,kCAAkC;QAC7E,UAAU,eAAe,CAAC,MAAM,kDAAkD,CAAC;IAErF,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpF,MAAM,OAAO,GAAG;QACd,KAAK,OAAO,CAAC,MAAM,QAAQ;QAC3B,EAAE;QACF,yBAAyB,eAAe,CAAC,MAAM,gCAAgC,OAAO,CAAC,MAAM,WAAW;QACxG,EAAE;QACF,gBAAgB;QAChB,EAAE;QACF,WAAW;QACX,EAAE;QACF,cAAc;QACd,EAAE;QACF,GAAG,QAAQ;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO;QACL,IAAI;QACJ,WAAW;QACX,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO;QACP,iBAAiB,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAyB;IAEzB,OAAO,QAAQ,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAC7C,CAAC"}

package/dist/types.d.ts

@@ -46,7 +46,11 @@ export interface Instinct {
     inactive_count: number;
     evidence?: string[];
     flagged_for_removal?: boolean;
+    graduated_to?: GraduationTarget;
+    graduated_at?: string;
+    last_confirmed_session?: string;
 }
+export type GraduationTarget = "agents-md" | "skill" | "command";
 export interface ProjectEntry {
     id: string;
     name: string;
@@ -71,5 +75,10 @@ export interface Config {
     active_hours_end: number;
     max_idle_seconds: number;
     log_path?: string;
+    max_total_instincts_per_project: number;
+    max_total_instincts_global: number;
+    max_new_instincts_per_run: number;
+    flagged_cleanup_days: number;
+    instinct_ttl_days: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,WAAW,GACX,YAAY,GACZ,UAAU,GACV,WAAW,GACX,iBAAiB,GACjB,cAAc,CAAC;AAEnB,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AACjD,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,MAAM;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,MAAM,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continuous-learning",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A Pi extension that observes coding sessions and distills patterns into reusable instincts.",
   "type": "module",
   "license": "MIT",

package/src/agents-md.ts

@@ -1,9 +1,11 @@
 /**
- * Utility for reading AGENTS.md files.
- * Provides a safe wrapper around filesystem access that returns null on any failure.
+ * Utility for reading and writing AGENTS.md files.
+ * Provides safe wrappers around filesystem access.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Instinct } from "./types.js";
 
 /**
  * Reads an AGENTS.md file and returns its content.
@@ -21,3 +23,71 @@ export function readAgentsMd(filePath: string): string | null {
     return null;
   }
 }
+
+/**
+ * Formats an instinct as an AGENTS.md section entry.
+ * Produces a markdown block with the instinct title as heading and
+ * trigger/action as content.
+ */
+export function formatInstinctAsAgentsMdEntry(instinct: Instinct): string {
+  const lines = [
+    `### ${instinct.title}`,
+    "",
+    `**When:** ${instinct.trigger}`,
+    "",
+    instinct.action,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Generates a complete AGENTS.md diff showing proposed additions.
+ * Returns the full new content that would result from appending the entries.
+ */
+export function generateAgentsMdDiff(
+  currentContent: string | null,
+  instincts: Instinct[]
+): string {
+  const entries = instincts.map(formatInstinctAsAgentsMdEntry);
+  const graduatedSection = [
+    "",
+    "## Graduated Instincts",
+    "",
+    ...entries,
+  ].join("\n");
+
+  if (currentContent === null || currentContent.trim().length === 0) {
+    return `# Project Guidelines\n${graduatedSection}\n`;
+  }
+
+  // If the section already exists, append to it; otherwise add a new section
+  if (currentContent.includes("## Graduated Instincts")) {
+    return `${currentContent.trimEnd()}\n\n${entries.join("\n")}\n`;
+  }
+
+  return `${currentContent.trimEnd()}\n${graduatedSection}\n`;
+}
+
+/**
+ * Appends graduated instinct entries to an AGENTS.md file.
+ * Creates the file and parent directories if they don't exist.
+ *
+ * @param filePath - Absolute path to AGENTS.md
+ * @param instincts - Instincts to append as entries
+ * @returns The new file content that was written
+ */
+export function appendToAgentsMd(
+  filePath: string,
+  instincts: Instinct[]
+): string {
+  if (instincts.length === 0) return readAgentsMd(filePath) ?? "";
+
+  const currentContent = readAgentsMd(filePath);
+  const newContent = generateAgentsMdDiff(currentContent, instincts);
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, newContent, "utf-8");
+
+  return newContent;
+}

package/src/analysis-event-log.ts

@@ -0,0 +1,171 @@
+/**
+ * Append-only analysis event log with atomic rename for safe consumption.
+ *
+ * The background analyzer appends events to `analysis-events.jsonl`.
+ * The extension consumes events by atomically renaming the file to
+ * `.consumed`, reading it, then deleting it. On POSIX, rename is atomic -
+ * any in-flight appends follow the inode to the renamed file.
+ *
+ * Multiple analyzer runs can append before the extension reads. No events
+ * are lost because each run only appends; the file is never truncated by
+ * the analyzer.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { getProjectDir } from "./storage.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const EVENTS_FILENAME = "analysis-events.jsonl";
+const CONSUMED_FILENAME = "analysis-events.consumed";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface InstinctChangeSummary {
+  readonly id: string;
+  readonly title: string;
+  readonly scope: "project" | "global";
+  readonly trigger?: string;
+  readonly action?: string;
+  readonly confidence_delta?: number;
+}
+
+export interface AnalysisEvent {
+  readonly timestamp: string;
+  readonly project_id: string;
+  readonly project_name: string;
+  readonly created: readonly InstinctChangeSummary[];
+  readonly updated: readonly InstinctChangeSummary[];
+  readonly deleted: readonly InstinctChangeSummary[];
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+export function getEventsPath(projectId: string, baseDir?: string): string {
+  return join(getProjectDir(projectId, baseDir), EVENTS_FILENAME);
+}
+
+export function getConsumedPath(projectId: string, baseDir?: string): string {
+  return join(getProjectDir(projectId, baseDir), CONSUMED_FILENAME);
+}
+
+// ---------------------------------------------------------------------------
+// Write (analyzer side)
+// ---------------------------------------------------------------------------
+
+/**
+ * Appends an analysis event to the project's event log.
+ * Skips writing if nothing changed (all arrays empty).
+ * Creates the parent directory if needed.
+ */
+export function appendAnalysisEvent(event: AnalysisEvent, baseDir?: string): void {
+  if (
+    event.created.length === 0 &&
+    event.updated.length === 0 &&
+    event.deleted.length === 0
+  ) {
+    return;
+  }
+
+  const eventsPath = getEventsPath(event.project_id, baseDir);
+  mkdirSync(dirname(eventsPath), { recursive: true });
+  appendFileSync(eventsPath, JSON.stringify(event) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Read and clear (extension side)
+// ---------------------------------------------------------------------------
+
+/**
+ * Atomically consumes all pending analysis events for a project.
+ *
+ * Strategy:
+ * 1. Check for orphaned `.consumed` file from a prior crash - read it first
+ * 2. Rename `analysis-events.jsonl` to `.consumed` (atomic on POSIX)
+ * 3. Read and parse all lines from `.consumed`
+ * 4. Delete `.consumed`
+ *
+ * Returns an empty array if no events exist or rename fails (e.g. file
+ * doesn't exist, or another consumer raced us).
+ */
+export function consumeAnalysisEvents(
+  projectId: string,
+  baseDir?: string
+): readonly AnalysisEvent[] {
+  const eventsPath = getEventsPath(projectId, baseDir);
+  const consumedPath = getConsumedPath(projectId, baseDir);
+
+  const allEvents: AnalysisEvent[] = [];
+
+  // Step 1: recover orphaned consumed file from prior crash
+  if (existsSync(consumedPath)) {
+    allEvents.push(...parseEventsFile(consumedPath));
+    safeUnlink(consumedPath);
+  }
+
+  // Step 2: atomically rename the events file
+  if (existsSync(eventsPath)) {
+    try {
+      renameSync(eventsPath, consumedPath);
+    } catch {
+      // Rename failed (race with another consumer, or OS issue).
+      // Return whatever we recovered from step 1.
+      return allEvents;
+    }
+
+    // Step 3: read the renamed file
+    allEvents.push(...parseEventsFile(consumedPath));
+
+    // Step 4: delete consumed file
+    safeUnlink(consumedPath);
+  }
+
+  return allEvents;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseEventsFile(filePath: string): AnalysisEvent[] {
+  const events: AnalysisEvent[] = [];
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n").filter((line) => line.trim().length > 0);
+
+    for (const line of lines) {
+      try {
+        events.push(JSON.parse(line) as AnalysisEvent);
+      } catch {
+        // Skip malformed lines - don't lose other events
+      }
+    }
+  } catch {
+    // File read failed - return empty
+  }
+
+  return events;
+}
+
+function safeUnlink(filePath: string): void {
+  try {
+    if (existsSync(filePath)) unlinkSync(filePath);
+  } catch {
+    // Best effort cleanup
+  }
+}

package/src/analysis-notification.ts

@@ -0,0 +1,79 @@
+/**
+ * Extension-side notification for analysis events.
+ *
+ * On `before_agent_start`, consumes pending analysis events and shows
+ * a brief one-line notification summarizing instinct changes since the
+ * last session interaction.
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  consumeAnalysisEvents,
+  type AnalysisEvent,
+} from "./analysis-event-log.js";
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregates multiple analysis events into a single summary line.
+ * Returns null when no changes occurred.
+ */
+export function formatNotification(events: readonly AnalysisEvent[]): string | null {
+  if (events.length === 0) return null;
+
+  let created = 0;
+  let updated = 0;
+  let deleted = 0;
+  const createdIds: string[] = [];
+
+  for (const event of events) {
+    created += event.created.length;
+    updated += event.updated.length;
+    deleted += event.deleted.length;
+    for (const c of event.created) {
+      createdIds.push(c.id);
+    }
+  }
+
+  if (created === 0 && updated === 0 && deleted === 0) return null;
+
+  const parts: string[] = [];
+  if (created > 0) {
+    const idList = createdIds.slice(0, 3).join(", ");
+    const suffix = createdIds.length > 3 ? ", ..." : "";
+    parts.push(`+${created} new (${idList}${suffix})`);
+  }
+  if (updated > 0) {
+    parts.push(`${updated} updated`);
+  }
+  if (deleted > 0) {
+    parts.push(`${deleted} deleted`);
+  }
+
+  return `[instincts] Background analysis: ${parts.join(", ")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks for pending analysis events and shows a notification if any exist.
+ * Safe to call on every `before_agent_start` - no-ops when there's nothing.
+ */
+export function checkAnalysisNotifications(
+  ctx: ExtensionContext,
+  projectId: string | null,
+  baseDir?: string
+): void {
+  if (!projectId) return;
+
+  const events = consumeAnalysisEvents(projectId, baseDir);
+  const message = formatNotification(events);
+
+  if (message) {
+    ctx.ui.notify(message, "info");
+  }
+}

package/src/cli/analyze-single-shot.ts

@@ -10,6 +10,11 @@ import { complete } from "@mariozechner/pi-ai";
 import type { Instinct } from "../types.js";
 import { serializeInstinct } from "../instinct-parser.js";
 
+/** Chars-per-token heuristic for prompt size estimation. */
+const CHARS_PER_TOKEN = 4;
+import { validateInstinct, findSimilarInstinct } from "../instinct-validator.js";
+import { confirmationDelta } from "../confidence.js";
+
 export interface InstinctChangePayload {
   id: string;
   title: string;
@@ -23,6 +28,7 @@ export interface InstinctChangePayload {
   contradicted_count?: number;
   inactive_count?: number;
   evidence?: string[];
+  last_confirmed_session?: string;
 }
 
 export interface InstinctChange {
@@ -73,26 +79,100 @@ export function parseChanges(raw: string): InstinctChange[] {
 
 /**
  * Builds a full Instinct from a create/update change.
- * Returns null for delete changes or changes with missing instinct data.
+ * Returns null for delete changes, changes with missing instinct data,
+ * invalid fields, or semantically duplicate actions.
+ *
+ * @param change        - The change to apply
+ * @param existing      - The existing instinct with this ID, if any
+ * @param projectId     - Project ID for scoping
+ * @param allInstincts  - All current instincts, used for dedup check on creates
  */
 export function buildInstinctFromChange(
   change: InstinctChange,
   existing: Instinct | null,
-  projectId: string
+  projectId: string,
+  allInstincts: Instinct[] = []
 ): Instinct | null {
   if (change.action === "delete" || !change.instinct) {
     return null;
   }
 
-  const now = new Date().toISOString();
   const payload = change.instinct;
 
+  const validation = validateInstinct({
+    action: payload.action,
+    trigger: payload.trigger,
+    domain: payload.domain,
+  });
+  if (!validation.valid) {
+    return null;
+  }
+
+  // On create, reject if semantically similar to an existing instinct (skip self on update)
+  if (change.action === "create") {
+    const similar = findSimilarInstinct(
+      { trigger: payload.trigger, action: payload.action },
+      allInstincts,
+      payload.id
+    );
+    if (similar) {
+      return null;
+    }
+  }
+
+  const now = new Date().toISOString();
+
+  // For updates, recompute confidence client-side to enforce:
+  // 1. Per-session deduplication: only one confirmation per unique session_id
+  // 2. Diminishing returns: each additional confirmation yields a smaller delta
+  let resolvedConfidence: number;
+  let resolvedConfirmedCount = payload.confirmed_count ?? existing?.confirmed_count ?? 0;
+  let resolvedLastConfirmedSession = payload.last_confirmed_session ?? existing?.last_confirmed_session;
+
+  if (change.action === "update" && existing !== null) {
+    const prevConfirmedCount = existing.confirmed_count;
+    const newConfirmedCount = payload.confirmed_count ?? prevConfirmedCount;
+    const contradictionsAdded = Math.max(
+      0,
+      (payload.contradicted_count ?? 0) - existing.contradicted_count,
+    );
+
+    // Detect whether the LLM intends to add a confirmation
+    const wantsToConfirm = newConfirmedCount > prevConfirmedCount;
+
+    // Session dedup: reject the confirmation if the confirming session is the
+    // same as the one that last confirmed this instinct.
+    const sessionDuplicate =
+      wantsToConfirm &&
+      resolvedLastConfirmedSession !== undefined &&
+      payload.last_confirmed_session !== undefined &&
+      payload.last_confirmed_session === existing.last_confirmed_session;
+
+    if (sessionDuplicate) {
+      // Revert to existing count - this session already confirmed the instinct
+      resolvedConfirmedCount = prevConfirmedCount;
+    }
+
+    // Recompute confidence from existing + explicit deltas (don't trust LLM arithmetic)
+    resolvedConfidence = existing.confidence;
+    if (wantsToConfirm && !sessionDuplicate) {
+      resolvedConfidence += confirmationDelta(prevConfirmedCount);
+    }
+    if (contradictionsAdded > 0) {
+      resolvedConfidence -= 0.15 * contradictionsAdded;
+    }
+    resolvedConfidence = Math.max(0.1, Math.min(0.9, resolvedConfidence));
+  } else {
+    // For creates, trust the LLM's initial confidence (no prior state to base delta on)
+    resolvedConfidence = Math.max(0.1, Math.min(0.9, payload.confidence));
+  }
+
   return {
     id: payload.id,
     title: payload.title,
     trigger: payload.trigger,
     action: payload.action,
-    confidence: Math.max(0.1, Math.min(0.9, payload.confidence)),
+    confidence: resolvedConfidence,
     domain: payload.domain,
     scope: payload.scope,
     source: "personal",
@@ -100,15 +180,61 @@ export function buildInstinctFromChange(
     created_at: existing?.created_at ?? now,
     updated_at: now,
     observation_count: payload.observation_count ?? 1,
-    confirmed_count: payload.confirmed_count ?? 0,
+    confirmed_count: resolvedConfirmedCount,
     contradicted_count: payload.contradicted_count ?? 0,
     inactive_count: payload.inactive_count ?? 0,
     ...(payload.evidence !== undefined ? { evidence: payload.evidence } : {}),
+    ...(resolvedLastConfirmedSession !== undefined
+      ? { last_confirmed_session: resolvedLastConfirmedSession }
+      : {}),
   };
 }
 
+/**
+ * Returns days elapsed since the given ISO 8601 date string.
+ */
+function daysSince(dateStr: string): number {
+  const ms = Date.now() - new Date(dateStr).getTime();
+  return Math.max(0, Math.floor(ms / (1000 * 60 * 60 * 24)));
+}
+
+/**
+ * Formats existing instincts as a compact JSON array for inline context.
+ * Reduces token usage by ~70% compared to full YAML+markdown serialization.
+ * Includes only the fields the analyzer needs to make decisions.
+ */
+export function formatInstinctsCompact(instincts: Instinct[]): string {
+  if (instincts.length === 0) {
+    return "[]";
+  }
+  const summaries = instincts.map((i) => ({
+    id: i.id,
+    trigger: i.trigger,
+    action: i.action,
+    confidence: i.confidence,
+    domain: i.domain,
+    scope: i.scope,
+    confirmed: i.confirmed_count,
+    contradicted: i.contradicted_count,
+    inactive: i.inactive_count,
+    age_days: daysSince(i.created_at),
+    ...(i.last_confirmed_session !== undefined
+      ? { last_confirmed_session: i.last_confirmed_session }
+      : {}),
+  }));
+  return JSON.stringify(summaries);
+}
+
+/**
+ * Estimates the token count of a text string using a chars/token heuristic.
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
 /**
  * Formats existing instincts as serialized markdown blocks for inline context.
+ * @deprecated Use formatInstinctsCompact for lower token usage.
  */
 export function formatInstinctsForPrompt(instincts: Instinct[]): string {
   if (instincts.length === 0) {