pi-continuous-learning 0.6.0 → 0.8.0

package/src/cli/analyze.ts

@@ -6,6 +6,7 @@ import {
   writeFileSync,
   unlinkSync,
 } from "node:fs";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { AuthStorage } from "@mariozechner/pi-coding-agent";
 import { getModel } from "@mariozechner/pi-ai";
@@ -22,13 +23,21 @@ import {
 } from "../storage.js";
 import { countObservations } from "../observations.js";
 import { runDecayPass } from "../instinct-decay.js";
+import { runCleanupPass } from "../instinct-cleanup.js";
 import { tailObservationsSince } from "../prompts/analyzer-user.js";
 import { buildSingleShotSystemPrompt } from "../prompts/analyzer-system-single-shot.js";
 import { buildSingleShotUserPrompt } from "../prompts/analyzer-user-single-shot.js";
 import {
   runSingleShot,
   buildInstinctFromChange,
+  estimateTokens,
 } from "./analyze-single-shot.js";
+import { isLowSignalBatch } from "../observation-signal.js";
+import {
+  appendAnalysisEvent,
+  type InstinctChangeSummary,
+  type AnalysisEvent,
+} from "../analysis-event-log.js";
 import {
   loadProjectInstincts,
   loadGlobalInstincts,
@@ -106,9 +115,31 @@ function startGlobalTimeout(timeoutMs: number, logger: AnalyzeLogger): void {
 // Per-project analysis
 // ---------------------------------------------------------------------------
 
+/** Max estimated tokens before fallback strategies are applied. */
+const PROMPT_TOKEN_BUDGET = 40_000;
+
 interface ProjectMeta {
   last_analyzed_at?: string;
   last_observation_line_count?: number;
+  /** SHA-256 hash of the last AGENTS.md content sent for this project (project-level file). */
+  agents_md_project_hash?: string;
+  /** SHA-256 hash of the last AGENTS.md content sent (global file). */
+  agents_md_global_hash?: string;
+}
+
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Truncates AGENTS.md content to section headers only (lines starting with #).
+ * Used as a fallback when the prompt is over the token budget.
+ */
+function truncateAgentsMdToHeaders(content: string): string {
+  return content
+    .split("\n")
+    .filter((line) => line.startsWith("#"))
+    .join("\n");
 }
 
 function loadProjectsRegistry(baseDir: string): Record<string, ProjectEntry> {
@@ -178,6 +209,10 @@ async function analyzeProject(
     return { ran: false, skippedReason: "no new observation lines after preprocessing" };
   }
 
+  if (isLowSignalBatch(newObsLines)) {
+    return { ran: false, skippedReason: "low-signal batch (no errors, corrections, or user redirections)" };
+  }
+
   const obsCount = countObservations(project.id, baseDir);
   if (obsCount < config.min_observations_to_analyze) {
     return { ran: false, skippedReason: `below threshold (${obsCount}/${config.min_observations_to_analyze})` };
@@ -186,6 +221,7 @@ async function analyzeProject(
   const startTime = Date.now();
   logger.projectStart(project.id, project.name, rawLineCount, obsCount);
 
+  runCleanupPass(project.id, config, baseDir);
   runDecayPass(project.id, baseDir);
 
   // Load current instincts inline - no tool calls needed
@@ -193,8 +229,21 @@ async function analyzeProject(
   const globalInstincts = loadGlobalInstincts(baseDir);
   const allInstincts = [...projectInstincts, ...globalInstincts];
 
-  const agentsMdProject = readAgentsMd(join(project.root, "AGENTS.md"));
-  const agentsMdGlobal = readAgentsMd(join(homedir(), ".pi", "agent", "AGENTS.md"));
+  // Load AGENTS.md, skipping if content hash is unchanged since last run.
+  const rawAgentsMdProject = readAgentsMd(join(project.root, "AGENTS.md"));
+  const rawAgentsMdGlobal = readAgentsMd(join(homedir(), ".pi", "agent", "AGENTS.md"));
+
+  const projectMdHash = rawAgentsMdProject ? hashContent(rawAgentsMdProject) : null;
+  const globalMdHash = rawAgentsMdGlobal ? hashContent(rawAgentsMdGlobal) : null;
+
+  const agentsMdProject =
+    rawAgentsMdProject && projectMdHash !== meta.agents_md_project_hash
+      ? rawAgentsMdProject
+      : null;
+  const agentsMdGlobal =
+    rawAgentsMdGlobal && globalMdHash !== meta.agents_md_global_hash
+      ? rawAgentsMdGlobal
+      : null;
 
   let installedSkills: InstalledSkill[] = [];
   try {
@@ -208,9 +257,51 @@ async function analyzeProject(
     // Skills loading is best-effort - continue without them
   }
 
-  const userPrompt = buildSingleShotUserPrompt(project, allInstincts, newObsLines, {
-    agentsMdProject,
-    agentsMdGlobal,
+  let promptObsLines = newObsLines;
+  let promptAgentsMdProject = agentsMdProject;
+  let promptAgentsMdGlobal = agentsMdGlobal;
+
+  const userPrompt = buildSingleShotUserPrompt(project, allInstincts, promptObsLines, {
+    agentsMdProject: promptAgentsMdProject,
+    agentsMdGlobal: promptAgentsMdGlobal,
+    installedSkills,
+  });
+
+  // Estimate token budget and apply fallbacks if over limit.
+  const systemPromptTokens = estimateTokens(buildSingleShotSystemPrompt());
+  let estimatedTotal = systemPromptTokens + estimateTokens(userPrompt);
+
+  if (estimatedTotal > PROMPT_TOKEN_BUDGET) {
+    logger.warn(
+      `Prompt over budget (${estimatedTotal} est. tokens > ${PROMPT_TOKEN_BUDGET}). Applying fallbacks.`
+    );
+
+    // Fallback 1: truncate AGENTS.md to headers only.
+    if (promptAgentsMdProject) {
+      promptAgentsMdProject = truncateAgentsMdToHeaders(promptAgentsMdProject);
+    }
+    if (promptAgentsMdGlobal) {
+      promptAgentsMdGlobal = truncateAgentsMdToHeaders(promptAgentsMdGlobal);
+    }
+
+    // Fallback 2: reduce observation lines to fit budget.
+    // Use binary-search-like reduction: keep halving until under budget.
+    while (promptObsLines.length > 1) {
+      const trimmedPrompt = buildSingleShotUserPrompt(
+        project,
+        allInstincts,
+        promptObsLines,
+        { agentsMdProject: promptAgentsMdProject, agentsMdGlobal: promptAgentsMdGlobal, installedSkills }
+      );
+      estimatedTotal = systemPromptTokens + estimateTokens(trimmedPrompt);
+      if (estimatedTotal <= PROMPT_TOKEN_BUDGET) break;
+      promptObsLines = promptObsLines.slice(Math.floor(promptObsLines.length / 2));
+    }
+  }
+
+  const finalUserPrompt = buildSingleShotUserPrompt(project, allInstincts, promptObsLines, {
+    agentsMdProject: promptAgentsMdProject,
+    agentsMdGlobal: promptAgentsMdGlobal,
     installedSkills,
   });
 
@@ -226,7 +317,7 @@ async function analyzeProject(
   const context = {
     systemPrompt: buildSingleShotSystemPrompt(),
     messages: [
-      { role: "user" as const, content: userPrompt, timestamp: Date.now() },
+      { role: "user" as const, content: finalUserPrompt, timestamp: Date.now() },
     ],
   };
 
@@ -235,6 +326,9 @@ async function analyzeProject(
   const timeoutHandle = setTimeout(() => abortController.abort(), timeoutMs);
 
   const instinctCounts = { created: 0, updated: 0, deleted: 0 };
+  const createdSummaries: InstinctChangeSummary[] = [];
+  const updatedSummaries: InstinctChangeSummary[] = [];
+  const deletedSummaries: InstinctChangeSummary[] = [];
   const projectInstinctsDir = getProjectInstinctsDir(project.id, "personal", baseDir);
   const globalInstinctsDir = getGlobalInstinctsDir("personal", baseDir);
 
@@ -243,6 +337,10 @@ async function analyzeProject(
     const result = await runSingleShot(context, model, apiKey, abortController.signal);
     singleShotMessage = result.message;
 
+    // Enforce creation rate limit: only the first N create actions per run are applied.
+    const maxNewInstincts = config.max_new_instincts_per_run ?? DEFAULT_CONFIG.max_new_instincts_per_run;
+    let createsRemaining = maxNewInstincts;
+
     for (const change of result.changes) {
       if (change.action === "delete") {
         const id = change.id;
@@ -252,21 +350,47 @@ async function analyzeProject(
         if (existsSync(filePath)) {
           unlinkSync(filePath);
           instinctCounts.deleted++;
+          deletedSummaries.push({
+            id,
+            title: id,
+            scope: change.scope ?? "project",
+          });
         }
-      } else {
-        // create or update
+      } else if (change.action === "create") {
+        if (createsRemaining <= 0) continue; // rate limit reached
         const existing = allInstincts.find((i) => i.id === change.instinct?.id) ?? null;
-        const instinct = buildInstinctFromChange(change, existing, project.id);
+        const instinct = buildInstinctFromChange(change, existing, project.id, allInstincts);
         if (!instinct) continue;
 
         const dir = instinct.scope === "global" ? globalInstinctsDir : projectInstinctsDir;
         saveInstinct(instinct, dir);
+        instinctCounts.created++;
+        createsRemaining--;
+        createdSummaries.push({
+          id: instinct.id,
+          title: instinct.title,
+          scope: instinct.scope,
+          trigger: instinct.trigger,
+          action: instinct.action,
+        });
+      } else {
+        // update
+        const existing = allInstincts.find((i) => i.id === change.instinct?.id) ?? null;
+        const instinct = buildInstinctFromChange(change, existing, project.id, allInstincts);
+        if (!instinct) continue;
 
-        if (change.action === "create") {
-          instinctCounts.created++;
-        } else {
-          instinctCounts.updated++;
-        }
+        const dir = instinct.scope === "global" ? globalInstinctsDir : projectInstinctsDir;
+        saveInstinct(instinct, dir);
+        instinctCounts.updated++;
+        const delta = existing
+          ? instinct.confidence - existing.confidence
+          : undefined;
+        updatedSummaries.push({
+          id: instinct.id,
+          title: instinct.title,
+          scope: instinct.scope,
+          ...(delta !== undefined ? { confidence_delta: delta } : {}),
+        });
       }
     }
   } finally {
@@ -296,9 +420,27 @@ async function analyzeProject(
 
   logger.projectComplete(stats);
 
+  // Write analysis event for extension notification
+  const analysisEvent: AnalysisEvent = {
+    timestamp: new Date().toISOString(),
+    project_id: project.id,
+    project_name: project.name,
+    created: createdSummaries,
+    updated: updatedSummaries,
+    deleted: deletedSummaries,
+  };
+  appendAnalysisEvent(analysisEvent, baseDir);
+
   saveProjectMeta(
     project.id,
-    { ...meta, last_analyzed_at: new Date().toISOString(), last_observation_line_count: totalLineCount },
+    {
+      ...meta,
+      last_analyzed_at: new Date().toISOString(),
+      last_observation_line_count: totalLineCount,
+      // Update AGENTS.md hashes only when the content was actually sent.
+      ...(agentsMdProject && projectMdHash ? { agents_md_project_hash: projectMdHash } : {}),
+      ...(agentsMdGlobal && globalMdHash ? { agents_md_global_hash: globalMdHash } : {}),
+    },
     baseDir
   );
 

package/src/command-scaffold.ts

@@ -0,0 +1,105 @@
+/**
+ * Command scaffolding from instinct clusters.
+ *
+ * When 3+ related instincts in the same domain form an actionable workflow,
+ * generates a Pi slash command scaffold that codifies the pattern.
+ */
+
+import type { Instinct } from "./types.js";
+import type { DomainCluster } from "./graduation.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CommandScaffold {
+  name: string;
+  description: string;
+  domain: string;
+  content: string;
+  sourceInstinctIds: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toCommandName(domain: string): string {
+  return domain.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function formatInstinctAsStep(instinct: Instinct, index: number): string {
+  return [
+    `${index + 1}. **${instinct.title}**`,
+    `   - Trigger: ${instinct.trigger}`,
+    `   - Action: ${instinct.action}`,
+    "",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates a command scaffold from a domain cluster of instincts.
+ * The scaffold describes a slash command that encodes the workflow
+ * distilled from the instinct cluster.
+ */
+export function generateCommandScaffold(cluster: DomainCluster): CommandScaffold {
+  const name = toCommandName(cluster.domain);
+  const sortedInstincts = [...cluster.instincts].sort(
+    (a, b) => b.confidence - a.confidence
+  );
+
+  const description = `Learned ${cluster.domain} workflow from coding sessions. ` +
+    `Encodes ${sortedInstincts.length} steps distilled from instinct observations.`;
+
+  const steps = sortedInstincts.map((inst, i) => formatInstinctAsStep(inst, i));
+
+  const content = [
+    `# /${name} Command`,
+    "",
+    `> Auto-generated from ${sortedInstincts.length} graduated instincts in the "${cluster.domain}" domain.`,
+    "",
+    `## Description`,
+    "",
+    description,
+    "",
+    `## Command: \`/${name}\``,
+    "",
+    `When invoked, this command should guide the agent through these steps:`,
+    "",
+    ...steps,
+    `## Implementation Notes`,
+    "",
+    `Register this command in your Pi extension's \`index.ts\`:`,
+    "",
+    "```typescript",
+    `pi.registerCommand("${name}", {`,
+    `  description: "${description.replace(/"/g, '\\"')}",`,
+    `  handler: async (args, ctx) => {`,
+    `    // TODO: Implement ${name} workflow`,
+    `  },`,
+    `});`,
+    "```",
+    "",
+  ].join("\n");
+
+  return {
+    name,
+    description,
+    domain: cluster.domain,
+    content,
+    sourceInstinctIds: sortedInstincts.map((i) => i.id),
+  };
+}
+
+/**
+ * Generates command scaffolds for all qualifying clusters.
+ */
+export function generateAllCommandScaffolds(
+  clusters: DomainCluster[]
+): CommandScaffold[] {
+  return clusters.map(generateCommandScaffold);
+}

package/src/confidence.ts

@@ -21,12 +21,19 @@ const OBS_BRACKET_MED_MAX = 5;
 const OBS_BRACKET_HIGH_MAX = 10;
 
 // adjustConfidence deltas
-const DELTA_CONFIRMED = 0.05;
+// Confirmation uses diminishing returns to prevent runaway confidence on trivially easy-to-confirm instincts.
+const DELTA_CONFIRMED_TIER1 = 0.05; // 1st–3rd confirmation
+const DELTA_CONFIRMED_TIER2 = 0.03; // 4th–6th confirmation
+const DELTA_CONFIRMED_TIER3 = 0.01; // 7th+ confirmation
 const DELTA_CONTRADICTED = -0.15;
 const DELTA_INACTIVE = 0;
 
+const CONFIRMED_TIER1_MAX = 3;
+const CONFIRMED_TIER2_MAX = 6;
+
 // applyPassiveDecay
-const DECAY_PER_WEEK = 0.02;
+// Increased from 0.02 to 0.05: at 0.5 confidence, reaches 0.1 in ~8 weeks instead of 20.
+const DECAY_PER_WEEK = 0.05;
 const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
 
 // ---------------------------------------------------------------------------
@@ -35,6 +42,16 @@ const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
 
 export type FeedbackOutcome = "confirmed" | "contradicted" | "inactive";
 
+/**
+ * Returns the confirmation confidence delta using diminishing returns.
+ * Higher confirmed_count yields smaller increments to prevent runaway scores.
+ */
+export function confirmationDelta(confirmedCount: number): number {
+  if (confirmedCount <= CONFIRMED_TIER1_MAX) return DELTA_CONFIRMED_TIER1;
+  if (confirmedCount <= CONFIRMED_TIER2_MAX) return DELTA_CONFIRMED_TIER2;
+  return DELTA_CONFIRMED_TIER3;
+}
+
 export interface ConfidenceResult {
   confidence: number;
   flaggedForRemoval: boolean;
@@ -70,18 +87,28 @@ export function initialConfidence(observationCount: number): number {
 
 /**
  * Adjusts confidence based on a feedback outcome from the observer loop.
+ * For "confirmed" outcomes, applies diminishing returns based on how many
+ * times the instinct has already been confirmed (higher count = smaller delta).
  * Returns the clamped confidence and a flag indicating if removal is warranted.
+ *
+ * @param current       - Current confidence value
+ * @param outcome       - Feedback outcome type
+ * @param confirmedCount - Current confirmed_count (used for diminishing returns on confirmations)
  */
 export function adjustConfidence(
   current: number,
   outcome: FeedbackOutcome,
+  confirmedCount = 0,
 ): ConfidenceResult {
-  const deltas: Record<FeedbackOutcome, number> = {
-    confirmed: DELTA_CONFIRMED,
-    contradicted: DELTA_CONTRADICTED,
-    inactive: DELTA_INACTIVE,
-  };
-  const raw = current + deltas[outcome];
+  let delta: number;
+  if (outcome === "confirmed") {
+    delta = confirmationDelta(confirmedCount);
+  } else if (outcome === "contradicted") {
+    delta = DELTA_CONTRADICTED;
+  } else {
+    delta = DELTA_INACTIVE;
+  }
+  const raw = current + delta;
   return toResult(raw);
 }
 

package/src/config.ts

@@ -38,6 +38,34 @@ export const CONFIG_PATH = path.join(
   "config.json"
 );
 
+// ---------------------------------------------------------------------------
+// Graduation maturity criteria
+// ---------------------------------------------------------------------------
+
+/** Minimum age in days before an instinct is eligible for graduation. */
+export const GRADUATION_MIN_AGE_DAYS = 7;
+
+/** Minimum confidence to qualify for graduation. */
+export const GRADUATION_MIN_CONFIDENCE = 0.75;
+
+/** Minimum confirmed_count to qualify for graduation. */
+export const GRADUATION_MIN_CONFIRMED = 3;
+
+/** Maximum contradicted_count allowed for graduation. */
+export const GRADUATION_MAX_CONTRADICTED = 1;
+
+/** Minimum related instincts in same domain to propose a skill scaffold. */
+export const GRADUATION_SKILL_CLUSTER_SIZE = 3;
+
+/** Minimum related instincts in same domain to propose a command scaffold. */
+export const GRADUATION_COMMAND_CLUSTER_SIZE = 3;
+
+/** Maximum instinct age in days before TTL cull (aggressive decay / deletion). */
+export const GRADUATION_TTL_MAX_DAYS = 28;
+
+/** Confidence threshold below which TTL-expired instincts are deleted outright. */
+export const GRADUATION_TTL_CULL_CONFIDENCE = 0.3;
+
 export const DEFAULT_CONFIG: Config = {
   run_interval_minutes: 5,
   min_observations_to_analyze: 20,
@@ -49,6 +77,12 @@ export const DEFAULT_CONFIG: Config = {
   active_hours_start: 8,
   active_hours_end: 23,
   max_idle_seconds: 1800,
+  // Volume control defaults
+  max_total_instincts_per_project: 30,
+  max_total_instincts_global: 20,
+  max_new_instincts_per_run: 3,
+  flagged_cleanup_days: 7,
+  instinct_ttl_days: 28,
 };
 
 // ---------------------------------------------------------------------------
@@ -68,6 +102,12 @@ const PartialConfigSchema = Type.Partial(
     active_hours_end: Type.Number(),
     max_idle_seconds: Type.Number(),
     log_path: Type.String(),
+    // Volume control
+    max_total_instincts_per_project: Type.Number(),
+    max_total_instincts_global: Type.Number(),
+    max_new_instincts_per_run: Type.Number(),
+    flagged_cleanup_days: Type.Number(),
+    instinct_ttl_days: Type.Number(),
   })
 );