@codyswann/lisa 2.326.3 → 2.328.0

package/plugins/lisa/.codex-plugin/skills/lisa-setup-local-env/scripts/local-env.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Bring a developer's machine in line with the toolchain the project declares.
+ *
+ * The manifest, the planner, the pins and the installers are the remote flow's,
+ * unchanged and imported — this is the surface that was missing, not a second
+ * implementation. `remoteEnv.tools` was always surface-aware and the executor
+ * always understood `local`; the only way to reach either was to run a file
+ * called `setup-remote-env.mjs` out of a directory called `lisa-remote-env`,
+ * which nobody looking for local setup ever found.
+ *
+ * Two things differ from the remote flow, and both are because a person is here:
+ *
+ *   consent  — a container provisions itself silently because it is disposable
+ *              and nobody is watching. A laptop belongs to someone, so nothing
+ *              is installed until they ask with --install-tools.
+ *
+ *   tolerance — a container that cannot be fully provisioned should fail before
+ *              it half-runs, because there is no one to read the report. A
+ *              developer can act on a list, so an unprovisionable tool is
+ *              reported, everything else is still installed, and the exit code
+ *              carries the failure.
+ * @module local-env
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve a script belonging to a sibling skill.
+ *
+ * Skills are always siblings under one `skills/` directory, in every install
+ * layout, so this holds for a plugin install, a checkout, and node_modules
+ * alike. Failing loudly here beats reimplementing what the sibling owns.
+ * @param {string} skill Sibling skill slug.
+ * @param {string} script Script filename.
+ * @returns {string} Absolute path.
+ */
+function siblingScript(skill, script) {
+  const path = resolve(HERE, "..", "..", skill, "scripts", script);
+  if (!existsSync(path)) {
+    throw new Error(
+      `cannot find ${skill}/scripts/${script} beside this skill.\n` +
+        `Local setup composes with that skill rather than reimplementing it: ` +
+        `the pins, checksums and installers must be the same ones the remote ` +
+        `surface uses, or the two drift and only one gets fixed.`
+    );
+  }
+  return path;
+}
+
+/**
+ * Load the pieces the remote flow owns.
+ * @returns {Promise<object>} The imported helpers.
+ */
+async function loadRemoteEnv() {
+  const setup = await import(
+    pathToFileURL(
+      siblingScript("lisa-setup-remote-env", "setup-remote-env.mjs")
+    ).href
+  );
+  const toolchain = await import(
+    pathToFileURL(siblingScript("lisa-setup-remote-env", "toolchain.mjs")).href
+  );
+  return { ...toolchain, ...setup };
+}
+
+/**
+ * Describe one blocked decision in terms a person can act on.
+ *
+ * A blocked step on a laptop is usually one of two things, and they are fixed
+ * differently: a tool the project requires and the machine lacks (install it),
+ * or a tool with no artifact pinned for this platform (add the pin, or install
+ * it however this platform normally would). Printing the planner's reason alone
+ * left the reader to work out which.
+ * @param {object} step A plan step.
+ * @param {string} platform The platform key that was resolved against.
+ * @returns {string} A rendered block.
+ */
+function explainBlocked(step, platform) {
+  if (step.action === "invalid" && step.reason.includes("no pin for")) {
+    return (
+      `  ${step.name} — declared, but no artifact is pinned for ${platform}.\n` +
+      `      Lisa will not guess a download URL, because a guessed artifact is ` +
+      `one the checksum cannot vouch for.\n` +
+      `      Add a "${platform}" block under this tool's "platforms" map, or ` +
+      `install it yourself.`
+    );
+  }
+  return `  ${step.name} — ${step.reason.split("\n")[0]}`;
+}
+
+/**
+ * Report and optionally apply the local toolchain.
+ * @param {object} argv Parsed arguments.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function run(argv) {
+  const env = await loadRemoteEnv();
+  // Both seams exist for tests, and both default to this machine. A platform
+  // that can only be exercised by running on it is one CI will never cover,
+  // which is how a resolution bug ships to the platform nobody tested.
+  const platform = argv.platform ?? env.currentPlatform();
+  const { tools } = env.readRemoteEnvConfig(argv.cwd);
+
+  const declared = (tools.require ?? []).length + (tools.install ?? []).length;
+  if (declared === 0) {
+    console.log(
+      "No tools are declared in remoteEnv.tools, so there is nothing to check.\n" +
+        "Run /lisa:detect-tooling — it reads npm scripts, MCP servers, " +
+        "credential\nnotes and quality config, and proposes pinned entries for " +
+        "what it finds."
+    );
+    return 0;
+  }
+
+  const plan = env.planToolchain(tools, env.probe, "local", platform);
+  const blocked = plan.filter(
+    step => step.action === "missing" || step.action === "invalid"
+  );
+  const installable = plan.filter(step => step.action === "install");
+
+  if (argv.json) {
+    console.log(JSON.stringify({ platform, plan }, null, 2));
+    return blocked.length ? 1 : 0;
+  }
+
+  console.log(`Local toolchain for ${platform}\n`);
+  for (const step of plan) {
+    console.log(`  ${step.action.padEnd(8)} ${step.reason.split("\n")[0]}`);
+  }
+
+  if (installable.length && !argv.installTools) {
+    console.log(
+      `\n${installable.length} declared tool(s) can be installed here.\n` +
+        `Nothing has been installed: this machine is yours, not a container.\n` +
+        `Re-run with --install-tools to provision them into ~/.local/bin.`
+    );
+  }
+
+  if (installable.length && argv.installTools) {
+    const binDir = env.ensureBinDir();
+    console.log(`\nInstalling into ${binDir}`);
+    for (const step of installable) {
+      console.log(`  ${step.name}`);
+      if (!argv.dryRun) env.installTool(step.tool, binDir);
+    }
+  }
+
+  if (blocked.length) {
+    console.log(`\n${blocked.length} tool(s) this command cannot resolve:\n`);
+    for (const step of blocked) console.log(explainBlocked(step, platform));
+    return 1;
+  }
+
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const argv = {
+    installTools: process.argv.includes("--install-tools"),
+    dryRun: process.argv.includes("--dry-run"),
+    json: process.argv.includes("--json"),
+  };
+  run(argv)
+    .then(code => process.exit(code))
+    .catch(err => {
+      console.error(err.message);
+      process.exit(1);
+    });
+}

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/SKILL.md

@@ -95,6 +95,19 @@ This repository has paid for that twice: `gh` was declared nowhere and a cloud s
 
 The detector proposes and a human decides. It writes nothing, so provisioning still only ever happens from a reviewed, pinned, checksummed entry.
 
+## The same manifest provisions a laptop
+
+`remoteEnv.tools` is not a remote-only manifest, and `/lisa:setup:local-env` is how a developer
+applies it to their own machine — same pins, same checksums, same installers, differing only in
+that nothing installs without `--install-tools` and that a newer tool already on `PATH` is left
+alone rather than downgraded.
+
+A downloaded tool declares a `platforms` map keyed `<platform>-<arch>`, each block carrying its
+own `install` method, `url`, and `sha256`, because the artifact and the archive kind both vary
+by platform. Before that existed, the only way to keep a Linux binary off a laptop was
+`surfaces: ["remote"]`, which achieved it by making the tool uninstallable there — so `bws` and
+`gh` were required on developer machines and provisionable only in containers.
+
 ## Toolchain manifest — two entry kinds
 
 ```json
@@ -108,20 +121,23 @@ The detector proposes and a human decides. It writes nothing, so provisioning st
         { "name": "unzip" }
       ],
       "install": [
-        {
-          "name": "bws",
-          "version": "2.1.0",
-          "install": "release-zip",
-          "url": "https://<vendor>/releases/download/bws-v2.1.0/bws-<platform>-2.1.0.zip",
-          "sha256": "<sha256 published with that exact release>"
-        },
         {
           "name": "gh",
           "version": "2.83.0",
-          "install": "release-tar",
-          "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
-          "sha256": "<sha256 published with that exact release>",
-          "binary": "gh_2.83.0_linux_amd64/bin/gh"
+          "platforms": {
+            "linux-x64": {
+              "install": "release-tar",
+              "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
+              "sha256": "<sha256 published with that exact release>",
+              "binary": "gh_2.83.0_linux_amd64/bin/gh"
+            },
+            "darwin-arm64": {
+              "install": "release-zip",
+              "url": "https://<vendor>/releases/download/v2.83.0/gh_2.83.0_macOS_arm64.zip",
+              "sha256": "<sha256 published with that exact release>",
+              "binary": "gh_2.83.0_macOS_arm64/bin/gh"
+            }
+          }
         },
         {
           "name": "codex",

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -29,6 +29,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   chmodSync,
   existsSync,
@@ -37,7 +38,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
@@ -122,6 +123,34 @@ export function probe(name, exec = execFileSync) {
   }
 }
 
+/**
+ * Refuse an archive whose contents are not exactly what was pinned.
+ *
+ * Hashed in-process rather than by shelling out. `sha256sum` is a GNU coreutils
+ * program: it is not present on a stock macOS, where the equivalent is
+ * `shasum -a 256`, and it was never in the manifest's `require` list either — so
+ * the verification step depended on a tool nothing asserted, on every surface.
+ * Doing it here removes the dependency instead of adding a second name to probe
+ * for, and the check can then be tested without a real archive or a real binary.
+ * @param {string} archive Path to the downloaded file.
+ * @param {string} expected Pinned lowercase hex digest.
+ * @param {string} name Tool name, for the message.
+ */
+export function verifyChecksum(archive, expected, name) {
+  const actual = createHash("sha256")
+    .update(readFileSync(archive))
+    .digest("hex");
+  if (actual !== String(expected).trim().toLowerCase()) {
+    throw new Error(
+      `${name}: checksum mismatch — refusing to install.\n` +
+        `  expected ${expected}\n` +
+        `  actual   ${actual}\n` +
+        `The URL served something other than the reviewed artifact. Do not ` +
+        `update the pin to match without establishing why it changed.`
+    );
+  }
+}
+
 /**
  * Install a pinned archive, refusing anything whose checksum does not match.
  * @param {object} tool Manifest entry.
@@ -137,10 +166,7 @@ function installReleaseZip(tool, binDir) {
     });
     // Verify before unpacking, not after. An unexpected archive must fail
     // before any of its contents reach a directory that is on PATH.
-    execFileSync("sha256sum", ["-c", "-"], {
-      input: `${tool.sha256}  ${archive}\n`,
-      stdio: ["pipe", "ignore", "inherit"],
-    });
+    verifyChecksum(archive, tool.sha256, tool.name);
     execFileSync("unzip", ["-q", "-o", archive, "-d", temporary], {
       stdio: "inherit",
     });
@@ -171,10 +197,7 @@ function installReleaseTar(tool, binDir) {
     execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
       stdio: "inherit",
     });
-    execFileSync("sha256sum", ["-c", "-"], {
-      input: `${tool.sha256}  ${archive}\n`,
-      stdio: ["pipe", "ignore", "inherit"],
-    });
+    verifyChecksum(archive, tool.sha256, tool.name);
     execFileSync("tar", ["-xzf", archive, "-C", temporary], {
       stdio: "inherit",
     });
@@ -205,16 +228,46 @@ function installNpmGlobal(tool) {
 
 /**
  * Execute one install decision.
- * @param {object} tool Manifest entry.
+ *
+ * Exported because the local-environment flow installs from the same manifest
+ * with the same pins and the same checksum refusal. A second installer would be
+ * a second thing to keep honest, and the one people run least would rot.
+ * @param {object} tool Manifest entry, already resolved to this platform.
  * @param {string} binDir Directory for downloaded binaries.
  */
-function installTool(tool, binDir) {
+export function installTool(tool, binDir) {
   assertPinned(tool);
   if (tool.install === "release-zip") installReleaseZip(tool, binDir);
   else if (tool.install === "release-tar") installReleaseTar(tool, binDir);
   else installNpmGlobal(tool);
 }
 
+/**
+ * Create the directory installs land in, and make sure PATH will find it.
+ *
+ * Installing a binary somewhere nothing looks is the same as not installing it.
+ * `~/.local/bin` is on PATH by default on a developer workstation and is NOT on
+ * a minimal container, so the toolchain step reported `install bws`, the file
+ * landed at ~/.local/bin/bws mode 755, and the very next step died with
+ * `spawnSync bws ENOENT`.
+ *
+ * This was invisible in every local test because a workstation shell already
+ * exports the directory — the environment doing the hiding was the one used to
+ * verify the fix.
+ *
+ * Prepended, not appended: a pinned-and-checksummed binary must win over
+ * whatever an image happens to ship under the same name.
+ * @returns {string} The directory installs are written to.
+ */
+export function ensureBinDir() {
+  const binDir = join(process.env.HOME ?? "", ".local", "bin");
+  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  if (!pathContains(binDir)) {
+    process.env.PATH = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
+  }
+  return binDir;
+}
+
 /**
  * Apply the toolchain plan, reporting every decision.
  * @param {object} tools Manifest.
@@ -231,8 +284,7 @@ function applyToolchain(tools, dryRun, options = {}) {
     throw new Error(blocked.map(p => p.reason).join("\n\n"));
   }
 
-  const binDir = join(process.env.HOME ?? "", ".local", "bin");
-  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  const binDir = ensureBinDir();
   const byName = new Map((tools.install ?? []).map(t => [t.name, t]));
 
   // Installing is a different act on a laptop than in a container. A container
@@ -263,26 +315,14 @@ function applyToolchain(tools, dryRun, options = {}) {
     return plan;
   }
 
-  // Installing a binary somewhere nothing looks is the same as not installing
-  // it. `~/.local/bin` is on PATH by default on a developer workstation and is
-  // NOT on a minimal container, so the toolchain step reported `install bws`,
-  // the file landed at ~/.local/bin/bws mode 755, and the very next step died
-  // with `spawnSync bws ENOENT`.
-  //
-  // This was invisible in every local test because a workstation shell already
-  // exports the directory — the environment doing the hiding was the one used
-  // to verify the fix.
-  //
-  // Prepended, not appended: a pinned-and-checksummed binary must win over
-  // whatever an image happens to ship under the same name.
-  if (!pathContains(binDir)) {
-    process.env.PATH = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
-  }
-
   for (const step of plan) {
     console.log(`  ${step.action.padEnd(8)} ${step.reason}`);
+    // The planner already resolved this entry to the running platform, so use
+    // what it decided rather than looking the raw entry up again. `byName` is
+    // the pre-platform shape and would hand the installer a url that belongs to
+    // whichever platform happened to be written first.
     if (step.action === "install" && !dryRun)
-      installTool(byName.get(step.name), binDir);
+      installTool(step.tool ?? byName.get(step.name), binDir);
   }
   return plan;
 }

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/toolchain.mjs

@@ -100,7 +100,7 @@ function planRequired(tool, found) {
  * @param {{version: string|null, present: boolean}} found Probe result.
  * @returns {{name: string, action: string, reason: string}} The decision.
  */
-function planInstallable(tool, found) {
+function planInstallable(tool, found, pinIsFloor = false) {
   if (!tool.version) {
     return {
       name: tool.name,
@@ -115,6 +115,25 @@ function planInstallable(tool, found) {
       reason: `${tool.name} ${tool.version} already installed`,
     };
   }
+  // On a laptop the pin is a floor, not an equality. A container is disposable
+  // and reproducible by construction, so an exact match is right there. A
+  // developer's machine is shared with every other project they work on, and
+  // installing a pinned binary into ~/.local/bin ahead of a NEWER one already on
+  // PATH is a downgrade this project imposed on all of them — for gh, pinned at
+  // 2.83.0 against a workstation running 2.96.0, that is the likely case rather
+  // than the exotic one.
+  if (
+    pinIsFloor &&
+    found.present &&
+    found.version &&
+    compareVersions(found.version, tool.version) > 0
+  ) {
+    return {
+      name: tool.name,
+      action: "newer",
+      reason: `${tool.name} ${found.version} is newer than the pinned ${tool.version} — leaving it alone`,
+    };
+  }
   return {
     name: tool.name,
     action: "install",
@@ -127,6 +146,72 @@ function planInstallable(tool, found) {
 /** Surfaces a manifest entry may name. */
 const KNOWN_SURFACES = new Set(["local", "remote"]);
 
+/**
+ * The platform key a manifest entry is resolved against.
+ *
+ * `<platform>-<arch>` rather than either alone, because both halves change the
+ * artifact: an Apple Silicon laptop and an Intel one run different builds of the
+ * same release, and so do an arm64 container and an amd64 one.
+ * @param {{platform: string, arch: string}} [runtime] Injectable, for tests.
+ * @returns {string} A key such as "darwin-arm64" or "linux-x64".
+ */
+export function currentPlatform(runtime = process) {
+  return `${runtime.platform}-${runtime.arch}`;
+}
+
+/**
+ * Collapse a manifest entry to the artifact for one platform.
+ *
+ * A download URL is platform-specific and a checksum doubly so, which the
+ * single-URL shape could not express: the only way to stop a laptop being handed
+ * a Linux binary was `surfaces: ["remote"]`, which bought that safety by making
+ * the tool uninstallable on the laptop entirely. So `bws` and `gh` — the two
+ * tools Lisa's own guardrails shell out to — were declared, required, and
+ * unprovisionable on the machine most likely to be missing them.
+ *
+ * A `platforms` map fixes the cause instead of the symptom. `install` lives
+ * inside each block rather than beside it, because the method varies too: gh
+ * publishes a .tar.gz for Linux and a .zip for macOS, so a single install method
+ * would have forced one platform onto an archive kind its vendor does not ship.
+ *
+ * A flat entry is still valid and means "identical everywhere" — true of every
+ * `npm-global` install, which is genuinely platform-independent.
+ * @param {object} tool Manifest entry.
+ * @param {string} [platform] Platform key to resolve for.
+ * @returns {object} The entry with its platform block merged in.
+ */
+export function resolvePlatform(tool, platform = currentPlatform()) {
+  const { platforms } = tool;
+  if (platforms === undefined) return tool;
+  if (
+    typeof platforms !== "object" ||
+    platforms === null ||
+    Array.isArray(platforms)
+  ) {
+    throw new Error(
+      `${tool.name}: platforms must be an object keyed by <platform>-<arch>, ` +
+        `got ${Array.isArray(platforms) ? "an array" : typeof platforms}.\n` +
+        `Omit it when one artifact serves every platform.`
+    );
+  }
+  const block = platforms[platform];
+  if (!block) {
+    const known = Object.keys(platforms).sort().join(", ");
+    throw new Error(
+      `${tool.name}: no pin for ${platform}.\n` +
+        `Declared platforms: ${known || "(none)"}.\n` +
+        `Add a block for ${platform} with its own url and sha256, or drop the ` +
+        `tool from this surface. Guessing an artifact would defeat the ` +
+        `checksum.`
+    );
+  }
+  // The platform block wins over the shared fields, and `platforms` itself is
+  // dropped so a resolved entry is indistinguishable from a flat one — that is
+  // what lets assertPinned and the installers stay unaware of any of this.
+  const { platforms: _discarded, ...shared } = tool;
+  return { ...shared, ...block };
+}
+
 /**
  * Whether a manifest entry applies to the surface being provisioned.
  *
@@ -171,18 +256,48 @@ export function appliesToSurface(tool, surface) {
 
 /**
  * Produce the complete plan for a toolchain manifest.
+ *
+ * Install entries are resolved to the running platform here rather than at
+ * install time, so a tool with no artifact for this machine is reported
+ * alongside every other problem instead of aborting the run at the first one.
+ * An operator fixing a manifest wants the whole list.
+ *
+ * `require` entries are deliberately not resolved: they carry a name and a
+ * minimum version, nothing platform-specific, and inventing a per-platform shape
+ * for them would be ceremony with no artifact behind it.
  * @param {{require?: object[], install?: object[]}} tools Manifest.
  * @param {(name: string) => {version: string|null, present: boolean}} probe Version probe.
- * @returns {Array<{name: string, action: string, reason: string}>} Ordered decisions.
+ * @param {string} [surface] Surface being provisioned.
+ * @param {string} [platform] Platform key to resolve install entries against.
+ * @returns {Array<{name: string, action: string, reason: string, tool?: object}>} Ordered decisions.
  */
-export function planToolchain(tools, probe, surface = "remote") {
+export function planToolchain(
+  tools,
+  probe,
+  surface = "remote",
+  platform = currentPlatform()
+) {
   const plan = [];
   for (const tool of tools.require ?? [])
     if (appliesToSurface(tool, surface))
       plan.push(planRequired(tool, probe(tool.name)));
-  for (const tool of tools.install ?? [])
-    if (appliesToSurface(tool, surface))
-      plan.push(planInstallable(tool, probe(tool.name)));
+  for (const tool of tools.install ?? []) {
+    if (!appliesToSurface(tool, surface)) continue;
+    let resolved;
+    try {
+      resolved = resolvePlatform(tool, platform);
+    } catch (err) {
+      plan.push({ name: tool.name, action: "invalid", reason: err.message });
+      continue;
+    }
+    // The resolved entry travels with the decision so the installer never has to
+    // resolve a second time — two resolutions are two chances to disagree, and
+    // the one that installs would be the one nothing tested.
+    plan.push({
+      ...planInstallable(resolved, probe(tool.name), surface === "local"),
+      tool: resolved,
+    });
+  }
   return plan;
 }
 
@@ -195,6 +310,17 @@ export function planToolchain(tools, probe, surface = "remote") {
  * @param {object} tool Manifest entry.
  */
 export function assertPinned(tool) {
+  // An unresolved entry reaching here means a caller skipped resolvePlatform and
+  // is about to read a url and sha256 that belong to no platform in particular.
+  // Refusing is the point: the failure this whole change exists to prevent is
+  // exactly "downloaded the wrong platform's artifact", and a silent pass here
+  // would reintroduce it one call site at a time.
+  if (tool.platforms !== undefined) {
+    throw new Error(
+      `${tool.name}: platform-specific entry was not resolved before install.\n` +
+        `Call resolvePlatform() first — the shared fields alone do not name an artifact.`
+    );
+  }
   // Both archive kinds carry the same obligation, and differ only in how they
   // are unpacked. gh, for one, publishes no zip for Linux at all — only .deb,
   // .rpm and .tar.gz — so a zip-only installer could not pin the CLI that

package/plugins/lisa/.codex-plugin/skills/lisa-tracker-sync/SKILL.md

@@ -21,7 +21,7 @@ See the `config-resolution` rule for configuration and dispatch table.
    - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
 3. Pass through the output.
 
-`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), `--update-label`, `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), the vendor lane-write flag (`--update-label` on GitHub, `--update-state` on Linear), `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
 
 If `$ARGUMENTS` is empty, all vendor skills auto-detect a ticket reference from the active plan file (most recently modified `.md` in `plans/`).
 
@@ -60,6 +60,6 @@ This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that me
 ## Rules
 
 - Idempotent updates — running sync at the same milestone twice should not produce duplicate comments. Vendor skills enforce this.
-- Never auto-transition the underlying state. Linear's label-based transition (`status:*`) is the canonical signal and is updated only when the caller passes `--update-label`. Native states stay as suggestions.
+- Never auto-transition a lane the caller did not ask for. On GitHub the canonical signal is the `status:*` label, written only with `--update-label`; on Linear it is the native workflow state, written only with `--update-state`. Without the flag, every vendor arm only suggests.
 - Parent rollup derives state from children per the `leaf-only-lifecycle` rule; it never sets a parent to `ready` and never resolves a dev/staging `done` in this single-environment repo.
 - Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.

package/plugins/lisa/agents/linear-agent.md

@@ -47,7 +47,7 @@ Use the `linear-verify` skill to check the item against organizational standards
 
 **Gating behavior — this is the one place auto-transitioning is allowed:**
 
-Resolve build labels from `.lisa.config.json` `linear.labels.build.*` (defaults: `status:ready` / `status:in-progress` / `status:code-review`); resolve the `blocked` label from the same section (`linear.labels.build.blocked`, default `status:blocked`) and the `human_needed` marker label from the same section (`linear.labels.build.human_needed`, default `human-needed`).
+Resolve build labels from `.lisa.config.json` `linear.workflow.*` (defaults: `Todo` / `In Progress` / `In Review`); resolve the `blocked` label from the same section (`linear.workflow.blocked`, default `Blocked`) and the `human_needed` marker label from the same section (`linear.labels.build.human_needed`, default `human-needed`).
 
 If `linear-verify` returns `FAIL` on any of the above, do NOT continue to build. **Draft the missing spec content first, then block for confirmation** — never bounce a raw "go write all this" checklist back to the creator:
 1. **Best-effort autofill (before blocking).** Run `pre-flight-autofill` for every work item. Preserve a human bare configured key or `Confirmed: <env>`; automation writes `Inferred: <env> — evidence: <title|body|reproduction|hostname>`, `Assumption: <env> — remote default branch <branch>` for a unique reverse-map, or `Assumption: remote default branch <branch>` otherwise. Human confirmation replaces the annotation with the bare key or `Confirmed: <env>`. For a legacy bare value, use managed draft markers and current ticket content only; provider edit history is not required. A marker proves automation and requires re-annotation; otherwise unknown provenance plus conflicting evidence stops for confirmation. Resolve one exact `deploy.branches` key from the human-authored title, body, and reproduction steps or URL hostname; exclude the complete `Target Backend Environment` section and other machine-authored metadata/draft blocks so annotations cannot become evidence. A reported bug environment is an example, not a restriction. Evidence supersedes only `Assumption:`. Normalize `prod` ↔ `production` only when exactly one is configured; no other aliases exist. Conflicts stop; never infer from arbitrary branch text, URL paths/query strings, or substrings. Write through `linear-write-issue`, never overwrite human prose, then re-run `linear-verify`.
@@ -116,13 +116,13 @@ Use the `linear-evidence` skill to:
 
 ### 8. Suggest Status Transition
 
-Based on the milestone, suggest (but don't auto-transition the native Linear `state`). Label role names are resolved from `.lisa.config.json` `linear.labels.build.*`:
+Based on the milestone, suggest (but don't auto-transition the native Linear `state`). Label role names are resolved from `.lisa.config.json` `linear.workflow.*`:
 
 | Milestone | Suggested role | Default label |
 |-----------|----------------|---------------|
-| Plan created | `claimed` | `status:in-progress` |
-| PR ready | `review` | `status:code-review` |
-| PR merged | `done` (env-aware; build-intake performs if dispatched via that flow) | env-keyed variant per `linear.labels.build.done` |
+| Plan created | `claimed` | `In Progress` |
+| PR ready | `review` | `In Review` |
+| PR merged | `done` (env-aware; build-intake performs if dispatched via that flow) | env-keyed variant per `linear.workflow.done` |
 
 Note: `done` may be a string or an env-keyed map (`{ dev, staging, production }`). When suggesting the PR-merged transition, the env is implied by the PR's base branch via `deploy.branches` — surface the resolved label name; do not auto-transition.
 
@@ -132,7 +132,7 @@ The label transitions ARE the canonical signal. The native `state` field stays a
 
 - Never auto-transition the native Linear `state`, with one explicit exception: when `linear-verify` returns `FAIL` for the pre-flight gate (Step 2), first run the `pre-flight-autofill` draft-then-block procedure (draft the authorable missing sections into the description as labeled assumptions), then update labels to the configured `blocked` label, add the configured `human_needed` marker label (`linear.labels.build.human_needed`, default `human-needed`), and reassign to the creator with a confirmation comment. Every other status change remains a label-driven suggestion.
 - Always read the full item graph via `linear-read-issue` before determining intent — don't rely on type labels alone.
-- Never create or materially edit an item by calling MCP write tools directly — always delegate to `linear-write-issue` so relationships, Gherkin criteria, and metadata gates are enforced. Two explicit exceptions are permitted: (1) the Step 2 pre-flight failure path (when `linear-verify` returns `FAIL`) may call `lisa-linear-access operation: save-issue` and `lisa-linear-access operation: save-comment` directly to set `status:blocked`, add the configured `human_needed` marker label, and reassign to the creator — this narrow exception is already granted by the rule above; (2) the Step 3 triage path may call `lisa-linear-access operation: save-comment` to post triage findings and `lisa-linear-access operation: save-issue` to add the `claude-triaged-{repo}` label — these are lightweight metadata updates that do not create or materially edit ticket content and therefore do not need to route through `linear-write-issue`.
+- Never create or materially edit an item by calling MCP write tools directly — always delegate to `linear-write-issue` so relationships, Gherkin criteria, and metadata gates are enforced. Two explicit exceptions are permitted: (1) the Step 2 pre-flight failure path (when `linear-verify` returns `FAIL`) may call `lisa-linear-access operation: save-issue` and `lisa-linear-access operation: save-comment` directly to set `Blocked`, add the configured `human_needed` marker label, and reassign to the creator — this narrow exception is already granted by the rule above; (2) the Step 3 triage path may call `lisa-linear-access operation: save-comment` to post triage findings and `lisa-linear-access operation: save-issue` to add the `claude-triaged-{repo}` label — these are lightweight metadata updates that do not create or materially edit ticket content and therefore do not need to route through `linear-write-issue`.
 - If sign-in credentials are in the item, extract and pass them to the flow. If the item touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.
 - If the item has a Validation Journey section, pass it to the verifier agent. The Validation Journey's local-verification step must point at the target backend environment named in the description.
 - The environment handoff for every work item uses the same durable grammar: human bare configured key or `Confirmed: <env>`; automated `Inferred: <env> — evidence: <title|body|reproduction|hostname>`, `Assumption: <env> — remote default branch <branch>` for a unique reverse-map, or `Assumption: remote default branch <branch>` otherwise. Human confirmation replaces an automated annotation with the bare key or `Confirmed: <env>`. For legacy bare values, managed draft markers and current ticket content decide provenance; provider edit history is not required. A marker proves automation; otherwise unknown provenance plus conflicting evidence stops for confirmation. Human-confirmed wins, then validated `Inferred:`; otherwise one exact `deploy.branches` key from the human-authored title, body, and reproduction steps or URL hostname drives the implementation base branch. Exclude the complete `Target Backend Environment` section and other machine-authored metadata/draft blocks so annotations cannot become evidence. Evidence supersedes only `Assumption:`. Normalize `prod` ↔ `production` only when exactly one is configured; no other aliases exist. Conflicts stop. Never infer from arbitrary branch text, URL paths/query strings, or substrings. With no signal, use the remote default and record the applicable assumption without blocking on a non-unique reverse-map. Require any selected mapping and remote branch. A reported bug environment is an example of the all-work-type rule. Non-integration fixes still require the linked forward cherry-pick.