@codyswann/lisa 2.329.0 → 2.330.1

package/plugins/lisa-agy/hooks/block-instruction-file-edits.agy.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Antigravity (agy) PreToolUse adapter for Lisa's instruction-file guard.
+#
+# agy sends `{toolCall:{name:"run_command",args:{CommandLine:"..."}}}` and
+# expects an allow/deny JSON object on stdout. The canonical hook consumes the
+# Claude Bash-hook envelope and communicates denial with exit status 2. This
+# adapter only translates protocols; all classification stays in the canonical
+# block-instruction-file-edits.sh beside it (same delegation pattern as
+# block-shell-json-parsing.agy.sh).
+#
+# Scope note: agy plugin hooks match `run_command`, so only the Bash arm of the
+# guard reaches agy — an agy file-edit tool call writing AGENTS.md cannot be
+# intercepted. That gap is accepted and recorded here rather than papered over.
+#
+# Fail-open on missing runtimes: a missed refusal here costs context bloat in a
+# markdown file, not data loss.
+set -uo pipefail
+
+allow() {
+  printf '%s\n' '{"decision":"allow"}'
+  exit 0
+}
+
+deny() {
+  local reason="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -cn --arg reason "$reason" '{decision:"deny",reason:$reason}'
+  else
+    printf '%s\n' '{"decision":"allow"}'
+  fi
+  exit 0
+}
+
+input="$(cat 2>/dev/null || true)"
+[ -z "$input" ] && allow
+command -v jq >/dev/null 2>&1 || allow
+
+tool_name="$(printf '%s' "$input" | jq -r '.toolCall.name // empty' 2>/dev/null || true)"
+[ "$tool_name" != "run_command" ] && allow
+command_str="$(printf '%s' "$input" | jq -r '.toolCall.args.CommandLine // empty' 2>/dev/null || true)"
+[ -z "$command_str" ] && allow
+
+hook_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+canonical_hook="$hook_dir/block-instruction-file-edits.sh"
+[ -r "$canonical_hook" ] || allow
+
+canonical_input="$(jq -cn --arg command "$command_str" '{tool_name:"Bash",tool_input:{command:$command}}')"
+canonical_output=""
+canonical_status=0
+if canonical_output="$(printf '%s' "$canonical_input" | /bin/bash "$canonical_hook" 2>&1)"; then
+  canonical_status=0
+else
+  canonical_status=$?
+fi
+
+[ "$canonical_status" -eq 0 ] && allow
+[ -n "$canonical_output" ] || canonical_output="Blocked: AGENTS.md / CLAUDE.md are human-authored session-instruction files."
+deny "$canonical_output"

package/plugins/lisa-agy/hooks/block-instruction-file-edits.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# PreToolUse hook: refuse agent writes to the session-instruction files.
+#
+# `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` are the files
+# every agent loads at session start. They are human-authored and curated on
+# purpose — Lisa's own contract says so in two places:
+#   - plugins/src/base/rules/reference/project-learnings.md
+#   - plugins/src/base/skills/lisa-debrief-apply/SKILL.md ("CLAUDE.md is
+#     human-authored ... apply never writes to any of the three")
+#
+# Nothing enforced it, so agents appended their own findings anyway: one fleet
+# repo reached 949 lines of ticket-keyed trap dumps in `AGENTS.md` while its
+# learnings ledger held 22. Every one of those lines is charged to the context
+# of every later session in that project, forever. Prose did not hold; this is
+# the executable control that does.
+#
+# Blocked signatures:
+#   1. Write / Edit / MultiEdit / NotebookEdit whose target basename is one of
+#      the instruction files;
+#   2. Bash output redirection (`>`, `>>`), `tee`, or `sed -i` aimed at one.
+#      Reads (`cat AGENTS.md`, `rg pattern AGENTS.md`) never fire.
+#
+# Exemptions (allowed):
+#   - `LISA_ALLOW_INSTRUCTION_FILE_WRITE` set — the operator's explicit override,
+#     named in the refusal so a human who really wants the edit can take it;
+#   - payloads carrying a `<!-- LISA_` marker: Lisa's own marker-bounded regions
+#     (the agy project-learnings bridge, cross-pollinate's rule section) replace
+#     in place on re-run and cannot grow the file;
+#   - paths under `node_modules/` or `dist/` — vendored copies, not the host's.
+set -euo pipefail
+
+input="$(cat)"
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# The operator's override. Checked before anything else so it is always the
+# cheapest way out of a refusal a human deliberately wants to overrule.
+if [ -n "${LISA_ALLOW_INSTRUCTION_FILE_WRITE:-}" ]; then
+  exit 0
+fi
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+[ -n "$tool_name" ] || exit 0
+
+# Lisa's own bounded bridges write marked regions. A payload carrying a marker
+# is replacing a delimited block, not appending prose, so it cannot be the
+# unbounded growth this guard exists to stop.
+if printf '%s' "$input" | grep -q '<!-- LISA_'; then
+  exit 0
+fi
+
+# Basename match, case-insensitively: `agents.md` and `AGENTS.md` are the same
+# file on the macOS checkouts this fleet runs on.
+is_instruction_file() {
+  local candidate="$1"
+  case "$candidate" in
+    */node_modules/* | node_modules/* | */dist/* | dist/*) return 1 ;;
+  esac
+  local base="${candidate##*/}"
+  case "$(printf '%s' "$base" | tr '[:upper:]' '[:lower:]')" in
+    agents.md | claude.md | copilot-instructions.md) return 0 ;;
+  esac
+  return 1
+}
+
+refuse() {
+  local target="$1"
+  cat >&2 <<EOF
+BLOCKED: refusing to write \`$target\`.
+
+WHY: this is a session-instruction file, not a place to record what you just
+learned. Every line in it is loaded into the context of every agent, in every
+future session, in this project, forever. It is human-curated on purpose. An
+agent appending its own findings is how these files grow into hundreds of lines
+of stale, ticket-specific trivia that every later session pays for and half of
+which was only ever true once.
+
+WHERE IT GOES INSTEAD — take the first one that fits:
+
+1. Every agent genuinely needs this in every session, and only in this project.
+   That is a project rule — but do not write it yourself. Capture it with
+   \`/lisa:persist-learning\` so it lands in the learnings ledger with provenance
+   and a confidence score. The gardener (\`/lisa:learnings:audit\`) then proposes
+   promotion into \`.claude/rules/PROJECT_RULES.md\` as a human-gated ticket.
+
+2. It changes how an existing skill should behave. Edit that skill's SKILL.md.
+   Knowledge belongs next to the procedure it modifies, not in a global preamble.
+
+3. It is true beyond this project. Propose it upstream to Lisa via
+   \`/lisa:cross-pollinate\`, or open an issue on CodySwannGT/lisa. A local copy of
+   a general rule silently drifts the moment upstream changes.
+
+4. None of the above — it is background someone may want to look up, not a
+   standing instruction. Write it into the project documentation (\`wiki/\` or
+   \`docs/\`).
+
+If a human explicitly asked for this edit, they can re-run with
+\`LISA_ALLOW_INSTRUCTION_FILE_WRITE=1\` set, which bypasses this guard.
+EOF
+  exit 2
+}
+
+case "$tool_name" in
+  Write | Edit | MultiEdit | NotebookEdit | Update)
+    # `file_path` covers Write/Edit; `edits[].file_path` covers the MultiEdit
+    # shapes that carry a path per edit; `notebook_path` covers NotebookEdit.
+    paths="$(printf '%s' "$input" | jq -r '
+      [ .tool_input.file_path?,
+        .tool_input.path?,
+        .tool_input.notebook_path?,
+        (.tool_input.edits? // [] | .[].file_path?)
+      ] | map(select(. != null and . != "")) | .[]' 2>/dev/null || true)"
+    while IFS= read -r candidate; do
+      [ -n "$candidate" ] || continue
+      if is_instruction_file "$candidate"; then
+        refuse "$candidate"
+      fi
+    done <<EOF
+$paths
+EOF
+    ;;
+  Bash)
+    command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')"
+    [ -n "$command_str" ] || exit 0
+    # Fast path: no instruction filename mentioned means nothing to classify.
+    if ! printf '%s' "$command_str" |
+      grep -Eqi '(agents|claude|copilot-instructions)\.md'; then
+      exit 0
+    fi
+    # Write signatures only. A bare mention (`cat AGENTS.md`, `rg x AGENTS.md`)
+    # is a read and must stay allowed — the filename has to appear as the target
+    # of a redirection, a tee, or an in-place sed.
+    write_target='[^ |;&]*(agents|claude|copilot-instructions)\.md'
+    if printf '%s' "$command_str" |
+      grep -Eqi ">>?[[:space:]]*['\"]?$write_target|tee([[:space:]]+-[a-z]+)*[[:space:]]+['\"]?$write_target|sed[[:space:]]+[^|;&]*-i[^|;&]*$write_target"; then
+      refuse "$(printf '%s' "$command_str" |
+        grep -Eoi "$write_target" | head -1)"
+    fi
+    ;;
+esac
+
+exit 0

package/plugins/lisa-agy/hooks.json

@@ -37,5 +37,18 @@
         ]
       }
     ]
+  },
+  "lisa-block-instruction-file-edits": {
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.gemini/config/plugins/lisa/hooks/block-instruction-file-edits.agy.sh\""
+          }
+        ]
+      }
+    ]
   }
 }

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/skills/lisa-setup-workstation/SKILL.md

@@ -25,15 +25,36 @@ repository, and nothing here duplicates that manifest.
 
 ## Usage
 
+**Start here — this is the entry point that presumes nothing:**
+
+```sh
+npx -y @codyswann/lisa@latest workstation             # report what is present and missing
+npx -y @codyswann/lisa@latest workstation --install   # install what is missing
+```
+
+That form needs only Node. No checkout, no agent, no Lisa install — npx resolves
+the package into its own cache.
+
+**Why it matters:** this skill exists to prepare a machine with *no coding agent*
+and *no checkout*. But a skill can only be invoked by typing a slash command into
+an agent, and Lisa ships as a devDependency, so it does not exist until a repo is
+cloned and its dependencies installed. Both are exactly the state this is meant to
+create — so as a skill alone, the bootstrap was unreachable in the one scenario it
+was designed for. The CLI is the way in; the skill is the surface for people who
+already have an agent.
+
+Every flag is the same either way:
+
 ```sh
-node scripts/cli.mjs                              # report what is present and missing
-node scripts/cli.mjs --install                    # install what is missing
-node scripts/cli.mjs --install --agents=claude,codex   # only these agents
-node scripts/cli.mjs --provider=bitwarden         # credential manager (asked if a TTY)
-node scripts/cli.mjs --json                       # machine-readable plan
-node scripts/cli.mjs --print-dockerfile           # an image that runs this same script
+lisa workstation --install --agents=claude,codex   # only these agents
+lisa workstation --provider=bitwarden              # credential manager (asked if a TTY)
+lisa workstation --json                            # machine-readable plan
+lisa workstation --print-dockerfile                # an image that runs this same script
 ```
 
+Inside an agent, `/lisa:setup:workstation` runs the identical script; and the
+script itself is directly runnable as `node scripts/cli.mjs …`.
+
 Nothing is installed or written without `--install`. Exit status is non-zero when a required
 tool is absent or an install fails, so this is usable as a gate.
 

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.329.0",
+  "version": "2.330.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": "2.329.0",
+  "version": "2.330.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": "2.329.0",
+  "version": "2.330.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": "2.329.0",
+  "version": "2.330.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": "2.329.0",
+  "version": "2.330.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": "2.329.0",
+  "version": "2.330.1",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"
@@ -52,6 +52,19 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-shell-json-parsing.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-instruction-file-edits.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-instruction-file-edits.sh"
           }
         ]
       },

package/plugins/lisa-copilot/commands/lisa/setup/workstation.md

@@ -5,3 +5,5 @@ argument-hint: "[--install] [--agents=claude,codex] [--provider=bitwarden] [--js
 ---
 
 Use the /lisa-setup-workstation skill to report and optionally install the coding agents, credential manager, and base tools this machine needs. $ARGUMENTS
+
+Note: on a machine with no agent and no checkout — which is what this prepares — reach the same bootstrap without Lisa installed at all: `npx -y @codyswann/lisa@latest workstation --install`.

package/plugins/lisa-copilot/hooks/block-instruction-file-edits.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# PreToolUse hook: refuse agent writes to the session-instruction files.
+#
+# `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` are the files
+# every agent loads at session start. They are human-authored and curated on
+# purpose — Lisa's own contract says so in two places:
+#   - plugins/src/base/rules/reference/project-learnings.md
+#   - plugins/src/base/skills/lisa-debrief-apply/SKILL.md ("CLAUDE.md is
+#     human-authored ... apply never writes to any of the three")
+#
+# Nothing enforced it, so agents appended their own findings anyway: one fleet
+# repo reached 949 lines of ticket-keyed trap dumps in `AGENTS.md` while its
+# learnings ledger held 22. Every one of those lines is charged to the context
+# of every later session in that project, forever. Prose did not hold; this is
+# the executable control that does.
+#
+# Blocked signatures:
+#   1. Write / Edit / MultiEdit / NotebookEdit whose target basename is one of
+#      the instruction files;
+#   2. Bash output redirection (`>`, `>>`), `tee`, or `sed -i` aimed at one.
+#      Reads (`cat AGENTS.md`, `rg pattern AGENTS.md`) never fire.
+#
+# Exemptions (allowed):
+#   - `LISA_ALLOW_INSTRUCTION_FILE_WRITE` set — the operator's explicit override,
+#     named in the refusal so a human who really wants the edit can take it;
+#   - payloads carrying a `<!-- LISA_` marker: Lisa's own marker-bounded regions
+#     (the agy project-learnings bridge, cross-pollinate's rule section) replace
+#     in place on re-run and cannot grow the file;
+#   - paths under `node_modules/` or `dist/` — vendored copies, not the host's.
+set -euo pipefail
+
+input="$(cat)"
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# The operator's override. Checked before anything else so it is always the
+# cheapest way out of a refusal a human deliberately wants to overrule.
+if [ -n "${LISA_ALLOW_INSTRUCTION_FILE_WRITE:-}" ]; then
+  exit 0
+fi
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+[ -n "$tool_name" ] || exit 0
+
+# Lisa's own bounded bridges write marked regions. A payload carrying a marker
+# is replacing a delimited block, not appending prose, so it cannot be the
+# unbounded growth this guard exists to stop.
+if printf '%s' "$input" | grep -q '<!-- LISA_'; then
+  exit 0
+fi
+
+# Basename match, case-insensitively: `agents.md` and `AGENTS.md` are the same
+# file on the macOS checkouts this fleet runs on.
+is_instruction_file() {
+  local candidate="$1"
+  case "$candidate" in
+    */node_modules/* | node_modules/* | */dist/* | dist/*) return 1 ;;
+  esac
+  local base="${candidate##*/}"
+  case "$(printf '%s' "$base" | tr '[:upper:]' '[:lower:]')" in
+    agents.md | claude.md | copilot-instructions.md) return 0 ;;
+  esac
+  return 1
+}
+
+refuse() {
+  local target="$1"
+  cat >&2 <<EOF
+BLOCKED: refusing to write \`$target\`.
+
+WHY: this is a session-instruction file, not a place to record what you just
+learned. Every line in it is loaded into the context of every agent, in every
+future session, in this project, forever. It is human-curated on purpose. An
+agent appending its own findings is how these files grow into hundreds of lines
+of stale, ticket-specific trivia that every later session pays for and half of
+which was only ever true once.
+
+WHERE IT GOES INSTEAD — take the first one that fits:
+
+1. Every agent genuinely needs this in every session, and only in this project.
+   That is a project rule — but do not write it yourself. Capture it with
+   \`/lisa:persist-learning\` so it lands in the learnings ledger with provenance
+   and a confidence score. The gardener (\`/lisa:learnings:audit\`) then proposes
+   promotion into \`.claude/rules/PROJECT_RULES.md\` as a human-gated ticket.
+
+2. It changes how an existing skill should behave. Edit that skill's SKILL.md.
+   Knowledge belongs next to the procedure it modifies, not in a global preamble.
+
+3. It is true beyond this project. Propose it upstream to Lisa via
+   \`/lisa:cross-pollinate\`, or open an issue on CodySwannGT/lisa. A local copy of
+   a general rule silently drifts the moment upstream changes.
+
+4. None of the above — it is background someone may want to look up, not a
+   standing instruction. Write it into the project documentation (\`wiki/\` or
+   \`docs/\`).
+
+If a human explicitly asked for this edit, they can re-run with
+\`LISA_ALLOW_INSTRUCTION_FILE_WRITE=1\` set, which bypasses this guard.
+EOF
+  exit 2
+}
+
+case "$tool_name" in
+  Write | Edit | MultiEdit | NotebookEdit | Update)
+    # `file_path` covers Write/Edit; `edits[].file_path` covers the MultiEdit
+    # shapes that carry a path per edit; `notebook_path` covers NotebookEdit.
+    paths="$(printf '%s' "$input" | jq -r '
+      [ .tool_input.file_path?,
+        .tool_input.path?,
+        .tool_input.notebook_path?,
+        (.tool_input.edits? // [] | .[].file_path?)
+      ] | map(select(. != null and . != "")) | .[]' 2>/dev/null || true)"
+    while IFS= read -r candidate; do
+      [ -n "$candidate" ] || continue
+      if is_instruction_file "$candidate"; then
+        refuse "$candidate"
+      fi
+    done <<EOF
+$paths
+EOF
+    ;;
+  Bash)
+    command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')"
+    [ -n "$command_str" ] || exit 0
+    # Fast path: no instruction filename mentioned means nothing to classify.
+    if ! printf '%s' "$command_str" |
+      grep -Eqi '(agents|claude|copilot-instructions)\.md'; then
+      exit 0
+    fi
+    # Write signatures only. A bare mention (`cat AGENTS.md`, `rg x AGENTS.md`)
+    # is a read and must stay allowed — the filename has to appear as the target
+    # of a redirection, a tee, or an in-place sed.
+    write_target='[^ |;&]*(agents|claude|copilot-instructions)\.md'
+    if printf '%s' "$command_str" |
+      grep -Eqi ">>?[[:space:]]*['\"]?$write_target|tee([[:space:]]+-[a-z]+)*[[:space:]]+['\"]?$write_target|sed[[:space:]]+[^|;&]*-i[^|;&]*$write_target"; then
+      refuse "$(printf '%s' "$command_str" |
+        grep -Eoi "$write_target" | head -1)"
+    fi
+    ;;
+esac
+
+exit 0

package/plugins/lisa-copilot/skills/lisa-setup-workstation/SKILL.md

@@ -25,15 +25,36 @@ repository, and nothing here duplicates that manifest.
 
 ## Usage
 
+**Start here — this is the entry point that presumes nothing:**
+
+```sh
+npx -y @codyswann/lisa@latest workstation             # report what is present and missing
+npx -y @codyswann/lisa@latest workstation --install   # install what is missing
+```
+
+That form needs only Node. No checkout, no agent, no Lisa install — npx resolves
+the package into its own cache.
+
+**Why it matters:** this skill exists to prepare a machine with *no coding agent*
+and *no checkout*. But a skill can only be invoked by typing a slash command into
+an agent, and Lisa ships as a devDependency, so it does not exist until a repo is
+cloned and its dependencies installed. Both are exactly the state this is meant to
+create — so as a skill alone, the bootstrap was unreachable in the one scenario it
+was designed for. The CLI is the way in; the skill is the surface for people who
+already have an agent.
+
+Every flag is the same either way:
+
 ```sh
-node scripts/cli.mjs                              # report what is present and missing
-node scripts/cli.mjs --install                    # install what is missing
-node scripts/cli.mjs --install --agents=claude,codex   # only these agents
-node scripts/cli.mjs --provider=bitwarden         # credential manager (asked if a TTY)
-node scripts/cli.mjs --json                       # machine-readable plan
-node scripts/cli.mjs --print-dockerfile           # an image that runs this same script
+lisa workstation --install --agents=claude,codex   # only these agents
+lisa workstation --provider=bitwarden              # credential manager (asked if a TTY)
+lisa workstation --json                            # machine-readable plan
+lisa workstation --print-dockerfile                # an image that runs this same script
 ```
 
+Inside an agent, `/lisa:setup:workstation` runs the identical script; and the
+script itself is directly runnable as `node scripts/cli.mjs …`.
+
 Nothing is installed or written without `--install`. Exit status is non-zero when a required
 tool is absent or an install fails, so this is usable as a gate.
 

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

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

package/plugins/lisa-cursor/commands/lisa/setup/workstation.md

@@ -5,3 +5,5 @@ argument-hint: "[--install] [--agents=claude,codex] [--provider=bitwarden] [--js
 ---
 
 Use the /lisa-setup-workstation skill to report and optionally install the coding agents, credential manager, and base tools this machine needs. $ARGUMENTS
+
+Note: on a machine with no agent and no checkout — which is what this prepares — reach the same bootstrap without Lisa installed at all: `npx -y @codyswann/lisa@latest workstation --install`.