@codyswann/lisa 4.27.6 → 4.27.8

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

@@ -17,13 +17,22 @@
  * The port matches on the raw command text rather than tokenising it, which
  * makes it naturally immune to the prefix and tokenisation bypass classes the
  * shell guard had to be restructured to close — an unrecognised wrapper is just
- * more text before the CLI name. Two deliberate differences remain, both in the
- * permissive direction so this port can never refuse something the canonical
- * guard would allow:
- *   - `--body-file` contents are not read, so an OpenCode caller declaring a
- *     human gate puts the `[lisa-human-gate]` marker on the command line;
+ * more text before the CLI name.
+ *
+ * It reaches past the command text in the two places the canonical guard does:
+ * into the contents of any file the command names — which is what closes
+ * `bash create.sh`, `node wrapper.mjs` and `curl --data-binary @payload.json`
+ * — and into the lifecycle-role declaration a state-based tracker has to use
+ * because no flag on `curl` can carry a workflow state.
+ *
+ * Two deliberate differences remain, both in the permissive direction so this
+ * port can never refuse something the canonical guard would allow:
  *   - remote execution (`ssh host '…'`) is not intercepted, matching the shell
- *     guard's documented limit.
+ *     guard's documented limit;
+ *   - a declaration found inside a FILE answers for every creation in that
+ *     file. Matching raw text cannot attribute a label to one create among
+ *     several, and the alternative — accepting only whole-scope markers there
+ *     — would refuse an honest single-create script that carries its label.
  *
  * NOTE: This file is a template Lisa copies verbatim into a host project's
  * `.opencode/plugin/`. It is intentionally excluded from this repo's tsconfig
@@ -53,6 +62,37 @@ const LisaBlockDirectIssueCreate = async () => {
   const ISSUES_ENDPOINT = /repos\/([^/\s]+)\/([^/\s]+)\/issues\b/;
   const DEFAULT_READY_ROLE = "status:ready";
   const DEFAULT_UPSTREAM_REPO = "CodySwannGT/lisa";
+  /**
+   * The build-ready declaration for a tracker whose ready role is a workflow
+   * STATE rather than a label.
+   *
+   * GitHub's role is a label and labels are argv-native, so `--label` has
+   * always been writable there. JIRA's and Linear's are states living in the
+   * request payload, and the mandated client is `curl`, which has no flag that
+   * carries one — so the only declaration those trackers could satisfy was
+   * `[lisa-human-gate]`, a false statement about a build-ready item. A guard
+   * that leaves an honest operator no compliant command and one dishonest one
+   * fails in the harmful direction.
+   *
+   * The role is what the access layer already consumes: it refuses a
+   * caller-supplied state id, takes `lifecycle_role`, resolves it against the
+   * tracker's own catalog and fails closed. So the token decides the lane
+   * rather than decorating the command.
+   *
+   * The optional quote AFTER the key name is load-bearing: the refusal tells
+   * the operator to put the declaration in the request payload, and a JSON
+   * payload quotes its keys, so demanding `[:=]` immediately after a bare key
+   * name refuses the exact spelling it just asked for.
+   */
+  const LIFECYCLE_ROLE_READY =
+    /(?:^|[^\w.-])(?:lifecycle_role|LIFECYCLE_ROLE)["']?\s*[:=]\s*["']?ready\b|(?:^|[^\w.-])--role[=\s]+["']?ready\b/;
+  /** A creation verb, and a tracker endpoint to send it to. */
+  const GRAPHQL_CREATE = /createIssue|issueCreate/;
+  const TRACKER_ENDPOINT =
+    /api\.linear\.app\/graphql|api\.github\.com|atlassian\.net\/rest\/api|repos\/[^/\s?#'"]+\/[^/\s?#'"]+\/issues/i;
+  /** Bounds on reading files a command names, so a hook stays a hook. */
+  const MAX_FILE_BYTES = 262_144;
+  const MAX_FILES = 8;
   const CREATION_SIGNATURES: readonly {
     readonly re: RegExp;
     readonly name: string;
@@ -117,6 +157,8 @@ const LisaBlockDirectIssueCreate = async () => {
     readonly upstreamReadyRole: string;
     /** Whether the caller's ready role is a GitHub label at all. */
     readonly callerIsGithub: boolean;
+    /** Whether the caller's ready role is a workflow state, not a label. */
+    readonly stateRoleTracker: boolean;
   }
 
   /** Which roles satisfy a filing, and the target a refusal should name. */
@@ -179,11 +221,62 @@ const LisaBlockDirectIssueCreate = async () => {
       ).toLowerCase(),
       upstreamReadyRole: hardening.upstreamReadyRole ?? DEFAULT_READY_ROLE,
       callerIsGithub: tracker === "github",
+      stateRoleTracker: tracker === "jira" || tracker === "linear",
     };
   };
 
   const policy = await resolvePolicy();
 
+  /**
+   * The readable files a command names, with their contents.
+   *
+   * The guard used to match the command text and nothing else, so a creation
+   * one file away was invisible: `bash create.sh` is two words, and the
+   * conjunction it looks for — an endpoint and a creation verb together — never
+   * formed. Lisa's own guards push agents into exactly that shape, telling them
+   * to write payloads to a file and execute the file, so complying with the
+   * guidance produced the bypass.
+   *
+   * Which programs execute their operands is unbounded and every gap in such a
+   * list fails open, so the question is inverted the same way the wrapper
+   * question was: which tokens name a file? That is bounded by the command.
+   * @param props Helper inputs.
+   * @param props.text The command being inspected.
+   * @returns Each named file's path and contents, bounded in count and size.
+   */
+  const namedFiles = async ({
+    text,
+  }: Readonly<{ text: string }>): Promise<
+    readonly { readonly path: string; readonly text: string }[]
+  > => {
+    const found: { path: string; text: string }[] = [];
+    const seen = new Set<string>();
+    const candidates = text
+      .split(/[\s'"]+/)
+      // `curl -d@payload.json` is one word, and the path is the half after the
+      // `@`. Both halves are offered rather than guessing which flag it was.
+      .flatMap(raw =>
+        raw.includes("@") ? [raw, raw.split("@").pop() ?? ""] : [raw]
+      );
+    for (const raw of candidates) {
+      if (found.length >= MAX_FILES) break;
+      const token = raw.replace(/^@/, "");
+      if (!token || token === "-" || seen.has(token)) continue;
+      seen.add(token);
+      try {
+        const handle = Bun.file(token);
+        // A file too large to inspect is skipped rather than half-read: a
+        // truncated scan reports a confident allow about text it never saw.
+        if (handle.size === 0 || handle.size > MAX_FILE_BYTES) continue;
+        if (!(await handle.exists())) continue;
+        found.push({ path: token, text: await handle.text() });
+      } catch {
+        continue;
+      }
+    }
+    return found;
+  };
+
   /**
    * A repository token reduced to a comparable `owner/name`.
    *
@@ -274,10 +367,7 @@ const LisaBlockDirectIssueCreate = async () => {
       const inlineOverride = /LISA_ALLOW_DIRECT_ISSUE_CREATE=/.test(command);
       if (process.env["LISA_ALLOW_DIRECT_ISSUE_CREATE"] && !inlineOverride)
         return;
-      const signature = CREATION_SIGNATURES.find(entry =>
-        entry.re.test(command)
-      );
-      if (!signature) return;
+      const inline = CREATION_SIGNATURES.find(entry => entry.re.test(command));
       // The build-ready role counts ONLY as the value of a label / state flag.
       // A free-text scan of the command let a bug report's own title declare
       // readiness — `gh issue create --title "status:ready is broken"` — which
@@ -300,17 +390,71 @@ const LisaBlockDirectIssueCreate = async () => {
         policy,
         targetRepository({ declarable })
       );
-      const declaresRole = [...declarable.matchAll(LABEL_FLAG)].some(match =>
-        (match[2] ?? "")
-          .split(",")
-          .map(part => part.trim())
-          .some(candidate => roles.includes(candidate))
-      );
-      if (declaresRole || declarable.includes(HUMAN_GATE_MARKER)) return;
+      // The role escape is scoped: accepted only where no argv flag on the
+      // mandated client can carry a state, and never on a GitHub target where
+      // the label IS writable and a second weaker spelling would be a hole.
+      const stateRoleOk = policy.stateRoleTracker && named === undefined;
+      const declaresFor = (
+        text: string,
+        against: readonly string[],
+        roleOk: boolean
+      ): boolean =>
+        [...text.matchAll(LABEL_FLAG)].some(match =>
+          (match[2] ?? "")
+            .split(",")
+            .map(part => part.trim())
+            .some(candidate => against.includes(candidate))
+        ) ||
+        text.includes(HUMAN_GATE_MARKER) ||
+        (roleOk && LIFECYCLE_ROLE_READY.test(text));
+      const declares = (text: string): boolean =>
+        declaresFor(text, roles, stateRoleOk);
+      // A creation the command does not spell out itself, because it lives in
+      // a file the command runs or submits. The conjunction may straddle the
+      // two: `curl <endpoint> --data-binary @payload.json` keeps the endpoint
+      // in argv and the mutation in the file.
+      const fromFile = inline
+        ? undefined
+        : (await namedFiles({ text: command })).flatMap(file => {
+            const signature =
+              CREATION_SIGNATURES.find(entry => entry.re.test(file.text))
+                ?.name ??
+              (GRAPHQL_CREATE.test(file.text) &&
+              (TRACKER_ENDPOINT.test(file.text) ||
+                TRACKER_ENDPOINT.test(command))
+                ? "a tracker creation"
+                : undefined);
+            if (signature === undefined) return [];
+            // WHOSE vocabulary answers is decided by where the create inside
+            // the FILE is addressed, not by the command that ran it. `bash
+            // create.sh` names no repository, so reading the target from the
+            // command let a script doing `gh issue create --repo <other>` be
+            // waved through by this project's own lifecycle role — a role the
+            // other repository's build queue never reads.
+            const fileTarget = targetRepository({ declarable: file.text });
+            const scoped = rolesFor(policy, fileTarget);
+            const fileRoleOk =
+              policy.stateRoleTracker && scoped.named === undefined;
+            // A label rather than a marker, and the looseness is forced by
+            // this port's stated invariant. It matches raw text rather than
+            // tokenising, so it cannot attribute a label to ONE create inside
+            // a file. Accepting only whole-scope markers would refuse an
+            // honest single-create script that carries its label — a false
+            // refusal on the honest path, the failure mode this guard exists
+            // to remove. The cost is a decoy: a labelled create alongside an
+            // undeclared one in the same file passes here. The canonical guard
+            // refuses that, and this port is documented as never being
+            // STRICTER than the canonical guard, only ever looser.
+            if (declaresFor(file.text, scoped.roles, fileRoleOk)) return [];
+            return [`${signature} inside ${file.path}`];
+          })[0];
+      const signatureName = inline?.name ?? fromFile;
+      if (signatureName === undefined) return;
+      if (declares(declarable)) return;
       if (named !== undefined)
         throw new Error(
           [
-            `block-direct-issue-create: refusing ${signature.name} — this filing declares no readiness.`,
+            `block-direct-issue-create: refusing ${signatureName} — 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",
@@ -347,7 +491,7 @@ const LisaBlockDirectIssueCreate = async () => {
         );
       throw new Error(
         [
-          `block-direct-issue-create: refusing ${signature.name} — this filing declares no readiness.`,
+          `block-direct-issue-create: refusing ${signatureName} — 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",
@@ -369,6 +513,23 @@ const LisaBlockDirectIssueCreate = async () => {
           "If you must run the CLI directly, the command has to carry one of the",
           `two declarations itself: the configured build-ready role "${policy.readyRole}",`,
           `or a ${HUMAN_GATE_MARKER} marker in the body it submits.`,
+          ...(policy.stateRoleTracker
+            ? [
+                "",
+                `Your role "${policy.readyRole}" 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:",
+                "",
+                "  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.",
+              ]
+            : []),
+          "",
+          "WHERE THE DECLARATION IS READ FROM: the command, and the contents of any",
+          "file it runs or submits. Moving the create into a script no longer moves",
+          "it out of sight, so the declaration can live wherever the create does.",
           "",
           "OPERATOR ESCAPE: a human can export LISA_ALLOW_DIRECT_ISSUE_CREATE=1 in",
           "the environment before starting the session. Setting it inline on this",

package/expo/create-only/.github/nightly-e2e-policy.json

@@ -0,0 +1,16 @@
+{
+  "freshness_hours": 36,
+  "bypass_max_hours": 24,
+  "suites": [
+    {
+      "label": "🎭 Playwright Web E2E",
+      "workflow": "playwright-e2e.yml",
+      "match": { "mode": "run" }
+    },
+    {
+      "label": "📱 Maestro Native E2E",
+      "workflow": "maestro-e2e.yml",
+      "match": { "mode": "run" }
+    }
+  ]
+}

package/expo/create-only/.github/workflows/nightly-e2e-health.yml

@@ -85,6 +85,33 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  policy:
+    name: Read nightly E2E policy
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    outputs:
+      suites: ${{ steps.policy.outputs.suites }}
+      freshness_hours: ${{ steps.policy.outputs.freshness_hours }}
+      bypass_max_hours: ${{ steps.policy.outputs.bypass_max_hours }}
+    steps:
+      - name: Check out the policy
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Read the health suite table
+        id: policy
+        run: |
+          set -euo pipefail
+          file='.github/nightly-e2e-policy.json'
+          test -f "$file"
+          suites="$(jq -c '.suites' "$file")"
+          test "$(printf '%s' "$suites" | jq 'length')" -gt 0
+          printf 'suites=%s\n' "$suites" >> "$GITHUB_OUTPUT"
+          jq -er '.freshness_hours | numbers' "$file" \
+            | sed 's/^/freshness_hours=/' >> "$GITHUB_OUTPUT"
+          jq -er '.bypass_max_hours | numbers' "$file" \
+            | sed 's/^/bypass_max_hours=/' >> "$GITHUB_OUTPUT"
+
   # This job's `name:` is HALF of the required status-check context; the other
   # half is the reusable's job name (`🌙 Gate`). GitHub composes them as
   # `🌙 Nightly E2E Health / 🌙 Gate`. Pin both strings in a test.
@@ -102,6 +129,7 @@ jobs:
   # describing this context as required anywhere.
   health:
     name: 🌙 Nightly E2E Health
+    needs: policy
     # PIN AN IMMUTABLE REF. `@main` is not a supported pin for a merge gate: the
     # thing that decides whether code may merge must not change under you
     # between two runs of the same PR. Better still, pin the tag's commit SHA
@@ -189,14 +217,11 @@ jobs:
       # `⚠️ scope unverified: this run published no executed-flow count`.
       # Declaring `min_flows` is what turns that notice into a blocking question
       # — and from then on an UNREADABLE count blocks too, which is the point.
-      suites: |
-        [
-          {
-            "label": "Maestro native e2e",
-            "workflow": "maestro-e2e.yml",
-            "match": { "mode": "run" }
-          }
-        ]
+      suites: ${{ needs.policy.outputs.suites }}
+      freshness_hours: >-
+        ${{ fromJSON(needs.policy.outputs.freshness_hours) }}
+      bypass_max_hours: >-
+        ${{ fromJSON(needs.policy.outputs.bypass_max_hours) }}
       # A TIME-BOXED grace period. While this is in the future, MISSING evidence
       # reports but does not block, and every PR shows the expiry. A red suite
       # blocks inside the window too. Set it, do not remove it — and do not push

package/expo/create-only/.github/workflows/nightly-e2e-tracking.yml

@@ -0,0 +1,30 @@
+# Seeded by Lisa on first setup — this file is YOURS.
+# Lisa will not overwrite it. (copy-overwrite assets ARE replaced each run.)
+name: 📌 Nightly E2E Condition Tracking
+
+on:
+  workflow_run:
+    workflows:
+      - 🎭 Playwright Web E2E
+      - 📱 Maestro Native E2E
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read
+  issues: write
+
+concurrency:
+  group: nightly-e2e-tracking-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  track:
+    if: >-
+      github.event.workflow_run.event == 'schedule' &&
+      github.event.workflow_run.head_branch ==
+      github.event.repository.default_branch &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    uses: >-
+      CodySwannGT/lisa/.github/workflows/nightly-e2e-tracking.yml@08628ca0d2db045d3b0d87fcad8e444565836ff9
+    secrets: inherit

package/package.json

@@ -162,7 +162,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.27.6",
+  "version": "4.27.8",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -306,6 +306,6 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "ca4a03afc00b14c943a2b4eda506f4c9483ca4ec",
-  "gitHead": "ca4a03afc00b14c943a2b4eda506f4c9483ca4ec"
+  "lisaReleaseCommit": "6a87f9561279e498af1099f327f4c0c321a4e387",
+  "gitHead": "6a87f9561279e498af1099f327f4c0c321a4e387"
 }

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

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

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

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

package/plugins/lisa/.codex-plugin/skills/lisa-exploratory-qa/SKILL.md

@@ -122,17 +122,21 @@ Record **exactly one** outcome per invocation through the run-record CLI, naming
 specific, actionable, e.g. `Explored 4 personas; nothing confusing to file.` — or, when a decline suppressed the only candidates, `Explored 4 personas; 2 candidates suppressed by a prior decline — nothing new to propose.` — for `nothing-needed`; and for a `recovery-required` from an unreadable decline check, `Tracker unreachable during the decline check — restore credentials; nothing was filed this run.`):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+node "${CLAUDE_PLUGIN_ROOT:-node_modules/@codyswann/lisa/plugins/lisa}/scripts/automation-run-record.mjs" \
   --loop-id exploratory-bugs --outcome candidate-proposed \
   --summary "Explored 4 personas; filed 3 findings from the checkout flow — awaiting your flip to ready." \
   --runbook .lisa/automations/exploratory-bugs.runbook.md [--ref <ticket-url>]...
 ```
 
-If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
-`plugins/lisa/scripts/automation-run-record.mjs` or the source
-`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
-abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
-the cycle — a recording failure is a degradation to report, never a reason to block the loop.
+The `:-` default in that command is load-bearing, not decoration. `CLAUDE_PLUGIN_ROOT` is **not
+exported into an agent's Bash tool environment**, so the bare `"${CLAUDE_PLUGIN_ROOT}/scripts/…"`
+form expands to an absolute `/scripts/…` and exits 1. The default names the installed package copy,
+which resolves from the **consumer repository root** — which is where the recorder is actually
+invoked. Never substitute a bare `plugins/lisa/scripts/…` or `plugins/src/base/scripts/…` path:
+those are relative to the **Lisa package root**, not the repository you are standing in, and exit 1
+from there. If recording still fails, **degrade, never abort** (per `automation-runbook-contract`):
+note the recording failure in the run output and finish the cycle — a recording failure is a
+degradation to report, never a reason to block the loop.
 
 **Retirement evaluation (every run).** Evaluate this loop's runbook **Retirement condition** on
 every run, exactly as the `automation-runbook-contract` rule's Retirement section defines it — this

package/plugins/lisa/.codex-plugin/skills/lisa-intake/SKILL.md

@@ -145,33 +145,38 @@ Record **exactly one** outcome per invocation through the run-record CLI, naming
 specific, actionable, e.g. `Scanned 12 ready items; nothing to propose.` for `nothing-needed`):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+node "${CLAUDE_PLUGIN_ROOT:-node_modules/@codyswann/lisa/plugins/lisa}/scripts/automation-run-record.mjs" \
   --loop-id intake-tickets --outcome candidate-proposed \
   --summary "Routed PRD #1810 to Blocked with clarifying questions; the run succeeded." \
   --runbook .lisa/automations/intake-tickets.runbook.md [--ref <item-url>]...
 ```
 
 **A dry build lane must say what it looked in.** A `nothing-needed` run on `intake-tickets`
-additionally passes `--denominator` — the JSON from `buildIntakeDenominator()` in
-`scripts/intake-prework-denominator.mjs` — and the recorder **refuses the row without it**. This is
-not decoration: 31 consecutive cycles reported a dry lane against a queue holding 61 unswept
-pre-work rows, and every one of those records was honest. A missing row is noisy on inspection; a
-wrong denominator is silent forever and looks exactly like a healthy dry queue. Stating the swept
-set is what turns the silent wrong answer into an inspectable one (#2657).
+additionally passes `--denominator` — the JSON from `buildIntakeDenominator()` in the plugin
+scripts directory's `intake-prework-denominator.mjs`, resolved exactly like the recorder below —
+and the recorder **refuses the row without it**. This is not decoration: 31 consecutive cycles
+reported a dry lane against a queue holding 61 unswept pre-work rows, and every one of those
+records was honest. A missing row is noisy on inspection; a wrong denominator is silent forever
+and looks exactly like a healthy dry queue. Stating the swept set is what turns the silent wrong
+answer into an inspectable one (#2657).
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+node "${CLAUDE_PLUGIN_ROOT:-node_modules/@codyswann/lisa/plugins/lisa}/scripts/automation-run-record.mjs" \
   --loop-id intake-tickets --outcome nothing-needed \
   --summary "Nothing ready to build on team ENG. Looked in every lane holding work that has not started — Backlog (20), Todo (17), Ready (2), Blocked (61) — 100 items checked out of 343 still open." \
   --denominator "$DENOMINATOR_JSON" \
   --runbook .lisa/automations/intake-tickets.runbook.md
 ```
 
-If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
-`plugins/lisa/scripts/automation-run-record.mjs` or the source
-`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
-abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
-the cycle — a recording failure is a degradation to report, never a reason to block the loop.
+The `:-` default in that command is load-bearing, not decoration. `CLAUDE_PLUGIN_ROOT` is **not
+exported into an agent's Bash tool environment**, so the bare `"${CLAUDE_PLUGIN_ROOT}/scripts/…"`
+form expands to an absolute `/scripts/…` and exits 1. The default names the installed package copy,
+which resolves from the **consumer repository root** — which is where the recorder is actually
+invoked. Never substitute a bare `plugins/lisa/scripts/…` or `plugins/src/base/scripts/…` path:
+those are relative to the **Lisa package root**, not the repository you are standing in, and exit 1
+from there. If recording still fails, **degrade, never abort** (per `automation-runbook-contract`):
+note the recording failure in the run output and finish the cycle — a recording failure is a
+degradation to report, never a reason to block the loop.
 
 **Retirement evaluation (every run).** Both loop-ids this skill backs are **structural to the
 factory — they do not retire.** Their runbooks say so plainly instead of leaving the Retirement

package/plugins/lisa/.codex-plugin/skills/lisa-learnings-audit/SKILL.md

@@ -368,18 +368,24 @@ loop's runbook (the `--summary` is the operator-readable one-liner in the
 contract's exemplar voice — plain, specific, actionable):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+node "${CLAUDE_PLUGIN_ROOT:-node_modules/@codyswann/lisa/plugins/lisa}/scripts/automation-run-record.mjs" \
   --loop-id learnings-audit --outcome candidate-proposed \
   --summary "Proposed 2 promotions and 1 batch confirm; awaiting your flip to ready." \
   --runbook .lisa/automations/learnings-audit.runbook.md [--ref <ticket-url>]...
 ```
 
-If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory
-directly — the built copy `plugins/lisa/scripts/automation-run-record.mjs` or
-the source `plugins/src/base/scripts/automation-run-record.mjs`. If recording
-still fails, **degrade, never abort** (per `automation-runbook-contract`): note
-the recording failure in the run output and finish the run — a recording
-failure is a degradation to report, never a reason to block the loop.
+The `:-` default in that command is load-bearing, not decoration.
+`CLAUDE_PLUGIN_ROOT` is **not exported into an agent's Bash tool
+environment**, so the bare `"${CLAUDE_PLUGIN_ROOT}/scripts/…"` form expands
+to an absolute `/scripts/…` and exits 1. The default names the installed
+package copy, which resolves from the **consumer repository root** — which
+is where the recorder is actually invoked. Never substitute a bare
+`plugins/lisa/scripts/…` or `plugins/src/base/scripts/…` path: those are
+relative to the **Lisa package root**, not the repository you are standing
+in, and exit 1 from there. If recording still fails, **degrade, never
+abort** (per `automation-runbook-contract`): note the recording failure in
+the run output and finish the run — a recording failure is a degradation to
+report, never a reason to block the loop.
 
 ## Retirement condition
 

package/plugins/lisa/.codex-plugin/skills/lisa-linear-build-intake/SKILL.md

@@ -140,13 +140,15 @@ Build the denominator with the shared helper, which owns the type vocabulary so
 
 ```bash
 node -e '
-import("'"${CLAUDE_PLUGIN_ROOT:-plugins/src/base}"'/scripts/intake-prework-denominator.mjs").then(m => {
+import("'"${CLAUDE_PLUGIN_ROOT:-./node_modules/@codyswann/lisa/plugins/lisa}"'/scripts/intake-prework-denominator.mjs").then(m => {
   const d = m.buildIntakeDenominator({ lanes: JSON.parse(process.argv[1]), totalOpen: Number(process.argv[2]) });
   console.log(JSON.stringify(d));
   console.log(m.summarizeDryLane(d, { queue: process.argv[3] }));
 });' "$LANES_JSON" "$TOTAL_OPEN" "team $TEAM_KEY"
 ```
 
+The `./` on that default is load-bearing and is not the same as the recorder's. `import()` reads a bare `node_modules/…` as a **package specifier** named `node_modules` and fails with `ERR_MODULE_NOT_FOUND: Cannot find package 'node_modules'`; only `./`, `../`, `/` or a `file:` URL is a path. A `node <path>` command line has no such rule, which is why the run-recorder default alongside this one carries no `./`.
+
 `$LANES_JSON` is `[{"name":"<state>","type":"<state.type>","position":<state.position>,"count":<open rows>}, …]` for **every** state on the team, pre-work and not — the helper does the selecting.
 
 **Candidate order.** Work `$READY` first (it is the human-flipped signal), then the remaining pre-work lanes oldest-first. Every candidate outside `$READY` must clear Phase 2.5 before it is treated as a candidate at all.

package/plugins/lisa/.codex-plugin/skills/lisa-monitor/SKILL.md

@@ -171,17 +171,21 @@ plain, specific, actionable, e.g. `Health green; audit clean — nothing to prop
 unreachable during the decline check — restore credentials; nothing was filed this run.`):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+node "${CLAUDE_PLUGIN_ROOT:-node_modules/@codyswann/lisa/plugins/lisa}/scripts/automation-run-record.mjs" \
   --loop-id monitor --outcome candidate-proposed \
   --summary "Filed #1810 for the p99 latency spike; awaiting your flip to ready." \
   --runbook .lisa/automations/monitor.runbook.md [--ref <ticket-url>]...
 ```
 
-If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
-`plugins/lisa/scripts/automation-run-record.mjs` or the source
-`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
-abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
-the cycle — a recording failure is a degradation to report, never a reason to block the loop.
+The `:-` default in that command is load-bearing, not decoration. `CLAUDE_PLUGIN_ROOT` is **not
+exported into an agent's Bash tool environment**, so the bare `"${CLAUDE_PLUGIN_ROOT}/scripts/…"`
+form expands to an absolute `/scripts/…` and exits 1. The default names the installed package copy,
+which resolves from the **consumer repository root** — which is where the recorder is actually
+invoked. Never substitute a bare `plugins/lisa/scripts/…` or `plugins/src/base/scripts/…` path:
+those are relative to the **Lisa package root**, not the repository you are standing in, and exit 1
+from there. If recording still fails, **degrade, never abort** (per `automation-runbook-contract`):
+note the recording failure in the run output and finish the cycle — a recording failure is a
+degradation to report, never a reason to block the loop.
 
 **Retirement evaluation (every run).** Evaluate this loop's runbook **Retirement condition** on
 every standalone run, exactly as the `automation-runbook-contract` rule's Retirement section defines

package/plugins/lisa/.codex-plugin/skills/lisa-project-ideation/SKILL.md

@@ -321,17 +321,21 @@ propose.` for `nothing-needed`; and for a `recovery-required` from an unreadable
 `Tracker unreachable during the decline check — restore credentials; nothing was filed this run.`):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+node "${CLAUDE_PLUGIN_ROOT:-node_modules/@codyswann/lisa/plugins/lisa}/scripts/automation-run-record.mjs" \
   --loop-id exploratory-prds --outcome candidate-proposed \
   --summary "Created PRD #1810 for offline export; awaiting your flip to ready." \
   --runbook .lisa/automations/exploratory-prds.runbook.md [--ref <prd-url>]...
 ```
 
-If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
-`plugins/lisa/scripts/automation-run-record.mjs` or the source
-`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
-abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
-the run — a recording failure is a degradation to report, never a reason to block the loop.
+The `:-` default in that command is load-bearing, not decoration. `CLAUDE_PLUGIN_ROOT` is **not
+exported into an agent's Bash tool environment**, so the bare `"${CLAUDE_PLUGIN_ROOT}/scripts/…"`
+form expands to an absolute `/scripts/…` and exits 1. The default names the installed package copy,
+which resolves from the **consumer repository root** — which is where the recorder is actually
+invoked. Never substitute a bare `plugins/lisa/scripts/…` or `plugins/src/base/scripts/…` path:
+those are relative to the **Lisa package root**, not the repository you are standing in, and exit 1
+from there. If recording still fails, **degrade, never abort** (per `automation-runbook-contract`):
+note the recording failure in the run output and finish the run — a recording failure is a
+degradation to report, never a reason to block the loop.
 
 **Retirement evaluation (every run).** Evaluate this loop's runbook **Retirement condition** on
 every run, exactly as the `automation-runbook-contract` rule's Retirement section defines it — this