pi-continuous-learning 0.5.1 → 0.7.0

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

package/src/instinct-cleanup.ts

@@ -0,0 +1,204 @@
+/**
+ * Auto-cleanup rules for instinct volume control.
+ *
+ * Cleanup is run at the start of each analysis pass, before decay.
+ * Rules (all thresholds are config-driven):
+ *  1. Delete flagged_for_removal instincts older than `flagged_cleanup_days`.
+ *  2. Delete zero-confirmation instincts older than `instinct_ttl_days`.
+ *  3. Enforce per-dir hard caps by deleting lowest-confidence instincts.
+ */
+
+import { unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Instinct, Config } from "./types.js";
+import { listInstincts, invalidateCache } from "./instinct-store.js";
+import {
+  getBaseDir,
+  getProjectInstinctsDir,
+  getGlobalInstinctsDir,
+} from "./storage.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function ageInDays(isoDate: string): number {
+  return (Date.now() - new Date(isoDate).getTime()) / (24 * 60 * 60 * 1000);
+}
+
+function deleteInstinctFile(instinct: Instinct, dir: string): boolean {
+  const filePath = join(dir, `${instinct.id}.md`);
+  if (!existsSync(filePath)) return false;
+  try {
+    unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cleanup rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Deletes instincts marked `flagged_for_removal` whose `updated_at` is older
+ * than `flaggedCleanupDays`. `updated_at` is set when the flag is applied,
+ * so it serves as a proxy for when the instinct was flagged.
+ *
+ * @returns Number of instincts deleted.
+ */
+export function cleanupFlaggedInstincts(
+  dir: string,
+  flaggedCleanupDays: number
+): number {
+  const instincts = listInstincts(dir);
+  let deleted = 0;
+  for (const instinct of instincts) {
+    if (
+      instinct.flagged_for_removal &&
+      ageInDays(instinct.updated_at) >= flaggedCleanupDays
+    ) {
+      if (deleteInstinctFile(instinct, dir)) {
+        deleted++;
+      }
+    }
+  }
+  if (deleted > 0) invalidateCache(dir);
+  return deleted;
+}
+
+/**
+ * Deletes instincts with `confirmed_count === 0` whose `created_at` is older
+ * than `ttlDays`. These instincts were never validated by the agent and have
+ * aged out of relevance.
+ *
+ * @returns Number of instincts deleted.
+ */
+export function cleanupZeroConfirmedInstincts(
+  dir: string,
+  ttlDays: number
+): number {
+  const instincts = listInstincts(dir);
+  let deleted = 0;
+  for (const instinct of instincts) {
+    if (
+      instinct.confirmed_count === 0 &&
+      ageInDays(instinct.created_at) >= ttlDays
+    ) {
+      if (deleteInstinctFile(instinct, dir)) {
+        deleted++;
+      }
+    }
+  }
+  if (deleted > 0) invalidateCache(dir);
+  return deleted;
+}
+
+/**
+ * Enforces a hard cap on the number of instincts in a directory.
+ * When the count exceeds `maxCount`, deletes the lowest-confidence instincts
+ * until the count is at or below the cap.
+ *
+ * @returns Number of instincts deleted.
+ */
+export function enforceInstinctCap(dir: string, maxCount: number): number {
+  const instincts = listInstincts(dir);
+  if (instincts.length <= maxCount) return 0;
+
+  // Sort ascending by confidence - lowest confidence deleted first
+  const sorted = [...instincts].sort((a, b) => a.confidence - b.confidence);
+  const toDelete = sorted.slice(0, instincts.length - maxCount);
+
+  let deleted = 0;
+  for (const instinct of toDelete) {
+    if (deleteInstinctFile(instinct, dir)) {
+      deleted++;
+    }
+  }
+  if (deleted > 0) invalidateCache(dir);
+  return deleted;
+}
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export interface CleanupResult {
+  flaggedDeleted: number;
+  zeroConfirmedDeleted: number;
+  capDeleted: number;
+  total: number;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Runs all cleanup rules against a single directory.
+ * Order: flagged → zero-confirmed → cap enforcement (cap runs last so it
+ * accounts for deletions made by the earlier rules).
+ */
+export function cleanupDir(
+  dir: string,
+  config: Config,
+  maxCount: number
+): CleanupResult {
+  const flaggedDeleted = cleanupFlaggedInstincts(dir, config.flagged_cleanup_days);
+  const zeroConfirmedDeleted = cleanupZeroConfirmedInstincts(
+    dir,
+    config.instinct_ttl_days
+  );
+  const capDeleted = enforceInstinctCap(dir, maxCount);
+  const total = flaggedDeleted + zeroConfirmedDeleted + capDeleted;
+  return { flaggedDeleted, zeroConfirmedDeleted, capDeleted, total };
+}
+
+/**
+ * Runs a full cleanup pass over project and global instinct directories.
+ * Called at the start of each analysis run, before decay.
+ *
+ * @param projectId - Project ID to clean up (skipped when null/undefined)
+ * @param config    - Runtime config (provides all thresholds)
+ * @param baseDir   - Base storage directory (defaults to ~/.pi/continuous-learning/)
+ * @returns Aggregated cleanup result across both scopes
+ */
+export function runCleanupPass(
+  projectId: string | null | undefined,
+  config: Config,
+  baseDir = getBaseDir()
+): CleanupResult {
+  const result: CleanupResult = {
+    flaggedDeleted: 0,
+    zeroConfirmedDeleted: 0,
+    capDeleted: 0,
+    total: 0,
+  };
+
+  if (projectId) {
+    const projectDir = getProjectInstinctsDir(projectId, "personal", baseDir);
+    const projectResult = cleanupDir(
+      projectDir,
+      config,
+      config.max_total_instincts_per_project
+    );
+    result.flaggedDeleted += projectResult.flaggedDeleted;
+    result.zeroConfirmedDeleted += projectResult.zeroConfirmedDeleted;
+    result.capDeleted += projectResult.capDeleted;
+    result.total += projectResult.total;
+  }
+
+  const globalDir = getGlobalInstinctsDir("personal", baseDir);
+  const globalResult = cleanupDir(
+    globalDir,
+    config,
+    config.max_total_instincts_global
+  );
+  result.flaggedDeleted += globalResult.flaggedDeleted;
+  result.zeroConfirmedDeleted += globalResult.zeroConfirmedDeleted;
+  result.capDeleted += globalResult.capDeleted;
+  result.total += globalResult.total;
+
+  return result;
+}