@codyswann/lisa 2.298.0 → 2.299.0

package/plugins/lisa-copilot/hooks/parity-safety-net-heredoc.py

@@ -1,5 +1,64 @@
 #!/usr/bin/env python3
-"""Classify the only heredoc forms whose payload is non-executable text."""
+"""Classify the only heredoc forms whose payload is non-executable text.
+
+SCOPE — read this before hardening anything here (issue #1993).
+
+This module is a HEURISTIC RE-IMPLEMENTATION of bash's here-doc lexing, not an
+adversary-resistant control. Every divergence between this Python model and real
+bash is, by construction, a potential mis-classification, and five rounds of
+fix-then-re-attack on issue #1958 plus three more here (#1993) established that
+enumerating those divergences is an open-ended arms race. Treat the class as
+CLOSED: a newly found member is documented, not chased, unless someone first
+demonstrates it defeats the CONTENT GUARDS, which are the layer that matters.
+
+The one hard guarantee, and the reason a mis-classification is survivable:
+
+    Exit SAFE(0) is the ONLY path that strips payload text, and it requires the
+    narrow, fully-quoted `gh issue|pr create/edit/comment` + `<<'EOF'` grammar in
+    ``classify_safe``. EVERY other path — UNSUPPORTED(10) and MALFORMED(20) —
+    hands the RAW, unmodified command to the content guards. So a here-doc the
+    classifier mis-reads degrades to the guards; it does not bypass them. Any
+    change here must preserve that property: widen ``classify_safe`` only with
+    proof, and keep every other exit raw-pass-through.
+
+Known accepted bypass class (measured, deliberately not chased further):
+R5a — a trailing backslash on the last body line is a bash continuation that
+swallows the terminator; R5b — an odd apostrophe in an unquoted body poisons a
+flat quote scanner past the terminator; R5c — `<<\\DELIM` is a quoted delimiter
+this parser did not model. All three are FIXED below, but they are members of a
+family, not the family itself. Each requires deliberately-crafted input; none is
+a shape an agent emits by accident; and post-#1982 every destructive class the
+safety net exists to stop is independently blocked by the content guards on the
+raw text.
+
+The two bash invariants this file relies on — both measured directly against
+/bin/bash, not inferred — so a future round starts from a spec:
+
+1. UNQUOTED delimiter (`<<EOF`): the body performs NO quote or comment
+   processing (`'`, `"`, `#` are literal data bytes) but STILL expands `$(...)`,
+   backticks and parameters, and bash removes `\\<newline>` continuations BEFORE
+   matching the delimiter. Measured: `cat <<EOF` / `foo\\` / `EOF` / `bar` emits
+   `fooEOF\\nbar` — the here-doc never terminated.
+2. QUOTED delimiter in any spelling (`<<'EOF'`, `<<"EOF"`, `<<\\EOF`): the body is
+   fully literal, no expansion of any kind, and backslash is DATA rather than an
+   escape — so the delimiter IS matched per physical line there. Measured: the
+   same trailing-backslash shape under `<<'EOF'` emits `foo\\` and then fails on
+   `bar: command not found`.
+
+That asymmetry is why the continuation handling in ``terminator_line_index`` is
+conditioned on ``Marker.quoted`` rather than applied uniformly.
+
+``Marker.quoted`` means "bash makes this BODY literal" and nothing more. The
+three spellings above are interchangeable for body semantics ONLY — they are NOT
+interchangeable on the writer path. ``classify_safe`` still demands the literal
+``<<'DELIM'`` spelling, so `<<"EOF"` and `<<\\EOF` can never reach SAFE(0); since
+#1993 they additionally record a Marker, which arms the writer-owns-a-real-marker
+and multi-marker rules and lands a `gh … <<\\EOF` writer on MALFORMED(20) where it
+used to be UNSUPPORTED(10). That is a deliberate, test-pinned over-block: the
+documented payload-strip workaround is spelled `<<'EOF'`. Widening
+``classify_safe`` to admit other spellings is a separate change needing its own
+proof — do not do it as a side effect of body-semantics work.
+"""
 
 from __future__ import annotations
 
@@ -494,6 +553,105 @@ def collapse_body_continuations(body: str) -> str:
     return "".join(result)
 
 
+def trailing_continuation(line: str) -> str | None:
+    """Strip a bash ``\\<newline>`` continuation backslash, or ``None``.
+
+    A here-doc body line ends in a continuation exactly when it ends in an ODD
+    run of backslashes: each pair is one escaped literal backslash, so a leftover
+    single backslash is the one that escapes the following newline. Parity of the
+    TRAILING run is sufficient — any backslash earlier in the line is separated
+    from the run by a non-backslash byte, which ends that escape.
+    """
+    stripped = line.rstrip("\\")
+    if (len(line) - len(stripped)) % 2 == 0:
+        return None
+    return line[:-1]
+
+
+def terminator_line_index(command: str, marker: Marker) -> int | None:
+    """Index of the physical line that closes ``marker``, or ``None``.
+
+    THE single home of "where does this here-doc body end", consulted by the
+    closure check, the body scanner, the literal-body strip and the body
+    neutraliser so no two of them can ever disagree about the window (issue
+    #1993 R5a).
+
+    Bash removes ``\\<newline>`` continuations from an UNQUOTED here-doc body
+    BEFORE it matches the delimiter, so a trailing backslash on the last body
+    line JOINS that line to the delimiter line and the here-doc is NOT closed
+    there — the real body swallows the apparent terminator and keeps consuming
+    following lines, where a ``$(...)`` the classifier believed was ordinary
+    post-here-doc text is expanded and EXECUTED. Matching the delimiter per
+    PHYSICAL line therefore under-reads the body window for unquoted delimiters.
+    Measured ground truth: ``cat <<EOF`` / ``foo\\`` / ``EOF`` / ``bar`` prints
+    ``fooEOF\\nbar`` (never terminated), while the same shape with ``<<'EOF'``
+    prints ``foo\\`` and then fails on ``bar: command not found``.
+
+    A QUOTED (or backslash-quoted) delimiter makes the body fully literal —
+    backslash is DATA there, not an escape — so those markers keep the exact
+    per-physical-line match, which the same measurement proves correct.
+    """
+    lines = bash_lines(command)
+    marker_line = command.count("\n", 0, marker.start)
+    pending: list[str] = []
+    for index in range(marker_line + 1, len(lines)):
+        line = lines[index]
+        if not marker.quoted:
+            continued = trailing_continuation(line)
+            if continued is not None:
+                pending.append(continued)
+                continue
+        candidate = "".join(pending) + line
+        pending = []
+        if marker.strip_tabs:
+            candidate = candidate.lstrip("\t")
+        if candidate == marker.delimiter:
+            return index
+    return None
+
+
+def neutralize_heredoc_bodies(command: str, markers: list[Marker]) -> str:
+    """Blank every real here-doc body window, preserving offsets.
+
+    ``has_active_command_substitution`` runs ONE flat single/double-quote state
+    machine across the whole command — including here-doc bodies, where bash
+    applies NO quote processing at all. An odd apostrophe in an unquoted body
+    (``it's fine``) therefore opens a phantom single-quoted string in the flat
+    scanner that persists PAST the terminator, hiding a live ``$(...)`` on a
+    FOLLOWING command line that bash happily executes (issue #1993 R5b). The
+    trigger is precisely an odd ``'`` count: an even ``''``, an odd ``"``, a
+    ``#``, an ANSI-C ``$'a`` and a lone trailing backslash all leave the flat
+    state correct, which is what pins the defect to this one branch.
+
+    ``strip_provably_literal_body`` cannot fix this: it bails whenever the marker
+    is unquoted, so the poisoning body is exactly the one it never touches. So
+    blank the body window of EVERY marker bash really treats as a here-doc
+    redirection before the flat scan runs. Bytes are replaced with spaces and
+    newlines are preserved, so marker offsets and line numbering stay valid for
+    every later walker.
+
+    Blanking loses nothing: a substitution INSIDE an unquoted body is still
+    caught by ``unquoted_heredoc_body_has_substitution`` (scanned with correct
+    here-doc-body semantics), and a quoted body is genuinely inert to bash. A
+    marker that is not closed blanks to end of command — that command is
+    MALFORMED on the closure check regardless, and its trailing region is still
+    body-scanned. As everywhere else, a marker nested inside an open quoted
+    string is NOT a here-doc to bash and is skipped, so its "body" stays fully
+    visible to the flat scan (issue #1958 Finding 1).
+    """
+    lines = bash_lines(command)
+    blanked = list(lines)
+    for marker in markers:
+        if cross_line_quote_state(command, marker.start) != "plain":
+            continue
+        marker_line = command.count("\n", 0, marker.start)
+        end = terminator_line_index(command, marker)
+        stop = len(lines) if end is None else end
+        for index in range(marker_line + 1, stop):
+            blanked[index] = " " * len(lines[index])
+    return "\n".join(blanked)
+
+
 def body_line_has_substitution(line: str) -> bool:
     """True if an unquoted-heredoc-body line contains an active substitution.
 
@@ -553,22 +711,22 @@ def unquoted_heredoc_body_has_substitution(
         if cross_line_quote_state(command, marker.start) != "plain":
             continue
         marker_line = command.count("\n", 0, marker.start)
-        body_lines: list[str] = []
-        for index in range(marker_line + 1, len(lines)):
-            candidate = (
-                lines[index].lstrip("\t") if marker.strip_tabs else lines[index]
-            )
-            if candidate == marker.delimiter:
-                break
-            body_lines.append(lines[index])
+        end = terminator_line_index(command, marker)
+        stop = len(lines) if end is None else end
+        body_lines = lines[marker_line + 1 : stop]
         # Join the raw body window under bash's unquoted-here-doc ``\<newline>``
         # removal BEFORE scanning, so a ``$(`` a caller split across a line
         # continuation is seen as the one contiguous token bash executes. The
-        # terminator was matched per physical line above (bash matches the
-        # delimiter before continuation processing), so continuations are joined
-        # only WITHIN the body window, never across the delimiter. This does not
-        # rely on ``collapse_line_continuations`` — whose flat quote state a body
-        # apostrophe corrupts — which is the whole point of Finding R4.
+        # window itself comes from ``terminator_line_index``, which applies that
+        # SAME removal before matching the delimiter — because bash does (issue
+        # #1993 R5a). An earlier revision matched the terminator per physical
+        # line here on the belief that bash matches the delimiter before
+        # continuation processing; that is false for an unquoted delimiter, and
+        # it let a trailing backslash on the last body line swallow the
+        # terminator so this scan stopped short of the region bash still treats
+        # as body. This does not rely on ``collapse_line_continuations`` — whose
+        # flat quote state a body apostrophe corrupts — which is the whole point
+        # of Finding R4.
         body = collapse_body_continuations("\n".join(body_lines))
         if body_line_has_substitution(body):
             return True
@@ -595,16 +753,42 @@ def parse_marker(line: str, start: int, offset: int) -> Marker | None:
         delimiter = line[index:end]
         final = end + 1
         # Deliberate POSIX divergence, fail-safe: POSIX makes the body
-        # non-expanding when ANY part of the delimiter is quoted — including
-        # `<<\EOF` (invisible to this parser: backslash is not a quote char and
-        # the identifier regex rejects it, so no Marker is recorded and the
-        # body stays raw-visible to every guard) and partial forms like
-        # `<<EO'F'` (mis-tokenized as delimiter EO, so the terminator never
-        # matches and the command fails closed as MALFORMED). Only a delimiter
-        # this parser can PROVE was one full quote pair earns quoted=True, and
-        # trailing word characters after the closing quote (`<<'EOF'X` — real
-        # bash delimiter EOFX) keep it conservative too: the next character
-        # must end the token.
+        # non-expanding when ANY part of the delimiter is quoted. Partial forms
+        # like `<<EO'F'` stay unmodelled (mis-tokenized as delimiter EO, so the
+        # terminator never matches and the command fails closed as MALFORMED).
+        # Only a delimiter this parser can PROVE was one full quote pair earns
+        # quoted=True, and trailing word characters after the closing quote
+        # (`<<'EOF'X` — real bash delimiter EOFX) keep it conservative too: the
+        # next character must end the token.
+        quoted = final >= len(line) or line[final] in " \t;&|)<>#"
+    elif line[index] == "\\":
+        # `<<\DELIM` is a BACKSLASH-quoted delimiter: bash and POSIX make its
+        # body fully literal, exactly like `<<'DELIM'` (measured: `cat <<\EOF`
+        # with body `it's $(echo RAN)` prints that text verbatim, unexpanded).
+        # This spelling used to record NO Marker at all, on the rationale that an
+        # unmodelled body stays raw-visible to every content guard. That covers
+        # the body's own contents but NOT the body's ability to corrupt the flat
+        # scanner's quote state for text AFTER the terminator: an apostrophe in
+        # an invisible body still opened a phantom string that hid a live
+        # `$(...)` on a following line (issue #1993 R5c). Recording it as the
+        # quoted marker bash actually treats it as is both more faithful and
+        # what brings it under `neutralize_heredoc_bodies`. The same
+        # token-must-end discipline as the quote-pair branch applies, so exotic
+        # spellings (`<<\EOF'x'` — real bash delimiter EOFx) stay conservative.
+        # quoted=True here is a statement about BODY semantics only. Recording a
+        # Marker where there was none also arms the writer-owns-a-real-marker and
+        # multi-marker rules, so `gh issue create --body-file - <<\EOF` and
+        # `cat <<\A <<B` now fail closed at MALFORMED instead of passing through
+        # at UNSUPPORTED. Both are valid, harmless bash, so that is a real
+        # over-block — accepted and test-pinned, because `classify_safe` requires
+        # the literal `<<'DELIM'` spelling and `<<\EOF` can never reach SAFE
+        # anyway. The documented payload-strip workaround is `<<'EOF'`.
+        index += 1
+        match = re.match(r"[A-Za-z_][A-Za-z0-9_]*", line[index:])
+        if match is None:
+            return None
+        delimiter = match.group(0)
+        final = index + len(delimiter)
         quoted = final >= len(line) or line[final] in " \t;&|)<>#"
     else:
         match = re.match(r"[A-Za-z_][A-Za-z0-9_]*", line[index:])
@@ -698,21 +882,22 @@ def strip_provably_literal_body(command: str, markers: list[Marker]) -> str:
         return command
     lines = bash_lines(command)
     marker_line = command.count("\n", 0, marker.start)
-    for index in range(marker_line + 1, len(lines)):
-        candidate = lines[index].lstrip("\t") if marker.strip_tabs else lines[index]
-        if candidate == marker.delimiter:
-            return "\n".join(lines[: marker_line + 1] + lines[index:])
-    return command
+    end = terminator_line_index(command, marker)
+    if end is None:
+        return command
+    return "\n".join(lines[: marker_line + 1] + lines[end:])
 
 
 def marker_is_closed(command: str, marker: Marker) -> bool:
-    marker_line = command.count("\n", 0, marker.start)
-    lines = bash_lines(command)
-    for line in lines[marker_line + 1 :]:
-        candidate = line.lstrip("\t") if marker.strip_tabs else line
-        if candidate == marker.delimiter:
-            return True
-    return False
+    """True when bash really terminates this here-doc inside the command.
+
+    Delegates to ``terminator_line_index`` so the closure verdict and the body
+    window are decided by one rule. For an unquoted delimiter that rule removes
+    ``\\<newline>`` continuations first, so a trailing backslash on the last body
+    line correctly reads as NOT closed — which is what bash does, and what makes
+    the swallowed-terminator shape fail closed as MALFORMED (issue #1993 R5a).
+    """
+    return terminator_line_index(command, marker) is not None
 
 
 def main() -> int:
@@ -748,11 +933,18 @@ def main() -> int:
         return MALFORMED
 
     # Nested substitution plus a heredoc is executable shell syntax unless it
-    # matched the one exact quoted `--body "$(cat ...)"` form above. The body
-    # of a single provably-literal heredoc is excluded from this scan (its
-    # tokens are inert data); the text outside that window is still scanned.
+    # matched the one exact quoted `--body "$(cat ...)"` form above. Here-doc
+    # bodies are neutralised before the flat scan: bash applies NO quote
+    # processing inside a body, so leaving those bytes in a flat quote state
+    # machine let an odd body apostrophe poison the scanner PAST the terminator
+    # and hide a live substitution on a following command line (issue #1993
+    # R5b). Neutralising preserves offsets, so the narrower literal-body strip
+    # still applies on top; the text outside every body window is still scanned,
+    # and in-body substitutions are covered by the body-semantics scan below.
     if has_active_command_substitution(
-        strip_provably_literal_body(logical_command, markers)
+        strip_provably_literal_body(
+            neutralize_heredoc_bodies(logical_command, markers), markers
+        )
     ) or unquoted_heredoc_body_has_substitution(logical_command, markers):
         return MALFORMED
     if len(markers) > 1:

package/plugins/lisa-copilot/hooks/parity-safety-net.sh

@@ -54,7 +54,27 @@
 # would never expand — a single-quoted `echo '$(rm -rf /)'` or an escaped
 # `echo "\$(rm -rf /)"` — because the scan has no quote-context awareness. That
 # over-block stays inside this accepted class. Workaround: quote-break the string
-# or use the gh-writer heredoc form, whose payload is stripped before the guards run.
+# or use the gh-writer heredoc form, whose payload is stripped before the guards
+# run — spelled with a QUOTE-PAIR delimiter (`<<'EOF'`). That exact spelling is
+# what the SAFE path recognises; `<<"EOF"` and `<<\EOF` do not reach it, and
+# since #1993 a `gh … <<\EOF` writer fails closed instead (see parse_marker).
+#
+# Known accepted BYPASS class (the symmetric error direction, issue #1993): the
+# heredoc classifier in parity-safety-net-heredoc.py re-implements bash's
+# here-doc lexing in Python, and any divergence from real bash is a shape it
+# mis-classifies. Five rounds on #1958 and three more on #1993 (R5a swallowed
+# terminator, R5b body-apostrophe quote-state poisoning, R5c backslash-quoted
+# delimiter) established that enumerating those divergences is an open-ended
+# arms race, so the class is CLOSED as accepted rather than chased further. This
+# is survivable because of where a mis-classification lands: ONLY the narrow
+# gh-writer SAFE path strips payload text, and every other classifier exit hands
+# the RAW command to the guards below. A missed here-doc therefore degrades to
+# the content guards; it does not bypass them. Since #1982 taught those guards to
+# see through substitution wrappers, every destructive class this net exists to
+# stop is blocked on the raw text regardless of how the here-doc was read. The
+# net catches ACCIDENTAL catastrophic commands; it is not a wall against an
+# adversary who knows bash's lexer, and it was never the only thing standing
+# between an agent and arbitrary execution.
 #
 # Operators extend the built-in rules with a project-local rule file — one
 # extended-regex (ERE) per line, blank lines and `#` comments ignored — managed

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-parity-safety-net-rules/SKILL.md

@@ -103,7 +103,44 @@ same reason the rm guard treats substitution-wrapping as verdict-neutral (issue
 #1982): an executable `echo "$(rm -rf /)"` is blocked, and so are inert twins the
 shell would never expand — a single-quoted `echo '$(rm -rf /)'` or an escaped
 `echo "\$(rm -rf /)"` — since the scan has no quote-context awareness. The same
-quote-break or heredoc workaround applies.
+quote-break or heredoc workaround applies. Spell that heredoc workaround with a
+**quote-pair** delimiter (`gh issue create --body-file - <<'EOF'`) — only that
+spelling reaches the payload-strip path. `<<"EOF"` and `<<\EOF` do not, and a
+`gh … <<\EOF` writer now fails closed instead.
+
+## What this does and does not defend against
+
+Read this before treating the safety net as a wall.
+
+**What it is for:** stopping *accidental* catastrophic commands — an agent (or a
+human) that reaches for `rm -rf /`, force-pushes `main`, drops a table, or writes
+to a raw device by mistake. Within that job the guards above are the floor and
+they are always on.
+
+**What it is not:** a security boundary against a deliberate adversary. Two
+structural reasons, both accepted rather than open bugs:
+
+- **It is a text scan, not a shell engine.** It has no quote-context awareness,
+  which produces the false positives described above and means an operation
+  spelled in a way the patterns do not anticipate is not matched.
+- **The here-doc classifier re-implements bash's lexer in Python** to decide
+  which payload text is inert data. Every divergence from real bash is a shape it
+  mis-classifies. Eight distinct divergences were found and fixed across issues
+  #1958 and #1993; the class is open-ended, so it is now closed as an accepted
+  limitation rather than chased indefinitely.
+
+**Why that is tolerable:** a here-doc mis-classification degrades to the content
+guards rather than bypassing them. Only the narrow `gh issue|pr` writer form ever
+strips payload text; every other path passes the **raw** command to the guards,
+and since issue #1982 those guards see through substitution wrappers. So a
+mis-read here-doc costs no guard coverage for any destructive class listed above.
+
+**The honest bottom line:** an agent that is actively trying to run something
+destructive has many paths that never involve a here-doc at all — the safety net
+does not claim to close them. Do not rely on it as the only control over what an
+agent may execute; treat it as the last line of defence against mistakes, and
+keep the real boundary (credentials, permissions, environment isolation) outside
+the agent.
 
 ## View the current rules
 

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.0",
+  "version": "2.299.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"