@codyswann/lisa 2.298.1 → 2.299.0

package/package.json

@@ -115,7 +115,7 @@
     "brace-expansion": ">=5.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-learnings-audit/SKILL.md

@@ -40,17 +40,25 @@ memorized list:
    exemption from projection-only serving) plus `projectLearnings` for the
    bounded projection (to measure **budget pressure**: how many entries the
    projection omits). Never hand-parse or hand-edit the raw file.
-2. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
+2. **The overflow buffer** — captures the ledger had no budget to accept, held
+   in `PROJECT_LEARNINGS.overflow.md` beside the resolved ledger. Read it ONLY
+   through the executable contract: `bunx @codyswann/lisa learnings-overflow`,
+   which prints `{ file, pending, entries }` as JSON. Never hand-parse or
+   hand-edit it. These are judged-durable learnings with nowhere to live, so a
+   non-empty overflow is the single strongest budget-pressure evidence there is
+   — stronger than an omission count, because room was not merely tight, a real
+   capture was turned away. Drain it every run (see The audit cycle).
+3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
    the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
    human-authored only — its existing sections are still audit candidates;
    first-run candidates come from exactly there).
-3. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
+4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
-4. **The wiki index** — `wiki/index.md` when the project has a wiki.
-5. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
+5. **The wiki index** — `wiki/index.md` when the project has a wiki.
+6. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
    rules, git hooks, test suites, and `package.lisa.json` force sections:
    the surfaces that answer "does a mechanical owner already exist?".
-6. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
+7. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
    are its memory; see Idempotency.
 
 ## Candidate-selection rules
@@ -64,7 +72,7 @@ Gather, per item, the five evidence axes:
 | **Staleness** | Does the item reference files, flags, versions, or tools that no longer exist? | Glob/Grep the referenced paths and configs. |
 | **Redundancy** | Does a mechanical owner already enforce the invariant? (The double-payment hunter.) | Check lint/ast-grep/hook/test/force surfaces for the same invariant. |
 | **Contradiction** | Does the item contradict another rule, skill, config, or observed current behavior? | Cross-reference the inventoried surfaces. |
-| **Budget pressure** | Is the ledger projection omitting entries, or the eager tier growing? | `projectLearnings` omission count; eager-tree token/size trend. |
+| **Budget pressure** | Is the ledger projection omitting entries, captures landing in the overflow, or the eager tier growing? | `projectLearnings` omission count; `learnings-overflow` pending count; eager-tree token/size trend. |
 
 Selection outcomes per candidate: **PROMOTE** (up the ladder), **DEMOTE**
 (down the ladder), **CONFIRM** (evidence the entry demonstrably applied —
@@ -117,6 +125,34 @@ audits the auditor without re-running it.
 ## The audit cycle
 
 1. **Inventory** the sources of truth above.
+1.5. **Drain the overflow** — before anything else, because these captures are
+   the only knowledge in the system with no durable home at all. For each entry
+   `bunx @codyswann/lisa learnings-overflow` reports:
+
+   - **File its durable home first.** Route the entry through the ladder router
+     like any other candidate and file the resulting ticket, carrying the
+     entry's `rule`, `why`, `provenance`, and `confidence` verbatim so nothing
+     is paraphrased away. Use the ordinary `[lisa-gardener]` marker dedupe, so a
+     re-run never files the same overflowed capture twice.
+   - **Drain it only after that ticket exists**, one call naming exactly the ids
+     that now have a home:
+
+     ```bash
+     bunx @codyswann/lisa learnings-overflow --drain <id> [<id>...]
+     ```
+
+     Never drain first and file second, and never drain ids in bulk "to clean
+     up": the buffer is the only copy, so an entry removed before its ticket
+     exists is gone. Filing first makes a partial run — a rate limit, a network
+     failure — safely resumable, because everything unfiled is still in the
+     buffer for the next run. An id the command reports as `absent` was already
+     drained by an earlier run; that is expected, not an error.
+   - **Report the drain in the run proof**: how many were pending, which ids
+     were re-homed to which tickets, and how many remain.
+
+   A non-empty overflow also means the ledger turned a judged-durable capture
+   away, so treat it as top-priority budget-pressure evidence when selecting
+   RETIRE/PROMOTE candidates this run — the room has to come from somewhere.
 2. **Evidence** — gather the five axes per item; drop items with none.
 3. **Classify** — pass each candidate (`rule`, `why`, `provenance`,
    `evidence`) to the ladder router (the `skill-evaluator` agent). The router

package/plugins/lisa/.codex-plugin/skills/lisa-persist-learning/SKILL.md

@@ -187,8 +187,13 @@ No learning content is ever committed without a PR — there is no other write p
      Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
      ```
 
-     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The candidate itself is still dropped; this signal records the saturation, it does not persist the rule.
-4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The signal records the saturation; it does not persist the rule.
+   - **The dropped capture is preserved for you — ship it.** The writer does this itself, so there is nothing to compose by hand: when the budget re-assertion fails, `persistConsolidatedLearning` / `persistLearningEntry` write the rejected entry to the **overflow buffer** — `PROJECT_LEARNINGS.overflow.md`, a sibling of the resolved ledger — and then re-raise a budget error naming that file. The thrown error is the confirmation; if it does not name the overflow, the capture was NOT preserved (the overflow is full too) and that is what the error says instead.
+
+     The overflow is git-tracked and bound to the same union merge driver as the ledger, so **still open the pull request on a budget-forced drop** — carrying the overflow file instead of the ledger. That is the whole point of preserving it: a capture that reaches only a disposable `learning/<fingerprint>` worktree is durable in name only, and the gardener draining `main` would never see it. Never hand-edit the overflow, and never delete an entry from it to make room; the gardener drains it.
+
+     So a budget-forced drop produces **both** halves and neither substitutes for the other: the `[lisa-ledger-saturated]` ticket (the signal that room must be reclaimed) and a pull request carrying the overflow file (the content itself). Report both in the run summary.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings surface — the ledger, or the overflow buffer on a budget-forced drop; verify with `git diff --name-only` that the diff touches nothing else.
 5. **PR body.** Exactly one marker line plus the reviewable story:
 
    ```markdown

package/plugins/lisa/skills/lisa-learnings-audit/SKILL.md

@@ -40,17 +40,25 @@ memorized list:
    exemption from projection-only serving) plus `projectLearnings` for the
    bounded projection (to measure **budget pressure**: how many entries the
    projection omits). Never hand-parse or hand-edit the raw file.
-2. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
+2. **The overflow buffer** — captures the ledger had no budget to accept, held
+   in `PROJECT_LEARNINGS.overflow.md` beside the resolved ledger. Read it ONLY
+   through the executable contract: `bunx @codyswann/lisa learnings-overflow`,
+   which prints `{ file, pending, entries }` as JSON. Never hand-parse or
+   hand-edit it. These are judged-durable learnings with nowhere to live, so a
+   non-empty overflow is the single strongest budget-pressure evidence there is
+   — stronger than an omission count, because room was not merely tight, a real
+   capture was turned away. Drain it every run (see The audit cycle).
+3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
    the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
    human-authored only — its existing sections are still audit candidates;
    first-run candidates come from exactly there).
-3. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
+4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
-4. **The wiki index** — `wiki/index.md` when the project has a wiki.
-5. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
+5. **The wiki index** — `wiki/index.md` when the project has a wiki.
+6. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
    rules, git hooks, test suites, and `package.lisa.json` force sections:
    the surfaces that answer "does a mechanical owner already exist?".
-6. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
+7. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
    are its memory; see Idempotency.
 
 ## Candidate-selection rules
@@ -64,7 +72,7 @@ Gather, per item, the five evidence axes:
 | **Staleness** | Does the item reference files, flags, versions, or tools that no longer exist? | Glob/Grep the referenced paths and configs. |
 | **Redundancy** | Does a mechanical owner already enforce the invariant? (The double-payment hunter.) | Check lint/ast-grep/hook/test/force surfaces for the same invariant. |
 | **Contradiction** | Does the item contradict another rule, skill, config, or observed current behavior? | Cross-reference the inventoried surfaces. |
-| **Budget pressure** | Is the ledger projection omitting entries, or the eager tier growing? | `projectLearnings` omission count; eager-tree token/size trend. |
+| **Budget pressure** | Is the ledger projection omitting entries, captures landing in the overflow, or the eager tier growing? | `projectLearnings` omission count; `learnings-overflow` pending count; eager-tree token/size trend. |
 
 Selection outcomes per candidate: **PROMOTE** (up the ladder), **DEMOTE**
 (down the ladder), **CONFIRM** (evidence the entry demonstrably applied —
@@ -117,6 +125,34 @@ audits the auditor without re-running it.
 ## The audit cycle
 
 1. **Inventory** the sources of truth above.
+1.5. **Drain the overflow** — before anything else, because these captures are
+   the only knowledge in the system with no durable home at all. For each entry
+   `bunx @codyswann/lisa learnings-overflow` reports:
+
+   - **File its durable home first.** Route the entry through the ladder router
+     like any other candidate and file the resulting ticket, carrying the
+     entry's `rule`, `why`, `provenance`, and `confidence` verbatim so nothing
+     is paraphrased away. Use the ordinary `[lisa-gardener]` marker dedupe, so a
+     re-run never files the same overflowed capture twice.
+   - **Drain it only after that ticket exists**, one call naming exactly the ids
+     that now have a home:
+
+     ```bash
+     bunx @codyswann/lisa learnings-overflow --drain <id> [<id>...]
+     ```
+
+     Never drain first and file second, and never drain ids in bulk "to clean
+     up": the buffer is the only copy, so an entry removed before its ticket
+     exists is gone. Filing first makes a partial run — a rate limit, a network
+     failure — safely resumable, because everything unfiled is still in the
+     buffer for the next run. An id the command reports as `absent` was already
+     drained by an earlier run; that is expected, not an error.
+   - **Report the drain in the run proof**: how many were pending, which ids
+     were re-homed to which tickets, and how many remain.
+
+   A non-empty overflow also means the ledger turned a judged-durable capture
+   away, so treat it as top-priority budget-pressure evidence when selecting
+   RETIRE/PROMOTE candidates this run — the room has to come from somewhere.
 2. **Evidence** — gather the five axes per item; drop items with none.
 3. **Classify** — pass each candidate (`rule`, `why`, `provenance`,
    `evidence`) to the ladder router (the `skill-evaluator` agent). The router

package/plugins/lisa/skills/lisa-persist-learning/SKILL.md

@@ -187,8 +187,13 @@ No learning content is ever committed without a PR — there is no other write p
      Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
      ```
 
-     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The candidate itself is still dropped; this signal records the saturation, it does not persist the rule.
-4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The signal records the saturation; it does not persist the rule.
+   - **The dropped capture is preserved for you — ship it.** The writer does this itself, so there is nothing to compose by hand: when the budget re-assertion fails, `persistConsolidatedLearning` / `persistLearningEntry` write the rejected entry to the **overflow buffer** — `PROJECT_LEARNINGS.overflow.md`, a sibling of the resolved ledger — and then re-raise a budget error naming that file. The thrown error is the confirmation; if it does not name the overflow, the capture was NOT preserved (the overflow is full too) and that is what the error says instead.
+
+     The overflow is git-tracked and bound to the same union merge driver as the ledger, so **still open the pull request on a budget-forced drop** — carrying the overflow file instead of the ledger. That is the whole point of preserving it: a capture that reaches only a disposable `learning/<fingerprint>` worktree is durable in name only, and the gardener draining `main` would never see it. Never hand-edit the overflow, and never delete an entry from it to make room; the gardener drains it.
+
+     So a budget-forced drop produces **both** halves and neither substitutes for the other: the `[lisa-ledger-saturated]` ticket (the signal that room must be reclaimed) and a pull request carrying the overflow file (the content itself). Report both in the run summary.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings surface — the ledger, or the overflow buffer on a budget-forced drop; verify with `git diff --name-only` that the diff touches nothing else.
 5. **PR body.** Exactly one marker line plus the reviewable story:
 
    ```markdown

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-learnings-audit/SKILL.md

@@ -40,17 +40,25 @@ memorized list:
    exemption from projection-only serving) plus `projectLearnings` for the
    bounded projection (to measure **budget pressure**: how many entries the
    projection omits). Never hand-parse or hand-edit the raw file.
-2. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
+2. **The overflow buffer** — captures the ledger had no budget to accept, held
+   in `PROJECT_LEARNINGS.overflow.md` beside the resolved ledger. Read it ONLY
+   through the executable contract: `bunx @codyswann/lisa learnings-overflow`,
+   which prints `{ file, pending, entries }` as JSON. Never hand-parse or
+   hand-edit it. These are judged-durable learnings with nowhere to live, so a
+   non-empty overflow is the single strongest budget-pressure evidence there is
+   — stronger than an omission count, because room was not merely tight, a real
+   capture was turned away. Drain it every run (see The audit cycle).
+3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
    the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
    human-authored only — its existing sections are still audit candidates;
    first-run candidates come from exactly there).
-3. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
+4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
-4. **The wiki index** — `wiki/index.md` when the project has a wiki.
-5. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
+5. **The wiki index** — `wiki/index.md` when the project has a wiki.
+6. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
    rules, git hooks, test suites, and `package.lisa.json` force sections:
    the surfaces that answer "does a mechanical owner already exist?".
-6. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
+7. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
    are its memory; see Idempotency.
 
 ## Candidate-selection rules
@@ -64,7 +72,7 @@ Gather, per item, the five evidence axes:
 | **Staleness** | Does the item reference files, flags, versions, or tools that no longer exist? | Glob/Grep the referenced paths and configs. |
 | **Redundancy** | Does a mechanical owner already enforce the invariant? (The double-payment hunter.) | Check lint/ast-grep/hook/test/force surfaces for the same invariant. |
 | **Contradiction** | Does the item contradict another rule, skill, config, or observed current behavior? | Cross-reference the inventoried surfaces. |
-| **Budget pressure** | Is the ledger projection omitting entries, or the eager tier growing? | `projectLearnings` omission count; eager-tree token/size trend. |
+| **Budget pressure** | Is the ledger projection omitting entries, captures landing in the overflow, or the eager tier growing? | `projectLearnings` omission count; `learnings-overflow` pending count; eager-tree token/size trend. |
 
 Selection outcomes per candidate: **PROMOTE** (up the ladder), **DEMOTE**
 (down the ladder), **CONFIRM** (evidence the entry demonstrably applied —
@@ -117,6 +125,34 @@ audits the auditor without re-running it.
 ## The audit cycle
 
 1. **Inventory** the sources of truth above.
+1.5. **Drain the overflow** — before anything else, because these captures are
+   the only knowledge in the system with no durable home at all. For each entry
+   `bunx @codyswann/lisa learnings-overflow` reports:
+
+   - **File its durable home first.** Route the entry through the ladder router
+     like any other candidate and file the resulting ticket, carrying the
+     entry's `rule`, `why`, `provenance`, and `confidence` verbatim so nothing
+     is paraphrased away. Use the ordinary `[lisa-gardener]` marker dedupe, so a
+     re-run never files the same overflowed capture twice.
+   - **Drain it only after that ticket exists**, one call naming exactly the ids
+     that now have a home:
+
+     ```bash
+     bunx @codyswann/lisa learnings-overflow --drain <id> [<id>...]
+     ```
+
+     Never drain first and file second, and never drain ids in bulk "to clean
+     up": the buffer is the only copy, so an entry removed before its ticket
+     exists is gone. Filing first makes a partial run — a rate limit, a network
+     failure — safely resumable, because everything unfiled is still in the
+     buffer for the next run. An id the command reports as `absent` was already
+     drained by an earlier run; that is expected, not an error.
+   - **Report the drain in the run proof**: how many were pending, which ids
+     were re-homed to which tickets, and how many remain.
+
+   A non-empty overflow also means the ledger turned a judged-durable capture
+   away, so treat it as top-priority budget-pressure evidence when selecting
+   RETIRE/PROMOTE candidates this run — the room has to come from somewhere.
 2. **Evidence** — gather the five axes per item; drop items with none.
 3. **Classify** — pass each candidate (`rule`, `why`, `provenance`,
    `evidence`) to the ladder router (the `skill-evaluator` agent). The router

package/plugins/lisa-agy/skills/lisa-persist-learning/SKILL.md

@@ -187,8 +187,13 @@ No learning content is ever committed without a PR — there is no other write p
      Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
      ```
 
-     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The candidate itself is still dropped; this signal records the saturation, it does not persist the rule.
-4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The signal records the saturation; it does not persist the rule.
+   - **The dropped capture is preserved for you — ship it.** The writer does this itself, so there is nothing to compose by hand: when the budget re-assertion fails, `persistConsolidatedLearning` / `persistLearningEntry` write the rejected entry to the **overflow buffer** — `PROJECT_LEARNINGS.overflow.md`, a sibling of the resolved ledger — and then re-raise a budget error naming that file. The thrown error is the confirmation; if it does not name the overflow, the capture was NOT preserved (the overflow is full too) and that is what the error says instead.
+
+     The overflow is git-tracked and bound to the same union merge driver as the ledger, so **still open the pull request on a budget-forced drop** — carrying the overflow file instead of the ledger. That is the whole point of preserving it: a capture that reaches only a disposable `learning/<fingerprint>` worktree is durable in name only, and the gardener draining `main` would never see it. Never hand-edit the overflow, and never delete an entry from it to make room; the gardener drains it.
+
+     So a budget-forced drop produces **both** halves and neither substitutes for the other: the `[lisa-ledger-saturated]` ticket (the signal that room must be reclaimed) and a pull request carrying the overflow file (the content itself). Report both in the run summary.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings surface — the ledger, or the overflow buffer on a budget-forced drop; verify with `git diff --name-only` that the diff touches nothing else.
 5. **PR body.** Exactly one marker line plus the reviewable story:
 
    ```markdown

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/skills/lisa-learnings-audit/SKILL.md

@@ -40,17 +40,25 @@ memorized list:
    exemption from projection-only serving) plus `projectLearnings` for the
    bounded projection (to measure **budget pressure**: how many entries the
    projection omits). Never hand-parse or hand-edit the raw file.
-2. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
+2. **The overflow buffer** — captures the ledger had no budget to accept, held
+   in `PROJECT_LEARNINGS.overflow.md` beside the resolved ledger. Read it ONLY
+   through the executable contract: `bunx @codyswann/lisa learnings-overflow`,
+   which prints `{ file, pending, entries }` as JSON. Never hand-parse or
+   hand-edit it. These are judged-durable learnings with nowhere to live, so a
+   non-empty overflow is the single strongest budget-pressure evidence there is
+   — stronger than an omission count, because room was not merely tight, a real
+   capture was turned away. Drain it every run (see The audit cycle).
+3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
    the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
    human-authored only — its existing sections are still audit candidates;
    first-run candidates come from exactly there).
-3. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
+4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
-4. **The wiki index** — `wiki/index.md` when the project has a wiki.
-5. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
+5. **The wiki index** — `wiki/index.md` when the project has a wiki.
+6. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
    rules, git hooks, test suites, and `package.lisa.json` force sections:
    the surfaces that answer "does a mechanical owner already exist?".
-6. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
+7. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
    are its memory; see Idempotency.
 
 ## Candidate-selection rules
@@ -64,7 +72,7 @@ Gather, per item, the five evidence axes:
 | **Staleness** | Does the item reference files, flags, versions, or tools that no longer exist? | Glob/Grep the referenced paths and configs. |
 | **Redundancy** | Does a mechanical owner already enforce the invariant? (The double-payment hunter.) | Check lint/ast-grep/hook/test/force surfaces for the same invariant. |
 | **Contradiction** | Does the item contradict another rule, skill, config, or observed current behavior? | Cross-reference the inventoried surfaces. |
-| **Budget pressure** | Is the ledger projection omitting entries, or the eager tier growing? | `projectLearnings` omission count; eager-tree token/size trend. |
+| **Budget pressure** | Is the ledger projection omitting entries, captures landing in the overflow, or the eager tier growing? | `projectLearnings` omission count; `learnings-overflow` pending count; eager-tree token/size trend. |
 
 Selection outcomes per candidate: **PROMOTE** (up the ladder), **DEMOTE**
 (down the ladder), **CONFIRM** (evidence the entry demonstrably applied —
@@ -117,6 +125,34 @@ audits the auditor without re-running it.
 ## The audit cycle
 
 1. **Inventory** the sources of truth above.
+1.5. **Drain the overflow** — before anything else, because these captures are
+   the only knowledge in the system with no durable home at all. For each entry
+   `bunx @codyswann/lisa learnings-overflow` reports:
+
+   - **File its durable home first.** Route the entry through the ladder router
+     like any other candidate and file the resulting ticket, carrying the
+     entry's `rule`, `why`, `provenance`, and `confidence` verbatim so nothing
+     is paraphrased away. Use the ordinary `[lisa-gardener]` marker dedupe, so a
+     re-run never files the same overflowed capture twice.
+   - **Drain it only after that ticket exists**, one call naming exactly the ids
+     that now have a home:
+
+     ```bash
+     bunx @codyswann/lisa learnings-overflow --drain <id> [<id>...]
+     ```
+
+     Never drain first and file second, and never drain ids in bulk "to clean
+     up": the buffer is the only copy, so an entry removed before its ticket
+     exists is gone. Filing first makes a partial run — a rate limit, a network
+     failure — safely resumable, because everything unfiled is still in the
+     buffer for the next run. An id the command reports as `absent` was already
+     drained by an earlier run; that is expected, not an error.
+   - **Report the drain in the run proof**: how many were pending, which ids
+     were re-homed to which tickets, and how many remain.
+
+   A non-empty overflow also means the ledger turned a judged-durable capture
+   away, so treat it as top-priority budget-pressure evidence when selecting
+   RETIRE/PROMOTE candidates this run — the room has to come from somewhere.
 2. **Evidence** — gather the five axes per item; drop items with none.
 3. **Classify** — pass each candidate (`rule`, `why`, `provenance`,
    `evidence`) to the ladder router (the `skill-evaluator` agent). The router

package/plugins/lisa-copilot/skills/lisa-persist-learning/SKILL.md

@@ -187,8 +187,13 @@ No learning content is ever committed without a PR — there is no other write p
      Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
      ```
 
-     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The candidate itself is still dropped; this signal records the saturation, it does not persist the rule.
-4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The signal records the saturation; it does not persist the rule.
+   - **The dropped capture is preserved for you — ship it.** The writer does this itself, so there is nothing to compose by hand: when the budget re-assertion fails, `persistConsolidatedLearning` / `persistLearningEntry` write the rejected entry to the **overflow buffer** — `PROJECT_LEARNINGS.overflow.md`, a sibling of the resolved ledger — and then re-raise a budget error naming that file. The thrown error is the confirmation; if it does not name the overflow, the capture was NOT preserved (the overflow is full too) and that is what the error says instead.
+
+     The overflow is git-tracked and bound to the same union merge driver as the ledger, so **still open the pull request on a budget-forced drop** — carrying the overflow file instead of the ledger. That is the whole point of preserving it: a capture that reaches only a disposable `learning/<fingerprint>` worktree is durable in name only, and the gardener draining `main` would never see it. Never hand-edit the overflow, and never delete an entry from it to make room; the gardener drains it.
+
+     So a budget-forced drop produces **both** halves and neither substitutes for the other: the `[lisa-ledger-saturated]` ticket (the signal that room must be reclaimed) and a pull request carrying the overflow file (the content itself). Report both in the run summary.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings surface — the ledger, or the overflow buffer on a budget-forced drop; verify with `git diff --name-only` that the diff touches nothing else.
 5. **PR body.** Exactly one marker line plus the reviewable story:
 
    ```markdown

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cursor/skills/lisa-learnings-audit/SKILL.md

@@ -40,17 +40,25 @@ memorized list:
    exemption from projection-only serving) plus `projectLearnings` for the
    bounded projection (to measure **budget pressure**: how many entries the
    projection omits). Never hand-parse or hand-edit the raw file.
-2. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
+2. **The overflow buffer** — captures the ledger had no budget to accept, held
+   in `PROJECT_LEARNINGS.overflow.md` beside the resolved ledger. Read it ONLY
+   through the executable contract: `bunx @codyswann/lisa learnings-overflow`,
+   which prints `{ file, pending, entries }` as JSON. Never hand-parse or
+   hand-edit it. These are judged-durable learnings with nowhere to live, so a
+   non-empty overflow is the single strongest budget-pressure evidence there is
+   — stronger than an omission count, because room was not merely tight, a real
+   capture was turned away. Drain it every run (see The audit cycle).
+3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
    the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
    human-authored only — its existing sections are still audit candidates;
    first-run candidates come from exactly there).
-3. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
+4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
-4. **The wiki index** — `wiki/index.md` when the project has a wiki.
-5. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
+5. **The wiki index** — `wiki/index.md` when the project has a wiki.
+6. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
    rules, git hooks, test suites, and `package.lisa.json` force sections:
    the surfaces that answer "does a mechanical owner already exist?".
-6. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
+7. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
    are its memory; see Idempotency.
 
 ## Candidate-selection rules
@@ -64,7 +72,7 @@ Gather, per item, the five evidence axes:
 | **Staleness** | Does the item reference files, flags, versions, or tools that no longer exist? | Glob/Grep the referenced paths and configs. |
 | **Redundancy** | Does a mechanical owner already enforce the invariant? (The double-payment hunter.) | Check lint/ast-grep/hook/test/force surfaces for the same invariant. |
 | **Contradiction** | Does the item contradict another rule, skill, config, or observed current behavior? | Cross-reference the inventoried surfaces. |
-| **Budget pressure** | Is the ledger projection omitting entries, or the eager tier growing? | `projectLearnings` omission count; eager-tree token/size trend. |
+| **Budget pressure** | Is the ledger projection omitting entries, captures landing in the overflow, or the eager tier growing? | `projectLearnings` omission count; `learnings-overflow` pending count; eager-tree token/size trend. |
 
 Selection outcomes per candidate: **PROMOTE** (up the ladder), **DEMOTE**
 (down the ladder), **CONFIRM** (evidence the entry demonstrably applied —
@@ -117,6 +125,34 @@ audits the auditor without re-running it.
 ## The audit cycle
 
 1. **Inventory** the sources of truth above.
+1.5. **Drain the overflow** — before anything else, because these captures are
+   the only knowledge in the system with no durable home at all. For each entry
+   `bunx @codyswann/lisa learnings-overflow` reports:
+
+   - **File its durable home first.** Route the entry through the ladder router
+     like any other candidate and file the resulting ticket, carrying the
+     entry's `rule`, `why`, `provenance`, and `confidence` verbatim so nothing
+     is paraphrased away. Use the ordinary `[lisa-gardener]` marker dedupe, so a
+     re-run never files the same overflowed capture twice.
+   - **Drain it only after that ticket exists**, one call naming exactly the ids
+     that now have a home:
+
+     ```bash
+     bunx @codyswann/lisa learnings-overflow --drain <id> [<id>...]
+     ```
+
+     Never drain first and file second, and never drain ids in bulk "to clean
+     up": the buffer is the only copy, so an entry removed before its ticket
+     exists is gone. Filing first makes a partial run — a rate limit, a network
+     failure — safely resumable, because everything unfiled is still in the
+     buffer for the next run. An id the command reports as `absent` was already
+     drained by an earlier run; that is expected, not an error.
+   - **Report the drain in the run proof**: how many were pending, which ids
+     were re-homed to which tickets, and how many remain.
+
+   A non-empty overflow also means the ledger turned a judged-durable capture
+   away, so treat it as top-priority budget-pressure evidence when selecting
+   RETIRE/PROMOTE candidates this run — the room has to come from somewhere.
 2. **Evidence** — gather the five axes per item; drop items with none.
 3. **Classify** — pass each candidate (`rule`, `why`, `provenance`,
    `evidence`) to the ladder router (the `skill-evaluator` agent). The router

package/plugins/lisa-cursor/skills/lisa-persist-learning/SKILL.md

@@ -187,8 +187,13 @@ No learning content is ever committed without a PR — there is no other write p
      Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
      ```
 
-     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The candidate itself is still dropped; this signal records the saturation, it does not persist the rule.
-4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The signal records the saturation; it does not persist the rule.
+   - **The dropped capture is preserved for you — ship it.** The writer does this itself, so there is nothing to compose by hand: when the budget re-assertion fails, `persistConsolidatedLearning` / `persistLearningEntry` write the rejected entry to the **overflow buffer** — `PROJECT_LEARNINGS.overflow.md`, a sibling of the resolved ledger — and then re-raise a budget error naming that file. The thrown error is the confirmation; if it does not name the overflow, the capture was NOT preserved (the overflow is full too) and that is what the error says instead.
+
+     The overflow is git-tracked and bound to the same union merge driver as the ledger, so **still open the pull request on a budget-forced drop** — carrying the overflow file instead of the ledger. That is the whole point of preserving it: a capture that reaches only a disposable `learning/<fingerprint>` worktree is durable in name only, and the gardener draining `main` would never see it. Never hand-edit the overflow, and never delete an entry from it to make room; the gardener drains it.
+
+     So a budget-forced drop produces **both** halves and neither substitutes for the other: the `[lisa-ledger-saturated]` ticket (the signal that room must be reclaimed) and a pull request carrying the overflow file (the content itself). Report both in the run summary.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings surface — the ledger, or the overflow buffer on a budget-forced drop; verify with `git diff --name-only` that the diff touches nothing else.
 5. **PR body.** Exactly one marker line plus the reviewable story:
 
    ```markdown

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.298.1",
+  "version": "2.299.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"