pi-continuous-learning 0.3.0

package/src/instinct-parser.ts

@@ -0,0 +1,171 @@
+/**
+ * Instinct file parsing and serialization.
+ * Instinct files use YAML frontmatter + a markdown body for the action text.
+ *
+ * Format:
+ * ---
+ * id: some-kebab-id
+ * title: Human readable title
+ * trigger: when condition is met
+ * confidence: 0.7
+ * ...other metadata...
+ * ---
+ *
+ * Action text describing what to do.
+ */
+
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { Instinct } from "./types.js";
+
+// Constants
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const MIN_CONFIDENCE = 0.1;
+const MAX_CONFIDENCE = 0.9;
+
+const REQUIRED_FIELDS = [
+  "id",
+  "title",
+  "trigger",
+  "confidence",
+  "domain",
+  "source",
+  "scope",
+  "created_at",
+  "updated_at",
+  "observation_count",
+  "confirmed_count",
+  "contradicted_count",
+  "inactive_count",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function clampConfidence(value: number): number {
+  return Math.min(MAX_CONFIDENCE, Math.max(MIN_CONFIDENCE, value));
+}
+
+function assertKebabCase(id: string): void {
+  if (!KEBAB_RE.test(id)) {
+    throw new Error(
+      `Invalid instinct ID "${id}": must be kebab-case (lowercase letters, numbers, hyphens only).`
+    );
+  }
+}
+
+function splitFrontmatter(content: string): {
+  frontmatterStr: string;
+  body: string;
+} {
+  // Expect content starting with ---\n<yaml>\n---
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error(
+      "Invalid instinct file: content must begin with YAML frontmatter delimiters (---)."
+    );
+  }
+  return { frontmatterStr: match[1] ?? "", body: (match[2] ?? "").trim() };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an instinct markdown file (YAML frontmatter + body) into an Instinct.
+ * Throws if required fields are missing or the ID is not kebab-case.
+ * Clamps confidence to 0.1–0.9 rather than throwing.
+ */
+export function parseInstinct(content: string): Instinct {
+  const { frontmatterStr, body } = splitFrontmatter(content);
+
+  const fm = parseYaml(frontmatterStr) as Record<string, unknown>;
+
+  if (!fm || typeof fm !== "object") {
+    throw new Error("Invalid instinct file: frontmatter is not a valid YAML object.");
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (fm[field] === null || fm[field] === undefined) {
+      throw new Error(`Invalid instinct file: missing required field "${field}".`);
+    }
+  }
+
+  const id = String(fm["id"]);
+  assertKebabCase(id);
+
+  const confidence = clampConfidence(Number(fm["confidence"]));
+
+  const instinct: Instinct = {
+    id,
+    title: String(fm["title"]),
+    trigger: String(fm["trigger"]),
+    action: body,
+    confidence,
+    domain: String(fm["domain"]),
+    source: fm["source"] as Instinct["source"],
+    scope: fm["scope"] as Instinct["scope"],
+    created_at: String(fm["created_at"]),
+    updated_at: String(fm["updated_at"]),
+    observation_count: Number(fm["observation_count"]),
+    confirmed_count: Number(fm["confirmed_count"]),
+    contradicted_count: Number(fm["contradicted_count"]),
+    inactive_count: Number(fm["inactive_count"]),
+  };
+
+  if (fm["project_id"] !== undefined && fm["project_id"] !== null) {
+    instinct.project_id = String(fm["project_id"]);
+  }
+  if (fm["project_name"] !== undefined && fm["project_name"] !== null) {
+    instinct.project_name = String(fm["project_name"]);
+  }
+  if (Array.isArray(fm["evidence"])) {
+    instinct.evidence = (fm["evidence"] as unknown[]).map(String);
+  }
+  if (fm["flagged_for_removal"] !== undefined && fm["flagged_for_removal"] !== null) {
+    instinct.flagged_for_removal = Boolean(fm["flagged_for_removal"]);
+  }
+
+  return instinct;
+}
+
+/**
+ * Serialize an Instinct into a YAML-frontmatter markdown string.
+ * Confidence is clamped to 0.1–0.9 before writing.
+ */
+export function serializeInstinct(instinct: Instinct): string {
+  const confidence = clampConfidence(instinct.confidence);
+
+  const frontmatter: Record<string, unknown> = {
+    id: instinct.id,
+    title: instinct.title,
+    trigger: instinct.trigger,
+    confidence,
+    domain: instinct.domain,
+    source: instinct.source,
+    scope: instinct.scope,
+    created_at: instinct.created_at,
+    updated_at: instinct.updated_at,
+    observation_count: instinct.observation_count,
+    confirmed_count: instinct.confirmed_count,
+    contradicted_count: instinct.contradicted_count,
+    inactive_count: instinct.inactive_count,
+  };
+
+  if (instinct.project_id !== undefined) {
+    frontmatter["project_id"] = instinct.project_id;
+  }
+  if (instinct.project_name !== undefined) {
+    frontmatter["project_name"] = instinct.project_name;
+  }
+  if (instinct.evidence !== undefined) {
+    frontmatter["evidence"] = instinct.evidence;
+  }
+  if (instinct.flagged_for_removal !== undefined) {
+    frontmatter["flagged_for_removal"] = instinct.flagged_for_removal;
+  }
+
+  const yamlStr = stringifyYaml(frontmatter);
+  return `---\n${yamlStr}---\n\n${instinct.action}\n`;
+}

package/src/instinct-projects.ts

@@ -0,0 +1,119 @@
+/**
+ * /instinct-projects command for pi-continuous-learning.
+ * Displays all known projects with their instinct counts and last seen dates.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ProjectEntry } from "./types.js";
+import { getProjectsRegistryPath, getProjectInstinctsDir, getBaseDir } from "./storage.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const COMMAND_NAME = "instinct-projects";
+const NO_PROJECTS_MSG = "No projects found.";
+
+// ---------------------------------------------------------------------------
+// Data loading helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reads the projects.json registry. Returns an empty record on missing/invalid file.
+ */
+export function readProjectsRegistry(baseDir?: string): Record<string, ProjectEntry> {
+  const registryPath = getProjectsRegistryPath(baseDir ?? getBaseDir());
+  if (!existsSync(registryPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(registryPath, "utf-8")) as Record<string, ProjectEntry>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Counts .md files in a project's personal instincts directory.
+ * Returns 0 if the directory does not exist.
+ */
+export function countProjectInstincts(projectId: string, baseDir?: string): number {
+  const dir = getProjectInstinctsDir(projectId, "personal", baseDir ?? getBaseDir());
+  if (!existsSync(dir)) {
+    return 0;
+  }
+  try {
+    const entries = readdirSync(dir);
+    return entries.filter((f) => f.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Formats an ISO 8601 date string as a human-readable local date.
+ * Falls back to the raw string on parse failure.
+ */
+export function formatDate(isoDate: string): string {
+  try {
+    return new Date(isoDate).toLocaleDateString();
+  } catch {
+    return isoDate;
+  }
+}
+
+/**
+ * Formats the full projects output string from a registry.
+ * Returns a fallback message when no projects exist.
+ */
+export function formatProjectsOutput(
+  registry: Record<string, ProjectEntry>,
+  baseDir?: string
+): string {
+  const entries = Object.values(registry);
+  if (entries.length === 0) {
+    return NO_PROJECTS_MSG;
+  }
+
+  const sorted = [...entries].sort((a, b) =>
+    b.last_seen.localeCompare(a.last_seen)
+  );
+
+  const lines: string[] = ["=== Known Projects ===", ""];
+
+  for (const project of sorted) {
+    const count = countProjectInstincts(project.id, baseDir);
+    const lastSeen = formatDate(project.last_seen);
+    lines.push(`${project.name} (${project.id})`);
+    lines.push(`  Instincts: ${count}  |  Last seen: ${lastSeen}`);
+    lines.push("");
+  }
+
+  const total = entries.length;
+  lines.push(`Total: ${total} project${total !== 1 ? "s" : ""}`);
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Command handler for /instinct-projects.
+ * Reads the project registry, counts instincts per project, and displays results.
+ */
+export async function handleInstinctProjects(
+  _args: string,
+  ctx: ExtensionCommandContext,
+  baseDir?: string
+): Promise<void> {
+  const registry = readProjectsRegistry(baseDir);
+  const output = formatProjectsOutput(registry, baseDir);
+  ctx.ui.notify(output, "info");
+}

package/src/instinct-promote.ts

@@ -0,0 +1,231 @@
+/**
+ * /instinct-promote command for pi-continuous-learning.
+ * Promotes project-scoped instincts to global scope.
+ *
+ * With an ID argument: promotes that specific project instinct to global.
+ * Without an ID: auto-promotes all qualifying instincts
+ *   (confidence >= 0.8, present in 2+ projects).
+ */
+
+import { mkdirSync } from "node:fs";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { Instinct } from "./types.js";
+import {
+  loadProjectInstincts,
+  loadGlobalInstincts,
+  saveInstinct,
+  listInstincts,
+} from "./instinct-store.js";
+import {
+  getGlobalInstinctsDir,
+  getProjectInstinctsDir,
+  getProjectsRegistryPath,
+  getBaseDir,
+} from "./storage.js";
+import { readFileSync, existsSync } from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const COMMAND_NAME = "instinct-promote";
+
+/** Minimum confidence to qualify for auto-promotion. */
+export const AUTO_PROMOTE_MIN_CONFIDENCE = 0.8;
+
+/** Minimum number of distinct projects an instinct must appear in for auto-promotion. */
+export const AUTO_PROMOTE_MIN_PROJECTS = 2;
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a promoted copy of the instinct with scope set to global and
+ * project-specific fields removed.
+ * Does NOT mutate the original.
+ */
+export function toGlobalInstinct(instinct: Instinct): Instinct {
+  const promoted: Instinct = {
+    ...instinct,
+    scope: "global",
+    updated_at: new Date().toISOString(),
+  };
+  // Remove project-specific fields
+  delete (promoted as Partial<Instinct>).project_id;
+  delete (promoted as Partial<Instinct>).project_name;
+  return promoted;
+}
+
+// ---------------------------------------------------------------------------
+// Project registry reading
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns all known project IDs from the projects.json registry.
+ */
+export function getKnownProjectIds(baseDir: string): string[] {
+  const registryPath = getProjectsRegistryPath(baseDir);
+  if (!existsSync(registryPath)) return [];
+  try {
+    const raw = readFileSync(registryPath, "utf-8");
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return Object.keys(parsed);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Manual promotion
+// ---------------------------------------------------------------------------
+
+/**
+ * Promotes a single project instinct to global personal/ by ID.
+ * Returns the promoted instinct, or null if not found.
+ */
+export function promoteById(
+  id: string,
+  projectId: string,
+  baseDir: string
+): Instinct | null {
+  const projectInstincts = loadProjectInstincts(projectId, baseDir);
+  const found = projectInstincts.find((i) => i.id === id);
+  if (!found) return null;
+
+  const globalDir = getGlobalInstinctsDir("personal", baseDir);
+  mkdirSync(globalDir, { recursive: true });
+
+  const promoted = toGlobalInstinct(found);
+  saveInstinct(promoted, globalDir);
+  return promoted;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-promotion
+// ---------------------------------------------------------------------------
+
+/**
+ * Finds instinct IDs that appear in at least minProjects distinct projects.
+ * Returns a map of id -> array of matching instincts across projects.
+ */
+export function findCrossProjectInstincts(
+  projectIds: string[],
+  baseDir: string
+): Map<string, Instinct[]> {
+  const byId = new Map<string, Instinct[]>();
+
+  for (const projectId of projectIds) {
+    const personalDir = getProjectInstinctsDir(projectId, "personal", baseDir);
+    const instincts = listInstincts(personalDir);
+    for (const instinct of instincts) {
+      const existing = byId.get(instinct.id) ?? [];
+      byId.set(instinct.id, [...existing, instinct]);
+    }
+  }
+
+  return byId;
+}
+
+/**
+ * Auto-promotes all qualifying instincts:
+ *   - confidence >= AUTO_PROMOTE_MIN_CONFIDENCE
+ *   - present in >= AUTO_PROMOTE_MIN_PROJECTS distinct projects
+ * Already-global instincts (same ID in global personal/) are skipped.
+ *
+ * Returns the list of promoted instincts.
+ */
+export function autoPromoteInstincts(baseDir: string): Instinct[] {
+  const projectIds = getKnownProjectIds(baseDir);
+  if (projectIds.length < AUTO_PROMOTE_MIN_PROJECTS) return [];
+
+  const crossProject = findCrossProjectInstincts(projectIds, baseDir);
+
+  const existingGlobal = loadGlobalInstincts(baseDir);
+  const existingGlobalIds = new Set(existingGlobal.map((i) => i.id));
+
+  const globalDir = getGlobalInstinctsDir("personal", baseDir);
+  mkdirSync(globalDir, { recursive: true });
+
+  const promoted: Instinct[] = [];
+
+  for (const [id, instances] of crossProject) {
+    if (instances.length < AUTO_PROMOTE_MIN_PROJECTS) continue;
+
+    // Use the highest-confidence instance as the canonical one
+    const sorted = [...instances].sort((a, b) => b.confidence - a.confidence);
+    const best = sorted[0];
+    if (!best) continue;
+
+    if (best.confidence < AUTO_PROMOTE_MIN_CONFIDENCE) continue;
+    if (existingGlobalIds.has(id)) continue;
+
+    const globalInstinct = toGlobalInstinct(best);
+    saveInstinct(globalInstinct, globalDir);
+    promoted.push(globalInstinct);
+  }
+
+  return promoted;
+}
+
+// ---------------------------------------------------------------------------
+// handleInstinctPromote
+// ---------------------------------------------------------------------------
+
+/**
+ * Command handler for /instinct-promote.
+ * With an ID arg: promotes that specific instinct.
+ * Without an ID: auto-promotes qualifying instincts.
+ */
+export async function handleInstinctPromote(
+  args: string,
+  ctx: ExtensionCommandContext,
+  projectId?: string | null,
+  baseDir?: string
+): Promise<void> {
+  const effectiveBase = baseDir ?? getBaseDir();
+  const id = args.trim();
+
+  if (id.length > 0) {
+    // Manual promotion by ID
+    if (projectId == null) {
+      ctx.ui.notify(
+        "Cannot promote by ID: no active project detected.",
+        "error"
+      );
+      return;
+    }
+
+    const promoted = promoteById(id, projectId, effectiveBase);
+    if (!promoted) {
+      ctx.ui.notify(
+        `Instinct "${id}" not found in project instincts.`,
+        "error"
+      );
+      return;
+    }
+
+    ctx.ui.notify(
+      `Promoted instinct "${promoted.id}" ("${promoted.title}") to global scope.`,
+      "info"
+    );
+    return;
+  }
+
+  // Auto-promotion
+  const promoted = autoPromoteInstincts(effectiveBase);
+
+  if (promoted.length === 0) {
+    ctx.ui.notify(
+      `No instincts qualify for auto-promotion (confidence >= ${AUTO_PROMOTE_MIN_CONFIDENCE}, present in ${AUTO_PROMOTE_MIN_PROJECTS}+ projects).`,
+      "info"
+    );
+    return;
+  }
+
+  const lines = [
+    `Auto-promoted ${promoted.length} instinct${promoted.length !== 1 ? "s" : ""} to global scope:`,
+    ...promoted.map((i) => `  - ${i.id} (${i.confidence.toFixed(2)}): ${i.title}`),
+  ];
+  ctx.ui.notify(lines.join("\n"), "info");
+}

package/src/instinct-status.ts

@@ -0,0 +1,135 @@
+/**
+ * /instinct-status command for pi-continuous-learning.
+ * Displays all instincts grouped by domain with confidence scores,
+ * trend arrows, and feedback ratios.
+ */
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { Instinct } from "./types.js";
+import { loadProjectInstincts, loadGlobalInstincts } from "./instinct-store.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TREND_UP = "↑";
+const TREND_DOWN = "↓";
+const TREND_STABLE = "→";
+const FLAG_REMOVAL = "⚠ FLAGGED FOR REMOVAL";
+const COMMAND_NAME = "instinct-status";
+const NO_INSTINCTS_MSG = "No instincts found.";
+
+// ---------------------------------------------------------------------------
+// Trend and formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a trend arrow based on confirmed vs contradicted counts.
+ * ↑ when confirmed > contradicted, ↓ when contradicted > confirmed, → when equal.
+ */
+export function getTrendArrow(instinct: Instinct): string {
+  if (instinct.confirmed_count > instinct.contradicted_count) return TREND_UP;
+  if (instinct.contradicted_count > instinct.confirmed_count) return TREND_DOWN;
+  return TREND_STABLE;
+}
+
+/**
+ * Formats a single instinct line for display.
+ * Format: [confidence] title trend feedback_ratio [⚠ FLAGGED FOR REMOVAL]
+ */
+export function formatInstinct(instinct: Instinct): string {
+  const confidence = `[${instinct.confidence.toFixed(2)}]`;
+  const trend = getTrendArrow(instinct);
+  const feedbackRatio =
+    `✓${instinct.confirmed_count} ✗${instinct.contradicted_count} ○${instinct.inactive_count}`;
+
+  const parts = [`  ${confidence} ${instinct.title} ${trend} (${feedbackRatio})`];
+  if (instinct.flagged_for_removal) {
+    parts.push(`    ${FLAG_REMOVAL}`);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Groups instincts by domain. Returns a sorted record (sorted by domain name).
+ */
+export function groupByDomain(instincts: Instinct[]): Record<string, Instinct[]> {
+  const groups: Record<string, Instinct[]> = {};
+  for (const instinct of instincts) {
+    const domain = instinct.domain || "uncategorized";
+    if (!groups[domain]) {
+      groups[domain] = [];
+    }
+    groups[domain].push(instinct);
+  }
+  return groups;
+}
+
+/**
+ * Formats the full status output string from a list of instincts.
+ * Returns a header message when no instincts exist.
+ */
+export function formatStatusOutput(instincts: Instinct[]): string {
+  if (instincts.length === 0) return NO_INSTINCTS_MSG;
+
+  const groups = groupByDomain(instincts);
+  const sortedDomains = Object.keys(groups).sort();
+
+  const lines: string[] = ["=== Instinct Status ===", ""];
+
+  for (const domain of sortedDomains) {
+    const domainInstincts = groups[domain];
+    if (!domainInstincts || domainInstincts.length === 0) continue;
+
+    lines.push(`## ${domain}`);
+    for (const instinct of domainInstincts) {
+      lines.push(formatInstinct(instinct));
+    }
+    lines.push("");
+  }
+
+  const total = instincts.length;
+  const flagged = instincts.filter((i) => i.flagged_for_removal).length;
+  lines.push(`Total: ${total} instinct${total !== 1 ? "s" : ""} (${flagged} flagged for removal)`);
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// loadAllInstincts
+// ---------------------------------------------------------------------------
+
+/**
+ * Loads all instincts from disk (project + global), including flagged ones.
+ * Does NOT apply confidence filtering - status command shows everything.
+ */
+export function loadAllInstincts(
+  projectId?: string | null,
+  baseDir?: string
+): Instinct[] {
+  const projectInstincts =
+    projectId != null ? loadProjectInstincts(projectId, baseDir) : [];
+  const globalInstincts = loadGlobalInstincts(baseDir);
+  return [...projectInstincts, ...globalInstincts];
+}
+
+// ---------------------------------------------------------------------------
+// handleInstinctStatus
+// ---------------------------------------------------------------------------
+
+/**
+ * Command handler for /instinct-status.
+ * Loads all instincts, formats them grouped by domain, and notifies the user.
+ */
+export async function handleInstinctStatus(
+  _args: string,
+  ctx: ExtensionCommandContext,
+  projectId?: string | null,
+  baseDir?: string
+): Promise<void> {
+  const instincts = loadAllInstincts(projectId, baseDir);
+  const output = formatStatusOutput(instincts);
+  ctx.ui.notify(output, "info");
+}
+
+export { COMMAND_NAME };