@codyswann/lisa 2.329.0 → 2.330.1

package/plugins/src/base/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/src/base/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/src/base/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/scripts/build-plugins.sh

@@ -105,7 +105,8 @@ HOST_GUARD_DIR="$ROOT_DIR/all/copy-overwrite/scripts/lisa-hooks"
 if [ -d "$SRC_DIR/base/hooks" ]; then
   mkdir -p "$HOST_GUARD_DIR"
 fi
-for guard in block-no-verify parity-safety-net block-shell-json-parsing; do
+for guard in block-no-verify parity-safety-net block-shell-json-parsing \
+  block-instruction-file-edits; do
   if [ -f "$SRC_DIR/base/hooks/$guard.sh" ]; then
     cp "$SRC_DIR/base/hooks/$guard.sh" "$HOST_GUARD_DIR/$guard.sh"
     chmod +x "$HOST_GUARD_DIR/$guard.sh"

package/scripts/generate-agy-plugin-artifacts.mjs

@@ -234,6 +234,17 @@ const AGY_PLUGIN_HOOKS = [
     agyScript: "block-shell-json-parsing.agy.sh",
     supportScripts: ["block-shell-json-parsing.sh"],
   },
+  {
+    // Bash arm only. agy matches `run_command`, so its file-edit tool calls
+    // cannot be intercepted the way Claude's Write/Edit/MultiEdit are; the
+    // redirection / tee / sed -i signatures are what agy gets.
+    sourceScript: "block-instruction-file-edits.sh",
+    hookName: "lisa-block-instruction-file-edits",
+    event: "PreToolUse",
+    matcher: "run_command",
+    agyScript: "block-instruction-file-edits.agy.sh",
+    supportScripts: ["block-instruction-file-edits.sh"],
+  },
 ];
 
 /**

package/scripts/lib/per-agent-hook-filter.mjs

@@ -50,6 +50,16 @@ const SCRIPT_RULES = {
     agy: true, // ships via AGY_PLUGIN_HOOKS (agy-protocol adapter), like the other PreToolUse guards
     copilot: true,
   },
+  "block-instruction-file-edits.sh": {
+    claude: true,
+    codex: true,
+    cursor: true,
+    // agy receives only the Bash arm: agy's plugin hooks match `run_command`,
+    // so its file-edit tool calls cannot be intercepted. Documented gap — the
+    // redirection/tee/sed-i signatures still hold there.
+    agy: true,
+    copilot: true,
+  },
   "enforce-team-first.sh": {
     claude: true,
     codex: false,

package/scripts/lisa-enforcement-fallback.sh

@@ -4,7 +4,8 @@
 # is not installed.
 #
 # Every PreToolUse guard — block-no-verify, parity-safety-net,
-# block-shell-json-parsing — is declared in the Lisa plugin. A cloud session
+# block-shell-json-parsing, block-instruction-file-edits — is declared in the
+# Lisa plugin. A cloud session
 # installs plugins at session start from the marketplace the repository
 # declares, and when that does not happen the container runs with
 # `installed_plugins.json` empty and no enforcement whatsoever.
@@ -41,7 +42,8 @@ fi
 # host project whose plugin install fails has exactly the same hole and no
 # `plugins/` directory to fall back on.
 status=0
-for guard in block-no-verify parity-safety-net block-shell-json-parsing; do
+for guard in block-no-verify parity-safety-net block-shell-json-parsing \
+  block-instruction-file-edits; do
   script=""
   for candidate in \
     "$repo_root/scripts/lisa-hooks/$guard.sh" \