@codyswann/lisa 4.45.3 → 4.45.5

package/plugins/src/base/hooks/block-direct-issue-create.sh

@@ -346,7 +346,7 @@ 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 two, always explicit:
+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:
 
@@ -368,11 +368,26 @@ FILE IT THE SANCTIONED WAY — one of these two, always explicit:
      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 two
+If you must run the CLI directly, the command has to carry one of the three
 declarations itself:
 
 $(declaration_hint)
@@ -380,6 +395,9 @@ $(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
@@ -528,6 +546,78 @@ UNPARSEABLE_CREATION = re.compile(
 
 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 — exactly the asymmetry `HUMAN_GATE_MARKER` gets, and for the same
+# 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",
@@ -1433,6 +1523,65 @@ def declares_readiness(raw_args, roles, extra="", state_role_ok=False):
     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.
 
@@ -1880,6 +2029,15 @@ def scan(text, depth, from_file=False):
             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

package/plugins/src/base/hooks/worktree-binding-guard.mjs

@@ -304,6 +304,11 @@ function foreignTreeIn(text, bound, cwd) {
   for (const raw of code.match(/[^\s'";|&()<>]+/gu) ?? []) {
     const token = raw.replace(/^["']|["']$/gu, "");
     if (!token.includes("/")) continue;
+    // A null base means an unliteral `cd` left the directory this script runs
+    // from unknown. An ABSOLUTE token is unambiguous either way; a relative one
+    // is exactly the thing that cannot be placed, so it is skipped rather than
+    // resolved against a directory picked for having been handy.
+    if (!isAbsolute(token) && cwd === null) continue;
     const candidate = isAbsolute(token) ? token : join(cwd, token);
     let root;
     try {
@@ -317,6 +322,63 @@ function foreignTreeIn(text, bound, cwd) {
   return null;
 }
 
+/**
+ * A `cd` target this guard cannot turn into a literal directory.
+ *
+ * Mirrors `parity-safety-net.sh`'s `follow_cd` test exactly, and the mirror is
+ * the point: two spellings of one rule are how the guards drift.
+ */
+const UNLITERAL_CD_TARGET = /[$`*?[{]/u;
+
+/**
+ * The literal target of a leading `cd`, `""` for a bare `cd`, or null when the
+ * segment does not change directory.
+ *
+ * A bare `cd` is `cd "$HOME"`. Leaving the previous directory in place for it
+ * would resolve later tokens from a directory the shell has already left.
+ * @param segment - One statement from the command
+ * @returns The target text, or null when this segment is not a `cd`
+ */
+function cdTarget(segment) {
+  const tokens = tokenise(segment);
+  if (tokens.length === 0 || tokens[0] !== "cd") return null;
+  return tokens[1] ?? "";
+}
+
+/**
+ * Apply one `cd` to the directory currently in force.
+ *
+ * Contract points 1-4 of `cwd-resolution-corpus.json`: a literal target
+ * REPLACES the directory rather than joining a list of candidates — the
+ * ordering was #3933's entire defect; a relative target composes against the
+ * directory in force; a target that is not literal text yields unknown; and
+ * unknown is sticky only until the next resolvable `cd`, because this returns
+ * a fresh answer for each one.
+ * @param current - Directory in force, or null when it is already unknown
+ * @param target - Literal `cd` target, `""` for a bare `cd`
+ * @returns The new directory, or null when it cannot be known
+ */
+function applyCd(current, target) {
+  const home = homedir();
+  let value = target === "" ? home : target;
+  if (value === "~") value = home;
+  else if (value.startsWith("~/")) value = join(home, value.slice(2));
+  if (
+    value === "" ||
+    value.startsWith("-") ||
+    UNLITERAL_CD_TARGET.test(value)
+  ) {
+    return null;
+  }
+  if (!isAbsolute(value) && current === null) return null;
+  const next = isAbsolute(value) ? resolve(value) : resolve(current, value);
+  try {
+    return statSync(next).isDirectory() ? next : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The foreign worktree an executed script reaches, or null.
  *
@@ -340,41 +402,71 @@ function foreignTreeIn(text, bound, cwd) {
  * disagreeing. The scripted form is the one neither covers, and it is the only
  * cell this arm fills.
  *
- * ## A relative script path is resolved against `payload.cwd`, and that is a
- * KNOWN limitation shared with `parity-safety-net.sh`
+ * ## A relative script path is resolved against the cwd the command will have
+ *
+ * A leading `cd` establishes the directory this guard resolves relative tokens
+ * from, because that is the directory the shell will be in once the command
+ * runs. Resolving against `payload.cwd` instead was CodySwannGT/lisa#3933's
+ * defect, inherited here knowingly and fixed in CodySwannGT/lisa#3952: on a
+ * machine running many worktrees of one repository, every tree holds its own
+ * copy of every script at the same relative path, and they differ by whatever
+ * each lane is doing.
  *
- * CodySwannGT/lisa#3933, filed against that guard, is the same defect: a
- * relative token is resolved against the hook process's working directory, not
- * against the directory the command will have once it runs its own leading
- * `cd`. So `cd <other tree> && bash scripts/foo.sh` reads THIS tree's copy of
- * `scripts/foo.sh` and reports on it with full confidence.
+ * ## One contract, two implementations, and why that is the honest answer
  *
- * It matters here for the same reason it matters there: on a machine running
- * many worktrees of one repository, every tree holds its own copy of every
- * script at the same relative path, and they differ by whatever each lane is
- * doing. A confident scan of the wrong copy is wrong in both directions, and
- * the silent one — the copy that will run reaches out, the copy that was read
- * does not — is the direction this arm exists to prevent.
+ * `parity-safety-net.sh` answers this same question — "which file will this
+ * command actually execute?" — in POSIX shell, where `follow_cd` mutates
+ * file-scope state that `follow_locate` reads. This guard is Node. **There is
+ * no call that reaches from here into a shell function's file-scope state**, so
+ * the duplication is not a factoring somebody skipped; it is one idea that
+ * cannot cross a language boundary as a function call.
  *
- * NOT fixed here on purpose. #3933 is assigned and its options (honour a
- * leading `cd`, or fail closed when the effective cwd is uncertain) belong in
- * one place rather than two: a second implementation of the same resolution is
- * how two guards drift into disagreeing about which file a command runs.
- * When that lands, this call site should adopt whatever it produces.
+ * What binds the two is a written contract and a corpus of rows that BOTH
+ * guards are driven over in CI, so a divergence fails a test on the commit that
+ * causes it rather than surfacing later as a wrong verdict. Contract and corpus
+ * live in `tests/unit/hooks/support/cwd-resolution-corpus.json`.
  *
- * The exposure here is narrower than there. This arm is reached only after the
- * session has been confirmed to be in its bound worktree, so the common case
- * is a relative path resolving inside the tree the session is actually in.
+ * This is explicitly NOT unification, and CodySwannGT/lisa#3952 records it as
+ * such: two implementations remain. **A behaviour with no row in the corpus is
+ * free to diverge — add a row when you add a branch.**
+ *
+ * ## The two guards agree on the RESOLUTION, not on the verdict
+ *
+ * When the effective directory cannot be known, both guards decline to resolve
+ * the token. What they then do differs, and that difference is deliberate:
+ * `parity-safety-net.sh` refuses, because a destructive command it cannot see
+ * is the thing it exists to stop. This guard fails open, which is the doctrine
+ * every other undecidable case in this file follows. The corpus asserts the
+ * resolved path, not the exit code, precisely so that one contract can bind two
+ * guards whose fail directions are correctly different.
  *
  * Fails OPEN and says so, like every other undecidable case in this file.
  */
 function scriptReachingForeignTree(payload, bound) {
   const command = payload.tool_input?.command;
   if (typeof command !== "string" || !command) return null;
+  let cwd = payload.cwd;
   for (const segment of command.split(COMMAND_SEPARATORS)) {
+    const target = cdTarget(segment);
+    if (target !== null) {
+      cwd = applyCd(cwd, target);
+      continue;
+    }
     const named = executedPath(segment);
     if (!named) continue;
-    const path = isAbsolute(named) ? named : join(payload.cwd, named);
+    if (!isAbsolute(named) && cwd === null) {
+      // Contract point 3: the effective directory is unknown, so WHICH copy of
+      // a same-named script would run is unknown too. Declining to resolve is
+      // the half shared with parity-safety-net.sh; failing open rather than
+      // refusing is this guard's own doctrine, and the corpus binds the two
+      // guards on the resolution precisely so it does not have to bind them
+      // on a verdict one of them would be wrong to reach.
+      say(
+        `cannot tell which directory ${named} would run from; NOT enforcing on it`
+      );
+      continue;
+    }
+    const path = isAbsolute(named) ? resolve(named) : resolve(cwd, named);
     let text;
     try {
       if (statSync(path).size > SCRIPT_READ_LIMIT) {
@@ -386,7 +478,7 @@ function scriptReachingForeignTree(payload, bound) {
       // Not a readable file: nothing was executed that this can read.
       continue;
     }
-    const foreign = foreignTreeIn(text, bound, payload.cwd);
+    const foreign = foreignTreeIn(text, bound, cwd);
     if (foreign) return { script: path, foreign };
   }
   return null;

package/plugins/src/base/rules/eager/ready-role-filing.md

@@ -6,10 +6,11 @@ Filing a work item without the ready role is an **incomplete handoff** — build
 
 **An omitted `build_ready` is NOT build-ready on JIRA, GitHub, and Linear alike.** Ready is an explicit claim, never an accident of which tracker a project configured. This is a **breaking change** for GitHub and Linear callers, which previously treated omission as ready; `lisa-github-validate-issue` F4's compensating omitted → `true` normalization is removed with it.
 
-## Every filing declares one of two things
+## Every filing declares one of three things
 
 - **`build_ready: true`** — complete enough to build; enters the ready lane for auto-pickup. Required for any complete defect found during other work, so it is claimable next cycle with no human flipping status.
 - **`human_gate: "<why a human must judge this first>"`** — deliberately held outside the queue. The writer stamps a visible line plus `<!-- [lisa-human-gate] reason=<short-slug> -->` so the hold is auditable.
+- **The container declaration** — `None — container: state rolls up from children`, the canonical line `derived-branch-plan` defines and every writer stamps in place of a Target Backend Environment. A container is never build-ready (`leaf-only-lifecycle`) and needs no gate, so it declares the third thing instead. Deliberately **not** keyed on `--label type:Epic`: a declared type is a claim that costs a leaf nothing and leaves it looking buildable, where the container line costs the item the environment and Branch Plan a leaf needs to be built. It 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 — writers reject it and name both ways to resolve it. `build_ready: false` with no reason is the same omission with a value attached. `build_ready` stays subordinate to `leaf-only-lifecycle`: a container is never build-ready and needs no gate.
 
@@ -21,7 +22,7 @@ Filed, not ready, and no `human_gate` is the **incomplete handoff** case — wri
 
 ## This rule is enforced
 
-The PreToolUse guard `block-direct-issue-create.sh` refuses a direct tracker-creation command (`gh issue create`, `gh api` POST to an issues endpoint, `linear`/`jira`/`acli` creates, equivalent `curl` posts) that carries **no readiness declaration** — no configured build-ready role and no `[lisa-human-gate]` marker. It shipped because this rule as prose did not bind: 13 of 13 issues filed during the session that merged it bypassed it, several by the agent that wrote it, while the one obligation backed by a git hook was honored 50 of 50 times. It stands down where no tracker is configured, and for an operator who set `LISA_ALLOW_DIRECT_ISSUE_CREATE` **in the ambient environment** — never from an inline assignment on the refused command.
+The PreToolUse guard `block-direct-issue-create.sh` refuses a direct tracker-creation command (`gh issue create`, `gh api` POST to an issues endpoint, `linear`/`jira`/`acli` creates, equivalent `curl` posts) that carries **none of the three declarations** — no configured build-ready role, no `[lisa-human-gate]` marker, and no container declaration. It shipped because this rule as prose did not bind: 13 of 13 issues filed during the session that merged it bypassed it, several by the agent that wrote it, while the one obligation backed by a git hook was honored 50 of 50 times. It stands down where no tracker is configured, and for an operator who set `LISA_ALLOW_DIRECT_ISSUE_CREATE` **in the ambient environment** — never from an inline assignment on the refused command.
 
 **The role is the TARGET repository's, not the caller's.** A creation addressed at another repository — `--repo` / `-R`, or a `repos/<org>/<repo>/issues` endpoint — is judged against that repository's build-ready role: `hardening.upstreamReadyRole` (default `status:ready`) when the target is `hardening.upstreamRepo`, and the stock `status:ready` otherwise. A creation naming no repository, or naming the project's own `github.org`/`github.repo`, is judged against the project's own role exactly as before. A declaration is required either way; only its vocabulary changes.
 

package/plugins/src/base/rules/reference/ready-role-filing.md

@@ -22,7 +22,7 @@ So the same vendor-neutral `lisa-tracker-write` call produced a different lifecy
 
 The safe direction is the implicit one. A ticket that reaches a build queue by accident is worse than one that waits, because the queue is what agents act on autonomously.
 
-## Every filing declares one of two things
+## Every filing declares one of two things — three, counting containers
 
 A writer accepts a filing only when it carries **one** of:
 
@@ -38,6 +38,24 @@ Filed, not ready, and no `human_gate` is the **incomplete handoff** case: the wr
 
 `build_ready` remains strictly subordinate to `leaf-only-lifecycle`: a container is never build-ready regardless of what a caller passes, and a container needs no `human_gate` because its state rolls up from its children rather than being claimed.
 
+### The container declaration, on the direct-CLI path
+
+That exemption used to live only in writer prose, which meant the guard below — the thing that actually runs — had no arm for it. A container could satisfy the guard only by declaring a build-ready role `leaf-only-lifecycle` forbids on it, or a human gate it does not have. **A guard that can only be obeyed by writing something untrue is worse than one that simply refuses**, because the lie is indistinguishable from a correct filing afterwards, and both available lies corrupt data another control reads: a stamped role puts a container in the lane build-intake claims from, and a fabricated hold marker is a state change with no inverse.
+
+So a container filed directly through a tracker CLI declares a **third** thing — the canonical container line the `derived-branch-plan` rule already defines and every writer already stamps in place of a Target Backend Environment:
+
+```text
+## Target Backend Environment
+
+None — container: state rolls up from children
+```
+
+**Not `--label type:Epic`.** A declared type is a claim, and one that costs a leaf nothing: the item it produces still looks buildable, so keying the exemption on it would hand any item willing to mistype itself a free bypass of the readiness requirement — the shape of the measured case where an allowlist added to harden a guard became the way around it. The container line is self-limiting instead: writing it costs the item the Target Backend Environment and Branch Plan a leaf needs to be built at all, so it is only useful to something that actually is a container.
+
+The declaration is refused alongside a **by-design leaf type** declared as a flag value (`type:Bug` / `type:Task` / `type:Sub-task` / `type:Improvement`, or the `--type` spelling on a state-based tracker) — an item cannot be a container and a leaf at once. Story and Spike are deliberately not in that set: `leaf-only-lifecycle`'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.
+
+One string, defined in one rule, read by the guard and stamped by the writers — which is what keeps this exemption from drifting back into prose only.
+
 ## Complete defects found during other work are filed build-ready
 
 Any defect discovered while doing something else, which is complete enough to build, is filed through `lisa-track` / `lisa-tracker-write` with **explicit `build_ready: true`**. It must be claimable by build-intake on the next cycle with no human flipping status. "Complete enough to build" is the `work-item-definition-of-ready` bar — reproduction, observed-versus-expected, and Gherkin acceptance criteria — not a placeholder to be fleshed out later.
@@ -60,7 +78,7 @@ The rule shipped as prose first, and prose did not hold. A conformance audit of
 
 The control is the PreToolUse Bash guard `block-direct-issue-create.sh`, shipped to every agent variant (Claude, Codex, Cursor, Copilot, agy, OpenCode) and to the host `scripts/lisa-hooks/` fallback. It refuses a direct tracker-creation command — `gh issue create`, `gh api` POST to an issues endpoint, `gh api graphql createIssue`, `linear issue create`, `jira issue create`, `acli … create`, and equivalent `curl` posts — when the command carries **no readiness declaration**.
 
-What it checks is the artifact, not the caller. A Bash-level hook cannot observe call provenance: any provenance signal is settable by the very agent being governed, so a guard built on one would be theatre. So the guard asks whether the command about to run produces a correctly declared item — the configured build-ready role is applied, or a `[lisa-human-gate]` marker is present (inline, or in the `--body-file` the create is about to submit). That is precisely the machine-checkable content of this rule, and it lets the three writers through by construction, because they always stamp one.
+What it checks is the artifact, not the caller. A Bash-level hook cannot observe call provenance: any provenance signal is settable by the very agent being governed, so a guard built on one would be theatre. So the guard asks whether the command about to run produces a correctly declared item — the configured build-ready role is applied, or a `[lisa-human-gate]` marker is present, or the container declaration is (each read inline, or in the `--body-file` the create is about to submit). That is precisely the machine-checkable content of this rule, and it lets the three writers through by construction, because they always stamp one.
 
 Two ways out, both deliberate:
 

package/plugins/src/base/skills/lisa-github-write-issue/SKILL.md

@@ -289,6 +289,22 @@ proceed — the marker still holds. Never file the label *instead of* the marker
 
 If a leaf arrives with `build_ready` omitted or `false` **and** no `human_gate`, do not create it: report the incomplete handoff and name both ways to resolve it (`build_ready: true`, or a `human_gate` reason). Containers are exempt — their state rolls up from children, so they need neither.
 
+**The container exemption is executable, not prose.** It used to live only in the sentence above,
+which meant the `block-direct-issue-create.sh` guard — the control that actually runs on the CLI
+path — had no arm for it, and a container could satisfy that guard only by declaring a build-ready
+role `leaf-only-lifecycle` forbids on it or a human gate it does not have. A container now declares
+a **third** thing, and this skill already writes it: the canonical Target Backend Environment value
+`None — container: state rolls up from children`, defined once by `derived-branch-plan`. The guard
+reads that one string, so there is nothing for the skill and the guard to disagree about.
+
+Two consequences for a container written from here. Render the Target Backend Environment section
+with that exact value — an absent section reads as *underivable*, not exempt, and leaves the guard
+nothing to read. And do not put a **by-design leaf type** (`type:Bug` / `type:Task` /
+`type:Sub-task` / `type:Improvement`) on a filing carrying that declaration: an item cannot be a
+container and a leaf at once, and the guard refuses the combination. `type:Story` and `type:Spike`
+are not in that set, because `leaf-only-lifecycle`'s childless-parent exception makes them
+leaf-or-container depending on child work.
+
 ## Phase 5.5 — Validate (Pre-write Gate)
 
 Before any write, invoke `lisa-github-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa-github-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.

package/scripts/check-cwd-resolution-corpus.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Refuse a cwd-resolution corpus that cannot bite.
+ *
+ * Two guards answer "which file will this command actually execute?" in two
+ * languages — POSIX shell in `parity-safety-net.sh`, Node in
+ * `worktree-binding-guard.mjs` — and one corpus of rows is what keeps their
+ * answers the same (CodySwannGT/lisa#3952). That arrangement is only worth
+ * anything while the rows are adversarial, and rows decay in one direction: a
+ * `holds` row is easy to write and always passes, so a corpus left alone drifts
+ * towards proving the resolver RAN rather than that it BITES.
+ *
+ * So the shape is enforced rather than requested:
+ *
+ * - both adversarial classes present, because a resolver is wrong in two
+ *   directions and one class of row only ever catches one of them
+ * - every contract point carried by at least one adversarial row, because a
+ *   point pinned only by rows both wrong implementations already pass is
+ *   documented rather than pinned
+ * - at least one `unknown` expectation, because the fail-closed floor is the
+ *   half nobody writes voluntarily
+ * - a row that skips a guard must say why, in the row, rather than by omission
+ *
+ * Exits 1 with the reason on any violation. Report-only otherwise.
+ * @module scripts/check-cwd-resolution-corpus
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const CORPUS = path.resolve(
+  "tests/unit/hooks/support/cwd-resolution-corpus.json"
+);
+const GUARDS = ["shell", "node"];
+const CONTROLS = ["bites", "wall", "holds"];
+/** The classes that fail under a wrong implementation. `holds` does not. */
+const ADVERSARIAL = ["bites", "wall"];
+
+/**
+ * Read and parse the corpus.
+ * @returns The parsed corpus document
+ */
+function load() {
+  return JSON.parse(readFileSync(CORPUS, "utf8"));
+}
+
+/**
+ * Every id appears once, so a row cannot be silently replaced by a copy.
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkIds(rows) {
+  const seen = new Set();
+  const bad = [];
+  for (const row of rows) {
+    if (seen.has(row.id)) bad.push(`duplicate row id: ${row.id}`);
+    seen.add(row.id);
+  }
+  return bad;
+}
+
+/**
+ * Each row declares a known control class and at least one guard it applies to.
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkShape(rows) {
+  const bad = [];
+  for (const row of rows) {
+    if (!CONTROLS.includes(row.control)) {
+      bad.push(`${row.id}: control must be one of ${CONTROLS.join(", ")}`);
+    }
+    const applies = row.applies ?? [];
+    if (applies.length === 0) bad.push(`${row.id}: applies to no guard`);
+    for (const guard of applies) {
+      if (!GUARDS.includes(guard))
+        bad.push(`${row.id}: unknown guard ${guard}`);
+    }
+    if (!applies.includes("node") && !row.why_not_node) {
+      bad.push(
+        `${row.id}: skips the Node guard without saying why. A row that skips a guard by omission is how a gap becomes invisible — add why_not_node.`
+      );
+    }
+  }
+  return bad;
+}
+
+/**
+ * Both control classes are present, and the fail-closed floor is represented.
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkControls(rows) {
+  const bad = [];
+  for (const control of ADVERSARIAL) {
+    if (rows.some(row => row.control === control)) continue;
+    bad.push(
+      control === "bites"
+        ? 'no row has control "bites". Nothing here fails under a pre-fix implementation, so the silent direction — a confident verdict about a file nobody was about to run — is unguarded.'
+        : 'no row has control "wall". Nothing here fails under an over-eager implementation, so nothing stops the fail-closed floor becoming a wall, and a wall gets switched off.'
+    );
+  }
+  if (!rows.some(row => row.expect === "unknown")) {
+    bad.push(
+      'no row expects "unknown". The fail-closed floor is the half nobody writes voluntarily, so it is required.'
+    );
+  }
+  return bad;
+}
+
+/**
+ * Every contract point is carried by at least one row that a pre-fix
+ * implementation would fail.
+ * @param contract - Contract points, keyed by number
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkCoverage(contract, rows) {
+  const bad = [];
+  for (const point of Object.keys(contract)) {
+    const covering = rows.filter(row =>
+      (row.contract ?? []).map(String).includes(point)
+    );
+    if (covering.length === 0) {
+      bad.push(
+        `contract point ${point} has no row. Add a row when you add a branch.`
+      );
+      continue;
+    }
+    if (!covering.some(row => ADVERSARIAL.includes(row.control))) {
+      bad.push(
+        `contract point ${point} is carried only by "holds" rows, which both wrong implementations already pass. It is documented, not pinned.`
+      );
+    }
+  }
+  return bad;
+}
+
+/**
+ * Report every violation at once, then exit.
+ * @returns Process exit code
+ */
+function main() {
+  const corpus = load();
+  const rows = corpus.rows ?? [];
+  const bad = [
+    ...checkIds(rows),
+    ...checkShape(rows),
+    ...checkControls(rows),
+    ...checkCoverage(corpus.contract ?? {}, rows),
+  ];
+  if (bad.length > 0) {
+    process.stderr.write("cwd-resolution corpus is not adversarial enough:\n");
+    for (const line of bad) process.stderr.write(`  - ${line}\n`);
+    return 1;
+  }
+  const biting = rows.filter(row => ADVERSARIAL.includes(row.control)).length;
+  process.stdout.write(
+    `cwd-resolution corpus: ${rows.length} row(s), ${biting} of which a wrong implementation fails; ${Object.keys(corpus.contract).length} contract point(s) each pinned by at least one.\n`
+  );
+  return 0;
+}
+
+process.exit(main());