pi-continuous-learning 0.6.0 → 0.7.0

package/src/cli/analyze.ts

@@ -22,6 +22,7 @@ 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";
@@ -186,6 +187,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
@@ -243,6 +245,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;
@@ -253,20 +259,25 @@ async function analyzeProject(
           unlinkSync(filePath);
           instinctCounts.deleted++;
         }
-      } 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--;
+      } 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++;
       }
     }
   } finally {

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

@@ -26,7 +26,8 @@ const DELTA_CONTRADICTED = -0.15;
 const DELTA_INACTIVE = 0;
 
 // 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;
 
 // ---------------------------------------------------------------------------

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(),
   })
 );
 

package/src/graduation.ts

@@ -0,0 +1,243 @@
+/**
+ * Graduation pipeline - pure functions for instinct lifecycle management.
+ *
+ * Determines which instincts are mature enough to graduate into permanent
+ * knowledge (AGENTS.md, skills, or commands), and which have exceeded
+ * their TTL and should be culled.
+ */
+
+import type { Instinct, GraduationTarget } from "./types.js";
+import {
+  GRADUATION_MIN_AGE_DAYS,
+  GRADUATION_MIN_CONFIDENCE,
+  GRADUATION_MIN_CONFIRMED,
+  GRADUATION_MAX_CONTRADICTED,
+  GRADUATION_SKILL_CLUSTER_SIZE,
+  GRADUATION_COMMAND_CLUSTER_SIZE,
+  GRADUATION_TTL_MAX_DAYS,
+  GRADUATION_TTL_CULL_CONFIDENCE,
+} from "./config.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface MaturityCheck {
+  eligible: boolean;
+  reasons: string[];
+}
+
+export interface GraduationCandidate {
+  instinct: Instinct;
+  target: GraduationTarget;
+  reason: string;
+}
+
+export interface DomainCluster {
+  domain: string;
+  instincts: Instinct[];
+}
+
+export interface TtlResult {
+  toCull: Instinct[];
+  toDecay: Instinct[];
+}
+
+// ---------------------------------------------------------------------------
+// Age helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the age of an instinct in days based on created_at.
+ * Uses a reference date for testability.
+ */
+export function getAgeDays(instinct: Instinct, now = Date.now()): number {
+  const createdAt = new Date(instinct.created_at).getTime();
+  return Math.max(0, (now - createdAt) / MS_PER_DAY);
+}
+
+// ---------------------------------------------------------------------------
+// Maturity check
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks whether an instinct meets all graduation maturity criteria.
+ * Returns structured result with reasons for any failures.
+ */
+export function checkMaturity(
+  instinct: Instinct,
+  agentsMdContent: string | null,
+  now = Date.now()
+): MaturityCheck {
+  const reasons: string[] = [];
+
+  if (instinct.graduated_to !== undefined) {
+    return { eligible: false, reasons: [`Already graduated to ${instinct.graduated_to}`] };
+  }
+
+  if (instinct.flagged_for_removal) {
+    return { eligible: false, reasons: ["Flagged for removal"] };
+  }
+
+  const ageDays = getAgeDays(instinct, now);
+  if (ageDays < GRADUATION_MIN_AGE_DAYS) {
+    reasons.push(
+      `Age ${ageDays.toFixed(1)}d < ${GRADUATION_MIN_AGE_DAYS}d minimum`
+    );
+  }
+
+  if (instinct.confidence < GRADUATION_MIN_CONFIDENCE) {
+    reasons.push(
+      `Confidence ${instinct.confidence.toFixed(2)} < ${GRADUATION_MIN_CONFIDENCE} minimum`
+    );
+  }
+
+  if (instinct.confirmed_count < GRADUATION_MIN_CONFIRMED) {
+    reasons.push(
+      `Confirmed ${instinct.confirmed_count} < ${GRADUATION_MIN_CONFIRMED} minimum`
+    );
+  }
+
+  if (instinct.contradicted_count > GRADUATION_MAX_CONTRADICTED) {
+    reasons.push(
+      `Contradicted ${instinct.contradicted_count} > ${GRADUATION_MAX_CONTRADICTED} maximum`
+    );
+  }
+
+  // Check for duplicates in AGENTS.md (simple substring match on title/trigger)
+  if (agentsMdContent !== null) {
+    const lowerContent = agentsMdContent.toLowerCase();
+    const titleMatch = lowerContent.includes(instinct.title.toLowerCase());
+    const triggerMatch = lowerContent.includes(instinct.trigger.toLowerCase());
+    if (titleMatch && triggerMatch) {
+      reasons.push("Appears to duplicate existing AGENTS.md content");
+    }
+  }
+
+  return { eligible: reasons.length === 0, reasons };
+}
+
+// ---------------------------------------------------------------------------
+// Candidate scanning
+// ---------------------------------------------------------------------------
+
+/**
+ * Finds all instincts that qualify for graduation to AGENTS.md.
+ */
+export function findAgentsMdCandidates(
+  instincts: Instinct[],
+  agentsMdContent: string | null,
+  now = Date.now()
+): GraduationCandidate[] {
+  const candidates: GraduationCandidate[] = [];
+
+  for (const instinct of instincts) {
+    const check = checkMaturity(instinct, agentsMdContent, now);
+    if (check.eligible) {
+      candidates.push({
+        instinct,
+        target: "agents-md",
+        reason: `Mature instinct (${instinct.confidence.toFixed(2)} confidence, ${instinct.confirmed_count} confirmations)`,
+      });
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * Groups instincts by domain, returning only clusters meeting the size threshold.
+ */
+export function findDomainClusters(
+  instincts: Instinct[],
+  minSize: number
+): DomainCluster[] {
+  const byDomain = new Map<string, Instinct[]>();
+
+  for (const instinct of instincts) {
+    if (instinct.graduated_to !== undefined) continue;
+    if (instinct.flagged_for_removal) continue;
+
+    const existing = byDomain.get(instinct.domain) ?? [];
+    byDomain.set(instinct.domain, [...existing, instinct]);
+  }
+
+  const clusters: DomainCluster[] = [];
+  for (const [domain, domainInstincts] of byDomain) {
+    if (domainInstincts.length >= minSize) {
+      clusters.push({ domain, instincts: domainInstincts });
+    }
+  }
+
+  return clusters.sort((a, b) => b.instincts.length - a.instincts.length);
+}
+
+/**
+ * Finds instinct clusters that qualify for skill scaffolding.
+ */
+export function findSkillCandidates(instincts: Instinct[]): DomainCluster[] {
+  return findDomainClusters(instincts, GRADUATION_SKILL_CLUSTER_SIZE);
+}
+
+/**
+ * Finds instinct clusters that qualify for command scaffolding.
+ */
+export function findCommandCandidates(instincts: Instinct[]): DomainCluster[] {
+  return findDomainClusters(instincts, GRADUATION_COMMAND_CLUSTER_SIZE);
+}
+
+// ---------------------------------------------------------------------------
+// TTL enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * Identifies instincts that have exceeded the TTL without graduating.
+ * - Instincts with confidence < cull threshold are marked for outright deletion
+ * - Others are marked for aggressive decay
+ */
+export function enforceTtl(
+  instincts: Instinct[],
+  now = Date.now()
+): TtlResult {
+  const toCull: Instinct[] = [];
+  const toDecay: Instinct[] = [];
+
+  for (const instinct of instincts) {
+    // Skip already-graduated instincts
+    if (instinct.graduated_to !== undefined) continue;
+
+    const ageDays = getAgeDays(instinct, now);
+    if (ageDays < GRADUATION_TTL_MAX_DAYS) continue;
+
+    if (instinct.confidence < GRADUATION_TTL_CULL_CONFIDENCE) {
+      toCull.push(instinct);
+    } else {
+      toDecay.push(instinct);
+    }
+  }
+
+  return { toCull, toDecay };
+}
+
+/**
+ * Marks an instinct as graduated. Returns a new instinct with graduated_to
+ * and graduated_at set. Does not mutate the original.
+ */
+export function markGraduated(
+  instinct: Instinct,
+  target: GraduationTarget,
+  now = new Date()
+): Instinct {
+  return {
+    ...instinct,
+    graduated_to: target,
+    graduated_at: now.toISOString(),
+    updated_at: now.toISOString(),
+  };
+}

package/src/index.ts

@@ -32,6 +32,7 @@ import { handleInstinctImport, COMMAND_NAME as IMPORT_CMD } from "./instinct-imp
 import { handleInstinctPromote, COMMAND_NAME as PROMOTE_CMD } from "./instinct-promote.js";
 import { handleInstinctEvolve, COMMAND_NAME as EVOLVE_CMD } from "./instinct-evolve.js";
 import { handleInstinctProjects, COMMAND_NAME as PROJECTS_CMD } from "./instinct-projects.js";
+import { handleInstinctGraduate, COMMAND_NAME as GRADUATE_CMD } from "./instinct-graduate.js";
 import { registerAllTools } from "./instinct-tools.js";
 import { logError } from "./error-logger.js";
 import type { Config, InstalledSkill, ProjectEntry } from "./types.js";
@@ -193,4 +194,17 @@ export default function (pi: ExtensionAPI): void {
     handler: (args: string, ctx: ExtensionCommandContext) =>
       handleInstinctProjects(args, ctx),
   });
+
+  pi.registerCommand(GRADUATE_CMD, {
+    description: "Graduate mature instincts to AGENTS.md, skills, or commands",
+    handler: (args: string, ctx: ExtensionCommandContext) =>
+      handleInstinctGraduate(
+        args,
+        ctx,
+        pi,
+        project?.id,
+        undefined,
+        project?.root ?? null
+      ),
+  });
 }