@codyswann/lisa 4.38.0 → 4.38.2

package/dist/opencode/plugin-templates/lisa-block-direct-issue-create.ts

@@ -14,6 +14,15 @@
  * `output.args.command`. Throwing in `tool.execute.before` cancels the tool
  * call and surfaces the message to the agent.
  *
+ * SCOPE GAP, recorded rather than silently dropped (AGENTS.md). Since
+ * CodySwannGT/lisa#3753 the canonical guard covers a SECOND substrate —
+ * structured tool payloads, where a creation arrives as named fields rather
+ * than a command line — because the filing contract was enforced on the shell
+ * and unenforced on every tool call beside it. This port returns early for any
+ * tool other than `bash`, so on OpenCode that substrate is still uncovered.
+ * Closing it needs OpenCode's own creation-tool envelope, which is separate
+ * work from porting the shell path.
+ *
  * The port matches on the raw command text rather than tokenising it, which
  * makes it naturally immune to the prefix and tokenisation bypass classes the
  * shell guard had to be restructured to close — an unrecognised wrapper is just

package/package.json

@@ -169,7 +169,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.38.0",
+  "version": "4.38.2",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -317,7 +317,7 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "99484f8dc349184afd44f96a890524223c3ea97c",
-  "gitHead": "99484f8dc349184afd44f96a890524223c3ea97c",
-  "lisaReleaseTag": "v4.38.0"
+  "lisaReleaseCommit": "62b7f7f6571fa343cf1c31c9e460461f597ee9ac",
+  "gitHead": "62b7f7f6571fa343cf1c31c9e460461f597ee9ac",
+  "lisaReleaseTag": "v4.38.2"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.38.0",
+  "version": "4.38.2",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"
@@ -72,6 +72,15 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/discharge-work-item-gates.sh"
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write|NotebookEdit|Bash",
         "hooks": [
@@ -129,10 +138,6 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-instruction-file-edits.sh"
           },
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-direct-issue-create.sh"
-          },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-blind-automerge.sh"
@@ -169,6 +174,15 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforce-verification-gate.sh"
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-direct-issue-create.sh"
+          }
+        ]
       }
     ],
     "Stop": [

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

@@ -30,6 +30,15 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/discharge-work-item-gates.sh"
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write|NotebookEdit|Bash",
         "hooks": [
@@ -69,10 +78,6 @@
             "type": "command",
             "command": "${PLUGIN_ROOT}/hooks/block-instruction-file-edits.sh"
           },
-          {
-            "type": "command",
-            "command": "${PLUGIN_ROOT}/hooks/block-direct-issue-create.sh"
-          },
           {
             "type": "command",
             "command": "${PLUGIN_ROOT}/hooks/block-blind-automerge.sh"
@@ -100,6 +105,15 @@
             "command": "${PLUGIN_ROOT}/hooks/enforce-verification-gate.sh"
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/block-direct-issue-create.sh"
+          }
+        ]
       }
     ],
     "Stop": [

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

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

package/plugins/lisa/.codex-plugin/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/hooks/block-direct-issue-create.agy.sh

@@ -8,9 +8,19 @@
 # block-direct-issue-create.sh beside it (same delegation pattern as
 # block-instruction-file-edits.agy.sh).
 #
-# No scope gap here, unlike the instruction-file adapter: the canonical guard is
-# Bash-only by construction, and `run_command` is exactly the surface it needs.
-# agy therefore receives the whole guard, not an arm of it.
+# SCOPE GAP, recorded rather than silently dropped (AGENTS.md). This used to
+# read "no scope gap here: the canonical guard is Bash-only by construction, and
+# `run_command` is exactly the surface it needs." That stopped being true in
+# CodySwannGT/lisa#3753: the canonical guard now covers a SECOND substrate —
+# structured tool payloads, where a creation arrives as named fields rather than
+# as a command line — because the filing contract was enforced on the shell and
+# unenforced on every tool call beside it.
+#
+# This adapter forwards `run_command` and nothing else, so on agy that second
+# substrate is still uncovered. Closing it needs agy's own tool-call envelope
+# (which tool names its creation surface, and where the arguments land), and
+# that is a different piece of work from translating one protocol. The shell
+# surface agy does expose receives the whole guard, exactly as before.
 #
 # Fail-open on missing runtimes: a missed refusal costs one under-declared
 # ticket, and `lisa-repair-intake` already sweeps for exactly that. Failing

package/plugins/lisa/hooks/block-direct-issue-create.sh

@@ -79,6 +79,36 @@
 # settings env block, CI config). An escape the governed agent reaches by
 # typing one more token in front of the command it was just refused is not an
 # escape hatch — it is the prose problem with extra steps.
+#
+# ## What this hook costs, and the number that would change the decision
+#
+# Registered `matcher: ""` since CodySwannGT/lisa#3753 — it runs on EVERY tool
+# call, not only Bash. Measured on a developer machine at load ~8-26, 50
+# invocations per row:
+#
+#     16.7 ms   enforce-team-first.sh          already `matcher: ""` today
+#     17.5 ms   enforce-verification-gate.sh   already `matcher: ""` today
+#     11.5 ms   this guard, non-Bash payload   what the broad matcher adds
+#    112.3 ms   this guard, Bash payload       what Bash calls already paid
+#
+# So the broad registration was not novel — two hooks were already there, this
+# one is cheaper than either, and it raises an existing ~34 ms per-call baseline
+# by about a third.
+#
+# THIS IS A THRESHOLD, NOT A PRECEDENT. The argument is about the TOTAL cost of
+# the broad set, so it does not transfer to the next guard: four more hooks
+# moved to `matcher: ""` would put ~90 ms on every tool call and the answer
+# flips. **Before widening any other hook's matcher, re-run the measurement and
+# reconsider if the broad set totals more than ~100 ms per tool call, or if any
+# single broad hook exceeds ~50 ms.** Do not cite these numbers for a fifth
+# hook; measure again, because the number that matters is the sum.
+#
+# The cost is also irreducible rather than sloppy. A 9-line script containing
+# only this file's preamble measured 11.7 ms, and padding it to this file's
+# length changed nothing (11.5 ms) — it is process spawn plus one `jq`, not
+# parsing. Moving the early exit further up the file buys nothing; the exit is
+# already ahead of config resolution, which is what keeps the figure at 11.5
+# rather than at the 112 ms the Bash path pays.
 set -euo pipefail
 
 input="$(cat)"
@@ -99,13 +129,72 @@ for required in jq python3; do
 done
 
 tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+
+# ── The two substrates ────────────────────────────────────────────────────
+#
+# A creation reaches a tracker two ways, and until CodySwannGT/lisa#3753 this
+# guard saw only one of them. It was registered `matcher: "Bash"` AND gated
+# here on `tool_name != "Bash"`, so an MCP tool call was refused entry twice
+# over. MEASURED before the change, driving the guard with synthetic payloads:
+#
+#   ALLOW   mcp__linear-server__create_issue, undeclared      <- the defect
+#   ALLOW   mcp__github__create_issue, undeclared             <- the defect
+#   REFUSE  the same creation as `gh issue create` shell text <- control
+#   ALLOW   an ordinary Read tool call                        <- control
+#
+# The two controls are what make those ALLOWs mean anything: the refusal proves
+# the guard is live, the Read proves it is not simply refusing everything.
+#
+# **Widening the matcher alone would have changed nothing** — the call would
+# arrive and this gate would still exit 0. Anyone who "fixed" #3753 by editing
+# `plugin.json` would have seen no test fail and shipped a guard that still
+# allows every MCP filing. The registration and this gate had to move together.
+#
+# The SHELL path below is untouched. A structured payload has no command line
+# to tokenise, so it gets its own small classifier rather than being forced
+# through a parser built for shell text.
+structured_call=""
 if [ "$tool_name" != "Bash" ]; then
-  exit 0
+  # The cheap shape gate, deliberately BEFORE config resolution.
+  #
+  # This hook now runs on EVERY tool call, so the cost of the path that does
+  # nothing is the cost of the whole change. Config resolution spawns two jq
+  # processes per lookup and is what makes the Bash path ~112 ms; putting it
+  # ahead of this gate would charge that to every Read and Grep. So the
+  # not-a-creation exit happens here, on a shell `case` with no subprocess.
+  #
+  # Matched on SHAPE, not on an enumerated list of server tool names. Server
+  # names are supplied by whoever wrote the server and change when one is
+  # added or renamed, so a list would pass every row anyone thought of and
+  # miss the first one nobody did — the failure mode this repository's guard
+  # suites are written to defeat.
+  #
+  # RESIDUAL, stated rather than hidden: a server whose creation tool is named
+  # without a create-verb or without a tracker noun (`mcp__x__file_work`) is
+  # not recognised and is allowed. That is a fail-open, and it is the honest
+  # cost of refusing to enumerate. Add shapes here as they are measured.
+  case "$tool_name" in
+    Bash | Read | Write | Edit | MultiEdit | Glob | Grep | Task | TodoWrite)
+      exit 0
+      ;;
+  esac
+  case "$tool_name" in
+    *[Cc]reate* | *[Nn]ew* | *[Aa]dd* | *[Ff]ile*) ;;
+    *) exit 0 ;;
+  esac
+  case "$tool_name" in
+    *[Ii]ssue* | *[Tt]icket* | *[Tt]ask* | *[Ss]tory* | *[Bb]ug* | *[Ee]pic* | *[Ww]ork*) ;;
+    *) exit 0 ;;
+  esac
+  structured_call="1"
 fi
 
-command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
-if [ -z "$command_str" ]; then
-  exit 0
+command_str=""
+if [ -z "$structured_call" ]; then
+  command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+  if [ -z "$command_str" ]; then
+    exit 0
+  fi
 fi
 
 project_dir="${CLAUDE_PROJECT_DIR:-}"
@@ -1859,6 +1948,53 @@ print("ALLOW")
 PY
 
 set +e
+# ── The structured substrate ──────────────────────────────────────────────
+#
+# An MCP call carries named fields, not a command line, so `scan()` — which
+# tokenises shell text — has nothing to parse. The declaration is read from the
+# payload instead, and the recogniser is deliberately small: this path decides
+# ONE question (is a build-ready role or a human-gate marker present anywhere
+# in the submitted fields), where the shell path has to answer "which of these
+# tokens is a client, an endpoint, a flag value, or a file it executes".
+#
+# Every string in the payload is searched, at any depth, because a role lands
+# in a different field on every tracker — `labels[]` on GitHub, `stateId` or a
+# workflow state name on Linear, a transition `id` on JIRA — and enumerating
+# field names per vendor is the same brittleness as enumerating tool names.
+# Over-collecting is safe here: the values are compared against ONE configured
+# role string, so an unrelated field cannot accidentally satisfy it.
+if [ -n "$structured_call" ]; then
+  # The operator's ambient escape works on both substrates. There is no inline
+  # form to disqualify it here — a structured call has no shell in which to
+  # assign one — so the override is simply honoured.
+  if [ -n "$ambient_override" ]; then
+    exit 0
+  fi
+
+  structured_declaration="$(
+    printf '%s' "$input" |
+      jq -r --arg role "$ready_role" '
+        [(.tool_input // {}) | .. | strings] as $values
+        | if ($values | index($role)) then "role"
+          elif ($values | map(select(contains("[lisa-human-gate]"))) | length) > 0 then "gate"
+          else "" end
+      ' 2>/dev/null || printf 'UNREADABLE'
+  )"
+
+  # Fail closed on a creation-shaped call whose payload cannot be read. Silence
+  # about a filing the guard could not inspect is the defect this whole ticket
+  # is about, one substrate over.
+  if [ "$structured_declaration" = "UNREADABLE" ]; then
+    refuse "an unreadable $tool_name payload that reads as a tracker creation" \
+      "$ready_role" ""
+  fi
+
+  if [ -z "$structured_declaration" ]; then
+    refuse "a tracker creation through $tool_name" "$ready_role" ""
+  fi
+  exit 0
+fi
+
 verdict="$(
   printf '%s' "$classifier" |
     LISA_GUARD_COMMAND="$command_str" \

package/plugins/lisa/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

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/hooks/block-direct-issue-create.agy.sh

@@ -8,9 +8,19 @@
 # block-direct-issue-create.sh beside it (same delegation pattern as
 # block-instruction-file-edits.agy.sh).
 #
-# No scope gap here, unlike the instruction-file adapter: the canonical guard is
-# Bash-only by construction, and `run_command` is exactly the surface it needs.
-# agy therefore receives the whole guard, not an arm of it.
+# SCOPE GAP, recorded rather than silently dropped (AGENTS.md). This used to
+# read "no scope gap here: the canonical guard is Bash-only by construction, and
+# `run_command` is exactly the surface it needs." That stopped being true in
+# CodySwannGT/lisa#3753: the canonical guard now covers a SECOND substrate —
+# structured tool payloads, where a creation arrives as named fields rather than
+# as a command line — because the filing contract was enforced on the shell and
+# unenforced on every tool call beside it.
+#
+# This adapter forwards `run_command` and nothing else, so on agy that second
+# substrate is still uncovered. Closing it needs agy's own tool-call envelope
+# (which tool names its creation surface, and where the arguments land), and
+# that is a different piece of work from translating one protocol. The shell
+# surface agy does expose receives the whole guard, exactly as before.
 #
 # Fail-open on missing runtimes: a missed refusal costs one under-declared
 # ticket, and `lisa-repair-intake` already sweeps for exactly that. Failing

package/plugins/lisa-agy/hooks/block-direct-issue-create.sh

@@ -79,6 +79,36 @@
 # settings env block, CI config). An escape the governed agent reaches by
 # typing one more token in front of the command it was just refused is not an
 # escape hatch — it is the prose problem with extra steps.
+#
+# ## What this hook costs, and the number that would change the decision
+#
+# Registered `matcher: ""` since CodySwannGT/lisa#3753 — it runs on EVERY tool
+# call, not only Bash. Measured on a developer machine at load ~8-26, 50
+# invocations per row:
+#
+#     16.7 ms   enforce-team-first.sh          already `matcher: ""` today
+#     17.5 ms   enforce-verification-gate.sh   already `matcher: ""` today
+#     11.5 ms   this guard, non-Bash payload   what the broad matcher adds
+#    112.3 ms   this guard, Bash payload       what Bash calls already paid
+#
+# So the broad registration was not novel — two hooks were already there, this
+# one is cheaper than either, and it raises an existing ~34 ms per-call baseline
+# by about a third.
+#
+# THIS IS A THRESHOLD, NOT A PRECEDENT. The argument is about the TOTAL cost of
+# the broad set, so it does not transfer to the next guard: four more hooks
+# moved to `matcher: ""` would put ~90 ms on every tool call and the answer
+# flips. **Before widening any other hook's matcher, re-run the measurement and
+# reconsider if the broad set totals more than ~100 ms per tool call, or if any
+# single broad hook exceeds ~50 ms.** Do not cite these numbers for a fifth
+# hook; measure again, because the number that matters is the sum.
+#
+# The cost is also irreducible rather than sloppy. A 9-line script containing
+# only this file's preamble measured 11.7 ms, and padding it to this file's
+# length changed nothing (11.5 ms) — it is process spawn plus one `jq`, not
+# parsing. Moving the early exit further up the file buys nothing; the exit is
+# already ahead of config resolution, which is what keeps the figure at 11.5
+# rather than at the 112 ms the Bash path pays.
 set -euo pipefail
 
 input="$(cat)"
@@ -99,13 +129,72 @@ for required in jq python3; do
 done
 
 tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+
+# ── The two substrates ────────────────────────────────────────────────────
+#
+# A creation reaches a tracker two ways, and until CodySwannGT/lisa#3753 this
+# guard saw only one of them. It was registered `matcher: "Bash"` AND gated
+# here on `tool_name != "Bash"`, so an MCP tool call was refused entry twice
+# over. MEASURED before the change, driving the guard with synthetic payloads:
+#
+#   ALLOW   mcp__linear-server__create_issue, undeclared      <- the defect
+#   ALLOW   mcp__github__create_issue, undeclared             <- the defect
+#   REFUSE  the same creation as `gh issue create` shell text <- control
+#   ALLOW   an ordinary Read tool call                        <- control
+#
+# The two controls are what make those ALLOWs mean anything: the refusal proves
+# the guard is live, the Read proves it is not simply refusing everything.
+#
+# **Widening the matcher alone would have changed nothing** — the call would
+# arrive and this gate would still exit 0. Anyone who "fixed" #3753 by editing
+# `plugin.json` would have seen no test fail and shipped a guard that still
+# allows every MCP filing. The registration and this gate had to move together.
+#
+# The SHELL path below is untouched. A structured payload has no command line
+# to tokenise, so it gets its own small classifier rather than being forced
+# through a parser built for shell text.
+structured_call=""
 if [ "$tool_name" != "Bash" ]; then
-  exit 0
+  # The cheap shape gate, deliberately BEFORE config resolution.
+  #
+  # This hook now runs on EVERY tool call, so the cost of the path that does
+  # nothing is the cost of the whole change. Config resolution spawns two jq
+  # processes per lookup and is what makes the Bash path ~112 ms; putting it
+  # ahead of this gate would charge that to every Read and Grep. So the
+  # not-a-creation exit happens here, on a shell `case` with no subprocess.
+  #
+  # Matched on SHAPE, not on an enumerated list of server tool names. Server
+  # names are supplied by whoever wrote the server and change when one is
+  # added or renamed, so a list would pass every row anyone thought of and
+  # miss the first one nobody did — the failure mode this repository's guard
+  # suites are written to defeat.
+  #
+  # RESIDUAL, stated rather than hidden: a server whose creation tool is named
+  # without a create-verb or without a tracker noun (`mcp__x__file_work`) is
+  # not recognised and is allowed. That is a fail-open, and it is the honest
+  # cost of refusing to enumerate. Add shapes here as they are measured.
+  case "$tool_name" in
+    Bash | Read | Write | Edit | MultiEdit | Glob | Grep | Task | TodoWrite)
+      exit 0
+      ;;
+  esac
+  case "$tool_name" in
+    *[Cc]reate* | *[Nn]ew* | *[Aa]dd* | *[Ff]ile*) ;;
+    *) exit 0 ;;
+  esac
+  case "$tool_name" in
+    *[Ii]ssue* | *[Tt]icket* | *[Tt]ask* | *[Ss]tory* | *[Bb]ug* | *[Ee]pic* | *[Ww]ork*) ;;
+    *) exit 0 ;;
+  esac
+  structured_call="1"
 fi
 
-command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
-if [ -z "$command_str" ]; then
-  exit 0
+command_str=""
+if [ -z "$structured_call" ]; then
+  command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+  if [ -z "$command_str" ]; then
+    exit 0
+  fi
 fi
 
 project_dir="${CLAUDE_PROJECT_DIR:-}"
@@ -1859,6 +1948,53 @@ print("ALLOW")
 PY
 
 set +e
+# ── The structured substrate ──────────────────────────────────────────────
+#
+# An MCP call carries named fields, not a command line, so `scan()` — which
+# tokenises shell text — has nothing to parse. The declaration is read from the
+# payload instead, and the recogniser is deliberately small: this path decides
+# ONE question (is a build-ready role or a human-gate marker present anywhere
+# in the submitted fields), where the shell path has to answer "which of these
+# tokens is a client, an endpoint, a flag value, or a file it executes".
+#
+# Every string in the payload is searched, at any depth, because a role lands
+# in a different field on every tracker — `labels[]` on GitHub, `stateId` or a
+# workflow state name on Linear, a transition `id` on JIRA — and enumerating
+# field names per vendor is the same brittleness as enumerating tool names.
+# Over-collecting is safe here: the values are compared against ONE configured
+# role string, so an unrelated field cannot accidentally satisfy it.
+if [ -n "$structured_call" ]; then
+  # The operator's ambient escape works on both substrates. There is no inline
+  # form to disqualify it here — a structured call has no shell in which to
+  # assign one — so the override is simply honoured.
+  if [ -n "$ambient_override" ]; then
+    exit 0
+  fi
+
+  structured_declaration="$(
+    printf '%s' "$input" |
+      jq -r --arg role "$ready_role" '
+        [(.tool_input // {}) | .. | strings] as $values
+        | if ($values | index($role)) then "role"
+          elif ($values | map(select(contains("[lisa-human-gate]"))) | length) > 0 then "gate"
+          else "" end
+      ' 2>/dev/null || printf 'UNREADABLE'
+  )"
+
+  # Fail closed on a creation-shaped call whose payload cannot be read. Silence
+  # about a filing the guard could not inspect is the defect this whole ticket
+  # is about, one substrate over.
+  if [ "$structured_declaration" = "UNREADABLE" ]; then
+    refuse "an unreadable $tool_name payload that reads as a tracker creation" \
+      "$ready_role" ""
+  fi
+
+  if [ -z "$structured_declaration" ]; then
+    refuse "a tracker creation through $tool_name" "$ready_role" ""
+  fi
+  exit 0
+fi
+
 verdict="$(
   printf '%s' "$classifier" |
     LISA_GUARD_COMMAND="$command_str" \