@codyswann/lisa 4.74.8 → 4.75.0

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

@@ -0,0 +1,2603 @@
+#!/usr/bin/env bash
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
+# PreToolUse hook for Bash: refuse a direct tracker-creation command that
+# declares no readiness.
+#
+# WHY THIS IS A HOOK AND NOT A RULE
+#
+# The `ready-role-filing` rule says every filing declares either
+# `build_ready: true` or a `human_gate:` reason, and that filings go through
+# `lisa-track` / `lisa-tracker-write`. A conformance audit of the ~13 issues
+# filed during one working session found 13/13 bypassed it, with zero
+# `lisa-track` invocations — eight of them filed AFTER the rule merged, several
+# by the agent that wrote the rule. Over the same window `Co-Authored-By`
+# compliance was 50/50, because a husky `commit-msg` hook enforces it.
+#
+# Prose at the EAGER-RULE rung did not bind even its own author; the executable
+# control was never once violated. Lisa's `learnings-ladder` rule says
+# machine-checkable knowledge belongs at EXECUTABLE-CONTROL. This is that
+# promotion.
+#
+# WHAT IT CHECKS, AND WHY THAT AND NOT "DID YOU USE THE SKILL"
+#
+# A Bash-level hook cannot observe call provenance. Any provenance signal an
+# agent could carry — a flag, a marker, an env var — is settable by the very
+# agent being governed, so a guard built on one is theatre. What the hook CAN
+# observe is the artifact: whether the command about to run produces a
+# correctly declared work item. So it enforces the checkable half.
+#
+# A creation command is refused unless it carries a readiness declaration:
+#   - the project's configured build-ready role (GitHub label, JIRA/Linear
+#     workflow state) resolved from `.lisa.config.json`, never hard-coded;
+#   - on a tracker whose ready role is a STATE rather than a label, the
+#     `lifecycle_role: ready` declaration the access layer resolves that state
+#     from — because no flag on the mandated client can carry a state, and a
+#     guard with no satisfiable declaration is a guard that teaches lying; or
+#   - an explicit `[lisa-human-gate]` marker, inline or in the `--body-file`
+#     the create is about to submit.
+#
+# WHERE IT LOOKS
+#
+# argv, the request payload (inline, in a `--data-binary @file`, or piped in
+# over stdin from the same pipeline), and the contents of any file the command
+# names. The last of those is what CodySwannGT/lisa#3484 was: the guard
+# inspected argv and nothing else, so `bash /path/create.sh` showed it two
+# tokens and the creation was one file away. Lisa's own `parity-safety-net.sh`
+# tells agents to write payloads to a file and execute the file, so complying
+# with Lisa's guidance produced the bypass.
+#
+# That is exactly the machine-checkable content of `ready-role-filing`, and it
+# lets `lisa-github-write-issue` / `lisa-jira-write-ticket` /
+# `lisa-linear-write-issue` through by construction, because those writers
+# always stamp one. A blanket refusal would have blocked Lisa's own writers and
+# left the factory unable to file anything.
+#
+# Creation signatures, per tracker CLI and the two ways around each:
+#   gh issue create · gh api POST to .../issues · gh api graphql createIssue
+#   linear issue create · jira issue create · acli … workitem/issue create
+#   curl/http POST to api.github.com/…/issues, api.linear.app/graphql with
+#   issueCreate, or …atlassian.net/rest/api/…/issue
+# Reads never fire: `gh issue list`, `gh issue view`, `gh issue edit`,
+# `gh pr create`, `gh label create`, a bare `gh api …/issues` GET, and a prose
+# mention inside a quoted string are all allowed.
+#
+# STANDING DOWN
+#
+#   - No tracker configured (`.lisa.config.json` absent, or carrying no
+#     `tracker`). There is no `lisa-tracker-write` to route through, so the
+#     guard has nothing to redirect to. This is the bootstrapping case, and it
+#     is DETECTED rather than asserted — the operator does not have to remember
+#     an env var to bring up a new repo.
+#   - `LISA_ALLOW_DIRECT_ISSUE_CREATE` non-empty in the hook's inherited
+#     environment. This is the human operator's override, mirroring
+#     `LISA_ALLOW_INSTRUCTION_FILE_WRITE`.
+#
+# The override is honored ONLY from the ambient environment, and is refused
+# outright when it appears as an inline assignment in the intercepted command.
+# That distinction is the whole point: a tool-call shell is fresh every time
+# and its exports do not reach this hook's environment, so the ambient variable
+# can only have been set by a human before the session started (shell profile,
+# 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)"
+
+# Evaluate once per tool call when this guard is registered on both channels.
+#
+# Lisa reaches an agent through the repository dispatcher AND the plugin
+# manifest, and where both are live the harness runs this guard twice for one
+# tool call. `guard-dedupe.bash` short-circuits the second run ONLY when a
+# byte-identical copy already ALLOWED this exact payload on this exact tool
+# call; a differing vintage, a refusal, and a host with one channel all
+# evaluate exactly as before. Nothing is de-registered by it
+# (CodySwannGT/lisa#3814).
+#
+# Absent library means no dedupe, which is the pre-existing behaviour, so an
+# older channel copy that predates it is unaffected.
+lisa_guard_hook_dir="${BASH_SOURCE[0]%/*}"
+lisa_guard_dedupe_lib="$lisa_guard_hook_dir/guard-dedupe.bash"
+if [ -r "$lisa_guard_dedupe_lib" ]; then
+  # shellcheck source=guard-dedupe.bash
+  . "$lisa_guard_dedupe_lib"
+  trap 'lisa_guard_dedupe_record $?' EXIT
+  lisa_guard_dedupe block-direct-issue-create "$input"
+fi
+
+# Probe both interpreters before use and announce a missing one rather than
+# swallowing it. Under `set -e` an absent jq aborts with 127, and Claude Code
+# treats any non-2 exit as a NON-BLOCKING hook error — so the guard would
+# silently permit exactly what it exists to stop. Degrading to "allow" is
+# right (a hook that cannot parse its input cannot tell a filing from a read),
+# but doing it quietly is not: a guard that is silently absent reads exactly
+# like a guard that is passing. Same reasoning as block-no-verify.sh.
+for required in jq python3; do
+  if ! command -v "$required" >/dev/null 2>&1; then
+    printf 'block-direct-issue-create: %s not found; ready-role filing enforcement is NOT active\n' \
+      "$required" >&2
+    exit 0
+  fi
+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
+  # 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 | \
+      TaskCreate | TaskGet | TaskList | TaskOutput | TaskStop | TaskUpdate)
+      # The `Task*` family is Claude Code's in-session task list — LOCAL
+      # scratch, not a tracker write. `TaskCreate` carries `"type": "bug"`
+      # metadata the lisa-implement skill itself prescribes, so its name
+      # satisfies both shape gates below (create-verb + task noun) and was
+      # refused as "a tracker creation through TaskCreate"
+      # (CodySwannGT/lisa#4274). MCP creations are namespaced `mcp__*__*` and
+      # can never collide with a bare built-in name, so enumerating the
+      # built-ins here does not reopen the shape matcher for real filings.
+      exit 0
+      ;;
+  esac
+  # These terminal actions edit an existing item, not create the item.
+  # Strip only the measured action shape, then still inspect any preceding
+  # compound operation: create_issue_and_add_issue_comment remains a filing.
+  creation_name="$tool_name"
+  case "$creation_name" in
+    *[Aa]dd_[Ii]ssue_[Cc]omment)
+      creation_name="${creation_name%[Aa]dd_[Ii]ssue_[Cc]omment}" ;;
+    *[Aa]dd[Cc]omment[Tt]o[Jj]ira[Ii]ssue)
+      creation_name="${creation_name%[Aa]dd[Cc]omment[Tt]o[Jj]ira[Ii]ssue}" ;;
+    *[Aa]dd_[Cc]omment_[Tt]o_[Ii]ssue)
+      creation_name="${creation_name%[Aa]dd_[Cc]omment_[Tt]o_[Ii]ssue}" ;;
+    *[Aa]dd_[Ii]ssue_[Ll]abels)
+      creation_name="${creation_name%[Aa]dd_[Ii]ssue_[Ll]abels}" ;;
+    *[Aa]dd_[Ll]abels_[Tt]o_[Ii]ssue)
+      creation_name="${creation_name%[Aa]dd_[Ll]abels_[Tt]o_[Ii]ssue}" ;;
+    *[Aa]dd_[Rr]eaction_[Tt]o_[Ii]ssue_[Cc]omment)
+      creation_name="${creation_name%[Aa]dd_[Rr]eaction_[Tt]o_[Ii]ssue_[Cc]omment}" ;;
+  esac
+  case "$creation_name" in
+    *[Cc]reate* | *[Nn]ew* | *[Aa]dd* | *[Ff]ile*) ;;
+    *) exit 0 ;;
+  esac
+  case "$creation_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=""
+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:-}"
+if [ -z "$project_dir" ]; then
+  project_dir="$PWD"
+fi
+
+# Merged config, local overlay over base — the same precedence
+# `lisa-tracker-read` / `lisa-tracker-write` resolve with, so the guard can
+# never disagree with the writer about which tracker a project has.
+read_config_value() {
+  local filter="$1"
+  local value=""
+  local file
+  for file in "$project_dir/.lisa.config.json" "$project_dir/.lisa.config.local.json"; do
+    [ -f "$file" ] || continue
+    local candidate
+    candidate="$(jq -r "$filter // empty" "$file" 2>/dev/null || true)"
+    [ -n "$candidate" ] && value="$candidate"
+  done
+  printf '%s' "$value"
+}
+
+tracker="$(read_config_value '.tracker')"
+if [ -z "$tracker" ]; then
+  exit 0
+fi
+
+# The build-ready role is read from config, never hard-coded: a project that
+# renamed its ready lane must still be able to satisfy the guard, and the
+# refusal has to name the token that project actually uses.
+default_ready_role="status:ready"
+case "$tracker" in
+  github) ready_role="$(read_config_value '.github.labels.build.ready')" ;;
+  jira) ready_role="$(read_config_value '.jira.workflow.ready')" ;;
+  linear) ready_role="$(read_config_value '.linear.workflow.ready')" ;;
+  *) ready_role="" ;;
+esac
+if [ -z "$ready_role" ]; then
+  ready_role="$default_ready_role"
+fi
+
+# WHICH REPOSITORY'S VOCABULARY ANSWERS FOR THIS FILING
+#
+# The role above is the CALLING project's. For a same-repo filing that is the
+# right question. For a filing addressed at a DIFFERENT repository — which
+# Lisa ships a first-class, cron-driven path for in `lisa-persist-learning` —
+# it is the wrong repository's vocabulary, and the guard demanded a token the
+# target does not carry:
+#
+#   - a JIRA or Linear caller's ready role is a workflow STATE. Demanded as a
+#     `gh --label` on another repo it is unsatisfiable, because that label does
+#     not exist there and `gh` rejects an unknown one. Obeying the guard made
+#     the command fail, which is not the same thing as being refused.
+#   - a GitHub caller that renamed its ready lane demanded its own token of a
+#     repository that never had it.
+#   - a GitHub caller on the stock lane worked only because both repositories
+#     happened to choose the same string. That is a coincidence, not routing.
+#
+# The one escape that IS satisfiable cross-repo, `[lisa-human-gate]`, is a lie
+# about the item: it stamps a build-ready defect report as held for a human
+# product call, and the target's build queue scans the ready role and nothing
+# else. The report is filed and never picked up — precisely the incomplete
+# handoff this guard exists to prevent, committed one repository over.
+#
+# So the target's own role answers, resolved from CONFIG rather than the
+# network. A live `gh api repos/<o>/<r>/labels` lookup would be more general
+# and is the wrong trade for a PreToolUse hook: a network round-trip on every
+# intercepted command, and a new fail-open surface when it errors.
+own_org="$(read_config_value '.github.org')"
+own_name="$(read_config_value '.github.repo')"
+own_repo=""
+if [ -n "$own_org" ] && [ -n "$own_name" ]; then
+  own_repo="$own_org/$own_name"
+fi
+
+# `hardening.upstreamRepo` already names the upstream repository across Lisa's
+# filing skills; `hardening.upstreamReadyRole` is its sibling, so the guard
+# keeps its existing discipline — read the role from config, never hard-code it
+# — while reading it from the RIGHT repository's config.
+upstream_repo="$(read_config_value '.hardening.upstreamRepo')"
+if [ -z "$upstream_repo" ]; then
+  upstream_repo="CodySwannGT/lisa"
+fi
+upstream_ready_role="$(read_config_value '.hardening.upstreamReadyRole')"
+if [ -z "$upstream_ready_role" ]; then
+  upstream_ready_role="$default_ready_role"
+fi
+
+# A non-GitHub caller's ready role is a workflow STATE, so it is never the right
+# vocabulary for a GitHub target no matter what the target turns out to be. The
+# classifier needs to know that even when this project declares no repo of its
+# own to compare against.
+caller_is_github="0"
+if [ "$tracker" = "github" ]; then
+  caller_is_github="1"
+fi
+
+# Ambient-only override. Deliberately read here, from the hook process's own
+# environment, and never from the command being inspected.
+ambient_override="${LISA_ALLOW_DIRECT_ISSUE_CREATE:-}"
+
+# How to write the declaration down on THIS project's tracker. The answer is
+# not the same everywhere, and printing the GitHub answer at a Linear operator
+# is what made this guard unsatisfiable: it named a `--label` flag that the
+# mandated client does not have, on a role that is not a label.
+declaration_hint() {
+  case "$tracker" in
+    jira | linear)
+      cat <<EOF
+   Your build-ready role \`$ready_role\` is a workflow STATE, not a label, and
+   the mandated client is \`curl\` — which has no flag that carries a state. So
+   declare the LIFECYCLE ROLE the access layer resolves the state from, and let
+   it do the resolving:
+
+     LIFECYCLE_ROLE=ready curl -sS -X POST <the tracker endpoint> …
+
+   or \`lifecycle_role:ready\` in the request payload, or a \`--state\` /
+   \`--status\` flag where the CLI has one. The \`$tracker\` access layer takes
+   that role, resolves it against the tracker's own state catalog, and fails
+   CLOSED if it cannot — so the token is the input that decides the lane, not a
+   decoration.
+EOF
+      ;;
+    *)
+      cat <<EOF
+   The command has to carry the configured build-ready role \`$ready_role\` as
+   the value of a \`--label\` / \`--status\` / \`--state\` flag — not in the
+   title or body, because a role named in prose is not a role applied.
+EOF
+      ;;
+  esac
+}
+
+# The branch-specific half of the remediation, printed only for the branch that
+# fired. Every refusal this guard issues has to name an inverse the author can
+# actually perform — a refusal with none is a state change with no inverse, and
+# on a file-contents refusal it made a path permanently unnameable to any
+# command the guard did not recognise as a reader (CodySwannGT/lisa#3683).
+#
+# NEITHER PARAGRAPH IS AN ESCAPE HATCH, and that is deliberate. `3594` records
+# that a PreToolUse guard whose escape the guarded agent can set is not a
+# control, so nothing here is settable: the only inverses named are edits to
+# the refused command itself, and performing either one leaves a genuine
+# undeclared creation refused by the checks above. Re-quoting an unlexable
+# creation hands it to the parsed path, which refuses it; naming a document to
+# a reader files nothing, which is the whole point. The one true escape stays
+# what it was — an ambient variable a human exports before the session, which a
+# tool-call shell cannot reach because its exports do not survive into this
+# hook's environment.
+remedy_hint() {
+  case "${1:-}" in
+    unparseable)
+      cat <<'EOF'
+
+THIS COMMAND DID NOT LEX, so it was judged by pattern rather than by parse. An
+unbalanced quote is the cause, and an apostrophe in ordinary prose is the
+measured one. The pattern cannot separate a sentence about filing from a real
+filing hidden behind a trailing `#` comment, so it refuses both.
+
+THE INVERSE IS EXECUTABLE: re-quote the command so it lexes, and run it again.
+It is not a bypass — a re-quoted creation is handed to the full parser, which
+refuses it unless it declares readiness the ordinary way.
+
+A command whose every segment runs a known READER is not refused on this branch
+at all, so `cat`, `grep`, `ls`, `cp`, `mv`, `git` and `echo` never reach it.
+EOF
+      ;;
+    file)
+      cat <<'EOF'
+
+THIS REFUSAL CAME FROM A FILE THIS COMMAND RUNS. A path is opened only when the
+command puts it in a COMMAND position; a program that takes it as data — `cat`,
+`grep`, `ls`, `cp`, `mv`, `git`, a test runner — never reaches this branch. Two
+inverses, both executable:
+
+  - The file WRITES a payload locally and cannot transmit it (no HTTP client,
+    no CLI, no process spawn): it is read as data, not as a filing. Drop the
+    transmitting primitive, or slice the payload out of an existing file
+    instead of restating it here.
+  - The file produces no local artifact either — it is a DOCUMENT that quotes a
+    creation rather than a program that performs one. Name it to a reader
+    rather than to an interpreter; rewording its contents is not the remedy and
+    does not converge.
+EOF
+      ;;
+  esac
+}
+
+refuse() {
+  local signature="$1"
+  local roles="$2"
+  local target="$3"
+  local remedy="${4:-}"
+  if [ -n "$target" ]; then
+    refuse_cross_repo "$signature" "$roles" "$target"
+  fi
+  cat >&2 <<EOF
+BLOCKED: refusing \`$signature\` — this filing declares no readiness.
+
+WHY: a work item filed without the build-ready role is an incomplete handoff.
+Build-intake scans the ready lane and nothing else, so nothing will ever pick
+it up: the write succeeds and the work still dies. An audit of one working
+session found 13 of 13 issues filed this way, none of them through Lisa's
+filing path. The rule saying not to do this already existed — it did not bind,
+so it is now enforced here.
+
+FILE IT THE SANCTIONED WAY — one of these three, always explicit:
+
+1. The item is complete enough to build. Use the filing flow, not the CLI:
+
+     /lisa:track "<what needs building>"
+
+   which resolves or creates exactly one live leaf through
+   \`lisa-tracker-write\` with \`build_ready: true\`, validates it before the
+   write, and claims it. Complete means the \`work-item-definition-of-ready\`
+   bar — reproduction, observed-versus-expected, Gherkin acceptance criteria.
+
+2. A human product call is genuinely pending. Route the same way but pass
+   \`human_gate: "<why a human must judge this first>"\` in place of
+   \`build_ready: true\` — the two are mutually exclusive. The leaf is filed
+   into the default backlog role, outside the lane build-intake claims from,
+   and is deliberately NOT claimed, so it keeps attracting the human attention
+   it was filed for. The hold is stamped so it is auditable rather than
+   indistinguishable from an accident:
+
+     Held for a human product call: <reason>.
+     <!-- [lisa-human-gate] reason=<short-slug> -->
+
+3. The item is a CONTAINER — an Epic, or any item whose state rolls up from
+   its children. It is neither of the two above and must not pretend to be:
+   \`leaf-only-lifecycle\` FORBIDS the build-ready role on a container, and a
+   human gate it does not have is a durable false hold. It declares the third
+   thing instead — the canonical container line, in place of a Target Backend
+   Environment:
+
+     ## Target Backend Environment
+
+     None — container: state rolls up from children
+
+   That declaration is refused alongside a by-design leaf type
+   (\`type:Bug\` / \`type:Task\` / \`type:Sub-task\` / \`type:Improvement\`):
+   an item cannot be a container and a leaf at once.
+
+Filed, not ready, and no \`human_gate\` is the incomplete-handoff case, and
+\`build_ready: false\` with no reason is the same omission with a value
+attached. See the \`ready-role-filing\` rule for the full contract.
+
+If you must run the CLI directly, the command has to carry one of the three
+declarations itself:
+
+$(declaration_hint)
+
+   Or a \`[lisa-human-gate]\` marker in the body it submits, when a human
+   product call really is pending.
+
+   Or, for a container, \`None — container: state rolls up from children\` in
+   that body, and no by-design leaf type on the command.
+
+WHERE THE DECLARATION IS READ FROM: argv, the request payload — inline, in a
+\`--data-binary @file\`, or piped in over stdin — and the contents of a script
+this command runs. Moving the create into a file no longer moves it out of
+sight, so the declaration can live wherever the create does.
+
+$(remedy_hint "$remedy")
+
+OPERATOR ESCAPE: a human can export \`LISA_ALLOW_DIRECT_ISSUE_CREATE=1\` in the
+environment before starting the session. It is deliberately not reachable by
+setting it inline on this command — an inline assignment is refused.
+EOF
+  exit 2
+}
+
+# The cross-repo refusal is a separate message, not a variable swapped into the
+# one above, because its REMEDIATION is different. The local filing flow writes
+# to this project's own tracker and structurally cannot reach another
+# repository, so naming it here would send the agent to a path that cannot do
+# the thing it was just refused for. Name the route that reaches the target,
+# and name the target's role rather than this project's.
+refuse_cross_repo() {
+  local signature="$1"
+  local roles="$2"
+  local target="$3"
+  cat >&2 <<EOF
+BLOCKED: refusing \`$signature\` — this filing declares no readiness.
+
+WHY: a work item filed without the build-ready role is an incomplete handoff.
+Build-intake scans the ready lane and nothing else, so nothing will ever pick
+it up: the write succeeds and the work still dies.
+
+THIS FILING IS ADDRESSED AT ANOTHER REPOSITORY: \`$target\`.
+That repository runs its own build queue off its own ready role, so this
+project's role does not answer for it — and this project's filing flow writes
+to this project's tracker, so it cannot reach the target at all.
+
+FILE IT THE SANCTIONED WAY:
+
+1. An upstream defect or hardening report — the highest-signal report there is,
+   because it is reproduced and attributed rather than guessed at. Use the
+   upstream filing path, which composes a redacted, public-safe body through an
+   allowlist projection instead of free-form prose:
+
+     bunx @codyswann/lisa file-upstream --input <filing-event>.json
+
+   \`lisa-persist-learning\` step 6 runs exactly this, headless, on a cron, and
+   files the result with explicit \`build_ready: true\` so the target's queue
+   picks it up.
+
+2. If you must run the CLI directly, the command has to carry the TARGET
+   repository's build-ready role — \`$roles\` — as the value of a \`--label\`
+   flag. Configure it as \`hardening.upstreamReadyRole\` when the target renamed
+   its lane.
+
+DO NOT reach for \`[lisa-human-gate]\` to get past this one. It still satisfies
+the guard — it is a real declaration — but on an upstream defect report it is a
+false one: it stamps the item as held for a human product call, and the
+target's build queue scans the ready role and nothing else. The report is filed
+and never picked up, which is the incomplete handoff this guard exists to
+prevent, committed one repository over. Use it only when a human product call
+is genuinely pending on the target.
+
+OPERATOR ESCAPE: a human can export \`LISA_ALLOW_DIRECT_ISSUE_CREATE=1\` in the
+environment before starting the session. It is deliberately not reachable by
+setting it inline on this command — an inline assignment is refused.
+EOF
+  exit 2
+}
+
+# The classifier is read into a variable with a top-level here-document rather
+# than piped straight in from inside `$( … )`. bash 3.2 — which is what macOS
+# still ships as /bin/bash, and therefore what this fleet's hooks run under —
+# mis-parses a here-document nested in a command substitution, scanning the
+# document body for quotes and parentheses it should be treating as literal.
+# The whole script then fails to parse, which is the worst possible failure for
+# a guard: a syntax error exits non-zero, and Claude Code reads every non-2
+# exit as a non-blocking hook error, so the command runs unchecked.
+classifier=""
+read -r -d '' classifier <<'PY' || true
+import os
+import re
+import shlex
+import sys
+
+command = os.environ.get("LISA_GUARD_COMMAND", "")
+ready_role = os.environ.get("LISA_GUARD_READY_ROLE", "")
+ambient_override = os.environ.get("LISA_GUARD_AMBIENT_OVERRIDE", "")
+default_ready_role = os.environ.get("LISA_GUARD_DEFAULT_READY_ROLE", "")
+own_repo = os.environ.get("LISA_GUARD_OWN_REPO", "").strip().lower()
+upstream_repo = os.environ.get("LISA_GUARD_UPSTREAM_REPO", "").strip().lower()
+upstream_ready_role = os.environ.get("LISA_GUARD_UPSTREAM_READY_ROLE", "")
+caller_is_github = os.environ.get("LISA_GUARD_CALLER_IS_GITHUB", "") == "1"
+tracker = os.environ.get("LISA_GUARD_TRACKER", "").strip().lower()
+project_dir = os.environ.get("LISA_GUARD_PROJECT_DIR", "")
+
+OVERRIDE_NAME = "LISA_ALLOW_DIRECT_ISSUE_CREATE"
+HUMAN_GATE_MARKER = "[lisa-human-gate]"
+
+# Decoration a hold declaration may sit behind, and nothing more: whitespace,
+# blockquote arrows, list bullets or numbers, emphasis, an opening HTML
+# comment. One character class plus two optional groups, deliberately not a
+# nested quantifier — this runs over untrusted issue bodies.
+HUMAN_GATE_DECORATION = re.compile(r"^[ \t>*_+#-]*(?:\d+[.)][ \t]*)?(?:<!--[ \t]*)?[ \t]*")
+HUMAN_GATE_FENCE = re.compile(r"```.*?```", re.DOTALL)
+HUMAN_GATE_CODE_SPAN = re.compile(r"`[^`\n]*`")
+
+
+def declares_human_gate(text):
+    """Whether a text DECLARES a hold rather than mentioning one.
+
+    The comment this replaces said the marker is matched anywhere because it
+    "has no other meaning, so its presence in the title or body IS the
+    declaration". That was true when written and is false now: the marker
+    acquired a second meaning -- being discussed -- the moment the feature
+    became something people file tickets about, and a ticket about the marker
+    then declares a hold on itself (CodySwannGT/lisa#3815).
+
+    A declaration is POSITIONAL: the marker leads its line, behind at most the
+    decoration above, with fenced blocks and inline code spans removed first
+    because that is how the marker is written ABOUT. The same rule the intake
+    matcher applies, so the two surfaces cannot disagree about one body.
+
+    NOTE the direction here differs from the intake matcher's. There a match
+    HOLDS an item, so a false positive parks work. Here a match ADMITS a
+    filing, so a false positive is a hole -- which makes this the tightening
+    direction on both sides at once.
+
+    Args:
+        text: Any candidate text -- one argv value, a body file, a payload.
+
+    Returns:
+        True when some line of the text declares a hold.
+    """
+    if not text:
+        return False
+    body = HUMAN_GATE_CODE_SPAN.sub("", HUMAN_GATE_FENCE.sub("", str(text)))
+    for line in body.split("\n"):
+        if HUMAN_GATE_DECORATION.sub("", line, count=1).startswith(
+            HUMAN_GATE_MARKER
+        ):
+            return True
+        if _comment_carries_marker(line):
+            return True
+    return False
+
+
+def _comment_carries_marker(line):
+    """Whether an HTML comment on this line carries the marker.
+
+    The second accepted form, and the one this guard needs most: its inputs
+    are not markdown documents. A `--body` value is a single line, and a shell
+    script writes its declaration as `# <!-- ... -->`, so a purely
+    line-leading rule would refuse two declarations people have already
+    written -- both of which are in this repository's own test corpus.
+
+    It is not a loosening. An HTML comment is invisible when rendered, so
+    nobody wraps one around the marker in order to TALK about it; a quotation
+    has to be visible to be a quotation. Measured over this repository's 42
+    matching issue bodies, adding this branch changes not one verdict.
+
+    Args:
+        line: One line of text.
+
+    Returns:
+        True when some comment on the line contains the marker.
+    """
+    segments = line.split("<!--")
+    for segment in segments[1:]:
+        close = segment.find("-->")
+        inside = segment if close == -1 else segment[:close]
+        if HUMAN_GATE_MARKER in inside:
+            return True
+    return False
+
+# ---------------------------------------------------------------------------
+# WHY THIS IS A TOKEN SCAN AND NOT A PROGRAM RESOLVER
+#
+# The first version of this classifier asked "what program is being invoked?"
+# and answered it by stripping a fixed allowlist of wrapper programs. That
+# question is unbounded, so the allowlist could never be complete, and every
+# gap failed OPEN: an unrecognised prefix became the resolved program,
+# classification returned "not a creation", and the guard allowed. A
+# branch-enumerating probe found 36 fail-opens, including `nice -n 10 gh issue
+# create` — and `nice` is POSIX, present on every host, so one prepended token
+# defeated the whole control end to end.
+#
+# Enumerating command SHAPES had scored 21/21 against that same code. The
+# lesson is the method, not the list: probe the parser's decision points
+# (tokenise, split, locate, classify, declare), not the attacks you can think
+# of.
+#
+# So the question is inverted. Instead of "what program is this?" — unbounded —
+# the classifier asks "does this command line invoke a tracker CLI in a
+# creation mode?", which is bounded by a tracker list we already maintain.
+# Every token is examined; anything before the CLI token is irrelevant by
+# construction. `nice`, `stdbuf`, `caffeinate`, `xcrun`, `arch`, `script`,
+# `timeout`, `env -i`, `sudo -u`, `xargs -I{}`, absolute paths, and every
+# wrapper nobody has thought of yet all collapse into one code path.
+#
+# THE DEFAULT ANSWER TO "I DO NOT UNDERSTAND THIS" IS NOW REFUSE.
+# Tokenisation failure, a nesting bound, an unparsed operand: each refuses with
+# an explanation rather than passing. An operator who hits a false refusal says
+# so and the recogniser widens; an agent who hits a false allow says nothing,
+# which is the entire problem.
+# ---------------------------------------------------------------------------
+
+# Tracker CLIs. Bounded and reviewable, unlike the wrapper space.
+TRACKER_CLIS = {"gh", "jira", "linear", "acli"}
+HTTP_CLIS = {"curl", "http", "httpie", "wget"}
+
+# Text that looks like a tracker creation even when it cannot be tokenised.
+# Used ONLY on the tokenise-failure path, where the choice is between refusing
+# and permitting something we demonstrably cannot read. Deliberately narrower
+# than "mentions a tracker CLI" so an ordinary unparseable command
+# (`echo 'it's fine`) still passes.
+UNPARSEABLE_CREATION = re.compile(
+    r"\b(?:gh|jira|linear)\b[^\n]*?\bissue\b[^\n]*?\bcreate\b"
+    r"|\bacli\b[^\n]*?\b(?:workitem|issue)s?\b[^\n]*?\bcreate\b"
+    r"|\bcreateIssue\b|\bissueCreate\b"
+    r"|repos/[^/\s]+/[^/\s]+/issues"
+    r"|atlassian\.net/rest/api/[^/\s]+/issue",
+    re.IGNORECASE,
+)
+
+BODY_FILE_FLAGS = {"--body-file", "-F", "--input", "--data-binary"}
+LABEL_FLAGS = {"--label", "--labels", "--add-label", "--status", "--state"}
+
+# ---------------------------------------------------------------------------
+# THE THIRD DECLARATION: THIS ITEM IS A CONTAINER
+#
+# The two declarations above are both illegitimate for a container, and the
+# rules say so in as many words. `leaf-only-lifecycle` FORBIDS the build-ready
+# role on an Epic — its state rolls up from its children, and a hand-applied
+# role on a parent is the exact input that rule's claim-time arm exists to
+# reject. `lisa-github-write-issue` says a container needs no human gate.
+# So a guard with only those two arms could be satisfied for a container only
+# by writing something untrue, and BOTH untruths corrupt data another control
+# reads: a stamped role puts a container in the build lane, and a fabricated
+# hold marker is a state change with no inverse that reads to every later
+# observer as a real product hold. A guard that can only be obeyed by lying is
+# worse than one that simply refuses, because the lie is indistinguishable from
+# a correct filing afterwards.
+#
+# WHY NOT `--label type:Epic`
+#
+# Because a declared type is a CLAIM, and one that costs a leaf nothing: the
+# item it produces still looks buildable, so the exemption would be a free
+# bypass of the readiness requirement for anything willing to mistype itself.
+# That is the shape of this repository's measured case where an allowlist added
+# to harden a guard became the way around it.
+#
+# WHAT IS READ INSTEAD
+#
+# The canonical container declaration the `derived-branch-plan` rule already
+# defines and `lisa-github-write-issue` already stamps, in place of a Target
+# Backend Environment:
+#
+#   None — container: state rolls up from children
+#
+# It is a marker with no other meaning, so it is matched wherever the payload
+# reaches — the asymmetry `HUMAN_GATE_MARKER` gets, and for the related
+# reason. Reading the declaration the writer already emits is also what keeps
+# the guard and the skill from drifting apart a second time: there is one
+# string, defined in one rule, and both read it.
+#
+# It is self-limiting in a way a type label is not. Writing it costs the item
+# its Target Backend Environment and its Branch Plan — the two fields a leaf
+# needs to be built at all — so the declaration is only useful to something
+# that actually is a container. A leaf that writes it does not smuggle a
+# buildable item past the gate; it files an unbuildable one, in the lane
+# `leaf-only-lifecycle` and `lisa-repair-intake` already sweep.
+#
+# The WHOLE canonical value, `None` included, not just the distinctive tail.
+# Dropping the leading half would match ordinary prose about how a container's
+# state behaves — including a bug report ABOUT this guard — and a declaration
+# that ordinary prose satisfies is not a declaration. Whitespace-tolerant
+# because a body file may wrap the line; dash-tolerant because an author
+# retyping it by hand will not always reach for the em dash.
+CONTAINER_DECLARATION = re.compile(
+    r"None\s*[\u2014\u2013-]\s*container:\s*state\s+rolls\s+up\s+from\s+children",
+    re.IGNORECASE,
+)
+# The checkable half of "is it really a container". Provenance is unobservable
+# here, as the header notes, but a CONTRADICTION is not: an item cannot be a
+# container and a by-design leaf at once. Quoted from `leaf-only-lifecycle` —
+# "the by-design leaf types (Bug, Task, Sub-task, Improvement)". Story and
+# Spike are deliberately ABSENT: the same rule's childless-parent exception
+# makes them leaf-or-container depending on child work, and a decomposition
+# legitimately files a parent Story before the children that make it one.
+BY_DESIGN_LEAF_TYPES = {"bug", "task", "sub-task", "subtask", "improvement"}
+# Where a declared type can land on the created item. The label spellings are
+# GitHub's `type:<value>` convention; `--type` and its aliases are the JIRA and
+# Linear clients' spelling. Read with the same positional discipline as the
+# build-ready role — a type named in a title or body is not a type applied.
+TYPE_FLAGS = {
+    "--label", "--labels", "--add-label",
+    "--type", "--issue-type", "--issuetype",
+}
+POST_METHOD_FLAGS = {"-X", "--request", "--method"}
+POST_PAYLOAD_FLAGS = {
+    "-d", "--data", "--data-raw", "--data-binary",
+    "-f", "-F", "--raw-field", "--field", "--input",
+}
+# Flags whose VALUE is a payload field. `-f path=repos/o/r/issues` must not be
+# read as an endpoint: it is data being sent, not the address being posted to.
+PAYLOAD_VALUE_FLAGS = {"-f", "-F", "--raw-field", "--field"}
+
+# Matched against a token's PATH COMPONENT, never the raw argument — see
+# `endpoint_path`. The `$` anchor is load-bearing and stays: without it
+# `repos/o/r/issues/123/comments` reads as a creation, which is a different
+# operation this guard must not refuse. The segment classes exclude `?` and
+# `#` so the anchor cannot be reached past a decoration even if some future
+# caller forgets to parse first.
+GITHUB_ISSUES_PATH = re.compile(r"repos/[^/\s?#]+/[^/\s?#]+/issues/?$")
+GITHUB_ISSUES_URL = re.compile(r"api\.github\.com/repos/[^/\s]+/[^/\s]+/issues")
+# The repository a creation is ADDRESSED at, which decides whose ready role
+# answers for it. `gh` accepts the flag before or after the subcommand and in
+# either spelling, and the REST paths carry the same pair positionally.
+REPO_FLAGS = {"--repo", "-R"}
+GITHUB_ISSUES_PATH_REPO = re.compile(
+    r"repos/([^/\s?#]+)/([^/\s?#]+)/issues/?$"
+)
+GITHUB_ISSUES_URL_REPO = re.compile(
+    r"api\.github\.com/repos/([^/\s]+)/([^/\s]+)/issues"
+)
+JIRA_ISSUE_URL = re.compile(r"atlassian\.net/rest/api/[^/\s]+/issue")
+GRAPHQL_CREATE = re.compile(r"createIssue|issueCreate")
+
+# ---------------------------------------------------------------------------
+# REACH: THE COMMAND IS NOT THE ONLY TEXT THAT RUNS
+#
+# The classifier above asks the right question of the wrong text. It examines
+# argv, and argv is not where a creation has to live:
+#
+#   bash /tmp/create.sh          # URL and `issueCreate` both inside the script
+#   node wrapper.mjs --state x   # same, in JavaScript
+#   curl … --data-binary @p.json # URL in argv, mutation in the file
+#
+# All three ALLOWED, verified by driving the guard with synthetic payloads
+# (CodySwannGT/lisa#3484). The detection is a CONJUNCTION — an endpoint token
+# AND a creation verb in the SAME inspected command — so moving either half one
+# file away means the conjunction never forms. `bash <path>` shows the
+# classifier two tokens, neither of which is a tracker CLI.
+#
+# It is not an oversight that an operator had to be clever to find. Lisa's OWN
+# guards instruct agents into this shape: `parity-safety-net.sh` refuses
+# heredocs and says "write the payload to a file with the Write tool, then
+# execute that file directly", and `block-shell-json-parsing.sh` pushes JSON
+# construction into `jq` scripts. An agent complying perfectly with Lisa's
+# guidance lands in the uninspected path BY DEFAULT. The guards were
+# individually reasonable and jointly self-defeating.
+#
+# The fix follows this file's own inverted method. Enumerating interpreters —
+# bash, sh, zsh, ksh, dash, python3, node, bun, deno, ruby, perl, `./script`,
+# `source`, `env bash` — is the unbounded question all over again, and every
+# gap in it fails OPEN. So the question is inverted the same way the wrapper
+# question was: instead of "which programs execute their operands?", the
+# classifier asks "does this command name a readable file whose CONTENTS read
+# as an undeclared tracker creation?" — bounded by the tokens actually present.
+#
+# THE COST IS STATED, NOT HIDDEN. `cat create.sh` and `git add create.sh` are
+# refused too, because proving that a program does NOT execute its operand
+# requires exactly the allowlist this file already refuses to keep. That is the
+# documented direction of failure: an operator who hits a false refusal says
+# so, an agent who hits a false allow says nothing.
+FILE_OPERAND_MAX_BYTES = 262144
+FILE_OPERANDS_PER_SEGMENT = 8
+# Payload sources. A creation's mutation text may arrive inline, from a file,
+# or over stdin from an earlier stage of the same pipeline.
+PAYLOAD_SOURCE_FLAGS = {
+    "-d", "--data", "--data-raw", "--data-binary", "--data-ascii",
+    "--data-urlencode", "--input", "-F", "--form", "--upload-file", "-T",
+}
+STDIN_PAYLOAD_TOKENS = {"-", "@-"}
+# A tracker endpoint appearing anywhere in a file's text. Paired with
+# GRAPHQL_CREATE as a CONJUNCTION, so an ordinary file that merely mentions
+# `issueCreate` in prose — a changelog, a test name, a code comment — does not
+# read as a creation on its own.
+TRACKER_ENDPOINT = re.compile(
+    r"api\.linear\.app/graphql"
+    r"|api\.github\.com"
+    r"|atlassian\.net/rest/api"
+    r"|repos/[^/\s?#'\"]+/[^/\s?#'\"]+/issues",
+    re.IGNORECASE,
+)
+
+# ---------------------------------------------------------------------------
+# A PAYLOAD HELD AS DATA IS NOT A SUBMISSION
+#
+# The conjunction above — an endpoint AND a creation verb in one file — cannot
+# tell a payload being WRITTEN AS TEST DATA from one about to be SUBMITTED.
+# Measured (CodySwannGT/lisa#3943): a helper that assembles test fixtures, and
+# holds a mutation body as a string constant it writes to a fixture file, was
+# refused as "a tracker creation inside <path>". It submits nothing. The same
+# helper rewritten to SLICE the payload out of an existing file was allowed —
+# so the discriminator was the literal, not the behaviour.
+#
+# The behaviour that separates them is EGRESS. A file can only file an issue if
+# it can hand its bytes to another host or another process. A file with no such
+# primitive anywhere in it cannot submit whatever its constants spell, so the
+# conjunction is reading data.
+#
+# BOTH HALVES ARE REQUIRED, and the second one is why this is not a hole. The
+# exemption needs POSITIVE evidence that the file produces a local artifact
+# (`LOCAL_WRITE`) as well as the ABSENCE of egress, so it is bounded to the
+# measured population — a fixture writer — rather than granted to any file that
+# happens to use a transport nobody enumerated. Egress is over-matched on
+# purpose: every miss in `PAYLOAD_EGRESS` widens the exemption, so the list
+# reaches for `.post(`-shaped calls and process spawning as well as named HTTP
+# clients, and a file doing both is refused. That is the guard's usual
+# direction of failure — a false refusal is reported, a false allow is silent.
+#
+# RESIDUAL, stated rather than hidden: a submitting file that ALSO writes a
+# local artifact and reaches the network through a primitive no pattern here
+# names is allowed. Nothing about `text_declares_readiness`, the nested shell
+# scan, the unparseable arm, or the argv path is weakened — this reads only the
+# coarse conjunction, which is the only arm that ever inferred a submission
+# from contents alone.
+PAYLOAD_EGRESS = re.compile(
+    # Clients and trackers, by name.
+    r"\bcurl\b|\bwget\b|\bhttpie\b|\bgh\b|\bjira\b|\bacli\b"
+    r"|requests\.|httpx|aiohttp|pycurl|urllib|urlopen|http\.client|\bsocket\b"
+    r"|https?connection|httpurlconnection|httpclient|httprequest|webclient"
+    r"|okhttp|net::http|restclient|faraday|httparty|open-uri|\blwp\b|http::tiny"
+    r"|curl_init|curl_exec|guzzle|fsockopen|file_get_contents"
+    r"|\bfetch\s*\(|axios|xmlhttprequest|node-fetch|undici|superagent"
+    r"|http\.post|http\.newrequest"
+    # Handing the payload to another process, which can carry it anywhere.
+    r"|subprocess|os\.system|popen|child_process|execsync|spawnsync"
+    r"|\bspawn\s*\(|\bexec\s*\(|\bsystem\s*\(|bun\.spawn|deno\.command"
+    # The shape a send takes in almost any language, whatever the client is
+    # called. Over-matching here costs an exemption, never a refusal.
+    r"|\.post\s*\(|\.put\s*\(|\.patch\s*\(|\.request\s*\(|\.send\s*\("
+    r"|\.execute\s*\(|\.mutate\s*\(|\.do\s*\(",
+    re.IGNORECASE,
+)
+# Producing a local artifact: the positive half of the exemption.
+LOCAL_WRITE = re.compile(
+    r"\.write\s*\(|\.writelines\s*\(|write_text\s*\(|write_bytes\s*\("
+    r"|writefilesync|writefile\s*\(|createwritestream|outputstream"
+    r"|ioutil\.writefile|\btee\b"
+    # A shell redirect. Anchored on a separator so `=>` and `->` are not read
+    # as one, and required to be followed by something path-shaped.
+    r"|(?:^|[\s;&|(])>>?\s*[\"']?[\w./$~-]",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def payload_is_inert(text):
+    """Whether this file HOLDS a creation payload rather than submitting one.
+
+    Args:
+        text: The file's contents.
+
+    Returns:
+        True when the file writes a local artifact and carries no primitive
+        capable of transmitting anything.
+    """
+    return (
+        LOCAL_WRITE.search(text) is not None
+        and PAYLOAD_EGRESS.search(text) is None
+    )
+
+
+# ---------------------------------------------------------------------------
+# DECLARING BUILD-READY WHEN THE ROLE IS A STATE AND NOT A LABEL
+#
+# `declares_readiness` accepted the build-ready role only as the value of a
+# LABEL_FLAGS flag in argv. That is well-formed for a LABEL-based tracker and
+# structurally impossible for a STATE-based one:
+#
+#   - GitHub's ready role is a label, labels are argv-native (`--label`), so
+#     `flag_values` finds it and an honest command exists.
+#   - JIRA's and Linear's ready roles are workflow STATES. The mandated access
+#     path is raw `curl` to a GraphQL/REST endpoint, `curl` has no `--state`
+#     flag, and the state lives in the request payload as an ID the guard
+#     cannot resolve without a network round-trip it refuses to make.
+#
+# So on a Linear-tracked project the only declaration left that passed was
+# `[lisa-human-gate]`, which this file's own comments correctly forbid for a
+# build-ready item: it stamps the item as held for a human product call, and
+# build-intake scans the ready role and nothing else. An honest operator had NO
+# compliant command and exactly one dishonest one — a guard failing in the
+# harmful direction, where complying is worse than not.
+#
+# The declaration accepted here for state-based trackers is the LIFECYCLE ROLE
+# the access layer already consumes. `lisa-linear-access` refuses to accept a
+# caller-supplied `stateId`; it takes `lifecycle_role:<ROLE>`, resolves it
+# against config and the team's own state catalog through
+# `linear-state-write-target.mjs`, and fails CLOSED when it cannot. So the role
+# token is not decoration: it is the input that decides which lane the item
+# lands in, and a command carrying it either places the item in the ready lane
+# or refuses. That is the same epistemic standing as `--label status:ready`,
+# whose effect also happens one layer down inside `gh`.
+#
+# Scoped deliberately: accepted ONLY when the configured tracker's ready role
+# is a state, and ONLY for a filing addressed at this project's own tracker. A
+# GitHub filing — same-repo or cross-repo — still has to carry the label,
+# because for GitHub the label IS expressible and a second, weaker spelling
+# would be a hole rather than a remedy.
+STATE_ROLE_TRACKERS = {"jira", "linear"}
+#
+# The optional quote AFTER the key name is load-bearing, not decoration. Both
+# refusal messages tell the operator to put the declaration in the request
+# payload, and a JSON payload quotes its keys — so a pattern demanding `[:=]`
+# immediately after a bare key name refuses `"lifecycle_role": "ready"`, which
+# is the exact spelling it just asked for. Caught by review before it shipped.
+LIFECYCLE_ROLE_READY = re.compile(
+    r"(?:^|[^\w.-])(?:lifecycle_role|LIFECYCLE_ROLE)[\"']?\s*[:=]\s*[\"']?ready\b"
+    r"|(?:^|[^\w.-])--role[=\s]+[\"']?ready\b",
+)
+# Built per role at the point of use, because the role is project data. Kept
+# as a template rather than a compiled pattern so the role is always escaped.
+LABEL_FLAG_TEXT = r"--(?:label|labels|add-label|status|state)[=\s]+[\"']?%s(?![\w:.-])"
+
+MAX_NESTING_DEPTH = 3
+# Operators that can be GLUED to an adjacent word (`true&&gh issue create`),
+# so they must be split out of a token. Braces and parentheses are deliberately
+# absent: shlex collapses a quoted argument into one token, so a GraphQL
+# payload arrives as `query=mutation{issueCreate(input:{})…}` and splitting on
+# braces tore it into fragments — silently un-refusing every GraphQL creation.
+# Standalone grouping punctuation is handled at segment and basename level
+# instead, where it cannot reach into a payload's contents.
+GLUED_OPERATORS = ("&&", "||", ";;", ";", "|", "&")
+SEGMENT_BOUNDARIES = set(GLUED_OPERATORS) | {"(", ")", "{", "}"}
+
+
+def strip_full_line_comments(text):
+    """Blank lines beginning with `#` after optional whitespace.
+
+    This bounded fallback prevents ordinary prose comments from matching a
+    creation token after an apostrophe defeats shlex (CodySwannGT/lisa#3551).
+    It does not determine quote context: a leading `#` inside a multiline
+    string is also removed. This is a textual guard, not shell interpretation.
+
+    Args:
+        text: The raw command or file text.
+
+    Returns:
+        The text with whole-line comments blanked, line count preserved.
+    """
+    return "\n".join(
+        "" if line.lstrip().startswith("#") else line for line in text.split("\n")
+    )
+
+
+def strip_heredocs(text):
+    """Drop heredoc bodies so quoted prose cannot be read as argv.
+
+    Args:
+        text: The raw command string.
+
+    Returns:
+        The command with heredoc bodies removed.
+    """
+    lines = text.splitlines()
+    output = []
+    pending = []
+    marker_pattern = re.compile(
+        r"<<-?\s*(?:'([^']+)'|\"([^\"]+)\"|([A-Za-z_][A-Za-z0-9_]*))"
+    )
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        output.append(line)
+        pending.extend(
+            next(group for group in match.groups() if group)
+            for match in marker_pattern.finditer(line)
+        )
+        index += 1
+        while pending and index < len(lines):
+            if lines[index].strip() == pending[0]:
+                output.append(lines[index])
+                pending.pop(0)
+                index += 1
+                break
+            index += 1
+    return "\n".join(output)
+
+
+class LiteralToken(str):
+    """A source word containing quoted data, never a standalone separator."""
+
+
+def explode_operators(tokens, text=""):
+    """Separate unquoted operators without losing mixed-word quote boundaries.
+
+    Hide each quoted or escaped source fragment before the ordinary shlex pass.
+    Split operators while those fragments are opaque, then restore their values.
+    Per-occurrence placeholders cannot exempt a different, unquoted separator.
+    """
+    operators = re.compile("(" + "|".join(re.escape(op) for op in GLUED_OPERATORS) + ")")
+    if not text:
+        return [piece for token in tokens for piece in operators.split(token) if piece]
+
+    prefix = "__lisa_literal_"
+    while prefix in text:
+        prefix += "_"
+    values = []
+    fragments = re.compile(r"""'[^']*'|"(?:\\[\s\S]|[^"\\])*"|\\[\s\S]""")
+
+    def hide(match):
+        """Decode one protected fragment through the same POSIX lexer."""
+        value = shlex.split(match.group(0), posix=True)
+        values.append(value[0] if value else "")
+        return prefix + str(len(values) - 1) + "__"
+
+    masked = fragments.sub(hide, text)
+    marker = re.compile(re.escape(prefix) + r"(\d+)__")
+
+    def restore(value):
+        """Restore once, so decoded text cannot become another placeholder."""
+        return marker.sub(lambda match: values[int(match.group(1))], value)
+
+    shadow = shlex.split(masked, posix=True)
+    if [restore(token) for token in shadow] != tokens:
+        # If alignment cannot be established, grant no quoting exemptions.
+        return [piece for token in tokens for piece in operators.split(token) if piece]
+
+    exploded = []
+    for token in shadow:
+        for piece in operators.split(token):
+            if piece:
+                exploded.append(LiteralToken(restore(piece)) if marker.search(piece) else piece)
+    return exploded
+
+
+def segment(tokens):
+    """Split a token stream into individual commands at shell operators.
+
+    Args:
+        tokens: Exploded tokens.
+
+    Returns:
+        A list of argv lists.
+    """
+    segments = []
+    current = []
+    for token in tokens:
+        if token in SEGMENT_BOUNDARIES and not isinstance(token, LiteralToken):
+            segments.append(current)
+            current = []
+            continue
+        current.append(token)
+    segments.append(current)
+    return [item for item in segments if item]
+
+
+def basename(token):
+    """The final path component of a token, quotes stripped.
+
+    Args:
+        token: A shell token.
+
+    Returns:
+        The basename.
+    """
+    return token.strip("'\"").strip("(){}").rsplit("/", 1)[-1]
+
+
+def is_flag_value(args, index):
+    """Whether the token at `index` is the value of the preceding flag.
+
+    This is the single position question the classifier keeps having to ask,
+    and getting it wrong is what produced three separate bypasses: the role
+    read from a `--title`, the role read past `--`, and a subcommand read as a
+    flag's value. It is answered in exactly one place now.
+
+    Args:
+        args: A command's arguments.
+        index: The position to test.
+
+    Returns:
+        True when the previous token is a flag that carries no `=`.
+    """
+    if index == 0:
+        return False
+    previous = args[index - 1]
+    return previous.startswith("-") and previous != "-" and "=" not in previous
+
+
+def bare_index(args, word, start=0):
+    """Index of `word` appearing as itself rather than as a flag's value.
+
+    Args:
+        args: A command's arguments.
+        word: The word to locate.
+        start: Index to search from.
+
+    Returns:
+        The index, or -1.
+    """
+    for index in range(start, len(args)):
+        if args[index] == word and not is_flag_value(args, index):
+            return index
+    return -1
+
+
+def invokes_verb(args, groups, verb):
+    """Whether a group word is followed later by a bare verb.
+
+    Deliberately tolerant of anything between them, because a flag may sit
+    between the group and the verb — `gh issue --repo o/r create` is accepted
+    by cobra, which strips persistent flags before resolving the subcommand.
+    Tolerance is safe here only because the verb itself must be bare: that is
+    what keeps `gh issue list --search create` from reading as a creation.
+
+    Args:
+        args: A command's arguments.
+        groups: Acceptable group words, e.g. {"issue", "workitem"}.
+        verb: The verb, e.g. "create".
+
+    Returns:
+        True when the invocation names the verb.
+    """
+    # The bare-token filter is applied to the VERB only, never to the group
+    # word, and the asymmetry is the point. `--verbose` is boolean, so treating
+    # the token after any flag as that flag's value swallowed `api` in
+    # `gh --verbose api …` and `issue` in `gh --verbose issue create`. Being
+    # permissive about the group costs nothing, because the verb still has to
+    # match; being permissive about the VERB is what would read
+    # `gh issue list --search create` as a creation. Over-include where the
+    # consequence is another check, filter where the consequence is a refusal.
+    for group in groups:
+        if group not in args:
+            continue
+        group_at = args.index(group)
+        if bare_index(args, verb, group_at + 1) >= 0:
+            return True
+    return False
+
+
+def is_write_request(args):
+    """Whether the arguments describe an HTTP write rather than a read.
+
+    Args:
+        args: A command's arguments.
+
+    Returns:
+        True if a POST method or a payload-bearing flag is present.
+    """
+    for index, token in enumerate(args):
+        if token in POST_METHOD_FLAGS:
+            if index + 1 < len(args) and args[index + 1].upper() == "POST":
+                return True
+        if "=" in token:
+            head, value = token.split("=", 1)
+            if head in POST_METHOD_FLAGS and value.upper() == "POST":
+                return True
+        if token.upper() == "-XPOST":
+            return True
+        if token in POST_PAYLOAD_FLAGS:
+            return True
+    return False
+
+
+def endpoint_path(token):
+    """The path component of an endpoint-shaped argument.
+
+    An endpoint is a URL, and a URL is not its path: `?query` and `#fragment`
+    are separate components that address the SAME resource. Comparing the raw
+    argument against a path pattern therefore recognised a URL SHAPE rather
+    than an endpoint, and `repos/o/r/issues?foo=1` — the identical request —
+    was classified as a non-creation and allowed (#2939).
+
+    Trailing whitespace is stripped for the same reason: `"repos/o/r/issues "`
+    survives shlex as one token and addresses the same endpoint, but defeats an
+    end-anchored comparison just as a query string does.
+
+    Args:
+        token: One argument, possibly a decorated endpoint.
+
+    Returns:
+        The token with any fragment, query, and surrounding whitespace removed.
+    """
+    # Fragment first: it is the LAST component of a URL, so `path?q#f` yields
+    # `path?q` here and `path` after the query split, while a malformed
+    # `path#a?b` still collapses to `path` rather than keeping `a?b`.
+    return token.split("#", 1)[0].split("?", 1)[0].strip()
+
+
+def endpoint_paths(args, pattern):
+    """Endpoint path components matching a pattern, excluding payload values.
+
+    Scans every token rather than a filtered positional list, because a BOOLEAN
+    flag has no value to skip and filtering swallowed the endpoint behind one:
+    `gh api -X POST --silent repos/o/r/issues -f title=x` hid the endpoint
+    behind `--silent`. Payload values are excluded the other way, so
+    `-f path=repos/o/r/issues` is not mistaken for the address being posted to.
+
+    That payload exclusion is tested on the PATH, not the raw token, and the
+    order matters: a query string carries `=`, so testing the raw token skipped
+    `repos/o/r/issues?foo=1` before the pattern ever ran. Two independent
+    mechanisms — this filter and the pattern's end anchor — hid the same
+    creation, which is why fixing only the anchor would not have closed it.
+
+    Args:
+        args: A command's arguments.
+        pattern: The endpoint regex, written against a path component.
+
+    Returns:
+        The matching path components, decoration removed.
+    """
+    found = []
+    for index, token in enumerate(args):
+        path = endpoint_path(token)
+        if "=" in path:
+            continue
+        if index > 0 and args[index - 1] in PAYLOAD_VALUE_FLAGS:
+            continue
+        if pattern.search(path):
+            found.append(path)
+    return found
+
+
+def resolve_operand(token):
+    """A readable regular file named by one token, or None.
+
+    Bounded on purpose. The size cap keeps a PreToolUse hook off a multi-
+    megabyte read on every intercepted command, and a file too large to
+    inspect is skipped rather than half-read: a truncated scan reports a
+    confident ALLOW about text it never saw.
+
+    Args:
+        token: One argument, possibly quoted or `@`-prefixed for curl.
+
+    Returns:
+        An existing path, or None.
+    """
+    text = token.strip().strip("'\"")
+    # `-d@payload.json` names a file just as plainly as `@payload.json` does.
+    attached = attached_value(text)
+    if attached is not None:
+        text = attached
+    if text.startswith("@"):
+        text = text[1:]
+    if not text or text in STDIN_PAYLOAD_TOKENS:
+        return None
+    candidates = [text]
+    if project_dir and not os.path.isabs(text):
+        candidates.append(os.path.join(project_dir, text))
+    for candidate in candidates:
+        try:
+            if not os.path.isfile(candidate):
+                continue
+            if os.path.getsize(candidate) > FILE_OPERAND_MAX_BYTES:
+                continue
+        except OSError:
+            continue
+        return candidate
+    return None
+
+
+def read_operand(path):
+    """The text of a file the command names.
+
+    Args:
+        path: A path from `resolve_operand`.
+
+    Returns:
+        The contents, or an empty string when unreadable.
+    """
+    try:
+        with open(path, encoding="utf-8", errors="replace") as handle:
+            return handle.read(FILE_OPERAND_MAX_BYTES)
+    except OSError:
+        return ""
+
+
+def attached_value(token):
+    """A payload flag's value when it is GLUED to the flag.
+
+    `curl -d@payload.json` and `curl -d'{"query":…}'` are one token each, so a
+    parser that only looks at `args[i + 1]` and at `flag=value` sees neither —
+    and `-d@file` is the ordinary spelling, not an exotic one. Caught by review
+    before it shipped, and it was a real bypass: the mutation stayed in the
+    file, the conjunction never formed, and an undeclared creation passed.
+
+    Longest flag first, so `--data-binary@f` is not read as `--data` with a
+    `-binary@f` value. A remainder starting with `-` is rejected for the same
+    reason: it is another option, not this one's value.
+
+    Args:
+        token: One argument.
+
+    Returns:
+        The attached value, or None.
+    """
+    for flag in sorted(PAYLOAD_SOURCE_FLAGS, key=len, reverse=True):
+        if not token.startswith(flag) or len(token) == len(flag):
+            continue
+        rest = token[len(flag) :]
+        if rest.startswith("="):
+            rest = rest[1:]
+        if not rest or rest.startswith("-"):
+            continue
+        return rest
+    return None
+
+
+def payload_text(args, whole_command):
+    """The body this command will submit, wherever it is coming from.
+
+    Three sources, because a request body has three places to live and the
+    guard was reading only the first: inline after `-d`, in a file after
+    `--data-binary @path` / `--input path`, or on stdin from an earlier stage
+    of the same pipeline.
+
+    The stdin case takes the WHOLE command text rather than the segment,
+    because `jq -n … | curl … --data-binary @-` is one logical command that
+    `segment` has already split in two — the payload literally is the other
+    half. That is the shape `lisa-linear-access` mandates, so it has to be
+    readable rather than invisible.
+
+    Args:
+        args: A command's arguments.
+        whole_command: The full intercepted command string.
+
+    Returns:
+        The payload text, possibly empty.
+    """
+    parts = []
+    for index, token in enumerate(args):
+        value = None
+        if token in PAYLOAD_SOURCE_FLAGS and index + 1 < len(args):
+            value = args[index + 1]
+        elif "=" in token:
+            head, rhs = token.split("=", 1)
+            if head in PAYLOAD_SOURCE_FLAGS:
+                value = rhs
+        if value is None:
+            value = attached_value(token)
+        if value is None:
+            continue
+        stripped = value.strip().strip("'\"")
+        if stripped in STDIN_PAYLOAD_TOKENS:
+            parts.append(whole_command)
+            continue
+        parts.append(stripped)
+        path = resolve_operand(stripped)
+        if path is not None:
+            parts.append(read_operand(path))
+    return "\n".join(parts)
+
+
+def text_declares_readiness(text):
+    """Whether a file's or payload's own text carries a declaration.
+
+    The token-position machinery above cannot be reused here: a file is not
+    argv, and a payload is JSON. What is checked is deliberately the SAME
+    three declarations, matched textually and never loosened into "the role
+    string appears somewhere" — a state-based ready role is an ordinary word
+    like `Ready`, and accepting a bare occurrence of it would let prose in a
+    description declare readiness the item does not have.
+
+    Args:
+        text: File or payload contents.
+
+    Returns:
+        True when the text declares build-ready or a human gate.
+    """
+    if declares_human_gate(text):
+        return True
+    for role in (ready_role, upstream_ready_role, default_ready_role):
+        if not role:
+            continue
+        if re.search(LABEL_FLAG_TEXT % re.escape(role), text):
+            return True
+    if tracker in STATE_ROLE_TRACKERS:
+        if LIFECYCLE_ROLE_READY.search(text):
+            return True
+        if ready_role and re.search(
+            r"\"(?:state|status|stateName|statusName|state_name|name|transition)\""
+            r"\s*:\s*\"%s\"" % re.escape(ready_role),
+            text,
+            re.IGNORECASE,
+        ):
+            return True
+    return False
+
+
+def scope_declaration(text, state_role_ok):
+    """Whether a whole text declares readiness for everything inside it.
+
+    Only the two MARKERS qualify, never the `--label` flag, and that asymmetry
+    is the same one the argv check already makes. A marker has no other
+    meaning, so its presence anywhere in a script IS the declaration for that
+    script. A label flag is positional and belongs to one create; letting it
+    vouch for a second, unlabelled create further down the same file would be a
+    hole rather than a convenience.
+
+    `state_role_ok` carries the SAME scoping the argv path applies, and it has
+    to be threaded here rather than recomputed from the tracker alone: a Linear
+    project whose script files `gh issue create --repo <other>` is a cross-repo
+    GitHub filing, and this project's workflow role does not answer for another
+    repository's queue. Checking only `tracker in STATE_ROLE_TRACKERS` waved
+    exactly that through. Caught by review before it shipped.
+
+    Args:
+        text: A script's contents, or one command segment.
+        state_role_ok: Whether a lifecycle-role declaration answers here.
+
+    Returns:
+        True when the text carries a whole-scope declaration.
+    """
+    if declares_human_gate(text):
+        return True
+    return bool(state_role_ok and LIFECYCLE_ROLE_READY.search(text))
+
+
+def creation_signature(name, args, extra=""):
+    """Classify a tracker CLI invocation as a creation.
+
+    Args:
+        name: The CLI basename.
+        args: Every token after it in this segment.
+        extra: Payload text this command submits, from a file or stdin.
+
+    Returns:
+        A short human-readable signature, or None.
+    """
+    if "--help" in args or "-h" in args:
+        return None
+    joined = " ".join(args)
+    if extra:
+        joined = joined + "\n" + extra
+
+    if name == "gh":
+        if invokes_verb(args, {"issue"}, "create"):
+            return "gh issue create"
+        # Same reasoning: `api` is located without the flag-value filter, since
+        # an endpoint match and a write method must both also hold.
+        if "api" in args:
+            if GRAPHQL_CREATE.search(joined):
+                return "gh api graphql issue creation"
+            if endpoint_paths(args, GITHUB_ISSUES_PATH) and is_write_request(args):
+                return "gh api POST .../issues"
+        return None
+
+    if name in {"linear", "jira"}:
+        if invokes_verb(args, {"issue", "issues"}, "create"):
+            return "%s issue create" % name
+        return None
+
+    if name == "acli":
+        if invokes_verb(args, {"workitem", "workitems", "issue", "issues"}, "create"):
+            return "acli … create"
+        return None
+
+    if name in HTTP_CLIS:
+        if not is_write_request(args):
+            return None
+        for token in args:
+            if GITHUB_ISSUES_URL.search(token):
+                return "%s POST api.github.com/…/issues" % name
+            if JIRA_ISSUE_URL.search(token):
+                return "%s POST …/rest/api/…/issue" % name
+            if "api.linear.app/graphql" in token and GRAPHQL_CREATE.search(joined):
+                return "%s POST api.linear.app/graphql issueCreate" % name
+        return None
+
+    return None
+
+
+def before_end_of_options(args):
+    """The arguments up to a bare `--`.
+
+    Everything after `--` is an operand, not a flag, so it cannot reach the
+    created item — crediting a declaration from there is the same mistake as
+    reading the role out of a title, one position over.
+
+    The two CLIs available for testing disagree about it, which is why the
+    guard cannot lean on any of them being strict: gh 2.96.0 rejects a
+    post-`--` flag outright, while `acli` parses straight past it and proceeds
+    to create the work item with the trailing `--status` silently unapplied.
+    That made it a live bypass on the JIRA path, verified by running it.
+
+    Args:
+        args: A command's arguments.
+
+    Returns:
+        The arguments preceding the first bare `--`.
+    """
+    return args[: args.index("--")] if "--" in args else args
+
+
+def body_file_paths(args):
+    """Paths the command will submit as the item body.
+
+    Args:
+        args: A command's arguments.
+
+    Returns:
+        Candidate file paths, unverified.
+    """
+    paths = []
+    for index, token in enumerate(args):
+        if token in BODY_FILE_FLAGS and index + 1 < len(args):
+            paths.append(args[index + 1])
+        if "=" in token:
+            head, value = token.split("=", 1)
+            if head in BODY_FILE_FLAGS:
+                paths.append(value)
+        if token.startswith("@") and len(token) > 1:
+            paths.append(token[1:])
+    return paths
+
+
+def normalise_repo(value):
+    """A `--repo` value reduced to a comparable `owner/name`.
+
+    `gh` accepts `OWNER/REPO`, `HOST/OWNER/REPO`, and a full browser URL, and
+    GitHub itself is case-insensitive about both halves — so comparing the raw
+    token would call the same repository two different places depending on how
+    it was typed.
+
+    Casing is PRESERVED here and folded only at the point of comparison. The
+    refusal names this string back to an operator, and echoing
+    `codyswanngt/lisa` at someone who typed `CodySwannGT/lisa` reads as a
+    different repository — a message that has to be squinted at is the thing
+    this change is repairing.
+
+    Args:
+        value: The raw token.
+
+    Returns:
+        An as-typed `owner/name`, or None when the token names no repository.
+    """
+    text = value.strip().strip("'\"")
+    if text.endswith(".git"):
+        text = text[: -len(".git")]
+    parts = [part for part in text.split("/") if part and not part.endswith(":")]
+    if len(parts) < 2:
+        return None
+    return "%s/%s" % (parts[-2], parts[-1])
+
+
+def target_repository(args):
+    """The repository this creation is addressed at, when it names one.
+
+    Read only from positions that actually reach the created item: a flag
+    before the end-of-options marker, or the endpoint the write is posted to.
+    A `-f repo=o/r` payload field is data being SENT, not the address being
+    posted to, and `endpoint_paths` already excludes it.
+
+    Args:
+        args: A creating command's arguments.
+
+    Returns:
+        A lowercased `owner/name`, or None when the calling project is the
+        target — which is the overwhelmingly common case and today's behaviour.
+    """
+    scoped = before_end_of_options(args)
+    for index, token in enumerate(scoped):
+        if token in REPO_FLAGS and index + 1 < len(scoped):
+            return normalise_repo(scoped[index + 1])
+        if "=" in token:
+            head, value = token.split("=", 1)
+            if head in REPO_FLAGS:
+                return normalise_repo(value)
+    for path in endpoint_paths(scoped, GITHUB_ISSUES_PATH):
+        match = GITHUB_ISSUES_PATH_REPO.search(path)
+        if match:
+            return normalise_repo("%s/%s" % (match.group(1), match.group(2)))
+    for token in scoped:
+        match = GITHUB_ISSUES_URL_REPO.search(token)
+        if match:
+            return normalise_repo("%s/%s" % (match.group(1), match.group(2)))
+    return None
+
+
+def roles_for(target):
+    """Which ready-role tokens satisfy a creation addressed at `target`.
+
+    The guard demands a declaration either way; this decides only WHOSE
+    vocabulary the declaration is written in.
+
+    The indeterminate case is the last branch: a GitHub-tracked project that
+    declares no `github.org`/`github.repo` cannot be compared against a target,
+    so both roles are accepted rather than inventing a refusal. That is
+    permissive about which token, never about whether one is required.
+
+    Args:
+        target: The addressed repository as typed, or None.
+
+    Returns:
+        A (roles, cross_repo_target) pair. The target is None when the calling
+        project is the one being written to. When set it is the as-typed
+        spelling, because the refusal names it back to an operator.
+    """
+    # GitHub is case-insensitive about owner and name, so the comparison folds
+    # case while the reported string keeps the operator's own spelling.
+    folded = target.lower() if target is not None else None
+    if folded is None or (own_repo and folded == own_repo):
+        return [ready_role], None
+    if upstream_repo and folded == upstream_repo:
+        role = upstream_ready_role
+    else:
+        # Another repository Lisa has no configuration for. Its lane is
+        # whatever GitHub's stock one is; the caller's token is categorically
+        # not it.
+        role = default_ready_role
+    if own_repo or not caller_is_github:
+        return [role], target
+    # Indeterminate, and the target is deliberately NOT reported. The refusal
+    # would otherwise say "this filing is addressed at another repository" and
+    # "this project's role does not answer for it" — the first unproven and the
+    # second flatly false, since this branch accepts the project's role. A
+    # message naming a token that does not work is the remediation pointing
+    # away from the fix, which is the defect being repaired here.
+    return [ready_role, role], None
+
+
+def declares_readiness(raw_args, roles, extra="", state_role_ok=False):
+    """Whether the create carries one of the required declarations.
+
+    Args:
+        raw_args: The creating command's arguments.
+        roles: The build-ready role tokens that satisfy this filing.
+        extra: Payload text this command submits, from a file or stdin.
+        state_role_ok: Whether a lifecycle-role declaration answers here. True
+            only for a state-based tracker filing into its own tracker, where
+            no argv flag on the mandated client can carry the state.
+
+    Returns:
+        True when a build-ready role or a human-gate marker is present.
+    """
+    args = before_end_of_options(raw_args)
+    for role in roles:
+        if not role:
+            continue
+        for raw in flag_values(args, LABEL_FLAGS):
+            candidates = [part.strip().strip("'\"") for part in raw.split(",")]
+            if role in candidates:
+                return True
+    # Checked per ARGV VALUE rather than against `" ".join(args)`, and that is
+    # what makes the positional rule mean anything here. Joining first destroys
+    # position: after a join, no value's line start survives except the first
+    # argument's, so "the marker leads its line" would be decided by argument
+    # order. A `--title` value is its own single line, which is exactly the
+    # unit the rule is about -- and titles must keep being read, since this
+    # guard reads them and the intake matcher does not.
+    if any(declares_human_gate(value) for value in args):
+        return True
+    for path in body_file_paths(args):
+        try:
+            with open(path, encoding="utf-8", errors="replace") as handle:
+                if declares_human_gate(handle.read()):
+                    return True
+        except OSError:
+            continue
+    if declares_human_gate(extra):
+        return True
+    # The state-based path. Scoped by `state_role_ok` rather than checked
+    # unconditionally, so this adds a compliant command where none existed and
+    # takes none away where one already did.
+    if state_role_ok:
+        if LIFECYCLE_ROLE_READY.search(" ".join(args)):
+            return True
+        if extra and text_declares_readiness(extra):
+            return True
+    return False
+
+
+def declares_leaf_type(args):
+    """Whether the filing declares a by-design leaf type as a flag value.
+
+    Read only from positions that reach the created item, and never from a
+    title or body — the same discipline the build-ready role is held to, for
+    the same reason: a type named in prose is not a type applied.
+
+    Args:
+        args: The creating command's arguments, already scoped to the flags.
+
+    Returns:
+        True when a Bug / Task / Sub-task / Improvement is declared.
+    """
+    for raw in flag_values(args, TYPE_FLAGS):
+        for part in raw.split(","):
+            value = part.strip().strip("'\"").lower()
+            if value.startswith("type:"):
+                value = value[len("type:") :]
+            if value in BY_DESIGN_LEAF_TYPES:
+                return True
+    return False
+
+
+def declares_container(raw_args, texts=()):
+    """Whether the create declares the item a container.
+
+    A container is neither build-ready nor human-gated by construction, so this
+    is the third accepted declaration rather than a third way to satisfy the
+    first two. See the CONTAINER_DECLARATION block for why it reads the
+    canonical declaration and not a `type:Epic` claim.
+
+    Args:
+        raw_args: The creating command's arguments.
+        texts: Payload or script text this command submits or runs.
+
+    Returns:
+        True when the container declaration is present and uncontradicted.
+    """
+    args = before_end_of_options(raw_args)
+    # The contradiction check comes FIRST, so a filing that declares itself
+    # both a container and a by-design leaf is refused rather than allowed on
+    # the strength of the half that suits it.
+    if declares_leaf_type(args):
+        return False
+    if CONTAINER_DECLARATION.search(" ".join(args)):
+        return True
+    for path in body_file_paths(args):
+        try:
+            with open(path, encoding="utf-8", errors="replace") as handle:
+                if CONTAINER_DECLARATION.search(handle.read()):
+                    return True
+        except OSError:
+            continue
+    for text in texts:
+        if text and CONTAINER_DECLARATION.search(text):
+            return True
+    return False
+
+
+def flag_values(args, names):
+    """Every value assigned to one of the named flags.
+
+    Args:
+        args: A command's arguments.
+        names: The flag spellings to collect.
+
+    Returns:
+        The raw values, unsplit and unquoted.
+    """
+    values = []
+    for index, token in enumerate(args):
+        if token in names and index + 1 < len(args):
+            values.append(args[index + 1])
+        if "=" in token:
+            head, value = token.split("=", 1)
+            if head in names:
+                values.append(value)
+    return values
+
+
+def nested_operands(argv):
+    """Command strings this argv hands to another interpreter.
+
+    Position-scoped rather than shell-allowlisted: the operand after `-c` (or
+    after `eval`) is a command by the calling convention itself, whoever the
+    program is. That covers `bash -c`, `sh -c`, `zsh -c`, `python -c`, and the
+    POSIX builtin `eval`, without an allowlist to keep complete.
+
+    Recursing into arbitrary trailing quoted operands was considered and
+    rejected: it re-refuses `git commit -m "the gh issue create guard"`, which
+    is an ordinary and correct command. `ssh host '…'` is therefore NOT
+    intercepted — a documented limit, since that runs against another host's
+    tracker config and needs that host's own guard.
+
+    Args:
+        argv: One command's tokens.
+
+    Returns:
+        Nested command strings.
+    """
+    operands = []
+    for index, token in enumerate(argv):
+        if index + 1 >= len(argv):
+            continue
+        if token == "-c" or token.endswith("-c") and token.startswith("-"):
+            operands.append(argv[index + 1])
+        elif basename(token) == "eval":
+            operands.append(argv[index + 1])
+    return operands
+
+
+inspected_files = set()
+
+
+# Interpreters whose OPERAND is a program they run. Broader than a shell list
+# because `file_creation` recognises a creation in any language — the
+# `node wrapper.mjs` that speaks HTTP directly is exactly the shape #3484
+# measured as a fail-open, so narrowing this to shells would reopen it.
+EXECUTING_INTERPRETERS = {
+    "bash", "dash", "ksh", "sh", "zsh",
+    "bun", "deno", "node", "nodejs", "perl", "php",
+    "python", "python3", "ruby", "ts-node", "tsx",
+}
+
+# `.` and its `source` alias run the named file in the CURRENT shell.
+SOURCE_BUILTINS = {"source", "."}
+
+# Wrappers that run what FOLLOWS them without changing what it is, mapped to
+# (options whose value is a SEPARATE token, positional operands consumed).
+# The positional count is why this is a table: `timeout 5 bash create.sh` puts
+# an operand between the wrapper and the interpreter, so a walk that steps over
+# `-flags` only stops at `5` and never reaches the interpreter.
+EXEC_WRAPPERS = {
+    "builtin": (frozenset(), 0),
+    "command": (frozenset(), 0),
+    "exec": (frozenset({"-a"}), 0),
+    "env": (frozenset({"-u", "--unset", "-C", "--chdir", "--argv0"}), 0),
+    "nice": (frozenset({"-n", "--adjustment"}), 0),
+    "nohup": (frozenset(), 0),
+    "setsid": (frozenset(), 0),
+    "stdbuf": (frozenset({"-i", "-o", "-e"}), 0),
+    "sudo": (frozenset({
+        "-u", "--user", "-g", "--group", "-C", "--close-from",
+        "-p", "--prompt", "-h", "--host", "-r", "--role",
+        "-t", "--type", "-U", "--other-user",
+    }), 0),
+    "time": (frozenset(), 0),
+    "timeout": (frozenset({"-k", "--kill-after", "-s", "--signal"}), 1),
+}
+
+# Interpreter options that mean "no script file follows": a command string or a
+# module name, both of which the guard reads by other means or not at all. These
+# are interpreter-specific on purpose. `bash -e create.sh` and `sh -m create.sh`
+# still execute the following file; treating Python and Node flags as universal
+# silently stopped the scan before those shell operands.
+NO_SCRIPT_OPTIONS = {
+    "bun": {"-e", "--eval"},
+    "node": {"-e", "--eval"},
+    "nodejs": {"-e", "--eval"},
+    "perl": {"-e"},
+    "php": {"-r"},
+    "python": {"-c", "-m", "--command", "--module"},
+    "python3": {"-c", "-m", "--command", "--module"},
+    "ruby": {"-e"},
+}
+
+# Interpreter switches whose value is a separate token, followed by the real
+# script operand. Treating the value as the script makes the guard inspect a
+# preload or option value and never reach what the interpreter executes.
+INTERPRETER_VALUE_OPTIONS = {
+    "bash": {"-o", "--option"},
+    "dash": {"-o"},
+    "deno": {"-c", "--config"},
+    "ksh": {"-o"},
+    "node": {"-r", "--require"},
+    "nodejs": {"-r", "--require"},
+    "sh": {"-o"},
+    "zsh": {"-o"},
+}
+
+# Runtime subcommands that introduce the script path rather than name it.
+INTERPRETER_SUBCOMMANDS = {
+    "bun": {"run"},
+    "deno": {"run"},
+}
+
+
+def is_assignment_word(token):
+    """Whether token is a POSIX shell assignment in command-prefix position."""
+    return re.match(r"^[A-Za-z_][A-Za-z0-9_]*\+?=", token) is not None
+
+# Programs that READ their operands and never execute them as programs.
+#
+# This is an allowlist of readers rather than the inverse, and the asymmetry is
+# deliberate. An UNKNOWN program with a file operand is still followed, because
+# whether it executes that operand is genuinely unknowable from the command —
+# and a probe in this guard's own suite drives it with a runner nobody
+# enumerated precisely so a fix keyed on a list of interpreters fails. Failing
+# closed on the unknown keeps that coverage.
+#
+# What the list buys is the measured population of #3705, every member of which
+# is a well-known inspector: `git diff`, `grep -n`, `wc -l`, a `git grep`
+# PATHSPEC, `sed -n '1,50p'`, and a test run. `git` is here wholesale because no
+# git subcommand executes a named file as a program — `git commit -F <file>` and
+# `git grep -- <pathspec>` both take the path as data.
+#
+# Test runners are here on purpose and it is the one entry worth arguing about.
+# `vitest <file>` does run that file, so the executes-rule would follow it — but
+# running a test is not filing an issue, and refusing a test run is the sharpest
+# harm #3705 records, because it can block the verification of a fix while
+# saying nothing about why.
+#
+# RELOCATION AND ECHOING ARE READS TOO, and leaving them off is what turned a
+# false positive into a property of the repository (CodySwannGT/lisa#3683). A
+# file that QUOTES a creation was already reachable by `grep`, `cat` and `ls`
+# once this list existed — but not by `cp` or `mv`, so the file could be read
+# and never moved, by any agent and by CI, for as long as the literal stayed in
+# it. The measured case shows why "reword it" is not the inverse: the refusal
+# recurred AFTER the content had been reworded, on a different file quoting the
+# same command. None of these four executes an operand: `cp` and `mv` copy
+# bytes, `echo` and `printf` write them to stdout. They are also the vocabulary
+# `unparseable_reads_only` answers with when the text could not be lexed at all.
+#
+# RESIDUAL, stated rather than hidden: a reader NOT on this list is still
+# followed and can still over-refuse. The set of read-only tools is unbounded,
+# so this closes the measured population and not the class. Add names here as
+# they are measured; do not invert the default to close it by fiat, or the
+# executed-script reach that #3484 bought is lost.
+#
+# The copy/move/link family is measured, not inferred: `cp <a file that files>`
+# was refused as "an unparseable command that reads as a tracker creation
+# inside <path>" (CodySwannGT/lisa#3683, trip 5, reproduced in this guard's own
+# suite). These four relocate bytes and never execute an operand, so following
+# them can only ever over-refuse — and the harm is the propagating kind this
+# ticket is about, because a file that quotes a creation then cannot be copied
+# by any agent or by CI.
+#
+# `mv`, `ln` and `install` join `cp` as the same operation rather than as a
+# guess: the list already carries whole families (`git` wholesale, `bat`/`xxd`
+# beside `cat`) on exactly that reasoning. Path arithmetic and metadata tools
+# are deliberately NOT added — unmeasured, and the residual note above is the
+# standing instruction to add on measurement rather than by sweep.
+READ_ONLY_PROGRAMS = {
+    "awk", "bat", "cat", "cksum", "cmp", "column", "comm", "cp", "cut",
+    "diff", "du", "echo", "file", "fold", "git", "grep", "head",
+    "hexdump", "install", "jest", "jq", "less", "ln", "ls", "md5",
+    "md5sum", "more", "mv", "nl", "od", "printf", "pytest", "rg",
+    "sed", "sha1sum", "sha256sum", "shellcheck", "shfmt", "sort",
+    "stat", "strings", "tail", "tee", "uniq", "vitest", "wc", "xxd",
+    "yamllint",
+}
+
+
+def executing_command(argv):
+    """The program this command runs, and the tokens after it.
+
+    Steps over leading variable assignments and over wrappers that do not
+    change what runs. Reading a wrapper as the command is how a payload hides
+    from a classifier that inspects only a segment's first word.
+
+    Args:
+        argv: One command's tokens.
+
+    Returns:
+        A triple (token, program, args); (None, None, []) when none is named.
+        The raw token is carried alongside the basename because a script run by
+        bare path — `./create.sh`, relying on its shebang — has no interpreter
+        to recognise, and the command word IS the thing being executed.
+    """
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if is_assignment_word(token):
+            index += 1
+            continue
+        program = basename(token)
+        if program not in EXEC_WRAPPERS:
+            return (token, program, argv[index + 1 :])
+        separate, positional = EXEC_WRAPPERS[program]
+        index += 1
+        while index < len(argv) and argv[index].startswith("-"):
+            option = argv[index]
+            if option == "--":
+                index += 1
+                break
+            index += 2 if option in separate else 1
+        index += positional
+    return (None, None, [])
+
+
+# Operators that end a command in raw shell text. Used ONLY where `shlex` has
+# already refused the text, so a quote-aware split is not available — and
+# OVER-splitting is the safe direction here, because an extra segment can only
+# add a command word to check, never remove one.
+RAW_SEGMENT_SPLIT = re.compile(r"&&|\|\||[;|&\n]")
+
+
+def raw_command_words(text):
+    """The program each segment of unlexable text puts in command position.
+
+    Answered on a whitespace split because the reason this path exists is that
+    `shlex` refused the text. It still routes through `executing_command`, so a
+    leading assignment and a wrapper — `nice`, `env`, `sudo`, `timeout` — are
+    stepped over here exactly as they are on the parsed path. Reading the
+    wrapper as the command is the bypass this guard's own comments record.
+
+    Args:
+        text: The raw command string.
+
+    Returns:
+        One entry per non-empty segment: the resolved program name, or None
+        when the segment names none.
+    """
+    words = []
+    for chunk in RAW_SEGMENT_SPLIT.split(text):
+        tokens = chunk.split()
+        if not tokens:
+            continue
+        words.append(executing_command(tokens)[1])
+    return words
+
+
+def unparseable_reads_only(text):
+    """Whether unlexable text only READS, and therefore files nothing.
+
+    `UNPARSEABLE_CREATION` matches raw text, so it cannot tell a filing from a
+    sentence about one. `echo the guard's <creation> behaviour` fails to lex
+    for the apostrophe alone, and was refused as a tracker creation — a command
+    that files nothing, told that "this filing declares no readiness", with no
+    printed remedy that applied to any part of it (CodySwannGT/lisa#3683).
+
+    The fallback is NOT removable and is not narrowed here. `<creation> #'` is
+    a real filing that bash runs and `shlex` rejects, so "I could not parse it"
+    must keep meaning refuse. What this asks instead is the COMMAND POSITION
+    question the parsed path already asks and this arm skipped: only a command
+    position can run anything, and a reader takes its operands as data.
+
+    Fails closed on everything else, which is the same asymmetry
+    `READ_ONLY_PROGRAMS` documents: an unresolvable command word, an
+    unrecognised program, or a text with no segments at all is refused.
+
+    Args:
+        text: The raw command string that would not lex.
+
+    Returns:
+        True when every segment's command word is a known reader.
+    """
+    # Unlexable operands cannot be certified as data when shell substitutions
+    # may execute inside them. Preserve the plain apostrophe reader exemption.
+    if any(operator in text for operator in ("$(", "`", "<(", ">(")):
+        return False
+    words = raw_command_words(text)
+    return bool(words) and all(word in READ_ONLY_PROGRAMS for word in words)
+
+
+def executed_operand(argv):
+    """The path this command EXECUTES, or None.
+
+    THIS IS THE COMMAND-POSITION QUESTION, and declining to ask it is what
+    #3705 records: the guard opened any readable file any token named, then
+    justified a refusal from that FILE's contents rather than from the
+    COMMAND's behaviour. Measured refusals included `git diff`, `grep -n`,
+    `wc -l`, a `git grep` PATHSPEC and a test run — every one of them read-only,
+    and one of them blocked running the tests that would have proved a fix.
+
+    `parity-safety-net.sh` already states the rule this restores, and names the
+    opposite as the known-wrong fix (`origin/main`, lines 337-346 and 704-705):
+    "Only a COMMAND POSITION can execute something. A path anywhere else is an
+    argument, and an argument is data." `block-no-verify.sh:495-513`
+    (`strip_command_prefix`) implements the same split with a fail-closed third
+    state. Both live in this directory; this guard was the one that declined.
+
+    NOT narrowed to shells, and NOT narrowed to an enumerated interpreter list.
+    `file_creation` recognises a creation in any language, so `node wrapper.mjs`
+    must still be followed — a measured fail-open in #3484 — and this guard's
+    own suite drives it with a runner nobody enumerated, precisely so a fix
+    keyed on such a list fails. So the default for an unrecognised program is to
+    FOLLOW, and only a known reader is exempt. A script run by bare path with no
+    interpreter at all (`./create.sh`, via its shebang) is followed too: there
+    the command word is itself the thing being executed.
+
+    Reading a REQUEST PAYLOAD is a separate question with a separate answer:
+    `payload_text` resolves `--data-binary @file` and friends by flag name, so
+    narrowing this walk does not stop a creation whose body lives in a file
+    from being seen.
+
+    Args:
+        argv: One command's tokens.
+
+    Returns:
+        The operand token naming a program that will run, or None.
+    """
+    token, program, args = executing_command(argv)
+    if program is None:
+        return None
+    # A reader takes its operands as data. This is the #3705 population.
+    if program in READ_ONLY_PROGRAMS:
+        return None
+    if program in SOURCE_BUILTINS:
+        return args[0] if args else None
+    # A command word that is ITSELF a readable file is being executed by its
+    # shebang — `./create.sh` names no interpreter and runs all the same.
+    if program not in EXECUTING_INTERPRETERS and resolve_operand(token) is not None:
+        return token
+    # Reached by a known interpreter AND by a program this parser cannot name.
+    # The unknown case is followed on purpose — see READ_ONLY_PROGRAMS.
+    redirected = None
+    index = 0
+    while index < len(args):
+        argument = args[index]
+        if argument == "<":
+            if index + 1 < len(args):
+                redirected = args[index + 1]
+            index += 2
+            continue
+        if argument == "--":
+            index += 1
+            return args[index] if index < len(args) else redirected
+        if argument.startswith("-"):
+            # A command string or a module name; no script file follows.
+            head = argument.split("=", 1)[0]
+            if program in {"bash", "dash", "ksh", "sh", "zsh"}:
+                # Shell `-c` may be clustered (`-ec`), while `-e` and `-m` are
+                # ordinary shell options and do not consume the script path.
+                if not head.startswith("--") and "c" in head[1:]:
+                    return None
+                # `-n` is noexec: the shell READS and parses the file and then
+                # exits without running a line of it. `bash -n <file>` is the
+                # one shape that puts a path at a command position while
+                # provably executing nothing, so it is the exact seam between
+                # reading and running — and this walk got it wrong in BOTH
+                # directions (CodySwannGT/lisa#3781). A creation-shaped file
+                # earned a false refusal; a file carrying a human-gate marker
+                # earned a false ALLOW, adjudicating as "declared" a command
+                # that filed nothing. The silent direction is the worse one.
+                #
+                # Not a read-only-command exemption: `bash <file>` still runs
+                # the file and is still refused. The distinction is noexec, not
+                # the program.
+                if head == "--noexec" or (
+                    not head.startswith("--") and "n" in head[1:]
+                ):
+                    return None
+            elif head in NO_SCRIPT_OPTIONS.get(program, set()):
+                return None
+            takes_value = head in INTERPRETER_VALUE_OPTIONS.get(program, set())
+            index += 2 if takes_value and "=" not in argument else 1
+            continue
+        if argument in INTERPRETER_SUBCOMMANDS.get(program, set()):
+            index += 1
+            continue
+        return argument
+    # `bash < create.sh` runs stdin only when no explicit script was named.
+    return redirected
+
+
+def file_operands(argv):
+    """The file this command EXECUTES, if it executes one.
+
+    Deciding WHICH programs execute their operands is the question this file
+    used to refuse to ask, and refusing it is what made the guard read a path
+    quoted as prose inside a `--body-file` markdown and attribute its contents
+    to the command. It is answered in `executed_operand` now.
+
+    Args:
+        argv: One command's tokens.
+
+    Returns:
+        Existing paths, deduplicated across the whole scan and capped.
+    """
+    paths = []
+    operand = executed_operand(argv)
+    for token in [operand] if operand is not None else []:
+        if len(paths) >= FILE_OPERANDS_PER_SEGMENT:
+            break
+        path = resolve_operand(token)
+        if path is None:
+            continue
+        try:
+            key = os.path.realpath(path)
+        except OSError:
+            key = path
+        if key in inspected_files:
+            continue
+        inspected_files.add(key)
+        paths.append(path)
+    return paths
+
+
+def file_creation(text, depth):
+    """An undeclared tracker creation inside a file's contents, or None.
+
+    Two recognisers, because a creation inside a file is not always shell.
+    The shell path handles `bash create.sh`; the CONJUNCTION path handles
+    `node wrapper.mjs`, a Python client, or anything else that speaks HTTP
+    directly — it needs a tracker endpoint AND a creation verb in the same
+    file, which is what keeps a changelog that merely mentions `issueCreate`
+    from reading as a creation. It also needs the file to be capable of
+    SENDING what it spells: a helper that writes the same payload into a test
+    fixture submits nothing. See `payload_is_inert`.
+
+    Args:
+        text: The file's contents.
+        depth: Current nesting depth.
+
+    Returns:
+        A (signature, roles, cross_repo_target) triple, or None.
+    """
+    nested = scan(text, depth + 1, from_file=True)
+    if nested is not None:
+        return nested
+    # The coarse path answers to a coarse declaration check, and the precise
+    # path above answers to the precise one. Reversing that — screening the
+    # whole file first — would let a declaration on one create in a script
+    # vouch for a different, undeclared one further down.
+    if (
+        GRAPHQL_CREATE.search(text)
+        and TRACKER_ENDPOINT.search(text)
+        and not text_declares_readiness(text)
+        # A payload the file WRITES rather than SENDS is data. See
+        # `payload_is_inert` for why the absence of egress alone is not enough.
+        and not payload_is_inert(text)
+    ):
+        return "a tracker creation", [ready_role], None
+    return None
+
+
+def scan(text, depth, from_file=False):
+    """Find the first undeclared tracker creation in a command string.
+
+    Args:
+        text: A shell command.
+        depth: Current nesting depth.
+        from_file: Whether `text` is a file's contents rather than a typed
+            command.
+
+    Returns:
+        A (signature, roles, cross_repo_target) triple, or None when nothing
+        creation-shaped was found.
+    """
+    try:
+        stripped = strip_heredocs(text)
+        tokens = explode_operators(shlex.split(stripped, posix=True), stripped)
+    except ValueError:
+        # Bash's grammar is not shlex's. `gh issue create --title x #'` is a
+        # comment to bash, which strips it and RUNS the create, while shlex
+        # raises on the unbalanced quote. Two appended characters, no binary
+        # required. "I could not parse it" must never mean "it is fine".
+        #
+        # A FILE that does not lex is judged by the same recogniser rather than
+        # waved through: an unbalanced quote inside a script is the identical
+        # two-character trick moved one file away, and skipping it would hand
+        # the bypass straight back.
+        #
+        # The declaration check is NOT gated on `from_file`, and that is the
+        # #3727 fix. Tokenisation is what feeds every argv-based check below,
+        # so when it throws, a TYPED command was previously judged with no
+        # declaration consulted at all — not its `--body-file`, not even a
+        # plain `--label <ready role>` sitting in argv. A correctly declared
+        # filing was refused for the unrelated reason that its command happened
+        # not to lex, and told "this filing declares no readiness", which was
+        # false. Reading the text here is the only check available once `shlex`
+        # has failed.
+        #
+        # It cannot reopen the bypass the paragraph above defends. That bypass
+        # is an UNDECLARED create hiding behind a quote, and an undeclared
+        # create has no marker and no `--label <ready role>` for
+        # `text_declares_readiness` to match — which is asserted, not assumed,
+        # by the rejection controls covering a bare create, the role mentioned
+        # in prose, and the role appearing inside a URL.
+        #
+        # A marker in a SEPARATE `--body-file` stays refused, because finding
+        # that operand needs the tokenisation that just failed. That case is
+        # reachable by declaring inline instead, which this change makes work.
+        if text_declares_readiness(text):
+            return None
+        # The command-position arm of the same reasoning `executed_operand`
+        # applies. A text every one of whose segments runs a known READER
+        # cannot file anything, whatever its prose says — see
+        # `unparseable_reads_only` for why this does not narrow the fallback.
+        if unparseable_reads_only(text):
+            return None
+        # Ignore whole-line prose comments when applying the fallback matcher.
+        if UNPARSEABLE_CREATION.search(strip_full_line_comments(text)):
+            return (
+                "an unparseable command that reads as a tracker creation",
+                [ready_role],
+                None,
+            )
+        return None
+
+    for argv in segment(tokens):
+        for index, token in enumerate(argv):
+            name = basename(token)
+            if name not in TRACKER_CLIS and name not in HTTP_CLIS:
+                continue
+            args = argv[index + 1 :]
+            submitted = payload_text(args, text)
+            signature = creation_signature(name, args, submitted)
+            if signature is None:
+                continue
+            # The ambient override is the human operator's. An inline
+            # assignment is the agent granting itself the exemption, so it
+            # disqualifies the override rather than supplying it.
+            if ambient_override and not inline_override:
+                continue
+            roles, target = roles_for(target_repository(args))
+            state_role_ok = tracker in STATE_ROLE_TRACKERS and target is None
+            if declares_readiness(args, roles, submitted, state_role_ok):
+                continue
+            # The container arm. Checked after readiness, so it adds a
+            # compliant filing where none existed and takes none away where one
+            # already did. `text` joins the scan only for a creation found
+            # INSIDE a file, where the declaration lives in the same file as
+            # the create it answers for.
+            if declares_container(
+                args, (submitted, text) if from_file else (submitted,)
+            ):
+                continue
+            # `LIFECYCLE_ROLE=ready curl …` puts the declaration BEFORE the
+            # client, which is where an inline assignment has to go, so the
+            # role is read from the whole segment rather than from the client's
+            # own arguments. Scoped to the segment and not the command, so a
+            # declaration cannot be shouted from an unrelated pipeline stage.
+            if state_role_ok and LIFECYCLE_ROLE_READY.search(" ".join(argv)):
+                continue
+            # A script declares once, for itself. See `scope_declaration`.
+            if from_file and scope_declaration(text, state_role_ok):
+                continue
+            return signature, roles, target
+
+        for operand in nested_operands(argv):
+            if depth >= MAX_NESTING_DEPTH:
+                # Refuse at the bound rather than skipping past it. Skipping
+                # made a creation inside a 4th `bash -c` layer pass, which is
+                # the depth cap being used as the bypass.
+                if UNPARSEABLE_CREATION.search(operand):
+                    return (
+                        "a tracker creation nested past the inspection depth",
+                        [ready_role],
+                        None,
+                    )
+                continue
+            nested = scan(operand, depth + 1)
+            if nested is not None:
+                return nested
+
+        # The locate step, which used to stop at `bash` and never reach the
+        # operand. Deliberately last: an inline creation is the cheaper and
+        # more precise finding, so it is reported before a file is opened.
+        # The operator's ambient override is checked BEFORE the depth bound,
+        # not after it. The other order meant a creation reached past the cap
+        # was refused even with `LISA_ALLOW_DIRECT_ISSUE_CREATE=1` exported —
+        # while the refusal text advertised that escape. An escape hatch the
+        # refusal names and the code ignores is worse than none. Caught by
+        # review before it shipped.
+        if ambient_override and not inline_override:
+            continue
+        for path in file_operands(argv):
+            contents = read_operand(path)
+            if not contents:
+                continue
+            if depth >= MAX_NESTING_DEPTH:
+                if GRAPHQL_CREATE.search(contents) or UNPARSEABLE_CREATION.search(
+                    contents
+                ):
+                    return (
+                        "a tracker creation inside %s, nested past the "
+                        "inspection depth" % path,
+                        [ready_role],
+                        None,
+                    )
+                continue
+            found = file_creation(contents, depth)
+            if found is not None:
+                return ("%s inside %s" % (found[0], path), found[1], found[2])
+    return None
+
+
+# The inline-override check runs over the WHOLE raw command text, not over
+# parsed tokens, so it catches `X=1 gh …`, `env X=1 gh …`, `export X=1 && gh …`,
+# and the same forms buried inside a nested `bash -c '…'` string alike. Any
+# appearance of the assignment disqualifies the ambient override: this is the
+# one place the guard deliberately over-matches, because a false positive costs
+# a human one retry and a false negative costs the entire control.
+inline_override = (OVERRIDE_NAME + "=") in command
+
+
+def remedy_for(signature):
+    """Which extra remediation paragraph this refusal earns.
+
+    A guard that prints every remedy it knows prints one that does not apply,
+    and a remedy that cannot be performed is the failure this ticket is about
+    (CodySwannGT/lisa#3683): the file-payload paragraph told an author to drop
+    a transmitting primitive that a DOCUMENT does not have, and the
+    unparseable arm printed declaration advice for a command that files
+    nothing. Both are now keyed off which branch actually fired.
+
+    Args:
+        signature: The refusal signature.
+
+    Returns:
+        A key the shell half maps to a paragraph, or an empty string.
+    """
+    if signature.startswith("an unparseable command"):
+        return "unparseable"
+    if " inside " in signature:
+        return "file"
+    return ""
+
+
+found = scan(command, 0)
+if found is not None:
+    signature, roles, target = found
+    # Key=value lines rather than one delimited string: a signature contains
+    # spaces and slashes, and a role may contain a colon, so anything the shell
+    # would have to split on appears inside a value already.
+    print("REFUSE")
+    print("signature=%s" % signature)
+    print("roles=%s" % ", ".join(role for role in roles if role))
+    print("target=%s" % (target or ""))
+    print("remedy=%s" % remedy_for(signature))
+    sys.exit(0)
+
+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
+
+  # A PACKED label string counts. Exact equality against the flattened value
+  # list reads `labels: ["status:ready"]` and nothing else, but the same
+  # compliant filing spelled `labels: "status:ready,type:Bug"` — the shape
+  # `gh issue create --label` takes, and the shape several MCP servers pass
+  # through verbatim — carries no value equal to the role, so the guard
+  # refused a filing that had declared exactly what it demanded. A false
+  # positive in a guard costs more than a miss: it teaches the operator that
+  # the guard is wrong, and the next refusal is argued with rather than
+  # obeyed.
+  #
+  # Split on the DELIMITERS a packed list uses (comma, semicolon, newline) and
+  # trimmed, never on a `contains` match. `contains` would accept a body that
+  # merely mentions the role in prose — "do not mark this status:ready" — and
+  # that is a fail-open on the one question this path exists to answer.
+  structured_declaration="$(
+    printf '%s' "$input" |
+      jq -r --arg role "$ready_role" '
+        [(.tool_input // {}) | .. | strings] as $values
+        | ($values + ($values
+            | map(splits("[,;\n]"))
+            | map(sub("^\\s+"; "") | sub("\\s+$"; "")))) as $atoms
+        | if ($atoms | 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" \
+      LISA_GUARD_READY_ROLE="$ready_role" \
+      LISA_GUARD_AMBIENT_OVERRIDE="$ambient_override" \
+      LISA_GUARD_DEFAULT_READY_ROLE="$default_ready_role" \
+      LISA_GUARD_OWN_REPO="$own_repo" \
+      LISA_GUARD_UPSTREAM_REPO="$upstream_repo" \
+      LISA_GUARD_UPSTREAM_READY_ROLE="$upstream_ready_role" \
+      LISA_GUARD_CALLER_IS_GITHUB="$caller_is_github" \
+      LISA_GUARD_TRACKER="$tracker" \
+      LISA_GUARD_PROJECT_DIR="$project_dir" \
+      python3 -
+)"
+python_status=$?
+set -e
+
+# A crashed classifier must not be read as "allow" without saying so.
+if [ "$python_status" -ne 0 ]; then
+  printf 'block-direct-issue-create: classifier failed (exit %s); enforcement is NOT active for this call\n' \
+    "$python_status" >&2
+  exit 0
+fi
+
+verdict_field() {
+  printf '%s\n' "$verdict" | sed -n "s/^$1=//p" | head -1
+}
+
+case "$verdict" in
+  REFUSE*)
+    refuse \
+      "$(verdict_field signature)" \
+      "$(verdict_field roles)" \
+      "$(verdict_field target)" \
+      "$(verdict_field remedy)"
+    ;;
+esac
+
+exit 0