@keel_flow/learn 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jglasskatz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/apply.d.ts

@@ -0,0 +1,20 @@
+import type { LearningProposal } from "@keel_flow/schema";
+export interface ApplyProposalInput {
+    proposal: LearningProposal;
+    diff: string;
+    cwd: string;
+    verifyFn?: () => Promise<{
+        exitCode: number;
+    }>;
+    branchPrefix?: string;
+}
+export interface ApplyProposalResult {
+    branch: string;
+    applied: boolean;
+    verifyExitCode: number | null;
+    deferred: boolean;
+    reason?: string;
+}
+export declare function inferBranchName(proposalId: string, prefix?: string): string;
+export declare function applyAccepted(input: ApplyProposalInput): Promise<ApplyProposalResult>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,SAAe,GAAG,MAAM,CAEjF;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CA8E9B"}

package/dist/apply.js

@@ -0,0 +1,89 @@
+import { promises as fs } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { markStatus } from "./queue.js";
+function git(args, cwd) {
+    const res = spawnSync("git", args, { cwd, encoding: "utf-8" });
+    return {
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+        ok: res.status === 0,
+    };
+}
+export function inferBranchName(proposalId, prefix = "keel-learn") {
+    return `${prefix}/${proposalId.slice(0, 12)}`;
+}
+export async function applyAccepted(input) {
+    const cwd = resolve(input.cwd);
+    const branch = inferBranchName(input.proposal.id, input.branchPrefix);
+    // Capture the current branch so we can return to it on failure
+    const head = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    const previousBranch = head.ok ? head.stdout.trim() : null;
+    // Create the new branch off HEAD
+    const create = git(["checkout", "-b", branch], cwd);
+    if (!create.ok) {
+        await markStatus(input.proposal.id, "deferred", cwd, {
+            note: `Could not create branch ${branch}: ${create.stderr.trim()}`,
+        });
+        return {
+            branch,
+            applied: false,
+            verifyExitCode: null,
+            deferred: true,
+            reason: `branch-create-failed`,
+        };
+    }
+    // Write the diff to a tmp file and apply
+    const tmpPath = join(cwd, `.keel-learn-${input.proposal.id}.patch`);
+    await fs.writeFile(tmpPath, input.diff.endsWith("\n") ? input.diff : input.diff + "\n", "utf-8");
+    const apply = git(["apply", "--whitespace=nowarn", tmpPath], cwd);
+    await fs.rm(tmpPath, { force: true });
+    if (!apply.ok) {
+        if (previousBranch)
+            git(["checkout", previousBranch], cwd);
+        git(["branch", "-D", branch], cwd);
+        await markStatus(input.proposal.id, "deferred", cwd, {
+            note: `git apply failed: ${apply.stderr.trim()}`,
+        });
+        return {
+            branch,
+            applied: false,
+            verifyExitCode: null,
+            deferred: true,
+            reason: "git-apply-failed",
+        };
+    }
+    // Run verify (injected for tests, otherwise no-op pass-through)
+    let verifyExitCode = null;
+    if (input.verifyFn) {
+        const v = await input.verifyFn();
+        verifyExitCode = v.exitCode;
+    }
+    // exitCode === 2 means critical violations per the verify-gate contract
+    if (verifyExitCode === 2) {
+        if (previousBranch)
+            git(["checkout", previousBranch], cwd);
+        await markStatus(input.proposal.id, "deferred", cwd, {
+            note: "verify gate flagged critical violations",
+            verifyExitCode,
+        });
+        return {
+            branch,
+            applied: true,
+            verifyExitCode,
+            deferred: true,
+            reason: "verify-critical-failure",
+        };
+    }
+    await markStatus(input.proposal.id, "accepted", cwd, {
+        note: `applied on branch ${branch}`,
+        ...(verifyExitCode !== null ? { verifyExitCode } : {}),
+    });
+    return {
+        branch,
+        applied: true,
+        verifyExitCode,
+        deferred: false,
+    };
+}
+//# sourceMappingURL=apply.js.map

package/dist/apply.js.map

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

package/dist/diff-gen.d.ts

@@ -0,0 +1,20 @@
+import type { ModelProvider } from "@keel_flow/runtime";
+import type { LearningProposal } from "@keel_flow/schema";
+import type { ParsedSuggestion } from "@keel_flow/reflect";
+export interface DiffGenInput {
+    proposal: LearningProposal;
+    suggestion: ParsedSuggestion;
+    cwd: string;
+    provider: ModelProvider;
+    model?: string;
+    /** Override the file the diff is applied to. Defaults to defaultTargetPath. */
+    targetPath?: string;
+}
+export interface DiffGenResult {
+    path: string;
+    diff: string;
+    unableToDiff: boolean;
+    reason?: string;
+}
+export declare function proposalToDiff(input: DiffGenInput): Promise<DiffGenResult>;
+//# sourceMappingURL=diff-gen.d.ts.map

package/dist/diff-gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-gen.d.ts","sourceRoot":"","sources":["../src/diff-gen.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAe3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAgDhF"}

package/dist/diff-gen.js

@@ -0,0 +1,63 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { defaultTargetPath } from "./proposals.js";
+const DIFF_SYSTEM_PROMPT = `You are the diff generator for Keel's learning loop.
+
+Given a single proposed change description and the current contents of a target file, produce a unified diff (\`diff -u\` format) that applies the change.
+
+Hard constraints:
+- Emit ONLY the unified diff, no preamble, no closing remarks, no fences.
+- Use the exact path supplied by the user as both \`---\` and \`+++\` paths (no a/ or b/ prefix).
+- Preserve the file's surrounding context (3 context lines per hunk).
+- Make the smallest change that accomplishes the proposal.
+- Do not invent edits the proposal does not call for.
+- If the proposal cannot be expressed as a sensible diff, emit a single-line comment \`# unable-to-diff: <reason>\` instead.`;
+async function readTargetSafely(path) {
+    if (!existsSync(path))
+        return "";
+    return fs.readFile(path, "utf-8");
+}
+export async function proposalToDiff(input) {
+    const path = input.targetPath ?? defaultTargetPath({
+        cwd: input.cwd,
+        target: input.proposal.target,
+    });
+    const cwdAbs = resolve(input.cwd);
+    const relPath = path.startsWith(cwdAbs + "/") ? path.slice(cwdAbs.length + 1) : path;
+    const current = await readTargetSafely(path);
+    const userPrompt = `Target file: ${relPath}\n` +
+        `Target kind: ${input.proposal.target}\n` +
+        `Proposal title: ${input.suggestion.title}\n` +
+        `Proposal rationale: ${input.suggestion.rationale}\n` +
+        `Proposal change: ${input.suggestion.change}\n\n` +
+        `## Current file contents (first 12k chars)\n\n` +
+        `\`\`\`\n${current.slice(0, 12000)}\n\`\`\`\n\n` +
+        `Emit the unified diff now.`;
+    const res = await input.provider.generate({
+        system: DIFF_SYSTEM_PROMPT,
+        messages: [
+            {
+                role: "user",
+                content: [{ type: "text", text: userPrompt }],
+            },
+        ],
+        maxTokens: 2048,
+        model: input.model ?? input.provider.defaultModel,
+    });
+    const text = res.content
+        .map((b) => (b.type === "text" ? b.text : ""))
+        .join("")
+        .trim();
+    const unableMatch = /^#\s*unable-to-diff:\s*(.*)$/m.exec(text);
+    if (unableMatch) {
+        return {
+            path,
+            diff: text,
+            unableToDiff: true,
+            reason: (unableMatch[1] ?? "").trim(),
+        };
+    }
+    return { path, diff: text, unableToDiff: false };
+}
+//# sourceMappingURL=diff-gen.js.map

package/dist/diff-gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-gen.js","sourceRoot":"","sources":["../src/diff-gen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,kBAAkB,GAAG;;;;;;;;;;6HAUkG,CAAC;AAmB9H,KAAK,UAAU,gBAAgB,CAAC,IAAY;IAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAmB;IACtD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,IAAI,iBAAiB,CAAC;QACjD,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM;KAC9B,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAErF,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAE7C,MAAM,UAAU,GACd,gBAAgB,OAAO,IAAI;QAC3B,gBAAgB,KAAK,CAAC,QAAQ,CAAC,MAAM,IAAI;QACzC,mBAAmB,KAAK,CAAC,UAAU,CAAC,KAAK,IAAI;QAC7C,uBAAuB,KAAK,CAAC,UAAU,CAAC,SAAS,IAAI;QACrD,oBAAoB,KAAK,CAAC,UAAU,CAAC,MAAM,MAAM;QACjD,gDAAgD;QAChD,WAAW,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc;QAChD,4BAA4B,CAAC;IAE/B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACxC,MAAM,EAAE,kBAAkB;QAC1B,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;aAC9C;SACF;QACD,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY;KAClD,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SAC7C,IAAI,CAAC,EAAE,CAAC;SACR,IAAI,EAAE,CAAC;IAEV,MAAM,WAAW,GAAG,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO;YACL,IAAI;YACJ,IAAI,EAAE,IAAI;YACV,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;SACtC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { loadProposalsFromReflectionMarkdown, defaultTargetPath, } from "./proposals.js";
+export type { LearningProposal, LearningTarget, LoadFromReflectionOptions, ProposalWithContext, TargetPathArgs, } from "./proposals.js";
+export { proposalToDiff } from "./diff-gen.js";
+export type { DiffGenInput, DiffGenResult } from "./diff-gen.js";
+export { loadAllProposals, loadPending, loadEmerging, loadByStatus, readStatusLog, markStatus, currentStatus, learnLogPath, } from "./queue.js";
+export type { ProposalRecord, StatusEvent } from "./queue.js";
+export { gateProposals, promotedProposals, lessonKey, RECURRENCE_THRESHOLD, } from "./recurrence.js";
+export type { GatedProposal, PromotionState } from "./recurrence.js";
+export { applyAccepted, inferBranchName } from "./apply.js";
+export type { ApplyProposalInput, ApplyProposalResult } from "./apply.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,EACnC,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { loadProposalsFromReflectionMarkdown, defaultTargetPath, } from "./proposals.js";
+export { proposalToDiff } from "./diff-gen.js";
+export { loadAllProposals, loadPending, loadEmerging, loadByStatus, readStatusLog, markStatus, currentStatus, learnLogPath, } from "./queue.js";
+export { gateProposals, promotedProposals, lessonKey, RECURRENCE_THRESHOLD, } from "./recurrence.js";
+export { applyAccepted, inferBranchName } from "./apply.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,EACnC,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/proposals.d.ts

@@ -0,0 +1,19 @@
+import type { LearningProposal, LearningTarget } from "@keel_flow/schema";
+import { type ParsedSuggestion } from "@keel_flow/reflect";
+export type { LearningProposal, LearningTarget } from "@keel_flow/schema";
+export interface LoadFromReflectionOptions {
+    markdown: string;
+    sessionId?: string;
+    createdAt?: string;
+}
+export declare function loadProposalsFromReflectionMarkdown(opts: LoadFromReflectionOptions): LearningProposal[];
+export interface TargetPathArgs {
+    cwd: string;
+    target: LearningTarget;
+}
+export declare function defaultTargetPath(args: TargetPathArgs): string;
+export interface ProposalWithContext extends LearningProposal {
+    suggestion: ParsedSuggestion;
+    reflectionPath: string;
+}
+//# sourceMappingURL=proposals.d.ts.map

package/dist/proposals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposals.d.ts","sourceRoot":"","sources":["../src/proposals.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,yBAAyB,GAC9B,gBAAgB,EAAE,CASpB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAa9D;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/proposals.js

@@ -0,0 +1,26 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseSuggestionsFromMarkdown, proposalFromSuggestion, } from "@keel_flow/reflect";
+export function loadProposalsFromReflectionMarkdown(opts) {
+    const suggestions = parseSuggestionsFromMarkdown(opts.markdown);
+    const sessionIds = opts.sessionId ? [opts.sessionId] : [];
+    return suggestions.map((s) => proposalFromSuggestion(s, {
+        sessionIds,
+        ...(opts.createdAt ? { createdAt: opts.createdAt } : {}),
+    }));
+}
+export function defaultTargetPath(args) {
+    switch (args.target) {
+        case "skill-global":
+            return join(homedir(), ".keel", "global-skill.md");
+        case "skill-local":
+            return join(resolve(args.cwd), ".keel", "local-skill.md");
+        case "principle-pack":
+            return join(resolve(args.cwd), "principles", "index.ts");
+        case "architecture":
+            return join(resolve(args.cwd), "architecture", "data.ts");
+        case "memory":
+            return join(resolve(args.cwd), ".keel", "memory.md");
+    }
+}
+//# sourceMappingURL=proposals.js.map

package/dist/proposals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposals.js","sourceRoot":"","sources":["../src/proposals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GAEvB,MAAM,oBAAoB,CAAC;AAU5B,MAAM,UAAU,mCAAmC,CACjD,IAA+B;IAE/B,MAAM,WAAW,GAAuB,4BAA4B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3B,sBAAsB,CAAC,CAAC,EAAE;QACxB,UAAU;QACV,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC,CACH,CAAC;AACJ,CAAC;AAOD,MAAM,UAAU,iBAAiB,CAAC,IAAoB;IACpD,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,cAAc;YACjB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACrD,KAAK,aAAa;YAChB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC;QAC5D,KAAK,gBAAgB;YACnB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;QAC3D,KAAK,cAAc;YACjB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;QAC5D,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}

package/dist/queue.d.ts

@@ -0,0 +1,35 @@
+import type { LearningProposal, LearningStatus } from "@keel_flow/schema";
+import type { ParsedSuggestion } from "@keel_flow/reflect";
+import { type GatedProposal } from "./recurrence.js";
+export interface ProposalRecord {
+    proposal: LearningProposal;
+    suggestion: ParsedSuggestion;
+    reflectionPath: string;
+}
+export interface StatusEvent {
+    proposalId: string;
+    status: LearningStatus;
+    ts: string;
+    note?: string;
+    verifyExitCode?: number;
+}
+export declare function learnLogPath(cwd: string): string;
+export declare function readStatusLog(cwd: string): Promise<StatusEvent[]>;
+export declare function markStatus(proposalId: string, status: LearningStatus, cwd: string, extras?: {
+    note?: string;
+    verifyExitCode?: number;
+}): Promise<void>;
+export declare function currentStatus(proposalId: string, events: StatusEvent[]): LearningStatus;
+export declare function loadAllProposals(cwd: string): Promise<ProposalRecord[]>;
+export declare function loadPending(opts: {
+    cwd: string;
+    gate?: boolean;
+}): Promise<ProposalRecord[]>;
+export declare function loadEmerging(opts: {
+    cwd: string;
+}): Promise<GatedProposal[]>;
+export declare function loadByStatus(opts: {
+    cwd: string;
+    status: LearningStatus;
+}): Promise<ProposalRecord[]>;
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAcvE;AAED,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACtD,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,WAAW,EAAE,GACpB,cAAc,CAIhB;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAc7E;AAOD,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAM5B;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAKlF;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,cAAc,CAAC;CACxB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAM5B"}

package/dist/queue.js

@@ -0,0 +1,84 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { listReflections, parseSuggestionsFromMarkdown, proposalFromSuggestion } from "@keel_flow/reflect";
+import { gateProposals, promotedProposals } from "./recurrence.js";
+export function learnLogPath(cwd) {
+    return join(resolve(cwd), ".keel", "learn", "proposals.jsonl");
+}
+export async function readStatusLog(cwd) {
+    const path = learnLogPath(cwd);
+    if (!existsSync(path))
+        return [];
+    const raw = await fs.readFile(path, "utf-8");
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // ignore malformed lines
+        }
+    }
+    return out;
+}
+export async function markStatus(proposalId, status, cwd, extras = {}) {
+    const path = learnLogPath(cwd);
+    await fs.mkdir(dirname(path), { recursive: true });
+    const entry = {
+        proposalId,
+        status,
+        ts: new Date().toISOString(),
+        ...(extras.note !== undefined ? { note: extras.note } : {}),
+        ...(extras.verifyExitCode !== undefined ? { verifyExitCode: extras.verifyExitCode } : {}),
+    };
+    await fs.appendFile(path, JSON.stringify(entry) + "\n", "utf-8");
+}
+export function currentStatus(proposalId, events) {
+    const matches = events.filter((e) => e.proposalId === proposalId);
+    if (matches.length === 0)
+        return "pending";
+    return matches[matches.length - 1].status;
+}
+export async function loadAllProposals(cwd) {
+    const reflections = await listReflections(cwd);
+    const records = [];
+    for (const summary of reflections) {
+        const md = await fs.readFile(summary.path, "utf-8");
+        const suggestions = parseSuggestionsFromMarkdown(md);
+        for (const s of suggestions) {
+            const p = proposalFromSuggestion(s, {
+                sessionIds: summary.sessionId ? [summary.sessionId] : [],
+            });
+            records.push({ proposal: p, suggestion: s, reflectionPath: summary.path });
+        }
+    }
+    return records;
+}
+// Pending proposals that have passed the recurrence/severity gate — this is
+// the human review queue. A lesson reaches it only after recurring across
+// reflections or being flagged critical once (see recurrence.ts). Set
+// `gate: false` to get the ungated pending set (every suggestion), e.g. for
+// diagnostics. `loadEmerging` returns the held-but-not-yet-promoted set.
+export async function loadPending(opts) {
+    const events = await readStatusLog(opts.cwd);
+    const all = await loadAllProposals(opts.cwd);
+    const pending = all.filter((r) => currentStatus(r.proposal.id, events) === "pending");
+    if (opts.gate === false)
+        return pending;
+    return promotedProposals(pending);
+}
+export async function loadEmerging(opts) {
+    const events = await readStatusLog(opts.cwd);
+    const all = await loadAllProposals(opts.cwd);
+    const pending = all.filter((r) => currentStatus(r.proposal.id, events) === "pending");
+    return gateProposals(pending).filter((g) => g.state === "emerging");
+}
+export async function loadByStatus(opts) {
+    const events = await readStatusLog(opts.cwd);
+    const all = await loadAllProposals(opts.cwd);
+    return all.filter((r) => currentStatus(r.proposal.id, events) === opts.status);
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

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

package/dist/recurrence.d.ts

@@ -0,0 +1,14 @@
+import type { ProposalRecord } from "./queue.js";
+export declare const RECURRENCE_THRESHOLD = 2;
+export type PromotionState = "promoted" | "emerging";
+export interface GatedProposal {
+    record: ProposalRecord;
+    state: PromotionState;
+    occurrences: number;
+    promotedBy: "recurrence" | "severity" | null;
+    reflectionPaths: string[];
+}
+export declare function lessonKey(record: ProposalRecord): string;
+export declare function gateProposals(records: ProposalRecord[]): GatedProposal[];
+export declare function promotedProposals(records: ProposalRecord[]): ProposalRecord[];
+//# sourceMappingURL=recurrence.d.ts.map

package/dist/recurrence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence.d.ts","sourceRoot":"","sources":["../src/recurrence.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,aAAa;IAE5B,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,cAAc,CAAC;IAEtB,WAAW,EAAE,MAAM,CAAC;IAEpB,UAAU,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAAC;IAG7C,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAOxD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,aAAa,EAAE,CA2CxE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAI7E"}

package/dist/recurrence.js

@@ -0,0 +1,63 @@
+export const RECURRENCE_THRESHOLD = 2;
+// Two suggestions are "the same lesson" when they target the same artifact and
+// have a normalized-equal title. Title normalization is deliberately loose
+// (lowercase, collapse whitespace, strip trailing punctuation) so trivially
+// reworded restatements of the same lesson still group.
+export function lessonKey(record) {
+    const title = record.suggestion.title
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(/[.!?,;:]+$/g, "")
+        .trim();
+    return `${record.suggestion.target}::${title}`;
+}
+export function gateProposals(records) {
+    const groups = new Map();
+    for (const record of records) {
+        const key = lessonKey(record);
+        const group = groups.get(key);
+        if (group)
+            group.push(record);
+        else
+            groups.set(key, [record]);
+    }
+    const gated = [];
+    for (const group of groups.values()) {
+        const distinctReflections = new Set(group.map((r) => r.reflectionPath));
+        const occurrences = distinctReflections.size;
+        const isCritical = group.some((r) => r.suggestion.severity === "high");
+        let state = "emerging";
+        let promotedBy = null;
+        if (isCritical) {
+            state = "promoted";
+            promotedBy = "severity";
+        }
+        else if (occurrences >= RECURRENCE_THRESHOLD) {
+            state = "promoted";
+            promotedBy = "recurrence";
+        }
+        // Representative = the last occurrence (most recent reflection wins its
+        // current wording), but provenance lists every contributing reflection.
+        const record = group[group.length - 1];
+        gated.push({
+            record,
+            state,
+            occurrences,
+            promotedBy,
+            reflectionPaths: [...distinctReflections],
+        });
+    }
+    // Promoted first, then by occurrence count — the review queue surfaces the
+    // strongest-evidence lessons at the top.
+    return gated.sort((a, b) => {
+        if (a.state !== b.state)
+            return a.state === "promoted" ? -1 : 1;
+        return b.occurrences - a.occurrences;
+    });
+}
+export function promotedProposals(records) {
+    return gateProposals(records)
+        .filter((g) => g.state === "promoted")
+        .map((g) => g.record);
+}
+//# sourceMappingURL=recurrence.js.map

package/dist/recurrence.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@keel_flow/learn",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@keel_flow/core": "0.2.0",
+    "@keel_flow/reflect": "0.2.0",
+    "@keel_flow/runtime": "0.2.0",
+    "@keel_flow/schema": "0.2.0",
+    "@keel_flow/telemetry": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}