@codyswann/lisa 4.37.3 → 4.38.1

package/plugins/lisa/rules/reference/withdrawn-rulings.md

@@ -0,0 +1,114 @@
+# Withdrawn Rulings — reference
+
+Long-form body for the eager rule `withdrawn-rulings`. Origin: CodySwannGT/lisa#3752.
+
+## The general property
+
+A session is a snapshot. Three independent instances of it were measured on one day:
+
+1. **Plugin version.** A session executes the plugin cache directory resolved *when the session
+   started*. A session roughly eleven hours old was running one version while the default branch and
+   the marketplace clone were two releases ahead — with the newer version already sitting in that
+   cache. Not a distribution failure: updating the cache does not help a running session, only a
+   restart re-resolves. That session reported an already-fixed defect as live, persuasively, because
+   it really had observed the behaviour. It was reporting the truth about a stale binary.
+2. **Rules injection.** The rule injector reads `rules/eager/*.md` and concatenates them into
+   context at SessionStart and SubagentStart. No metadata, no expiry, no filter — a rule withdrawn
+   upstream stays in the context of every session that started before the withdrawal, for that
+   session's whole life.
+3. **Shipped versus in effect.** A fix merged to the default branch is not in effect for any session
+   already running.
+
+**A fix has two facts behind it: that it exists, and that it is in effect.** Testing either one and
+reporting "fixed" is the error. Two agents made opposite halves of that mistake in a single evening,
+neither carelessly, each holding a real measurement.
+
+## The two instances that produced this rule
+
+**A correction that was itself wrong, published.** A claim was refuted with specific file-and-line
+evidence. The refutation was propagated to two agents and into a public work-item comment before a
+third agent, reading the source directly, established that the original claim was right and the
+refutation had been produced by grepping a stale checkout. The wrong correction stood for roughly
+forty minutes. Anyone who read that item in the interval holds the wrong version and has no signal
+it changed — the retraction is a later comment, which a reader who has already formed a conclusion
+will not necessarily see.
+
+**A workaround circulated, then retracted.** A technique was recommended to three agents, then
+disproved by measurement and withdrawn. The three had no mechanism to learn it was withdrawn.
+
+And the technique had **zero observed successes but still read as having worked**: the agent
+performed it, the very next operation was refused, it worked around the failure by other means, and
+later the condition the technique was supposed to create arrived on its own for unrelated reasons.
+Nothing about that sequence looks like a failure from outside.
+
+## Why durable memory is the worst case
+
+A superseded finding survives longest exactly where it was best recorded. A claim made in passing
+decays with the conversation; a claim written to a memory file persists and is re-read
+authoritatively by future sessions. **The more responsibly a finding was captured, the more durable
+its error becomes** — and the retraction, being conversational, decays while the claim does not.
+
+## What makes this hard
+
+- **A session cannot detect that its own context is stale.** Context completeness is not observable
+  from inside. Any fix that asks an agent to assess its own context is the trap, not the remedy.
+- **A retraction is usually not written to any canonical surface.** It is a reply, produced under
+  exactly the conditions least likely to bear a chore.
+- **The audience is not enumerable.** Whoever received the original may have relayed it onward, and
+  a session that has gone quiet is unreachable by any message.
+
+The third point is why the mechanism is a **re-check by the reader**, not a broadcast by the
+publisher. The publisher records once; every live session re-checks on its own.
+
+## The ledger's two tiers
+
+| tier | path | who it reaches |
+|---|---|---|
+| repository | `.lisa/WITHDRAWN.jsonl` (committed, union-merged) | every future reader of this project, forever |
+| machine | `${LISA_STATE_HOME:-~/.lisa}/withdrawn-rulings.jsonl` | sibling sessions in **other worktrees on this machine, now** |
+
+A withdrawal is written to both by one command; reads are the union, de-duplicated by id. The
+machine tier exists because a committed file cannot reach a sibling agent until it is merged and
+pulled, and the audience that needs the retraction soonest is the one working beside you.
+
+JSONL rather than prose: each line is independent, so concurrent appends from many agents do not
+collide and `merge=union` reconstructs the union exactly. A prose ledger would need a bespoke merge
+driver to survive the same traffic.
+
+## How a running session is reached
+
+`--session-start` stamps a per-session mark recording the ids the session was born already knowing.
+`--hook` runs after every tool result and announces exactly the entries that appeared **since**,
+once each.
+
+The common case is the cheap case: when neither ledger's `size:mtime` has moved, `--hook` returns
+after two `stat` calls without parsing anything. It fires on every tool call in every session and
+every subagent, so anything expensive multiplies.
+
+A **missing mark is deliberately silent**. A session with no mark is one whose starting knowledge is
+unknown; announcing every historical withdrawal to it would degrade the mechanism into distrusting
+everything, which is the failure the control case in #3752 exists to prevent.
+
+## Surface parity
+
+| surface | session stamp | mid-session announcement | `--list` at the escalation boundary |
+|---|---|---|---|
+| Claude Code | yes — SessionStart and SubagentStart | yes — PostToolUse | yes |
+| Codex | yes, interactive only | yes, interactive only | yes |
+| Cursor | yes — both start events | yes | yes |
+| Copilot | main sessions only — it has no subagent-start event, so a Copilot subagent is stamp-less and therefore silent | yes — `postToolUse` | yes |
+| Antigravity | no — its plugin ships blocking `PreToolUse` guards only, and headless hooks do not fire | no | yes |
+| OpenCode | no — it has no plugin hook runtime, only rules and skills | no | yes |
+
+Where a surface cannot carry the automatic half, the eager rule's `--list` instruction is the
+carried half: it is the same pointer shape #3592 shipped, which survives precisely because it does
+not travel inside the thing it points at. `codex exec` runs no plugin hooks at all, so on that
+surface the ledger is a read the agent performs, not one performed for it. Antigravity and OpenCode
+are the same shape, permanently rather than per-invocation: neither carries a session-lifecycle hook
+today, which is the identical accommodation `failure-signature-index` makes on those two surfaces.
+
+## What deliberately does not belong here
+
+A disagreement that has not been settled. The ledger is for a claim its own author has **withdrawn**
+— not for a claim someone doubts. A tombstone for a live dispute converts the ledger into an
+argument, and an argument is not something a session can act on in one line.

package/plugins/lisa/skills/lisa-git-submit-pr/SKILL.md

@@ -57,6 +57,7 @@ Add provider-appropriate linkage to the PR title and/or body without changing th
 - **GitHub Issues**:
   - If `work_item_ref` is a GitHub issue URL, `org/repo#<n>`, or `#<n>`, add a dedicated issue reference line to the PR body.
   - Always use a non-closing reference such as `Refs #<n>`, so the merge cannot close the issue before the post-merge deploy, remote verification, health check, and terminal `done` label.
+  - **This rule is what makes the managed backlink mandatory, and neither rule says so on its own.** `Refs` creates no native development link, so gate 5 has nothing to defer to and the `[lisa-pr-link]` comment becomes the only backlink there is. Anyone following the non-closing rule alone will hit gate 5. Separately, `Refs #<n>` does **not** satisfy gate 4 either: the body needs its own `Work-Item: <ref>` line, and `Closes`/`Fixes` do not satisfy it. One `Refs` line, one `Work-Item:` line, one backlink comment — three different requirements that look like one. `discharge-pr-gates` (below) is what checks the last two together.
   - **A non-closing reference does not populate the issue's Development / linked pull requests surface, and no non-closing form does.** That surface *is* the closing-reference mechanism: a closing keyword populates the PR's `closingIssuesReferences`, while `Refs` yields only a `CrossReferencedEvent`. Measured on this repository — a `Refs`-only PR reports `closingIssuesReferences: 0`; a `Closes` PR reports 1. So the ticket-side backlink cannot be delegated to GitHub: the managed `[lisa-pr-link]` comment written by `node scripts/lisa-work-item.mjs backlink` — the one producer, which `lisa-github-sync` and the other vendor sync skills call rather than reimplement — is the **required** backlink under this rule, not a fallback for when native linkage happens to be absent. Two-way linkage (`lisa-implement` step 7a) depends on that comment, and so does the Work-Item Traceability check wherever the project declares `workItem.verify: "full"` — there, a PR carrying a correct `Refs` line still fails the check without it. Post it either way: under the default `trailer` level the check does not read the tracker, but the two-way linkage a human follows is still worth having, and a project can raise its level at any time.
   - For cross-repo issue refs, use the fully qualified non-closing form, for example `Refs CodySwannGT/lisa#614`.
 - **Linear**:
@@ -76,13 +77,17 @@ When updating an existing PR, preserve any existing linkage line unless the new
 After creating or updating the PR, always make the reverse link durable on the source work item when `work_item_ref` is available:
 
 1. Resolve the live PR URL with `gh pr view <pr-number> --json url --jq .url`.
-2. Run the backlink command. It is the executable form of this requirement — it writes the managed `[lisa-pr-link]` comment on the work item, or updates the one already there, for every tracker Lisa supports:
+2. Discharge the two gates the push could not check. Gate 4 (the `Work-Item:` line in the PR BODY) and gate 5 (the backlink) are both properties of a pull request, so a push before the PR existed reported them as `UNRESOLVED` rather than checked. One command closes both out at the first moment they *are* checkable:
 
    ```bash
-   node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>
+   node scripts/lisa-work-item.mjs discharge-pr-gates
    ```
 
-   It is idempotent, so run it on every push rather than deciding whether it is needed. It refuses loudly for a tracker it cannot write, and never silently no-ops. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
+   It posts (or refreshes) the managed `[lisa-pr-link]` comment on every item the range names — so gate 5 passes without anyone remembering to — and then evaluates gate 4 against the live body, failing here rather than one CI cycle later. Exit 3 means there is no pull request for this branch yet, which is not a violation; exit 1 is a real unmet requirement and the message names it.
+
+   It writes no PR body. Gate 4 is the author's declaration of what the change is for; a command that inserted the line would be answering its own question.
+
+   The narrower `node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>` is what it wraps, and remains the right call when you hold a ref and a URL but no checkout of the PR's branch (a sync skill updating a backlink after the fact). Both are idempotent, refuse loudly for a tracker they cannot write, and never silently no-op. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
 3. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known. That is the progress-note and status side; it is not what satisfies the traceability check.
 4. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available.
 

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/skills/lisa-git-submit-pr/SKILL.md

@@ -57,6 +57,7 @@ Add provider-appropriate linkage to the PR title and/or body without changing th
 - **GitHub Issues**:
   - If `work_item_ref` is a GitHub issue URL, `org/repo#<n>`, or `#<n>`, add a dedicated issue reference line to the PR body.
   - Always use a non-closing reference such as `Refs #<n>`, so the merge cannot close the issue before the post-merge deploy, remote verification, health check, and terminal `done` label.
+  - **This rule is what makes the managed backlink mandatory, and neither rule says so on its own.** `Refs` creates no native development link, so gate 5 has nothing to defer to and the `[lisa-pr-link]` comment becomes the only backlink there is. Anyone following the non-closing rule alone will hit gate 5. Separately, `Refs #<n>` does **not** satisfy gate 4 either: the body needs its own `Work-Item: <ref>` line, and `Closes`/`Fixes` do not satisfy it. One `Refs` line, one `Work-Item:` line, one backlink comment — three different requirements that look like one. `discharge-pr-gates` (below) is what checks the last two together.
   - **A non-closing reference does not populate the issue's Development / linked pull requests surface, and no non-closing form does.** That surface *is* the closing-reference mechanism: a closing keyword populates the PR's `closingIssuesReferences`, while `Refs` yields only a `CrossReferencedEvent`. Measured on this repository — a `Refs`-only PR reports `closingIssuesReferences: 0`; a `Closes` PR reports 1. So the ticket-side backlink cannot be delegated to GitHub: the managed `[lisa-pr-link]` comment written by `node scripts/lisa-work-item.mjs backlink` — the one producer, which `lisa-github-sync` and the other vendor sync skills call rather than reimplement — is the **required** backlink under this rule, not a fallback for when native linkage happens to be absent. Two-way linkage (`lisa-implement` step 7a) depends on that comment, and so does the Work-Item Traceability check wherever the project declares `workItem.verify: "full"` — there, a PR carrying a correct `Refs` line still fails the check without it. Post it either way: under the default `trailer` level the check does not read the tracker, but the two-way linkage a human follows is still worth having, and a project can raise its level at any time.
   - For cross-repo issue refs, use the fully qualified non-closing form, for example `Refs CodySwannGT/lisa#614`.
 - **Linear**:
@@ -76,13 +77,17 @@ When updating an existing PR, preserve any existing linkage line unless the new
 After creating or updating the PR, always make the reverse link durable on the source work item when `work_item_ref` is available:
 
 1. Resolve the live PR URL with `gh pr view <pr-number> --json url --jq .url`.
-2. Run the backlink command. It is the executable form of this requirement — it writes the managed `[lisa-pr-link]` comment on the work item, or updates the one already there, for every tracker Lisa supports:
+2. Discharge the two gates the push could not check. Gate 4 (the `Work-Item:` line in the PR BODY) and gate 5 (the backlink) are both properties of a pull request, so a push before the PR existed reported them as `UNRESOLVED` rather than checked. One command closes both out at the first moment they *are* checkable:
 
    ```bash
-   node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>
+   node scripts/lisa-work-item.mjs discharge-pr-gates
    ```
 
-   It is idempotent, so run it on every push rather than deciding whether it is needed. It refuses loudly for a tracker it cannot write, and never silently no-ops. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
+   It posts (or refreshes) the managed `[lisa-pr-link]` comment on every item the range names — so gate 5 passes without anyone remembering to — and then evaluates gate 4 against the live body, failing here rather than one CI cycle later. Exit 3 means there is no pull request for this branch yet, which is not a violation; exit 1 is a real unmet requirement and the message names it.
+
+   It writes no PR body. Gate 4 is the author's declaration of what the change is for; a command that inserted the line would be answering its own question.
+
+   The narrower `node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>` is what it wraps, and remains the right call when you hold a ref and a URL but no checkout of the PR's branch (a sync skill updating a backlink after the fact). Both are idempotent, refuse loudly for a tracker they cannot write, and never silently no-op. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
 3. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known. That is the progress-note and status side; it is not what satisfies the traceability check.
 4. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available.
 

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.37.3",
+  "version": "4.38.1",
   "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": "4.37.3",
+  "version": "4.38.1",
   "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": "4.37.3",
+  "version": "4.38.1",
   "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": "4.37.3",
+  "version": "4.38.1",
   "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": "4.37.3",
+  "version": "4.38.1",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.37.3",
+  "version": "4.38.1",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"
@@ -36,6 +36,15 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/discharge-work-item-gates.sh"
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write|NotebookEdit|Bash",
         "hooks": [
@@ -44,6 +53,15 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/threshold-ratchet.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash|Edit|Write|Read|Task|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/withdrawn-rulings.sh --hook"
+          }
+        ]
       }
     ],
     "preToolUse": [
@@ -129,6 +147,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/withdrawn-rulings.sh --session-start"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [

package/plugins/lisa-copilot/hooks/discharge-work-item-gates.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# =============================================================================
+# Discharge Deferred Work-Item Gates Hook (PostToolUse - Bash)
+# =============================================================================
+# Two of the five Work-Item Traceability gates live OUTSIDE the commits: gate 4
+# is the `Work-Item:` line in the pull-request BODY, and gate 5 is the managed
+# `[lisa-pr-link]` backlink on the item. A push cannot check either one —
+# both are properties of a pull request, and the push is what makes the pull
+# request possible — so until this hook existed the next thing that looked was
+# CI, one cycle later (CodySwannGT/lisa#3791).
+#
+# This fires the moment a pull request is created or its body edited, which is
+# the FIRST moment both gates are checkable. It evaluates them, and posts the
+# backlink that gate 5 needs, so neither waits for a red CI run to be revealed.
+#
+# Exit 2 blocks and hands the output back to the agent, which is the point: a
+# non-blocking notice here would be the same defect the discharge exists to
+# fix — a finding delivered somewhere nobody has to act on it.
+# =============================================================================
+set -uo pipefail
+
+JSON_INPUT="$(cat)"
+
+command -v jq >/dev/null 2>&1 || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+COMMAND="$(printf '%s' "$JSON_INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+[ -n "$COMMAND" ] || exit 0
+
+# `gh pr create` opens one; `gh pr edit` is the other way a body comes to carry
+# — or lose — its declaration. Both change the answer to gate 4.
+case "$COMMAND" in
+  *"gh pr create"* | *"gh pr edit"*) ;;
+  *) exit 0 ;;
+esac
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ -f "$repo_root/scripts/lisa-work-item.mjs" ] || exit 0
+
+output="$(cd "$repo_root" && node scripts/lisa-work-item.mjs discharge-pr-gates 2>&1)"
+status=$?
+
+# 0 is a clean discharge. 3 is the validator's own answer for "no pull request
+# to check yet", which PostToolUse reaches on every `gh pr create` that FAILED
+# — the tool call still ran, so the hook still fires. Collapsing 3 into the
+# blocking arm would report a work-item violation on somebody's typo.
+case "$status" in
+  0 | 3) exit 0 ;;
+esac
+
+printf '%s\n' "$output" >&2
+exit 2