@codyswann/lisa 2.236.0 → 2.238.0

package/dist/cli/check-learnings-budget-cmd.d.ts

@@ -0,0 +1,20 @@
+/** Injectable collaborators for {@link runCheckLearningsBudget}. */
+export interface CheckLearningsBudgetDependencies {
+    /** Working directory used to resolve the config and default file. */
+    readonly cwd?: string;
+    /** Sink for the pass / missing informational line (defaults to stdout). */
+    readonly log?: (message: string) => void;
+    /** Sink for the violation diagnostic (defaults to stderr). */
+    readonly error?: (message: string) => void;
+}
+/**
+ * Run the budget check for one project and return the intended process exit
+ * code (0 pass or missing, 1 violation). Never throws for an expected
+ * condition — a missing learnings file resolves to a silent, successful pass.
+ * @param fileArg - Optional explicit learnings file to check (default: resolved
+ *   from `.lisa.config.json`)
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code
+ */
+export declare function runCheckLearningsBudget(fileArg: string | undefined, dependencies?: CheckLearningsBudgetDependencies): Promise<number>;
+//# sourceMappingURL=check-learnings-budget-cmd.d.ts.map

package/dist/cli/check-learnings-budget-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-learnings-budget-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/check-learnings-budget-cmd.ts"],"names":[],"mappings":"AAyBA,oEAAoE;AACpE,MAAM,WAAW,gCAAgC;IAC/C,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAoBD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,YAAY,GAAE,gCAAqC,GAClD,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/dist/cli/check-learnings-budget-cmd.js

@@ -0,0 +1,59 @@
+/**
+ * `lisa check-learnings-budget` — fail CI when a project's learnings file breaks
+ * its hard budget.
+ *
+ * This is the delivery vehicle that carries the budget gate (built into Lisa's
+ * core) out to every host project's CI: the Lisa-managed reusable quality
+ * workflow invokes this command with `bunx`, which resolves the project's
+ * learnings file from `.lisa.config.json` and checks it against the shared
+ * contract. The learnings path is ALWAYS resolved through the
+ * executable config resolver — never hardcoded — so a project that relocates
+ * its rules directory is still gated at the right file. A project with no
+ * learnings file is the common, expected case and passes silently (exit 0), so
+ * hosts that have never recorded a learning stay green with zero configuration.
+ * @module cli/check-learnings-budget-cmd
+ */
+import * as path from "node:path";
+import { checkLearningsBudget, formatDiagnosticPath, } from "../core/learnings-budget-check.js";
+import { readProjectConfig, resolveProjectLearningsFile, } from "../core/project-config.js";
+/**
+ * Resolve the learnings file to check: an explicit path argument wins;
+ * otherwise the project config's resolved learnings path (never hardcoded).
+ * @param fileArg - Optional explicit learnings file argument
+ * @param cwd - Working directory the run is anchored to
+ * @returns Absolute learnings file path
+ */
+async function resolveLearningsPath(fileArg, cwd) {
+    if (fileArg !== undefined) {
+        return path.resolve(cwd, fileArg);
+    }
+    const config = await readProjectConfig(cwd);
+    return path.resolve(cwd, resolveProjectLearningsFile(config));
+}
+/**
+ * Run the budget check for one project and return the intended process exit
+ * code (0 pass or missing, 1 violation). Never throws for an expected
+ * condition — a missing learnings file resolves to a silent, successful pass.
+ * @param fileArg - Optional explicit learnings file to check (default: resolved
+ *   from `.lisa.config.json`)
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code
+ */
+export async function runCheckLearningsBudget(fileArg, dependencies = {}) {
+    const cwd = dependencies.cwd ?? process.cwd();
+    const log = dependencies.log ?? ((message) => console.log(message));
+    const error = dependencies.error ?? ((message) => console.error(message));
+    const resolvedFile = await resolveLearningsPath(fileArg, cwd);
+    const result = await checkLearningsBudget(resolvedFile);
+    if (result.kind === "missing") {
+        log(`no learnings file at ${formatDiagnosticPath(resolvedFile)} — nothing to check`);
+        return 0;
+    }
+    if (result.kind === "violation") {
+        error(`check-learnings-budget: ${formatDiagnosticPath(resolvedFile)}: ${result.detail}`);
+        return 1;
+    }
+    log(`${formatDiagnosticPath(resolvedFile)}: learnings budget passed (${result.entryCount}/${result.maxEntries} entries, ${result.measuredTokens}/${result.maxTokens} maxTokens)`);
+    return 0;
+}
+//# sourceMappingURL=check-learnings-budget-cmd.js.map

package/dist/cli/check-learnings-budget-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-learnings-budget-cmd.js","sourceRoot":"","sources":["../../src/cli/check-learnings-budget-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,2BAA2B,CAAC;AAYnC;;;;;;GAMG;AACH,KAAK,UAAU,oBAAoB,CACjC,OAA2B,EAC3B,GAAW;IAEX,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAA2B,EAC3B,eAAiD,EAAE;IAEnD,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9C,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5E,MAAM,KAAK,GACT,YAAY,CAAC,KAAK,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,YAAY,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,YAAY,CAAC,CAAC;IACxD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,GAAG,CACD,wBAAwB,oBAAoB,CAAC,YAAY,CAAC,qBAAqB,CAChF,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,KAAK,CACH,2BAA2B,oBAAoB,CAAC,YAAY,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,CAClF,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,GAAG,CACD,GAAG,oBAAoB,CAAC,YAAY,CAAC,8BAA8B,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,aAAa,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,SAAS,aAAa,CAC7K,CAAC;IACF,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cli/index.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { runApply } from "./apply.js";
+import { runCheckLearningsBudget } from "./check-learnings-budget-cmd.js";
 import { runCrossPollinate } from "./cross-pollinate-cmd.js";
 import { runDoctor } from "./doctor.js";
 import { printUpdateWarning } from "./print-update-warning.js";
@@ -34,6 +35,8 @@ export interface ProgramDependencies {
     runSync: typeof runSync;
     /** Serves the Lisa settings console (after a config sync). */
     runUi: typeof runUi;
+    /** Checks the project learnings file against its hard budget. */
+    runCheckLearningsBudget: typeof runCheckLearningsBudget;
     /** Runs the non-fatal npm update check (defaults to {@link runUpdateCheck}). */
     runUpdateCheck: typeof runUpdateCheck;
     /** Prints the update warning (defaults to {@link printUpdateWarning}). */

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAEL,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAuB,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAqB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,kEAAkE;IAClE,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,4DAA4D;IAC5D,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,wCAAwC;IACxC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,yDAAyD;IACzD,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,qCAAqC;IACrC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,4EAA4E;IAC5E,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,2EAA2E;IAC3E,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,gFAAgF;IAChF,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,0EAA0E;IAC1E,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CAC/C;AAyGD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,YAAY,GAAE,OAAO,CAAC,mBAAmB,CAAM,GAC9C,OAAO,CA4ET;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAEL,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAuB,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAqB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,kEAAkE;IAClE,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,4DAA4D;IAC5D,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,wCAAwC;IACxC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,yDAAyD;IACzD,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,qCAAqC;IACrC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,4EAA4E;IAC5E,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,2EAA2E;IAC3E,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,iEAAiE;IACjE,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,gFAAgF;IAChF,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,0EAA0E;IAC1E,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CAC/C;AAuID;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,YAAY,GAAE,OAAO,CAAC,mBAAmB,CAAM,GAC9C,OAAO,CAiFT;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/cli/index.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { runApply } from "./apply.js";
+import { runCheckLearningsBudget } from "./check-learnings-budget-cmd.js";
 import { runCrossPollinate, } from "./cross-pollinate-cmd.js";
 import { runDoctor } from "./doctor.js";
 import { printUpdateWarning } from "./print-update-warning.js";
@@ -23,11 +24,30 @@ const DEFAULT_DEPENDENCIES = {
     runCrossPollinate,
     runSync,
     runUi,
+    runCheckLearningsBudget,
     runUpdateCheck,
     printUpdateWarning,
 };
 /** Shared help text for the optional project-path positional argument. */
 const PATH_ARG_DESCRIPTION = "Project path (default: current directory)";
+/**
+ * Register the `check-learnings-budget` gate command. Extracted so the broader
+ * maintenance-command registrar stays within the function-length budget.
+ * @param program - Commander program to mutate
+ * @param deps - Program dependencies
+ */
+function addCheckLearningsBudgetCommand(program, deps) {
+    program
+        .command("check-learnings-budget")
+        .description("Fail if the project learnings file exceeds its hard budget (missing file passes)")
+        .argument("[path]", "Learnings file to check (default: resolved from .lisa.config.json)")
+        .action(async (targetPath) => {
+        const code = await deps.runCheckLearningsBudget(targetPath);
+        if (code !== 0) {
+            process.exitCode = code;
+        }
+    });
+}
 /**
  * Register CLI maintenance commands that do not run the root update warning.
  * @param program - Commander program to mutate
@@ -81,6 +101,7 @@ function addMaintenanceCommands(program, deps) {
         .action(async (targetPath, options) => {
         await deps.runUi(targetPath, options);
     });
+    addCheckLearningsBudgetCommand(program, deps);
     program
         .command("cross-pollinate")
         .description("Make locally-authored agent definitions available to the other agents this project supports")
@@ -116,7 +137,14 @@ export function createProgram(dependencies = {}) {
     // Run the npm update-check once per invocation, before the matched action.
     // It is non-fatal: a failed check never blocks the action from running.
     program.hook("preAction", async (_thisCommand, actionCommand) => {
-        if (["doctor", "sync", "ui", "update", "version"].includes(actionCommand.name())) {
+        if ([
+            "doctor",
+            "sync",
+            "ui",
+            "update",
+            "version",
+            "check-learnings-budget",
+        ].includes(actionCommand.name())) {
             return;
         }
         if (program.opts().updateCheck === false) {

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAEL,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAmB,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAuB,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAqB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAkCjD,MAAM,oBAAoB,GAAwB;IAChD,QAAQ;IACR,eAAe;IACf,YAAY;IACZ,UAAU;IACV,SAAS;IACT,SAAS;IACT,iBAAiB;IACjB,OAAO;IACP,KAAK;IACL,uBAAuB;IACvB,cAAc;IACd,kBAAkB;CACnB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,oBAAoB,GAAG,2CAA2C,CAAC;AAEzE;;;;;GAKG;AACH,SAAS,8BAA8B,CACrC,OAAgB,EAChB,IAAyB;IAEzB,OAAO;SACJ,OAAO,CAAC,wBAAwB,CAAC;SACjC,WAAW,CACV,kFAAkF,CACnF;SACA,QAAQ,CACP,QAAQ,EACR,oEAAoE,CACrE;SACA,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,EAAE;QAC/C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;QAC5D,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAC7B,OAAgB,EAChB,IAAyB;IAEzB,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,6BAA6B,CAAC;SAC1C,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CACV,0EAA0E,CAC3E;SACA,MAAM,CAAC,OAAO,EAAE,8CAA8C,CAAC;SAC/D,MAAM,CAAC,KAAK,EAAE,OAA0B,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,kDAAkD,CAAC;SAC/D,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;SAC7C,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC;SAC7B,MAAM,CAAC,WAAW,EAAE,qBAAqB,CAAC;SAC1C,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,OAAO,EAAE,EAAE;QACxD,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CACV,6FAA6F,CAC9F;SACA,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;SACxC,MAAM,CAAC,WAAW,EAAE,0CAA0C,CAAC;SAC/D,MAAM,CAAC,QAAQ,EAAE,yBAAyB,CAAC;SAC3C,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,OAAuB,EAAE,EAAE;QACxE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,IAAI,CAAC;SACb,WAAW,CACV,0EAA0E,CAC3E;SACA,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;SACxC,MAAM,CAAC,eAAe,EAAE,mBAAmB,EAAE,MAAM,CAAC;SACpD,MAAM,CAAC,WAAW,EAAE,iCAAiC,CAAC;SACtD,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,OAAqB,EAAE,EAAE;QACtE,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEL,8BAA8B,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE9C,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CACV,6FAA6F,CAC9F;SACA,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;SACxC,MAAM,CAAC,SAAS,EAAE,wDAAwD,CAAC;SAC3E,MAAM,CACL,KAAK,EACH,UAA8B,EAC9B,OAA8B,EAC9B,EAAE;QACF,MAAM,IAAI,CAAC,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC,CACF,CAAC;IAEJ,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,eAA6C,EAAE;IAE/C,MAAM,IAAI,GAAwB;QAChC,GAAG,oBAAoB;QACvB,GAAG,YAAY;KAChB,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,MAAM,CAAC;SACZ,WAAW,CACV,0FAA0F,CAC3F;SACA,OAAO,CAAC,iBAAiB,EAAE,CAAC;SAC5B,MAAM,CAAC,mBAAmB,EAAE,mCAAmC,CAAC,CAAC;IAEpE,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,EAAE;QAC9D,IACE;YACE,QAAQ;YACR,MAAM;YACN,IAAI;YACJ,QAAQ;YACR,SAAS;YACT,wBAAwB;SACzB,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAChC,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;YACzC,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,4EAA4E;IAC5E,8EAA8E;IAC9E,0EAA0E;IAC1E,uEAAuE;IACvE,gBAAgB,CACd,OAAO;SACJ,OAAO,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;SACrC,WAAW,CAAC,0DAA0D,CAAC;SACvE,QAAQ,CAAC,eAAe,EAAE,+BAA+B,CAAC,CAC9D,CAAC,MAAM,CAAC,KAAK,EAAE,WAA+B,EAAE,OAAmB,EAAE,EAAE;QACtE,MAAM,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,gBAAgB,CACd,OAAO;SACJ,OAAO,CAAC,eAAe,CAAC;SACxB,WAAW,CAAC,uDAAuD,CAAC;SACpE,cAAc,CACb,eAAe,EACf,iBAAiB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAC3C;SACA,QAAQ,CAAC,eAAe,EAAE,8CAA8C,CAAC,CAC7E,CAAC,MAAM,CACN,KAAK,EACH,WAA+B,EAC/B,OAAuC,EACvC,EAAE;QACF,MAAM,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC,CACF,CAAC;IAEF,gBAAgB,CACd,OAAO;SACJ,OAAO,CAAC,YAAY,CAAC;SACrB,WAAW,CAAC,0DAA0D,CAAC;SACvE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAC5C,CAAC,MAAM,CAAC,KAAK,EAAE,WAA+B,EAAE,OAAmB,EAAE,EAAE;QACtE,MAAM,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,sBAAsB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEtC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/core/learnings-budget-check.d.ts

@@ -0,0 +1,42 @@
+/** A learnings file that satisfies every hard budget. */
+export interface LearningsBudgetOk {
+    readonly kind: "ok";
+    readonly entryCount: number;
+    readonly maxEntries: number;
+    readonly measuredTokens: number;
+    readonly maxTokens: number;
+}
+/** No learnings file exists at the resolved path — an expected, silent case. */
+export interface LearningsBudgetMissing {
+    readonly kind: "missing";
+    readonly detail: string;
+}
+/** The learnings file breached a budget or is otherwise unsafe or invalid. */
+export interface LearningsBudgetViolation {
+    readonly kind: "violation";
+    readonly detail: string;
+}
+/** Structured outcome of one budget check. */
+export type LearningsBudgetResult = LearningsBudgetOk | LearningsBudgetMissing | LearningsBudgetViolation;
+/**
+ * Check one already-resolved absolute learnings path against the shared hard
+ * budgets. Callers resolve the path (from config or an explicit argument) and
+ * decide the exit policy from the returned discriminated union.
+ * @param file - Absolute learnings file path
+ * @returns Structured budget-check result
+ */
+export declare function checkLearningsBudget(file: string): Promise<LearningsBudgetResult>;
+/**
+ * Render a caught failure without allowing filesystem paths or control bytes
+ * embedded in an Error message to forge additional terminal/CI output.
+ * @param error - Unknown thrown failure
+ * @returns Stable, single-line diagnostic detail
+ */
+export declare function formatErrorDetail(error: unknown): string;
+/**
+ * Quote one path after applying terminal-safe JSON-style escaping.
+ * @param file - Path to render in diagnostics
+ * @returns Quoted, terminal-safe path
+ */
+export declare function formatDiagnosticPath(file: string): string;
+//# sourceMappingURL=learnings-budget-check.d.ts.map

package/dist/core/learnings-budget-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-budget-check.d.ts","sourceRoot":"","sources":["../../src/core/learnings-budget-check.ts"],"names":[],"mappings":"AA4BA,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CAgChC;AA2CD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYxD;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/core/learnings-budget-check.js

@@ -0,0 +1,210 @@
+/**
+ * Reusable core check for the canonical project-learnings document and its hard
+ * budgets.
+ *
+ * Extracted from the package-facing `scripts/check-learnings-budget.ts` so the
+ * identical bounded-read, token-budget, per-entry validation, and canonical
+ * format checks can be shared by every caller — the existing package script and
+ * the `lisa check-learnings-budget` CLI subcommand that ships the gate into host
+ * projects' CI. Every hardening property of the original script is preserved
+ * here: a bounded regular-file read, an `O_NONBLOCK` open with TOCTOU stat
+ * checks, and terminal-escape-safe diagnostic text. The function never throws
+ * for an expected condition — a missing file is a distinct result and every
+ * other failure is a `violation` carrying a single-line, terminal-safe detail —
+ * so each caller owns its own exit policy.
+ * @module learnings-budget-check
+ */
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { LEARNINGS_CONTRACT, estimateLearningTokens, } from "./learnings-contract.js";
+import { parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
+import { validateLearningEntry } from "./learnings-entry.js";
+/**
+ * Check one already-resolved absolute learnings path against the shared hard
+ * budgets. Callers resolve the path (from config or an explicit argument) and
+ * decide the exit policy from the returned discriminated union.
+ * @param file - Absolute learnings file path
+ * @returns Structured budget-check result
+ */
+export async function checkLearningsBudget(file) {
+    try {
+        const content = await readBoundedRegularFile(file, LEARNINGS_CONTRACT.maxTokens);
+        const measuredTokens = estimateLearningTokens(content);
+        if (measuredTokens > LEARNINGS_CONTRACT.maxTokens) {
+            throw new Error(`maxTokens exceeded: measured ${measuredTokens}, allowed ${LEARNINGS_CONTRACT.maxTokens}`);
+        }
+        const entries = parseLearningsFile(content);
+        for (const entry of entries) {
+            validateLearningEntry(entry);
+        }
+        if (renderLearningsFile(entries) !== content) {
+            throw new Error("non-canonical project learnings format");
+        }
+        return {
+            kind: "ok",
+            entryCount: entries.length,
+            maxEntries: LEARNINGS_CONTRACT.maxEntries,
+            measuredTokens,
+            maxTokens: LEARNINGS_CONTRACT.maxTokens,
+        };
+    }
+    catch (error) {
+        const detail = formatErrorDetail(error);
+        return isFileNotFound(error)
+            ? { kind: "missing", detail }
+            : { kind: "violation", detail: withRemediation(detail, file) };
+    }
+}
+/**
+ * Append a terse, actionable remediation clause to a file-level budget breach
+ * so an operator reading CI output learns the fix, not just the number. Only
+ * the whole-file budgets (token ceiling, entry count, canonical format) are
+ * augmented; per-entry validation failures already name the offending entry
+ * and are left verbatim, as are non-budget filesystem errors.
+ * @param detail - Terminal-safe diagnostic detail
+ * @param file - Absolute learnings file path
+ * @returns The detail, with a remediation clause when one applies
+ */
+function withRemediation(detail, file) {
+    if (detail.startsWith("Invalid learning entry")) {
+        return detail;
+    }
+    const target = formatDiagnosticPath(file);
+    if (detail.includes("maxEntries")) {
+        return `${detail} — consolidate or remove entries in ${target} to fit the learnings budget`;
+    }
+    if (detail.includes("maxTokens")) {
+        return `${detail} — shorten or remove entries in ${target} to fit the learnings budget`;
+    }
+    if (detail.includes("canonical") || detail.includes("format")) {
+        return `${detail} — re-generate ${target} with the learnings writer to restore the canonical format`;
+    }
+    return detail;
+}
+/**
+ * Whether a caught failure is a "file does not exist" filesystem error, which
+ * callers treat as an expected, silent condition rather than a violation.
+ * @param error - Unknown thrown failure
+ * @returns True when the error reports an absent path
+ */
+function isFileNotFound(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        readOwnString(error, "code") === "ENOENT");
+}
+/**
+ * Render a caught failure without allowing filesystem paths or control bytes
+ * embedded in an Error message to forge additional terminal/CI output.
+ * @param error - Unknown thrown failure
+ * @returns Stable, single-line diagnostic detail
+ */
+export function formatErrorDetail(error) {
+    if (error !== null && typeof error === "object") {
+        const code = readOwnString(error, "code");
+        if (code !== undefined && /^[A-Z][A-Z0-9_]*$/u.test(code)) {
+            const syscall = readOwnString(error, "syscall");
+            return syscall === undefined
+                ? `filesystem error ${code}`
+                : `filesystem error ${code} during ${escapeDiagnosticText(syscall)}`;
+        }
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return escapeDiagnosticText(message);
+}
+/**
+ * Read one inert own string property without invoking an accessor.
+ * @param candidate - Object to inspect
+ * @param key - Property name to read
+ * @returns The own string value, or undefined
+ */
+function readOwnString(candidate, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+    return descriptor !== undefined &&
+        "value" in descriptor &&
+        typeof descriptor.value === "string"
+        ? descriptor.value
+        : undefined;
+}
+/**
+ * Escape terminal controls while retaining ordinary diagnostic wording.
+ * @param value - Raw diagnostic text
+ * @returns Terminal-safe, single-line text
+ */
+function escapeDiagnosticText(value) {
+    const jsonBody = JSON.stringify(value).slice(1, -1);
+    return Array.from(jsonBody)
+        .map(character => {
+        const code = character.charCodeAt(0);
+        const isForbidden = (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029;
+        return isForbidden
+            ? `\\u${code.toString(16).padStart(4, "0")}`
+            : character;
+    })
+        .join("");
+}
+/**
+ * Quote one path after applying terminal-safe JSON-style escaping.
+ * @param file - Path to render in diagnostics
+ * @returns Quoted, terminal-safe path
+ */
+export function formatDiagnosticPath(file) {
+    return `"${escapeDiagnosticText(file)}"`;
+}
+/**
+ * Read at most one byte beyond the hard budget from one verified regular-file
+ * handle. Non-blocking open prevents a FIFO path from stalling the gate.
+ * @param file - Absolute candidate learnings path
+ * @param maximumBytes - Shared executable maxTokens byte ceiling
+ * @returns Strictly decoded UTF-8 content within the byte ceiling
+ */
+async function readBoundedRegularFile(file, maximumBytes) {
+    const handle = await open(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile()) {
+            throw new Error("unsafe input: expected a regular file");
+        }
+        if (before.size > BigInt(maximumBytes)) {
+            throw new Error(`maxTokens exceeded: measured ${before.size}, allowed ${maximumBytes}`);
+        }
+        const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+        const bytesRead = await fillBuffer(handle, buffer, 0);
+        if (bytesRead > maximumBytes) {
+            throw new Error(`maxTokens exceeded: measured at least ${bytesRead}, allowed ${maximumBytes}`);
+        }
+        const after = await handle.stat({ bigint: true });
+        if (after.dev !== before.dev ||
+            after.ino !== before.ino ||
+            after.size !== before.size ||
+            after.mtimeNs !== before.mtimeNs ||
+            after.ctimeNs !== before.ctimeNs) {
+            throw new Error("unsafe input: file changed during bounded read");
+        }
+        return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Fill a fixed buffer from a handle via bounded recursion, returning the total
+ * bytes read. Recursion (rather than a mutable accumulator) keeps the module
+ * within the repository's immutability lint rules while preserving the
+ * original loop's "stop at EOF or buffer end" semantics; depth is bounded by
+ * the small fixed buffer, which a learnings file fills in one or two reads.
+ * @param handle - Verified regular-file handle
+ * @param buffer - Destination buffer sized to the byte ceiling plus one
+ * @param offset - Bytes already read into the buffer
+ * @returns Total bytes read into the buffer
+ */
+async function fillBuffer(handle, buffer, offset) {
+    if (offset >= buffer.length) {
+        return offset;
+    }
+    const result = await handle.read(buffer, offset, buffer.length - offset, null);
+    if (result.bytesRead === 0) {
+        return offset;
+    }
+    return fillBuffer(handle, buffer, offset + result.bytesRead);
+}
+//# sourceMappingURL=learnings-budget-check.js.map

package/dist/core/learnings-budget-check.js.map

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

package/dist/core/learnings-document.js

@@ -66,7 +66,12 @@ function validateParsedLearningEntry(candidate, index) {
     }
     catch (error) {
         const id = readDiagnosticEntryId(candidate);
-        const label = id === undefined ? `entry ${index + 1}` : `entry ${JSON.stringify(id)}`;
+        // Single-quote the id rather than JSON.stringify it: the message is later
+        // rendered through a JSON-body escaper for terminal safety, which would
+        // double-escape embedded double quotes into `\"id\"`. Single quotes read
+        // cleanly and are not re-escaped, while control-character neutralization
+        // still happens downstream.
+        const label = id === undefined ? `entry ${index + 1}` : `entry '${id}'`;
         const detail = error instanceof Error ? error.message : String(error);
         throw new Error(`Invalid learning ${label}: ${detail}`);
     }

package/dist/core/learnings-document.js.map

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

package/dist/core/learnings-writer.d.ts

@@ -1,10 +1,32 @@
+/** Write-time consolidation options for {@link persistConsolidatedLearning}. */
+export interface ConsolidatedLearningOptions {
+    /** Ids of existing entries the new entry merges or replaces. */
+    readonly supersede?: readonly string[];
+}
 /**
  * Persist one already-selected learning without generating or truncating it.
+ * Append-only: a duplicate id always throws. Kept as the stable back-compat
+ * entry point; consolidation-aware writers use
+ * {@link persistConsolidatedLearning} instead.
  * @param projectRoot - Absolute path to the host project root
  * @param candidate - Untrusted seven-field learning entry
  * @returns Absolute path to the persisted learnings file
  */
 export declare function persistLearningEntry(projectRoot: string, candidate: unknown): Promise<string>;
+/**
+ * Persist one learning with mandatory write-time consolidation semantics:
+ * entries named in `supersede` are dropped from the document in the same
+ * atomic write that adds the new entry, so a related existing entry is merged
+ * or replaced instead of gaining a near-duplicate sibling. The rendered
+ * document is re-validated against the shared entry and file budgets after
+ * consolidation. Without `supersede` this is exactly the append-only
+ * {@link persistLearningEntry} behavior, including the duplicate-id throw.
+ * @param projectRoot - Absolute path to the host project root
+ * @param candidate - Untrusted seven-field learning entry
+ * @param options - Optional consolidation directives
+ * @returns Absolute path to the persisted learnings file
+ */
+export declare function persistConsolidatedLearning(projectRoot: string, candidate: unknown, options?: ConsolidatedLearningOptions): Promise<string>;
 export { parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
 export { validateLearningEntry } from "./learnings-entry.js";
 //# sourceMappingURL=learnings-writer.d.ts.map

package/dist/core/learnings-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learnings-writer.d.ts","sourceRoot":"","sources":["../../src/core/learnings-writer.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"learnings-writer.d.ts","sourceRoot":"","sources":["../../src/core/learnings-writer.ts"],"names":[],"mappings":"AAsBA,gFAAgF;AAChF,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/core/learnings-writer.js

@@ -9,25 +9,44 @@ import { withLearningTargetLock } from "./learnings-lock.js";
 import { readProjectConfig, resolveProjectLearningsFile, } from "./project-config.js";
 /**
  * Persist one already-selected learning without generating or truncating it.
+ * Append-only: a duplicate id always throws. Kept as the stable back-compat
+ * entry point; consolidation-aware writers use
+ * {@link persistConsolidatedLearning} instead.
  * @param projectRoot - Absolute path to the host project root
  * @param candidate - Untrusted seven-field learning entry
  * @returns Absolute path to the persisted learnings file
  */
 export async function persistLearningEntry(projectRoot, candidate) {
+    return persistConsolidatedLearning(projectRoot, candidate);
+}
+/**
+ * Persist one learning with mandatory write-time consolidation semantics:
+ * entries named in `supersede` are dropped from the document in the same
+ * atomic write that adds the new entry, so a related existing entry is merged
+ * or replaced instead of gaining a near-duplicate sibling. The rendered
+ * document is re-validated against the shared entry and file budgets after
+ * consolidation. Without `supersede` this is exactly the append-only
+ * {@link persistLearningEntry} behavior, including the duplicate-id throw.
+ * @param projectRoot - Absolute path to the host project root
+ * @param candidate - Untrusted seven-field learning entry
+ * @param options - Optional consolidation directives
+ * @returns Absolute path to the persisted learnings file
+ */
+export async function persistConsolidatedLearning(projectRoot, candidate, options = {}) {
     const entry = validateLearningEntry(candidate);
-    const initialDocument = buildNextDocument([], entry);
+    const supersede = validateSupersedeIds(options.supersede);
     const config = await readProjectConfig(projectRoot);
     const relativeFile = resolveProjectLearningsFile(config);
     const { root, target } = resolveSafeLearningTarget(projectRoot, relativeFile);
+    // Fast budget fail on the lone entry before any directory is created.
+    buildNextDocument([], entry, []);
     await assertSafeLearningParents(root, path.dirname(target));
     await fse.ensureDir(path.dirname(target));
     return withLearningTargetLock(target, async () => {
         await assertSafeLearningParents(root, path.dirname(target));
         const existing = await readExistingLearnings(target);
         const entries = existing === undefined ? [] : parseLearningsFile(existing);
-        const rendered = existing === undefined
-            ? initialDocument
-            : buildNextDocument(entries, entry);
+        const rendered = buildNextDocument(entries, entry, supersede);
         const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${crypto.randomUUID()}.tmp`);
         try {
             await writeFile(temporary, rendered, { encoding: "utf8", flag: "wx" });
@@ -43,18 +62,42 @@ export async function persistLearningEntry(projectRoot, candidate) {
 export { parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
 export { validateLearningEntry } from "./learnings-entry.js";
 /**
- * Build and budget-check the next canonical document.
+ * Build and budget-check the next canonical document, dropping superseded
+ * entries before the new entry is added so consolidation and the budget
+ * re-assertion happen in one deterministic step.
  * @param entries - Existing validated entries
  * @param entry - New validated entry
+ * @param supersede - Ids of existing entries the new entry replaces
  * @returns Next canonical document
  */
-function buildNextDocument(entries, entry) {
-    if (entries.some(current => current.id === entry.id)) {
+function buildNextDocument(entries, entry, supersede) {
+    const missing = supersede.filter(id => !entries.some(current => current.id === id));
+    if (missing.length > 0) {
+        throw new Error(`Cannot supersede unknown learning id(s): ${missing.join(", ")}`);
+    }
+    const supersededIds = new Set(supersede);
+    const retained = entries.filter(current => !supersededIds.has(current.id));
+    if (retained.some(current => current.id === entry.id)) {
         throw new Error(`Duplicate learning id: ${entry.id}`);
     }
-    const nextEntries = [...entries, entry].sort((left, right) => left.id.localeCompare(right.id));
+    const nextEntries = [...retained, entry].sort((left, right) => left.id.localeCompare(right.id));
     const rendered = renderLearningsFile(nextEntries);
     assertDocumentBudget(rendered, nextEntries.length, "Learnings file");
     return rendered;
 }
+/**
+ * Reject malformed supersede directives before any filesystem work.
+ * @param supersede - Caller-supplied (possibly untrusted) supersede ids
+ * @returns Deduplicated list of validated supersede ids
+ */
+function validateSupersedeIds(supersede) {
+    if (supersede === undefined) {
+        return [];
+    }
+    if (!Array.isArray(supersede) ||
+        supersede.some(id => typeof id !== "string" || id.trim() === "")) {
+        throw new Error("Invalid supersede option: expected non-empty learning id strings");
+    }
+    return [...new Set(supersede)];
+}
 //# sourceMappingURL=learnings-writer.js.map