@codyswann/lisa 2.326.3 → 2.328.0

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

@@ -287,7 +287,7 @@ For each epic identified in Phase 1, **invoke the `lisa-tracker-write` skill** (
 - `artifacts`: the full Phase 1.5 artifact list — every artifact, regardless of domain. The epic is the canonical hub. No filtering at the epic level.
 - `priority`, `labels`, `components`, `fix_version`: as appropriate
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa-tracker-write` must not be passed `status:ready` for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready label is applied only in Phase 5.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa-tracker-write` must not be passed the build-ready role for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready role is applied only in Phase 5.
 
 Capture the returned epic key — Phase 4 needs it as the parent for stories.
 
@@ -318,7 +318,7 @@ For each story, **invoke `lisa-tracker-write`** with:
 | Infrastructure | `ops`, `reference` |
 | Mixed / setup ("X.0") | All domains |
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass `status:ready` to `lisa-tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready label is applied only in Phase 5.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass the build-ready role to `lisa-tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready role is applied only in Phase 5.
 
 Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
 
@@ -335,7 +335,7 @@ Each sub-task MUST:
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
 3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa-tracker-write` applies `status:ready` here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready role. `lisa-tracker-write` applies the build-ready role here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply the build-ready role to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
 
 Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task.
 

package/plugins/lisa/.codex-plugin/skills/lisa-linear-validate-issue/SKILL.md

@@ -61,12 +61,12 @@ authenticated_surface: true       # → requires Sign-in Required
 artifacts_attached: true          # → requires Source Precedence section
 relations: [{ id: "ENG-99", type: "blocked_by" }]   # known issue relations (may be empty)
 remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
-build_ready: true                 # caller asserts the build-ready role (status:ready) is/would be applied — see S15
+build_ready: true                 # caller asserts the build-ready role (the `Todo` state) is/would be set — see S15
 child_refs: ["ENG-601", "ENG-602"]   # known child work (sub-issues / project-member issues / blocked_by parentage) — see S15
 prd_source: "https://notion.so/..."    # set when the Issue was generated from a PRD — requires the Source Requirement section, see S16
 ```
 
-If the caller passes only an identifier, fetch the item via `lisa-linear-access operation: get-issue` (Issue) or `lisa-linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item — then run gates.
+If the caller passes only an identifier, fetch the item via `lisa-linear-access operation: get-issue` (Issue) or `lisa-linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `build_ready` (label set contains `Todo`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item — then run gates.
 
 ## Gates
 
@@ -235,9 +235,9 @@ This gate depends on S11. It is `N/A` for containers — a **Project** (the Epic
 
 #### S15 — Leaf-only build-ready
 
-Enforces the build-side of the vendor-neutral `leaf-only-lifecycle` rule: **only a leaf work unit may carry the build-ready role.** This is the symmetric write-side guard for the Linear validator — a stale or hand-applied `status:ready` label on a container is a lifecycle error and must FAIL here, regardless of how the item was produced. (Mirrors the "Build-ready label is leaf-only" rule that `lisa-linear-write-issue` applies at write time.)
+Enforces the build-side of the vendor-neutral `leaf-only-lifecycle` rule: **only a leaf work unit may carry the build-ready role.** This is the symmetric write-side guard for the Linear validator — a stale or hand-applied `Todo` label on a container is a lifecycle error and must FAIL here, regardless of how the item was produced. (Mirrors the "Build-ready label is leaf-only" rule that `lisa-linear-write-issue` applies at write time.)
 
-**When the gate applies.** Run S15 whenever the item is build-ready — i.e. `build_ready = true`, or the spec/live labels include `status:ready`. If the item is not build-ready, S15 is `N/A` (nothing claims a non-ready item, so the invariant is vacuous).
+**When the gate applies.** Run S15 whenever the item is build-ready — i.e. `build_ready = true`, or the spec/live labels include `Todo`. If the item is not build-ready, S15 is `N/A` (nothing claims a non-ready item, so the invariant is vacuous).
 
 **Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an item is a **container** if it has child work, whatever its declared type; otherwise the **issue type** decides. Determine child work from (in order) `child_refs`, native sub-issues, project-member issues (an Epic is modeled as a Linear Project), and `blocked_by` / parent references — the same hierarchy resolution `lisa-linear-read-issue` uses. When validating a live identifier, query sub-issues / project members alongside the item fetch.
 
@@ -255,7 +255,7 @@ PASS (the childless-parent exception) when the item is build-ready and is a **le
 | Epic (Project) | no | yes | **FAIL** (childless Epic/Project — pure rollup container, exception does not apply) |
 | any | any | no | **N/A** (not build-ready) |
 
-Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle. Move status:ready off this container onto its leaf children (or, for a childless Epic, decompose it into leaf children or reclassify it to a leaf type); a parent's lifecycle state rolls up from its children and is never set to ready directly."`
+Remediation: `"Build-ready is leaf-only per leaf-only-lifecycle. Move the build-ready role off this container onto its leaf children (or, for a childless Epic, decompose it into leaf children or reclassify it to a leaf type); a parent's lifecycle state rolls up from its children and is never set to ready directly."`
 
 `product_relevant: false` — a build-ready container is a lifecycle/decomposition error for the caller to repair, not a product question.
 
@@ -362,7 +362,7 @@ system, and never invent or ask for credentials inline.
 
 ## Execution
 
-1. Parse `$ARGUMENTS`. If it's an identifier, fetch the item and derive the spec from the fetched fields — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item. Otherwise parse the YAML spec.
+1. Parse `$ARGUMENTS`. If it's an identifier, fetch the item and derive the spec from the fetched fields — including `build_ready` (label set contains `Todo`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item. Otherwise parse the YAML spec.
 2. Resolve team ID via `lisa-linear-access operation: list-teams({query: <teamKey>})` if any feasibility gate will run.
 3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
 4. Unless the caller passed `--spec-only` (dry-run), run every Feasibility gate. Collect results.

package/plugins/lisa/.codex-plugin/skills/lisa-linear-write-issue/SKILL.md

@@ -31,7 +31,7 @@ Linear's data model maps Epic / Story / Sub-task to **different entity types**.
 | `Bug` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level |
 | `Spike` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level |
 
-Status workflow uses **labels** (`status:ready`, `status:in-progress`, `status:on-dev`, `status:done`) for portability across teams — Linear's per-team workflow state names vary, but labels are workspace-scoped and stable. Native Linear `state` is set to the team's default `Todo` state on create.
+The build lifecycle uses native **workflow states** (`Todo`, `In Progress`, `In Review`, `Blocked`, `On Dev`, `On Stg`, `Done`), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new Issue is created in the team's default backlog/unstarted state unless `build_ready` promotes it (below).
 
 ## Phase 1 — Resolve Intent
 
@@ -227,7 +227,8 @@ If the item modifies an existing user-facing surface, a `lisa-product-walkthroug
 
 Before create/update, verify each field is populated where applicable:
 
-- **Labels**: include `status:ready` for a new **leaf** work unit (Bug / Task / Sub-task / Improvement with no child work) per `leaf-only-lifecycle`, **unless `build_ready: false`** (see the Build-ready control input below); component labels (`component:<name>`); status / priority labels are NOT redundant with native fields — labels exist for portability and downstream queries. A container (Epic Project / Story with sub-issues / Spike) never receives `status:ready`.
+- **Workflow state**: set the resolved `ready` state (`linear.workflow.ready`, default `Todo`) on a new **leaf** work unit (Bug / Task / Sub-task / Improvement with no child work) per `leaf-only-lifecycle`, **unless `build_ready: false`** (see the Build-ready control input below). A container (Epic Project / Story with sub-issues / Spike) is never put in the build-ready state.
+- **Labels**: taxonomy only — `type:<Kind>`, `repo:<name>`, `component:<name>`, and the `prd-intake-feedback` sentinel. Lifecycle is **not** a label on Linear; do not add `status:*` labels.
 - **Native priority field**: 0–4 per Linear's scale; explicit, not "unset".
 - **Native estimate**: per Linear's team-configured estimate scale (often 0–8 Fibonacci); skip for Epic / Spike.
 - **ProjectMilestone**: when the team uses dated milestones, set the milestone on the Project (Epic) or on the Issue (when an Issue belongs to a milestone).
@@ -238,11 +239,11 @@ For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
 
 ### Build-ready control input (`build_ready`)
 
-`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit's `status:ready` label is applied on create. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special state: the Issue is still created with Linear's default native `Todo` state; it just lacks the `status:ready` **label** the build lifecycle keys off, so a human can promote it later.
+`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit is created **in the resolved `ready` workflow state**. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special state: the Issue is simply left in the team's default backlog/unstarted state, which a human can promote later. This mirrors `lisa-jira-write-ticket`, because Linear is a state-driven tracker like JIRA, not a label-driven one like GitHub.
 
-- **Omitted** → current behavior: a leaf work unit receives `status:ready`. Preserves what every existing caller (`lisa-plan`, the `*-to-tracker` skills) relies on.
-- **`build_ready: false`** → create the leaf **without** the `status:ready` label, so it sits in the backlog for a human to review and promote into the queue.
-- **`build_ready: true`** → ensure the leaf carries `status:ready` so `lisa-intake` / `lisa-linear-build-intake` auto-picks it up.
+- **Omitted** → current behavior: a leaf work unit is created in the resolved `ready` state. Preserves what every existing caller (`lisa-plan`, the `*-to-tracker` skills) relies on.
+- **`build_ready: false`** → create the leaf **without** the `ready` state, leaving it in the team's default backlog state so it waits for a human to review and promote it into the queue.
+- **`build_ready: true`** → transition the **leaf** to the resolved `ready` state (`.linear.workflow.ready`) so `lisa-intake` / `lisa-linear-build-intake` auto-picks it up. Best-effort: if the state cannot be resolved or the transition is rejected, do not fail the write — leave the Issue in its default state and record the reason.
 
 ## Phase 5.5 — Validate (Pre-write Gate)
 
@@ -268,7 +269,7 @@ If the validator reports `PASS`, continue to Phase 6.
 
 ### CREATE — Story / Task / Bug / Spike / Improvement (Issue with projectId)
 
-1. Resolve any required Issue labels (`component:<name>`, `prd-intake-feedback` only if this is a sentinel issue, etc.) via `lisa-linear-access operation: list-issue-labels` (create via `lisa-linear-access operation: create-issue-label` if missing). Include `status:ready` in `labelIds` only for a **leaf** work unit and only when `build_ready` is not `false` (per the Build-ready control input) — omit it for a container, and for a `build_ready: false` leaf which then waits in the backlog for a human to promote it.
+1. Resolve any required Issue labels (`type:<Kind>`, `repo:<name>`, `component:<name>`, `prd-intake-feedback` only if this is a sentinel issue) via `lisa-linear-access operation: list-issue-labels` (create via `lisa-linear-access operation: create-issue-label` if missing). Separately resolve the `ready` **state** id via `lisa-linear-access operation: list-workflow-states`, and set it as `stateId` only for a **leaf** work unit and only when `build_ready` is not `false` — omit it for a container, and for a `build_ready: false` leaf which then waits in the default backlog state for a human to promote it.
 2. Call `lisa-linear-access operation: save-issue` with: `team` (teamId), `title` (summary), `description` (markdown), `projectId` (the Epic Project), `priority` (0–4), `estimate`, `labelIds`, `assignee` if known.
 3. Capture the returned identifier (e.g. `ENG-123`) — Phase 4 sub-tasks need it as `parentId`.
 4. Add relationships from Phase 4b via `save_issue` (relations field) or paired relation calls.

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

@@ -274,7 +274,7 @@ For each PRD epic, **invoke the `lisa-tracker-write` skill** (do not call `creat
 - `artifacts`: the full Phase 1.5 artifact list — every artifact, regardless of domain. The epic is the canonical hub, and anyone working on the epic or its descendants must be able to reach the full set from one place. No filtering at the epic level. `lisa-tracker-write` Phase 4c attaches them as remote links.
 - `priority`, `labels`, `components`, `fix_version`: as appropriate
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa-tracker-write` must not be passed `status:ready` for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready label is applied only in Phase 5.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa-tracker-write` must not be passed the build-ready role for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready role is applied only in Phase 5.
 
 Capture the returned epic key — Phase 4 needs it as the parent for stories.
 
@@ -308,7 +308,7 @@ For each story, **invoke `lisa-tracker-write`** with:
 - `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below — `lisa-tracker-write` Phase 4c attaches them as remote links
 - `priority`, `labels`, `components`, `fix_version`: as appropriate
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass `status:ready` to `lisa-tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready label is applied only in Phase 5.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass the build-ready role to `lisa-tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready role is applied only in Phase 5.
 
 Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
 
@@ -336,7 +336,7 @@ Each sub-task MUST:
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
 3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa-tracker-write` applies `status:ready` here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready role. `lisa-tracker-write` applies the build-ready role here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply the build-ready role to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
 
 **Verification plan examples by stack:**
 - **Backend APIs**: curl GraphQL/REST calls with auth token, database queries, checking audit entries

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

@@ -178,7 +178,7 @@ rule — never hardcode status/label strings. The relevant repair roles:
 |-----------|--------|----------------------|------------------|----------------------------|
 | Build | JIRA | `jira.workflow.claimed` (`In Progress`) | `jira.workflow.blocked` (`Blocked`) | env-resolved `jira.workflow.done` |
 | Build | GitHub | `github.labels.build.claimed` (`status:in-progress`) | `github.labels.build.blocked` (`status:blocked`) | env-resolved `github.labels.build.done` (`status:done`) |
-| Build | Linear | `linear.labels.build.claimed` (`status:in-progress`) | `linear.labels.build.blocked` (`status:blocked`) | env-resolved `linear.labels.build.done` (`status:done`) |
+| Build | Linear | `linear.workflow.claimed` (`In Progress`) | `linear.workflow.blocked` (`Blocked`) | env-resolved `linear.workflow.done` (`Done`) |
 | PRD | Notion | `notion.values.in_review` (`In Review`) | `notion.values.blocked` (`Blocked`) | `notion.values.shipped` (`Shipped`) |
 | PRD | GitHub | `github.labels.prd.in_review` (`prd-in-review`) | `github.labels.prd.blocked` (`prd-blocked`) | `github.labels.prd.shipped` (`prd-shipped`) |
 | PRD | Linear | `linear.labels.prd.in_review` (`prd-in-review`) | `linear.labels.prd.blocked` (`prd-blocked`) | `linear.labels.prd.shipped` (`prd-shipped`) |

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -73,8 +73,16 @@ function bindingsFor(surface) {
   return SURFACE_BINDINGS[surface] ?? ["repository"];
 }
 
-/** Install methods the toolchain runner supports. */
-const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
+/**
+ * Install methods the toolchain runner supports.
+ *
+ * `release-tar` was missing here while the runner had supported it for as long
+ * as gh has been pinned — so this validator would have rejected the project's
+ * own manifest, and the only reason nobody hit it is that nothing ran the two
+ * against each other. Kept in step with `assertPinned` in `toolchain.mjs`,
+ * which is the list that actually decides.
+ */
+const INSTALL_METHODS = new Set(["release-zip", "release-tar", "npm-global"]);
 
 /**
  * Validate the `secrets` block.
@@ -143,6 +151,44 @@ export function validateSecrets(secrets) {
   return problems;
 }
 
+/**
+ * Validate the artifact half of one install entry.
+ *
+ * Split out because the same obligations apply whether the fields sit directly
+ * on the entry or inside a per-platform block: a method must be one Lisa can
+ * execute, an archive must carry a checksum, and an npm install must name a
+ * package. Duplicating those three rules per shape is how one shape ends up
+ * quietly weaker than the other.
+ * @param {string} label How to name this entry in a message.
+ * @param {object} entry The entry or platform block.
+ * @param {string[]} problems Accumulator.
+ */
+function validateInstallArtifact(label, entry, problems) {
+  if (!INSTALL_METHODS.has(entry.install)) {
+    problems.push(
+      `remoteEnv install ${label} has method ${JSON.stringify(entry.install)}. ` +
+        `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+    );
+    return;
+  }
+  // Both archive kinds, not just zip. A tarball pinned without a checksum
+  // trusts whatever the URL serves today exactly as much as a zip does, and
+  // checking only one of them meant the tool Lisa's guardrails shell out to —
+  // gh, which ships a tarball on Linux — was the one going unverified.
+  if (
+    (entry.install === "release-zip" || entry.install === "release-tar") &&
+    !(entry.url && entry.sha256)
+  ) {
+    problems.push(
+      `remoteEnv install ${label} needs both url and sha256. A pinned ` +
+        `version with no checksum still trusts whatever the URL serves today.`
+    );
+  }
+  if (entry.install === "npm-global" && !entry.package) {
+    problems.push(`remoteEnv install ${label} needs a package`);
+  }
+}
+
 /**
  * Validate the `remoteEnv` block.
  * @param {object|undefined} remoteEnv The block, if present.
@@ -163,21 +209,37 @@ export function validateRemoteEnv(remoteEnv) {
     if (!tool.version) {
       problems.push(`remoteEnv install "${tool.name}" has no pinned version`);
     }
-    if (!INSTALL_METHODS.has(tool.install)) {
+    // A flat entry means one artifact serves every platform — true of npm-global
+    // and of nothing else. Anything downloaded is platform-specific, so those
+    // declare a block per platform and each block is validated in full: a
+    // half-filled map is the failure this shape exists to prevent, and it is
+    // invisible until someone runs setup on the platform that was left out.
+    if (tool.platforms === undefined) {
+      validateInstallArtifact(`"${tool.name}"`, tool, problems);
+      continue;
+    }
+    if (
+      typeof tool.platforms !== "object" ||
+      tool.platforms === null ||
+      Array.isArray(tool.platforms)
+    ) {
       problems.push(
-        `remoteEnv install "${tool.name}" has method ${JSON.stringify(tool.install)}. ` +
-          `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+        `remoteEnv install "${tool.name}" has a platforms field that is not an ` +
+          `object keyed by <platform>-<arch>. Omit it when one artifact serves ` +
+          `every platform.`
       );
       continue;
     }
-    if (tool.install === "release-zip" && !(tool.url && tool.sha256)) {
+    const platforms = Object.entries(tool.platforms);
+    if (platforms.length === 0) {
       problems.push(
-        `remoteEnv install "${tool.name}" needs both url and sha256. A pinned ` +
-          `version with no checksum still trusts whatever the URL serves today.`
+        `remoteEnv install "${tool.name}" declares platforms but lists none, so ` +
+          `it can never be installed anywhere.`
       );
+      continue;
     }
-    if (tool.install === "npm-global" && !tool.package) {
-      problems.push(`remoteEnv install "${tool.name}" needs a package`);
+    for (const [platform, block] of platforms) {
+      validateInstallArtifact(`"${tool.name}" (${platform})`, block, problems);
     }
   }
 

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

@@ -152,19 +152,41 @@ read_role() {  # $1=namespace (build|prd) $2=role $3=default
 }
 ```
 
-#### 3a. Build-queue labels — ISSUE labels (only if Linear is the tracker)
+#### 3a. Build-queue lifecycle — WORKFLOW STATES (only if Linear is the tracker)
 
-Probe with `lisa-linear-access operation: list-issue-labels` (scoped to the team). For each role's resolved name, create it via `lisa-linear-access operation: create-issue-label` only if absent. The `done` role is env-keyed — create all three defaults; collapse to a single string in config later if the project's terminal state is env-independent.
+The build lane resolves to native workflow **states**, not labels — see "Why Linear uses states, not labels" in `config-resolution`. Read role → state name with the same ladder, against `linear.workflow`:
 
-| Role | Default |
-|------|---------|
-| `ready` | `status:ready` |
-| `claimed` | `status:in-progress` |
-| `review` | `status:code-review` |
-| `blocked` | `status:blocked` |
-| `done.dev` | `status:on-dev` |
-| `done.staging` | `status:on-stg` |
-| `done.production` | `status:done` |
+```bash
+read_state() {  # $1=role path (e.g. ready, done.dev) $2=default
+  local role="$1" default="$2" local_v global_v
+  local_v=$(jq -r ".linear.workflow.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".linear.workflow.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+```
+
+Enumerate the team's states with `lisa-linear-access operation: list-workflow-states` (each carries `id`, `name`, `type`, `position`). For each role, resolve in this order — the same cascade `lisa-setup-jira` uses, with one extra rung Linear affords that JIRA does not:
+
+1. **Exact name match** → resolved, nothing to do.
+2. **A plausible existing state of the right `type`** (`ready` → `unstarted`, `claimed`/`review` → `started`, `blocked` → `started` or `unstarted`, terminal `done` → `completed`) → present the team's state list via `AskUserQuestion` and let the user pick which state means this role. Record the choice as a config override in Step 4.
+3. **Nothing plausible** → offer to **create** the state via `lisa-linear-access operation: create-workflow-state` (name, `type`, `position`, colour), showing the exact name and type first. Linear's API permits this where JIRA's workflow editing is admin-gated — which is why this rung exists here and not there.
+4. **User declines creation** → stop and say which role is unresolvable and that the lifecycle cannot run without it. Never silently fall back to a state whose meaning differs, and never invent a name in config that does not exist in the team.
+
+| Role | Default state | `type` | Ships with a stock team? |
+|------|---------------|--------|--------------------------|
+| `ready` | `Todo` | `unstarted` | yes |
+| `claimed` | `In Progress` | `started` | yes |
+| `review` | `In Review` | `started` | yes |
+| `blocked` | `Blocked` | `unstarted` | **no — must be created or mapped** |
+| `done.dev` | `On Dev` | `started` | **no — must be created or mapped** |
+| `done.staging` | `On Stg` | `started` | **no — must be created or mapped** |
+| `done.production` | `Done` | `completed` | yes |
+
+**The env rungs are deliberately `started`, not `completed`.** `On Dev` and `On Stg` mean "merged and deployed *that far*" — work that is emphatically not finished. Typing them `completed` would make Linear treat them as closed: they would leave the active board, stop counting in cycles, and re-create the exact premature-closure problem this model exists to fix. Only `done.production` is `completed`.
+
+**Position them between `In Review` and `Done`** so the board reads left-to-right in real lifecycle order. A team that orders its board differently can pass its own `position`.
+
+**Turn off the team's `merge → Done` git automation.** Linear's per-team git automations (Settings → Team → Workflow, or the `gitAutomationStates` API) auto-complete an Issue on merge to **any** branch. With this model that automation is an unwanted second writer: it jumps an Issue straight to `Done` at a `dev` merge, skipping `On Dev` / `On Stg` and asserting production-done. Lisa itself moves the state at each rung, so the automation is redundant as well as wrong. Detect it and offer to delete it; leave `start` and `review` alone — those assert non-terminal states and are harmless.
 
 #### 3b. PRD-lifecycle labels — PROJECT labels (only if Linear is the PRD source)
 
@@ -205,14 +227,39 @@ if [ -n "$TEAM_KEY" ]; then
      .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
 fi
 
-# Conditionally write label overrides (only non-default role names).
+# Conditionally write label overrides (markers + PRD lane only — the build lane
+# is states now, and lives under .linear.workflow below).
 if [ -n "$LABEL_OVERRIDES_JSON" ] && [ "$LABEL_OVERRIDES_JSON" != "{}" ]; then
   jq --argjson o "$LABEL_OVERRIDES_JSON" \
      '.linear.labels = ((.linear.labels // {}) * $o)' \
      .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
 fi
+
+# Workflow-state overrides: only roles whose resolved state name differs from
+# the default, INCLUDING any the user mapped onto an existing state in 3a.
+if [ -n "$WORKFLOW_OVERRIDES_JSON" ] && [ "$WORKFLOW_OVERRIDES_JSON" != "{}" ]; then
+  jq --argjson w "$WORKFLOW_OVERRIDES_JSON" \
+     '.linear.workflow = ((.linear.workflow // {}) * $w)' \
+     .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+fi
 ```
 
+**Migrating a project that predates the state model.** A config carrying
+`linear.labels.build.{ready,claimed,review,blocked,done}` was written against the
+old label-driven lane. Those keys are inert now — nothing reads them — but
+leaving them in place reads as configuration and will mislead the next person.
+Migrate in one pass, and do it before the first intake cycle runs, or that cycle
+sees an empty queue:
+
+1. Resolve each build role to a state per 3a, writing `linear.workflow`.
+2. **Backfill live Issues**: for every Issue carrying a `status:*` label, set its
+   workflow state to the role that label encoded. Do this before deleting
+   anything — the labels are the only record of where each Issue sits.
+3. Drop `build.{ready,claimed,review,blocked,done}` from `linear.labels`, keeping
+   `build.human_needed` and the whole `prd` map.
+4. Leave the `status:*` labels themselves in the workspace, unapplied, until the
+   first intake cycle after the migration has run green. They are the rollback.
+
 No secrets in config — the API key stays in keychain / `LINEAR_API_KEY`, the MCP session in its own store.
 
 ### Step 5 — Offer to set top-level `tracker` / `source`

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

@@ -0,0 +1,95 @@
+---
+name: lisa-setup-local-env
+description: "Bring a developer's machine in…"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Setup Local Environment: $ARGUMENTS
+
+Make this machine match what the project says it needs.
+
+## Why this exists separately
+
+`remoteEnv.tools` was always the manifest for **every** surface, and the executor always
+understood `local`. What did not exist was a way to ask for it. The only path ran a file named
+`setup-remote-env.mjs`, out of a directory named `lisa-remote-env`, via a skill named
+`lisa-setup-remote-env` — and it only existed at all once someone had provisioned a *remote*
+environment, because that is what writes it into the repository.
+
+So the machine most likely to be missing a tool was the one with no way to ask about it.
+
+This skill is that surface. It adds no manifest, no pins, and no installer: it imports the
+ones the remote flow owns. A second installer would be a second thing to keep honest, and the
+one people run least is the one that rots.
+
+## Usage
+
+```sh
+node scripts/local-env.mjs                  # report what diverges
+node scripts/local-env.mjs --install-tools  # install what is missing
+node scripts/local-env.mjs --json           # machine-readable plan
+```
+
+Exit status is non-zero when a tool cannot be resolved, so this is usable as a gate.
+
+## What differs from a container
+
+Two things, and both are because a person is here.
+
+**Consent.** A container is disposable and provisions itself silently — that is the whole
+point of it. A laptop belongs to someone, and putting pinned binaries into their
+`~/.local/bin` uninvited is not ours to decide. Nothing installs until `--install-tools`.
+Reporting happens either way, because knowing the machine diverges from what the project
+declares is most of the value.
+
+**The pin is a floor, not an equality.** A container should hold exactly the pinned version;
+it exists to be reproducible. A developer's machine is shared with every other project they
+work on, so installing a pinned binary ahead of a **newer** one already on `PATH` is a
+downgrade this project imposed on all of them. A newer tool is reported as `newer` and left
+alone. Older, or absent, is an install.
+
+## Platform pins
+
+An install entry either serves every platform — true of `npm-global` and nothing else — or
+declares a `platforms` map keyed `<platform>-<arch>`, each block carrying its own `install`
+method, `url`, and `sha256`:
+
+```json
+{
+  "name": "gh",
+  "version": "2.83.0",
+  "platforms": {
+    "linux-x64":    { "install": "release-tar", "url": "...linux_amd64.tar.gz", "sha256": "...", "binary": "gh_2.83.0_linux_amd64/bin/gh" },
+    "darwin-arm64": { "install": "release-zip", "url": "...macOS_arm64.zip",    "sha256": "...", "binary": "gh_2.83.0_macOS_arm64/bin/gh" }
+  }
+}
+```
+
+The method lives **inside** each block because it varies: gh publishes a `.tar.gz` for Linux
+and a `.zip` for macOS, so a single method would have forced one platform onto an archive kind
+its vendor does not ship.
+
+When a tool has no block for the running platform, this skill says so and stops there. It will
+not guess a download URL — a guessed artifact is one the checksum cannot vouch for, and the
+checksum is the only thing standing between a pinned entry and whatever a URL serves today.
+Add the block, or install that one tool however the platform normally would.
+
+## Detect before you install
+
+Run `/lisa:detect-tooling` when the report looks thin. The manifest is the only thing that puts
+a binary on `PATH`, and nothing populates it automatically — so a project ships npm scripts
+invoking `maestro`, wires an MCP server whose CLI it also shells out to, and configures
+Playwright thresholds, while `remoteEnv.tools` stays empty and each of those fails at the
+moment of use instead of at setup.
+
+The detector proposes and a human decides. It writes nothing, so a tool still only ever reaches
+a machine from a reviewed, pinned, checksummed entry.
+
+## What it will not do
+
+- **No unpinned installs.** Every install goes through the same `assertPinned` gate the remote
+  flow uses, and the same in-process checksum verification, which refuses before unpacking.
+- **No package-manager fallback.** Shelling out to Homebrew would give no version pin and no
+  checksum, which is the property this design exists to enforce.
+- **No writes to the manifest.** Proposing entries belongs to `/lisa:detect-tooling`; deciding
+  belongs to a human reviewing a diff.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-local-env/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Local Env"
+short_description: "Bring a developer's machine in…"
+default_prompt:
+  - "Use $lisa-setup-local-env: Bring a developer's machine in…."