pi-continuous-learning 0.6.0 → 0.7.0

package/src/instinct-validator.ts

@@ -0,0 +1,287 @@
+/**
+ * Instinct validation and semantic deduplication.
+ * Rejects instincts with empty, undefined, nonsense, or low-quality fields,
+ * and detects near-duplicate instincts via Jaccard similarity.
+ */
+
+import type { Instinct } from "./types.js";
+
+const MIN_FIELD_LENGTH = 10;
+const INVALID_LITERALS = new Set(["undefined", "null", "none", ""]);
+
+// ---------------------------------------------------------------------------
+// Known domains (with "other" as escape hatch)
+// ---------------------------------------------------------------------------
+
+export const KNOWN_DOMAINS = new Set([
+  "git",
+  "testing",
+  "debugging",
+  "workflow",
+  "typescript",
+  "javascript",
+  "python",
+  "go",
+  "css",
+  "design",
+  "security",
+  "performance",
+  "documentation",
+  "react",
+  "node",
+  "database",
+  "api",
+  "devops",
+  "architecture",
+  "other",
+]);
+
+// ---------------------------------------------------------------------------
+// Verb heuristic for action field
+// ---------------------------------------------------------------------------
+
+/** Common imperative verbs expected at the start of an instinct action. */
+export const KNOWN_VERBS = new Set([
+  "add",
+  "always",
+  "analyze",
+  "apply",
+  "ask",
+  "avoid",
+  "build",
+  "call",
+  "catch",
+  "check",
+  "clean",
+  "confirm",
+  "consider",
+  "create",
+  "define",
+  "delete",
+  "document",
+  "emit",
+  "ensure",
+  "exclude",
+  "export",
+  "extract",
+  "fetch",
+  "find",
+  "fix",
+  "follow",
+  "format",
+  "generate",
+  "get",
+  "handle",
+  "import",
+  "include",
+  "inspect",
+  "load",
+  "log",
+  "look",
+  "merge",
+  "monitor",
+  "move",
+  "never",
+  "parse",
+  "pass",
+  "prefer",
+  "print",
+  "read",
+  "record",
+  "refactor",
+  "reject",
+  "rename",
+  "require",
+  "resolve",
+  "return",
+  "run",
+  "save",
+  "scan",
+  "search",
+  "send",
+  "set",
+  "show",
+  "skip",
+  "start",
+  "stop",
+  "test",
+  "track",
+  "update",
+  "use",
+  "validate",
+  "verify",
+  "watch",
+  "wrap",
+  "write",
+]);
+
+// ---------------------------------------------------------------------------
+// Validation types
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  valid: boolean;
+  reason?: string;
+  /** Non-fatal warnings that indicate lower-quality instincts. */
+  warnings?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isInvalidField(value: unknown, fieldName: string): string | null {
+  if (value === undefined || value === null) {
+    return `${fieldName} is ${String(value)}`;
+  }
+  if (typeof value !== "string") {
+    return `${fieldName} is not a string (got ${typeof value})`;
+  }
+  const trimmed = value.trim();
+  if (INVALID_LITERALS.has(trimmed.toLowerCase())) {
+    return `${fieldName} is the literal string "${trimmed}"`;
+  }
+  if (trimmed.length < MIN_FIELD_LENGTH) {
+    return `${fieldName} is too short (${trimmed.length} chars, minimum ${MIN_FIELD_LENGTH})`;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// validateInstinct
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates that an instinct's fields meet quality requirements.
+ *
+ * Rules:
+ * - action and trigger must be non-empty, non-null, non-"undefined", and >= 10 chars
+ * - action first word should be a known imperative verb (warning if not)
+ * - domain, if provided, must be in KNOWN_DOMAINS (with "other" as escape hatch)
+ *
+ * Returns { valid: true } or { valid: false, reason: "..." }.
+ * Non-fatal issues are reported in the optional `warnings` array.
+ */
+export function validateInstinct(fields: {
+  action: unknown;
+  trigger: unknown;
+  domain?: unknown;
+}): ValidationResult {
+  const actionError = isInvalidField(fields.action, "action");
+  if (actionError) {
+    return { valid: false, reason: actionError };
+  }
+
+  const triggerError = isInvalidField(fields.trigger, "trigger");
+  if (triggerError) {
+    return { valid: false, reason: triggerError };
+  }
+
+  const warnings: string[] = [];
+
+  // Domain validation
+  if (fields.domain !== undefined) {
+    if (typeof fields.domain !== "string" || !KNOWN_DOMAINS.has(fields.domain.toLowerCase().trim())) {
+      return {
+        valid: false,
+        reason: `domain "${String(fields.domain)}" is not in the known set. Use one of: ${[...KNOWN_DOMAINS].join(", ")}`,
+      };
+    }
+  }
+
+  // Verb heuristic (warning only - does not reject)
+  const action = (fields.action as string).trim();
+  const firstWord = action.split(/\s+/)[0]?.toLowerCase() ?? "";
+  if (firstWord && !KNOWN_VERBS.has(firstWord)) {
+    warnings.push(
+      `action should start with an imperative verb (got "${firstWord}"). Consider rewriting as a clear instruction.`
+    );
+  }
+
+  return warnings.length > 0 ? { valid: true, warnings } : { valid: true };
+}
+
+// ---------------------------------------------------------------------------
+// Jaccard similarity deduplication
+// ---------------------------------------------------------------------------
+
+const STOP_WORDS = new Set([
+  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "should",
+  "could", "may", "might", "shall", "can", "of", "in", "on", "at", "to",
+  "for", "with", "by", "from", "up", "about", "into", "it", "its", "this",
+  "that", "these", "those", "and", "or", "but", "if", "as", "when", "where",
+  "how", "what", "which", "who", "not", "no", "so",
+]);
+
+/**
+ * Tokenizes text into a set of meaningful lowercase words.
+ * Splits on non-alphanumeric characters and filters stop words and short tokens.
+ */
+export function tokenize(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length > 2 && !STOP_WORDS.has(t))
+  );
+}
+
+/**
+ * Computes Jaccard similarity between two token sets.
+ * Returns 1.0 for two empty sets, 0.0 if one is empty.
+ */
+export function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 1.0;
+  if (a.size === 0 || b.size === 0) return 0.0;
+
+  let intersection = 0;
+  for (const token of a) {
+    if (b.has(token)) intersection++;
+  }
+
+  const union = a.size + b.size - intersection;
+  return intersection / union;
+}
+
+export interface SimilarityMatch {
+  instinct: Instinct;
+  similarity: number;
+}
+
+/**
+ * Checks whether a candidate instinct is semantically similar to any existing instinct.
+ *
+ * Tokenizes trigger+action for both candidate and each existing instinct,
+ * computes Jaccard similarity, and returns the closest match above the threshold.
+ *
+ * @param candidate  - The new instinct being considered (trigger + action)
+ * @param existing   - All current instincts to check against
+ * @param skipId     - ID to skip (the candidate's own ID on updates)
+ * @param threshold  - Similarity threshold; default 0.6
+ */
+export function findSimilarInstinct(
+  candidate: { trigger: string; action: string },
+  existing: Instinct[],
+  skipId?: string,
+  threshold = 0.6
+): SimilarityMatch | null {
+  const candidateTokens = tokenize(`${candidate.trigger} ${candidate.action}`);
+
+  let bestMatch: SimilarityMatch | null = null;
+
+  for (const instinct of existing) {
+    if (instinct.id === skipId) continue;
+
+    const existingTokens = tokenize(`${instinct.trigger} ${instinct.action}`);
+    const similarity = jaccardSimilarity(candidateTokens, existingTokens);
+
+    if (similarity >= threshold) {
+      if (bestMatch === null || similarity > bestMatch.similarity) {
+        bestMatch = { instinct, similarity };
+      }
+    }
+  }
+
+  return bestMatch;
+}

package/src/prompts/analyzer-system-single-shot.ts

@@ -119,5 +119,45 @@ When in doubt, prefer project scope.
 4. New instincts from observation data alone are capped at 0.85 confidence.
 5. Check existing instincts (provided in the user message) for duplicates before creating. Update instead.
 6. Write actions as clear instructions starting with a verb.
-7. Be skeptical of outliers - patterns seen only in unusual circumstances should not become instincts.`;
+7. Be skeptical of outliers - patterns seen only in unusual circumstances should not become instincts.
+
+## Quality Tiers
+
+Not all patterns are worth recording as instincts. Use this classification before creating:
+
+### Tier 1 - Project Conventions (RECORD as instinct)
+Patterns specific to this project's tech stack, codebase conventions, or team practices.
+Examples:
+- "Use the Result<T, E> type for error handling in this project"
+- "Place tests next to source files as *.test.ts"
+- "Prefer functional style - avoid class-based patterns in this codebase"
+
+### Tier 2 - Workflow Patterns (RECORD as global instinct)
+Recurring multi-step workflows that apply across many projects.
+Examples:
+- "Run linter and type-checker after every code change"
+- "Write tests before implementation in TDD projects"
+
+### Tier 3 - Generic Agent Behavior (DO NOT RECORD - already known)
+Fundamental behaviors all coding agents should follow. These are not project-specific patterns.
+
+**DO NOT create instincts for:**
+- Reading files before editing them ("read before edit")
+- Grepping for context before modifying code
+- Clarifying ambiguous requirements before starting
+- Using conventional commit message formats
+- Checking for errors after tool calls
+- Any behavior that is basic good practice for any coding agent
+
+These patterns belong in AGENTS.md from the start, not in learned instincts.
+
+## AGENTS.md Deduplication
+
+The user message includes the current AGENTS.md content for this project and globally.
+Before creating any instinct, check: **is this pattern already covered by AGENTS.md?**
+
+If yes: do NOT create an instinct. The pattern is already enforced.
+If a pattern appears in AGENTS.md in the same form, skip it entirely.
+
+Only create instincts for patterns that are genuinely absent from AGENTS.md.`;
 }

package/src/prompts/analyzer-user-single-shot.ts

@@ -80,6 +80,12 @@ export function buildSingleShotUserPrompt(
     "3. Return a JSON change-set: create new instincts, update existing ones, or delete obsolete ones.",
     "4. Apply feedback analysis using the active_instincts field in each observation.",
     "5. Passive confidence decay has already been applied before this analysis.",
+    "6. Before creating any instinct, check the Existing Guidelines section above.",
+    "   If the pattern is already covered by AGENTS.md, do NOT create an instinct for it.",
+    "7. Apply the Quality Tier rules from the system prompt:",
+    "   - Generic agent behaviors (read-before-edit, clarify-before-implement) -> skip entirely",
+    "   - Project-specific patterns -> project-scoped instinct",
+    "   - Universal workflow patterns -> global-scoped instinct",
     "",
     "Return ONLY the JSON object. No prose, no markdown fences."
   );

package/src/skill-scaffold.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 { Instinct } from "./types.js";
+import type { DomainCluster } from "./graduation.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SkillScaffold {
+  name: string;
+  description: string;
+  domain: string;
+  content: string;
+  sourceInstinctIds: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toSkillName(domain: string): string {
+  return domain.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function formatInstinctAsSection(instinct: Instinct, index: number): string {
+  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: DomainCluster): SkillScaffold {
+  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: DomainCluster[]
+): SkillScaffold[] {
+  return clusters.map(generateSkillScaffold);
+}

package/src/types.ts

@@ -67,8 +67,12 @@ export interface Instinct {
   inactive_count: number;
   evidence?: string[];
   flagged_for_removal?: boolean;
+  graduated_to?: GraduationTarget;
+  graduated_at?: string; // ISO 8601
 }
 
+export type GraduationTarget = "agents-md" | "skill" | "command";
+
 // ---------------------------------------------------------------------------
 // ProjectEntry
 // ---------------------------------------------------------------------------
@@ -103,4 +107,10 @@ export interface Config {
   active_hours_end: number; // 0-23
   max_idle_seconds: number;
   log_path?: string; // Override analyzer log location (default: ~/.pi/continuous-learning/analyzer.log)
+  // Volume control
+  max_total_instincts_per_project: number; // hard cap per project (enforced by auto-deletion)
+  max_total_instincts_global: number; // hard cap for global instincts (enforced by auto-deletion)
+  max_new_instincts_per_run: number; // creation rate limit per analyzer run
+  flagged_cleanup_days: number; // auto-delete flagged instincts after N days
+  instinct_ttl_days: number; // auto-delete zero-confirmation instincts after N days
 }