pi-continuous-learning 0.3.0

package/dist/instinct-import.js

@@ -0,0 +1,168 @@
+/**
+ * /instinct-import command for pi-continuous-learning.
+ * Imports instincts from a JSON file into the inherited instincts directory.
+ * Destination is determined by each instinct's scope field:
+ *   - scope "project" -> projects/<id>/instincts/inherited/
+ *   - scope "global"  -> instincts/inherited/
+ */
+import { readFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { saveInstinct, listInstincts } from "./instinct-store.js";
+import { getProjectInstinctsDir, getGlobalInstinctsDir, getBaseDir, } from "./storage.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const COMMAND_NAME = "instinct-import";
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const REQUIRED_FIELDS = [
+    "id",
+    "title",
+    "trigger",
+    "action",
+    "confidence",
+    "domain",
+    "source",
+    "scope",
+    "created_at",
+    "updated_at",
+    "observation_count",
+    "confirmed_count",
+    "contradicted_count",
+    "inactive_count",
+];
+/**
+ * Validates a raw JSON object as an Instinct.
+ * Returns an error string if invalid, null if valid.
+ */
+export function validateImportObject(obj, index) {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+        return { index, reason: "not an object" };
+    }
+    const record = obj;
+    for (const field of REQUIRED_FIELDS) {
+        if (record[field] === undefined || record[field] === null) {
+            return { index, reason: `missing required field "${field}"` };
+        }
+    }
+    const id = String(record["id"]);
+    if (!KEBAB_RE.test(id)) {
+        return { index, reason: `invalid id "${id}" - must be kebab-case` };
+    }
+    return null;
+}
+/**
+ * Reads and parses the import JSON file.
+ * Returns valid instincts and validation errors separately.
+ */
+export function loadImportFile(filePath) {
+    const content = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) {
+        throw new Error("Import file must contain a JSON array of instinct objects.");
+    }
+    const valid = [];
+    const invalid = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const err = validateImportObject(parsed[i], i);
+        if (err) {
+            invalid.push(err);
+        }
+        else {
+            valid.push(parsed[i]);
+        }
+    }
+    return { valid, invalid };
+}
+/**
+ * Partitions instincts into those to import and those skipped as duplicates.
+ * Checks existing inherited instincts in both project and global directories.
+ */
+export function partitionByDuplicates(instincts, projectId, baseDir) {
+    const existingIds = new Set();
+    const globalDir = getGlobalInstinctsDir("inherited", baseDir);
+    for (const inst of listInstincts(globalDir)) {
+        existingIds.add(inst.id);
+    }
+    if (projectId != null) {
+        const projectDir = getProjectInstinctsDir(projectId, "inherited", baseDir);
+        for (const inst of listInstincts(projectDir)) {
+            existingIds.add(inst.id);
+        }
+    }
+    const toImport = [];
+    const duplicates = [];
+    for (const inst of instincts) {
+        if (existingIds.has(inst.id)) {
+            duplicates.push(inst.id);
+        }
+        else {
+            toImport.push(inst);
+        }
+    }
+    return { toImport, duplicates };
+}
+// ---------------------------------------------------------------------------
+// Target directory resolution
+// ---------------------------------------------------------------------------
+/**
+ * Returns the inherited instincts directory for the given instinct.
+ * Project-scoped instincts go into the project's inherited dir.
+ * Global instincts go into the global inherited dir.
+ */
+export function getTargetDir(instinct, projectId, baseDir) {
+    if (instinct.scope === "project" && projectId != null) {
+        return getProjectInstinctsDir(projectId, "inherited", baseDir);
+    }
+    return getGlobalInstinctsDir("inherited", baseDir);
+}
+// ---------------------------------------------------------------------------
+// handleInstinctImport
+// ---------------------------------------------------------------------------
+/**
+ * Command handler for /instinct-import.
+ * Reads the JSON file at the given path, validates each instinct,
+ * skips duplicates, and saves valid instincts to inherited/ directories.
+ */
+export async function handleInstinctImport(args, ctx, projectId, baseDir) {
+    const effectiveBase = baseDir ?? getBaseDir();
+    const filePath = resolve(ctx.cwd, args.trim());
+    if (!existsSync(filePath)) {
+        ctx.ui.notify(`Import failed: file not found: ${filePath}`, "error");
+        return;
+    }
+    let loadResult;
+    try {
+        loadResult = loadImportFile(filePath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Import failed: ${msg}`, "error");
+        return;
+    }
+    const { valid, invalid } = loadResult;
+    const { toImport, duplicates } = partitionByDuplicates(valid, projectId, effectiveBase);
+    // Ensure target dirs exist before writing
+    const globalInheritedDir = getGlobalInstinctsDir("inherited", effectiveBase);
+    mkdirSync(globalInheritedDir, { recursive: true });
+    if (projectId != null) {
+        const projectInheritedDir = getProjectInstinctsDir(projectId, "inherited", effectiveBase);
+        mkdirSync(projectInheritedDir, { recursive: true });
+    }
+    // Save each instinct to the correct inherited directory
+    for (const instinct of toImport) {
+        const targetDir = getTargetDir(instinct, projectId, effectiveBase);
+        saveInstinct(instinct, targetDir);
+    }
+    // Build summary message
+    const lines = [
+        `Imported ${toImport.length} instinct${toImport.length !== 1 ? "s" : ""} from ${filePath}`,
+    ];
+    if (duplicates.length > 0) {
+        lines.push(`Skipped ${duplicates.length} duplicate${duplicates.length !== 1 ? "s" : ""}: ${duplicates.join(", ")}`);
+    }
+    if (invalid.length > 0) {
+        lines.push(`Skipped ${invalid.length} invalid entr${invalid.length !== 1 ? "ies" : "y"}: ${invalid.map((e) => `[${e.index}] ${e.reason}`).join("; ")}`);
+    }
+    ctx.ui.notify(lines.join("\n"), "info");
+}
+//# sourceMappingURL=instinct-import.js.map

package/dist/instinct-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-import.js","sourceRoot":"","sources":["../src/instinct-import.ts"],"names":[],"mappings":"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"}

package/dist/instinct-injector.d.ts

@@ -0,0 +1,39 @@
+/**
+ * System prompt injection for pi-continuous-learning.
+ * Loads filtered instincts and appends them to the system prompt on each
+ * before_agent_start event so the agent benefits from learned behaviors.
+ * Also bridges injected instinct IDs to shared active-instincts state (US-023).
+ */
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { BeforeAgentStartEvent, AgentEndEvent } from "./prompt-observer.js";
+import type { Config, Instinct } from "./types.js";
+/** Subset of BeforeAgentStartEventResult used by this module. */
+export interface InjectionResult {
+    /** Replacement system prompt to use for this turn. */
+    systemPrompt?: string;
+}
+export declare const INSTINCTS_HEADER = "## Learned Behaviors (Instincts)";
+/**
+ * Builds the injection block string from a list of instincts.
+ * Returns null when the list is empty (no block needed).
+ */
+export declare function buildInjectionBlock(instincts: Instinct[], maxChars?: number): string | null;
+/**
+ * Returns a modified system prompt string with injected instincts,
+ * or null when no qualifying instincts were found.
+ * Pure function - no I/O.
+ */
+export declare function injectInstincts(systemPrompt: string, instincts: Instinct[]): string | null;
+/**
+ * Handles before_agent_start events.
+ * Loads qualifying instincts, appends them to the system prompt, and stores
+ * their IDs in shared active-instincts state for observation tagging (US-023).
+ * Returns undefined when no instincts qualify (no-op).
+ */
+export declare function handleBeforeAgentStartInjection(event: BeforeAgentStartEvent, _ctx: ExtensionContext, config: Config, projectId?: string | null, baseDir?: string): InjectionResult | void;
+/**
+ * Handles agent_end events.
+ * Clears active instincts state so the next prompt starts clean (US-023).
+ */
+export declare function handleAgentEndClearInstincts(_event: AgentEndEvent, _ctx: ExtensionContext): void;
+//# sourceMappingURL=instinct-injector.d.ts.map

package/dist/instinct-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-injector.d.ts","sourceRoot":"","sources":["../src/instinct-injector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnD,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD,eAAO,MAAM,gBAAgB,qCAAqC,CAAC;AAMnE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B3F;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,QAAQ,EAAE,GACpB,MAAM,GAAG,IAAI,CAIf;AAMD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,eAAe,GAAG,IAAI,CAYxB;AAMD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAEN"}

package/dist/instinct-injector.js

@@ -0,0 +1,89 @@
+/**
+ * System prompt injection for pi-continuous-learning.
+ * Loads filtered instincts and appends them to the system prompt on each
+ * before_agent_start event so the agent benefits from learned behaviors.
+ * Also bridges injected instinct IDs to shared active-instincts state (US-023).
+ */
+import { loadAndFilterFromConfig, inferDomains } from "./instinct-loader.js";
+import { setCurrentActiveInstincts, clearActiveInstincts, } from "./active-instincts.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const INSTINCTS_HEADER = "## Learned Behaviors (Instincts)";
+// ---------------------------------------------------------------------------
+// buildInjectionBlock
+// ---------------------------------------------------------------------------
+/**
+ * Builds the injection block string from a list of instincts.
+ * Returns null when the list is empty (no block needed).
+ */
+export function buildInjectionBlock(instincts, maxChars) {
+    if (instincts.length === 0)
+        return null;
+    const headerLen = `\n\n${INSTINCTS_HEADER}\n`.length;
+    const allBullets = [];
+    let charCount = headerLen;
+    let omitted = 0;
+    for (const i of instincts) {
+        const bullet = `- [${i.confidence.toFixed(2)}] ${i.trigger}: ${i.action}`;
+        const bulletLen = bullet.length + 1; // +1 for newline
+        if (maxChars && charCount + bulletLen > maxChars) {
+            omitted = instincts.length - allBullets.length;
+            break;
+        }
+        allBullets.push(bullet);
+        charCount += bulletLen;
+    }
+    if (allBullets.length === 0)
+        return null;
+    let result = `\n\n${INSTINCTS_HEADER}\n${allBullets.join("\n")}`;
+    if (omitted > 0) {
+        result += `\n(${omitted} lower-confidence instinct${omitted > 1 ? "s" : ""} omitted)`;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// injectInstincts (pure, for testing)
+// ---------------------------------------------------------------------------
+/**
+ * Returns a modified system prompt string with injected instincts,
+ * or null when no qualifying instincts were found.
+ * Pure function - no I/O.
+ */
+export function injectInstincts(systemPrompt, instincts) {
+    const block = buildInjectionBlock(instincts);
+    if (block === null)
+        return null;
+    return systemPrompt + block;
+}
+// ---------------------------------------------------------------------------
+// handleBeforeAgentStartInjection
+// ---------------------------------------------------------------------------
+/**
+ * Handles before_agent_start events.
+ * Loads qualifying instincts, appends them to the system prompt, and stores
+ * their IDs in shared active-instincts state for observation tagging (US-023).
+ * Returns undefined when no instincts qualify (no-op).
+ */
+export function handleBeforeAgentStartInjection(event, _ctx, config, projectId, baseDir) {
+    const relevantDomains = inferDomains(event.prompt);
+    const instincts = loadAndFilterFromConfig(config, projectId, baseDir, relevantDomains);
+    const block = buildInjectionBlock(instincts, config.max_injection_chars);
+    if (block === null) {
+        setCurrentActiveInstincts([]);
+        return undefined;
+    }
+    setCurrentActiveInstincts(instincts.map((i) => i.id));
+    return { systemPrompt: event.systemPrompt + block };
+}
+// ---------------------------------------------------------------------------
+// handleAgentEndClearInstincts
+// ---------------------------------------------------------------------------
+/**
+ * Handles agent_end events.
+ * Clears active instincts state so the next prompt starts clean (US-023).
+ */
+export function handleAgentEndClearInstincts(_event, _ctx) {
+    clearActiveInstincts();
+}
+//# sourceMappingURL=instinct-injector.js.map

package/dist/instinct-injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-injector.js","sourceRoot":"","sources":["../src/instinct-injector.ts"],"names":[],"mappings":"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"}

package/dist/instinct-loader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Instinct loading and filtering for the injector.
+ * Loads project and global instincts, filters by confidence threshold,
+ * sorts by confidence descending, and caps to max_instincts.
+ */
+import type { Instinct, Config } from "./types.js";
+export declare function inferDomains(userPrompt: string): Set<string>;
+export interface LoadInstinctsOptions {
+    /** Project ID, or undefined/null when running outside a project. */
+    projectId?: string | null;
+    /** Minimum confidence threshold (default: DEFAULT_CONFIG.min_confidence). */
+    minConfidence?: number;
+    /** Maximum number of instincts to return (default: DEFAULT_CONFIG.max_instincts). */
+    maxInstincts?: number;
+    /** Optional base directory for storage (used in tests). */
+    baseDir?: string;
+    /** Domains relevant to the current context — matched instincts sort first. */
+    relevantDomains?: Set<string>;
+}
+/**
+ * Filters, sorts, and caps a flat list of instincts.
+ * Pure function - no I/O.
+ */
+export declare function filterInstincts(instincts: Instinct[], minConfidence: number, maxInstincts: number, relevantDomains?: Set<string>): Instinct[];
+/**
+ * Loads instincts from disk, filters by confidence threshold, sorts by
+ * confidence descending, and caps to max_instincts.
+ *
+ * When projectId is provided (and non-null), loads both project-scoped
+ * instincts and global instincts. Otherwise loads only global instincts.
+ */
+export declare function loadAndFilterInstincts(options?: LoadInstinctsOptions): Instinct[];
+/**
+ * Convenience wrapper - uses thresholds from a Config object.
+ */
+export declare function loadAndFilterFromConfig(config: Config, projectId?: string | null, baseDir?: string, relevantDomains?: Set<string>): Instinct[];
+//# sourceMappingURL=instinct-loader.d.ts.map

package/dist/instinct-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-loader.d.ts","sourceRoot":"","sources":["../src/instinct-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAuBnD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAS5D;AAMD,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC/B;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,QAAQ,EAAE,EACrB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,QAAQ,EAAE,CAiBZ;AAMD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,oBAAyB,GACjC,QAAQ,EAAE,CAoBZ;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,CAAC,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,QAAQ,EAAE,CASZ"}

package/dist/instinct-loader.js

@@ -0,0 +1,96 @@
+/**
+ * Instinct loading and filtering for the injector.
+ * Loads project and global instincts, filters by confidence threshold,
+ * sorts by confidence descending, and caps to max_instincts.
+ */
+import { loadProjectInstincts, loadGlobalInstincts } from "./instinct-store.js";
+import { DEFAULT_CONFIG } from "./config.js";
+// ---------------------------------------------------------------------------
+// Domain inference
+// ---------------------------------------------------------------------------
+const UNIVERSAL_DOMAINS = new Set(["workflow", "git"]);
+const DOMAIN_KEYWORDS = {
+    typescript: ["typescript", ".ts", "type ", "interface ", "generic"],
+    css: ["css", "style", "tailwind", "classname", "scss", "sass"],
+    testing: ["test", "spec", "vitest", "jest", "coverage", "assert"],
+    git: ["git", "commit", "branch", "merge", "rebase", "stash"],
+    debugging: ["debug", "error", "stack trace", "exception", "breakpoint"],
+    performance: ["performance", "slow", "memory", "profil", "latency", "cache"],
+    security: ["security", "auth", "token", "secret", "csrf", "xss", "injection"],
+    documentation: ["documentation", "readme", "jsdoc", "docstring"],
+    design: ["component", "ui ", "layout", "responsive", "accessibility"],
+    workflow: ["workflow", "ci", "pipeline", "deploy", "automat"],
+};
+export function inferDomains(userPrompt) {
+    const lower = userPrompt.toLowerCase();
+    const matched = new Set();
+    for (const [domain, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
+        if (keywords.some((kw) => lower.includes(kw))) {
+            matched.add(domain);
+        }
+    }
+    return matched;
+}
+// ---------------------------------------------------------------------------
+// filterInstincts
+// ---------------------------------------------------------------------------
+/**
+ * Filters, sorts, and caps a flat list of instincts.
+ * Pure function - no I/O.
+ */
+export function filterInstincts(instincts, minConfidence, maxInstincts, relevantDomains) {
+    const eligible = instincts.filter((i) => !i.flagged_for_removal && i.confidence >= minConfidence);
+    const sorted = [...eligible].sort((a, b) => {
+        // When relevantDomains are provided, prioritize domain-matched instincts
+        if (relevantDomains && relevantDomains.size > 0) {
+            const aRelevant = relevantDomains.has(a.domain) || UNIVERSAL_DOMAINS.has(a.domain);
+            const bRelevant = relevantDomains.has(b.domain) || UNIVERSAL_DOMAINS.has(b.domain);
+            if (aRelevant && !bRelevant)
+                return -1;
+            if (!aRelevant && bRelevant)
+                return 1;
+        }
+        return b.confidence - a.confidence;
+    });
+    return sorted.slice(0, maxInstincts);
+}
+// ---------------------------------------------------------------------------
+// loadAndFilterInstincts
+// ---------------------------------------------------------------------------
+/**
+ * Loads instincts from disk, filters by confidence threshold, sorts by
+ * confidence descending, and caps to max_instincts.
+ *
+ * When projectId is provided (and non-null), loads both project-scoped
+ * instincts and global instincts. Otherwise loads only global instincts.
+ */
+export function loadAndFilterInstincts(options = {}) {
+    const { projectId, minConfidence = DEFAULT_CONFIG.min_confidence, maxInstincts = DEFAULT_CONFIG.max_instincts, baseDir, relevantDomains, } = options;
+    const projectInstincts = projectId != null
+        ? loadProjectInstincts(projectId, baseDir)
+        : [];
+    const globalInstincts = loadGlobalInstincts(baseDir);
+    // Combine: project instincts first, then global (project-scoped are more specific)
+    const all = [...projectInstincts, ...globalInstincts];
+    return filterInstincts(all, minConfidence, maxInstincts, relevantDomains);
+}
+// ---------------------------------------------------------------------------
+// loadAndFilterFromConfig
+// ---------------------------------------------------------------------------
+/**
+ * Convenience wrapper - uses thresholds from a Config object.
+ */
+export function loadAndFilterFromConfig(config, projectId, baseDir, relevantDomains) {
+    const opts = {
+        minConfidence: config.min_confidence,
+        maxInstincts: config.max_instincts,
+    };
+    if (projectId !== undefined)
+        opts.projectId = projectId;
+    if (baseDir !== undefined)
+        opts.baseDir = baseDir;
+    if (relevantDomains !== undefined)
+        opts.relevantDomains = relevantDomains;
+    return loadAndFilterInstincts(opts);
+}
+//# sourceMappingURL=instinct-loader.js.map

package/dist/instinct-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-loader.js","sourceRoot":"","sources":["../src/instinct-loader.ts"],"names":[],"mappings":"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"}

package/dist/instinct-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { Instinct } from "./types.js";
+/**
+ * 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 declare function parseInstinct(content: string): Instinct;
+/**
+ * Serialize an Instinct into a YAML-frontmatter markdown string.
+ * Confidence is clamped to 0.1–0.9 before writing.
+ */
+export declare function serializeInstinct(instinct: Instinct): string;
+//# sourceMappingURL=instinct-parser.d.ts.map

package/dist/instinct-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-parser.d.ts","sourceRoot":"","sources":["../src/instinct-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAyD3C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAmDvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAkC5D"}

package/dist/instinct-parser.js

@@ -0,0 +1,143 @@
+/**
+ * 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";
+// 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",
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function clampConfidence(value) {
+    return Math.min(MAX_CONFIDENCE, Math.max(MIN_CONFIDENCE, value));
+}
+function assertKebabCase(id) {
+    if (!KEBAB_RE.test(id)) {
+        throw new Error(`Invalid instinct ID "${id}": must be kebab-case (lowercase letters, numbers, hyphens only).`);
+    }
+}
+function splitFrontmatter(content) {
+    // 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) {
+    const { frontmatterStr, body } = splitFrontmatter(content);
+    const fm = parseYaml(frontmatterStr);
+    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 = {
+        id,
+        title: String(fm["title"]),
+        trigger: String(fm["trigger"]),
+        action: body,
+        confidence,
+        domain: String(fm["domain"]),
+        source: fm["source"],
+        scope: fm["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"].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) {
+    const confidence = clampConfidence(instinct.confidence);
+    const frontmatter = {
+        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`;
+}
+//# sourceMappingURL=instinct-parser.js.map

package/dist/instinct-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instinct-parser.js","sourceRoot":"","sources":["../src/instinct-parser.ts"],"names":[],"mappings":"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"}