@codyswann/lisa 2.326.3 → 2.328.0

package/plugins/lisa/agents/linear-build-intake.md

@@ -17,7 +17,7 @@ skills:
 
 You are a Linear build-intake agent. Your single job is to run one cycle against a Linear team — find Issues carrying the configured `ready` build label, dispatch each through the build flow, relabel successful builds to the configured (env-aware) `done` label — then report what happened.
 
-Build-label role names (`ready`, `claimed`, `review`, `done`) are resolved from `.lisa.config.json` `linear.labels.build.*` by the `linear-build-intake` skill. The defaults match the legacy hardcoded names (`status:ready`, `status:in-progress`, `status:code-review`, env-keyed `{ dev: status:on-dev, staging: status:on-stg, production: status:done }`).
+Build-lifecycle role names (`ready`, `claimed`, `review`, `blocked`, `done`) are resolved from `.lisa.config.json` `linear.workflow.*` by the `linear-build-intake` skill, and name native **workflow states**, not labels. Defaults: `Todo`, `In Progress`, `In Review`, `Blocked`, env-keyed `{ dev: "On Dev", staging: "On Stg", production: "Done" }`.
 
 ## Confirmation policy
 
@@ -27,7 +27,7 @@ Once you have a team key, RUN. Do not ask the caller whether to proceed, do not
 
 ### 1. Receive the query
 
-The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear team key (e.g. `ENG`) or the literal token `linear` (which falls back to `linear.teamKey` in `.lisa.config.json`). You do not pick the team yourself. Lifecycle label names are read from `linear.labels.build.*` and are not your concern at this layer.
+The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear team key (e.g. `ENG`) or the literal token `linear` (which falls back to `linear.teamKey` in `.lisa.config.json`). You do not pick the team yourself. Lifecycle label names are read from `linear.workflow.*` and are not your concern at this layer.
 
 If no query is provided AND no `linear.teamKey` is configured, stop and ask. Never run intake against a default scope without explicit configuration — the side effects (label transitions, PRs opened, builds running) are too high to act without an explicit target.
 
@@ -58,7 +58,7 @@ If any Issues ended at the configured `blocked` label (pre-flight verify failed)
 - **Never run a cycle without an explicit query or configured `linear.teamKey`.** Side effects too high to default.
 - **Never modify the lifecycle**: only the configured `ready → claimed → done` transitions and terminal-only native Issue completion. Never touch the configured `blocked` label (owned by `linear-agent`) or any other label. (Exception: the configured `review` label is set by `linear-evidence` mid-flow — that's not your concern.)
 - **Never bypass `linear-agent` to do build work directly.** The intake skill dispatches; `linear-agent` builds. Skipping the dispatch produces broken work.
-- **Never invent labels.** Names live in `.lisa.config.json` `linear.labels.build.*` (canonical) — the setup skill writes them. If a team hasn't adopted them yet, the skill exits with an adoption hint. Don't guess label names.
+- **Never invent labels.** Names live in `.lisa.config.json` `linear.workflow.*` (canonical) — the setup skill writes them. If a team hasn't adopted them yet, the skill exits with an adoption hint. Don't guess label names.
 - **Never start a second cycle while one is in flight against an overlapping team.** Serial execution. Scheduling layer (when added) is responsible for not double-firing.
 - **Stop and surface failures rather than retry-loop.** If `linear-agent` returns an unexpected response or an error, the skill records it under "Errors" — pass that through. Do not auto-retry.
 - **Pre-flight failures are not your problem to fix.** If an Issue fails `linear-verify` (missing Validation Journey, sign-in, etc.), `linear-agent` transitions it to the configured `blocked` label and reassigns to the creator. Surface the count and move on. Do NOT try to add the missing pieces from this agent.

package/plugins/lisa/commands/setup/local-env.md

@@ -0,0 +1,7 @@
+---
+description: "Bring this machine in line with the toolchain the project declares. Reports every tool in remoteEnv.tools that is missing, outdated, or unpinned for this platform, and installs the missing ones into ~/.local/bin from the same pinned, checksummed entries the remote surfaces use — but only when asked with --install-tools. A newer tool already on PATH is left alone."
+allowed-tools: ["Skill"]
+argument-hint: "[--install-tools] [--json]"
+---
+
+Use the /lisa-setup-local-env skill to report and optionally install the project's declared toolchain on this machine. $ARGUMENTS

package/plugins/lisa/rules/eager/rejection-detection.md

@@ -21,9 +21,9 @@ Return exactly one of:
 
 - **GitHub** — `LABELED` / `UNLABELED` timeline events on the configured **ready** label (the Label-Event History surface from `lisa-github-read-issue`).
 - **JIRA** — the `changelog` operation on `lisa-atlassian-access` (`?expand=changelog`, status items).
-- **Linear** — the `history` operation on `lisa-linear-access`, keyed on `status:*` label history (`addedLabelIds`/`removedLabelIds` resolved against `list-issue-labels`).
+- **Linear** — the `history` operation on `lisa-linear-access`, keyed on **workflow-state** history (`fromState.name` / `toState.name`, inlined on each node — no label-ID resolution needed).
 
-**Lane names ALWAYS come from `.lisa.config.json` lanes** (`github.labels.build.{ready,claimed,done}` and the JIRA/Linear equivalents; `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS`). **Never hardcode** `status:ready`, `Ready`, etc.
+**Lane names ALWAYS come from `.lisa.config.json` lanes** (`github.labels.build.{ready,claimed,done}` for GitHub, `jira.workflow.*` and `linear.workflow.*` for the status/state trackers; `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS` and `LINEAR_WORKFLOW_DEFAULTS`). **Never hardcode** `status:ready`, `Ready`, `Todo`, etc.
 
 ## Never block the build
 

package/plugins/lisa/rules/reference/config-resolution.md

@@ -344,6 +344,28 @@ When `github.projects.v2` is present, later setup/doctor and writer preflight va
 |-------|---------------|-------|
 | `linear.workspace` | `tracker = "linear"`, `source = "linear"`, or any `linear-*` skill is invoked | Linear workspace slug (e.g. `acme`). |
 | `linear.teamKey` | `tracker = "linear"` | Linear team key (e.g. `ENG`). The team owns the destination Issues. For source mode, projects are workspace-scoped or team-scoped per the URL passed. |
+| `linear.workflow` | `tracker = "linear"` | Workflow **state** name per build lifecycle role — the Linear analogue of `jira.workflow`, not of `github.labels`. Defaults `{ ready: "Todo", claimed: "In Progress", review: "In Review", blocked: "Blocked", done: { dev: "On Dev", staging: "On Stg", production: "Done" } }`. Resolve and verify with `/lisa:setup:linear`. |
+| `linear.labels` | `tracker = "linear"` or `source = "linear"` | **Markers and the PRD lane only.** `build.human_needed` (default `human-needed`) and the `prd.*` map. The build lifecycle does **not** live here — see `linear.workflow`. |
+
+##### Why Linear uses states, not labels
+
+Linear Issues carry first-class workflow states with a machine-readable `type`
+(`backlog` / `unstarted` / `started` / `completed` / `canceled`) — the same shape
+JIRA statuses have. GitHub Issues has no such field (only open/closed), which is
+why the GitHub adapter *must* use labels; that is a constraint of GitHub's data
+model, not a Lisa preference, and Linear does not share it.
+
+Driving Linear off labels left **two writers on one lifecycle**: Linear's own git
+automations move `state` on merge while Lisa moved only labels. The two then
+disagreed permanently on any merge that did not run through a Lisa flow, and the
+env rungs (`On Dev` / `On Stg`) could never appear on a Linear board, cycle or
+insight at all, because those group by state.
+
+The historical objection was that per-team state NAMES vary and get renamed. That
+is equally true of JIRA statuses, which Lisa keys on regardless, and Linear
+additionally exposes the rename-proof `type` discriminator that the lifecycle
+skills already use for terminal detection. Names live in config, so a project
+that renames a state overrides one key.
 
 #### `verification.browser.kane`
 
@@ -405,16 +427,20 @@ Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`,
 
 **Build lifecycle** (work items):
 
-| Role | What it means | JIRA default | GitHub/Linear default |
-|---|---|---|---|
-| `ready` | Human signal "this is buildable; agent may claim" | `Ready` (status) | `status:ready` (label) |
-| `claimed` | Agent has picked the item up | `In Progress` (status) | `status:in-progress` (label) |
-| `review` | Optional post-build review hold, when a tracker/project still uses one | `Code Review` (status) | Linear default: `status:code-review`; GitHub has no default review label |
-| `blocked` | Agent stopped on triage ambiguities or external blocker | `Blocked` (status) | `status:blocked` (label) |
-| `done` | Terminal state for this work, **env-keyed** | map of env → status | map of env → label |
+| Role | What it means | JIRA default | Linear default | GitHub default |
+|---|---|---|---|---|
+| `ready` | Human signal "this is buildable; agent may claim" | `Ready` (status) | `Todo` (state) | `status:ready` (label) |
+| `claimed` | Agent has picked the item up | `In Progress` (status) | `In Progress` (state) | `status:in-progress` (label) |
+| `review` | Optional post-build review hold, when a tracker/project still uses one | `Code Review` (status) | `In Review` (state) | no default review label |
+| `blocked` | Agent stopped on triage ambiguities or external blocker | `Blocked` (status) | `Blocked` (state) | `status:blocked` (label) |
+| `done` | Terminal state for this work, **env-keyed** | map of env → status | map of env → state | map of env → label |
+
+**JIRA and Linear resolve roles to native workflow statuses/states** (`jira.workflow`, `linear.workflow`); **GitHub resolves them to labels** (`github.labels.build`) because GitHub Issues has no workflow-state field at all. A role transition is therefore a *state move* on JIRA and Linear, and a *label swap* on GitHub. Skills operate on roles and never hardcode either form.
 
 `review` is optional. GitHub build intake skips it by default and moves successful builds directly from `claimed` to the configured `done` label. Linear and JIRA projects that still use a post-build review hold can configure `review`; projects that keep the ticket in `claimed` until terminal can omit it and lifecycle skills will skip the intermediate transition.
 
+**Linear state resolution is `type`-aware.** When a configured name is missing, a lifecycle skill may fall back to the team's states by `type` — `ready` → the lowest-position `unstarted`, `claimed` → the lowest-position `started`, terminal `done` → `completed` — but only to *read*; it must never invent a state to write into. Missing states are a setup defect, repaired by `/lisa:setup:linear`, not papered over at runtime.
+
 `blocked` is what every vendor agent flips to when triage finds unresolved ambiguities or the build path is blocked by something the agent can't resolve. Different from `claimed` because it explicitly signals "human attention required."
 
 #### Build markers (additive labels, not lifecycle roles)
@@ -425,11 +451,13 @@ A **marker** is an additive label applied *alongside* a lifecycle role, not a st
 |---|---|---|---|
 | `human_needed` | Applied with `blocked` when — **after the agent has drafted every authorable missing section via the `pre-flight-autofill` procedure** — the block still requires a human to confirm the drafted assumptions or supply something no agent can invent: real missing credentials, access/permissions, or an irreducible product/scoping decision. | `Human Needed` (label) | `human-needed` (label) |
 
+Markers are labels on **every** vendor, Linear included — that is the one place the Linear build lane still touches `linear.labels`.
+
 Resolution keys:
 
 - JIRA: `jira.labels.human_needed` (default `Human Needed`). Applied as a JIRA **label** — not a workflow status — because an item holds exactly one status but any number of labels. The `blocked` status still drives the lifecycle; `human_needed` is the additive marker on top of it.
 - GitHub: `github.labels.build.human_needed` (default `human-needed`). Added next to the `blocked` label.
-- Linear: `linear.labels.build.human_needed` (default `human-needed`). Added next to the `blocked` label.
+- Linear: `linear.labels.build.human_needed` (default `human-needed`). Applied as a Linear **label**, for the same reason as JIRA — an Issue holds exactly one workflow state but any number of labels, so an additive marker cannot be a state. The `blocked` **state** still drives the lifecycle; `human_needed` is the marker on top of it. This is the only build-lane key left in `linear.labels`.
 
 **When to apply it.** Apply `human_needed` only when a human must act before the item can move — the pre-flight gate failures that bounce a ticket back to its reporter are exactly this case, but **only after** the agent has run the `pre-flight-autofill` draft-then-block procedure (drafting the authorable gaps — acceptance criteria, validation journey, repository, relationship search, etc. — into the ticket as labeled assumptions). What then remains for the human is to **confirm those assumptions** or supply a genuinely human-only input (real missing credentials, an irreducible product/scoping decision). The marker means "a human must confirm or decide," not "a human must author from scratch."
 
@@ -788,7 +816,7 @@ When `github-to-tracker` is invoked AND `tracker = "github"`, both reads and wri
 
 Never overload one label across both lifecycles.
 
-The same separation applies for Linear self-host (`source = "linear"` AND `tracker = "linear"`): project-level labels (`prd-*`) drive the PRD lifecycle; issue-level labels (`status:*`) drive the build lifecycle; the sentinel feedback issue carries the issue-level `prd-intake-feedback` label.
+The same separation applies for Linear self-host (`source = "linear"` AND `tracker = "linear"`), with one asymmetry: project-level **labels** (`prd-*`) drive the PRD lifecycle, because a PRD is a Linear Project and Projects carry their own status object rather than Issue workflow states; issue-level **workflow states** (`linear.workflow`) drive the build lifecycle; the sentinel feedback issue carries the issue-level `prd-intake-feedback` label. So on Linear the two lanes are not merely different vocabularies, they are different *mechanisms* — never move a PRD by state or an Issue by `status:*` label.
 
 ## Notion access (substrate ladder)
 

package/plugins/lisa/rules/reference/rejection-detection.md

@@ -31,7 +31,7 @@ History is always obtained through the vendor access layer — never a direct ve
 
 - **GitHub** — read the issue via `lisa-github-read-issue`, whose Label-Event History surface returns chronological `LabeledEvent` / `UnlabeledEvent` entries. A backward move is: the configured **ready** label was removed (item advanced) and later re-added (item bounced back). Non-status label churn is ignored for classification.
 - **JIRA** — call `lisa-atlassian-access operation: changelog key:<K>`. A backward move is a status changelog entry whose `to` is the configured ready status, following an earlier entry that reached a `review`/`done`-ward status.
-- **Linear** — call `lisa-linear-access operation: history id:<ID>`, keyed on `status:*` **label** history (Linear build lanes are label-driven — `lisa-linear-build-intake` keys the queue on `status:*` labels). Resolve `addedLabelIds` / `removedLabelIds` against `list-issue-labels`; a backward move is the configured ready label re-added after a later-lane label was applied. Linear workflow-state moves (`fromState`/`toState`) are a secondary corroborating signal where the project maps lanes to states.
+- **Linear** — call `lisa-linear-access operation: history id:<ID>`, keyed on **workflow-state** history (Linear build lanes are state-driven — `lisa-linear-build-intake` keys the queue on `linear.workflow.*`). Each history node inlines `fromState.name` / `toState.name`, so a backward move reads directly: a move back into the configured `ready` state from a later lane. No label-ID resolution, and no reconstruction from lossy `addedLabelIds` / `removedLabelIds` deltas — that indirection existed only while the lane was label-driven.
 
 ### Lane names are configuration, never literals
 
@@ -39,7 +39,7 @@ The ready / claimed / done lane names ALWAYS come from `.lisa.config.json` lanes
 
 - `github.labels.build.{ready,claimed,done}` (GitHub),
 - the JIRA status equivalents, and
-- the Linear label equivalents,
+- the Linear state equivalents (`linear.workflow.*`),
 
 resolved per the `config-resolution` rule with the `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS` (`ready: status:ready`, `claimed: status:in-progress`, `done: {dev: status:on-dev, staging: status:on-stg, production: status:done}`) as the fallback. **Never hardcode** a lane string in the detection logic — a project that renames its ready lane must still detect rejections.
 

package/plugins/lisa/skills/lisa-confluence-to-tracker/SKILL.md

@@ -308,7 +308,7 @@ For each PRD epic, **invoke the `lisa-tracker-write` skill** (do not invoke `lis
 - `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.
 
@@ -339,7 +339,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.
 
@@ -356,7 +356,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/skills/lisa-detect-tooling/SKILL.md

@@ -46,7 +46,27 @@ What genuinely differs is **consent**, not the list:
 
 Omitting `surfaces` means every surface, because that is true of most tools and the cost of forgetting should be a redundant check rather than a silent absence.
 
-A platform-specific pin is the exception worth knowing: a Linux release archive must be `surfaces: ["remote"]`, with a matching `require` entry for `local`, so a laptop asserts the tool without being offered a binary it cannot run.
+Platform differences are **not** expressed with `surfaces`. A downloaded tool declares a
+`platforms` map keyed `<platform>-<arch>`, each block carrying its own `install` method, `url`,
+and `sha256`:
+
+```json
+"platforms": {
+  "linux-x64":    { "install": "release-tar", "url": "...", "sha256": "..." },
+  "darwin-arm64": { "install": "release-zip", "url": "...", "sha256": "..." }
+}
+```
+
+The method lives inside the block because it varies — gh ships a `.tar.gz` for Linux and a
+`.zip` for macOS. A flat entry means one artifact serves everything, which is true of
+`npm-global` and nothing else.
+
+This replaces an earlier convention worth naming, because its residue may still be in a
+manifest you read: a Linux archive used to be marked `surfaces: ["remote"]` with a bare
+`require` entry for `local`, so a laptop asserted the tool without being offered a binary it
+could not run. That kept the wrong binary off the laptop by making the tool uninstallable
+there — which is how `bws` and `gh`, the two CLIs Lisa's own guardrails shell out to, came to
+be required on developer machines and provisionable only in containers.
 
 ## Usage
 

package/plugins/lisa/skills/lisa-detect-tooling/scripts/detect-tooling.mjs

@@ -361,9 +361,11 @@ export function detectTooling(cwd = process.cwd()) {
 /**
  * The manifest entries an operator can paste, with the parts only they supply.
  *
- * Returns both lists because a platform-specific archive needs both: an
- * `install` entry for the surface it is built for, and a `require` entry so the
- * other surface still asserts the tool instead of silently ignoring it.
+ * A release archive is proposed as a `platforms` map rather than a single URL
+ * plus `surfaces: ["remote"]`. The old shape could express only one artifact, so
+ * keeping a Linux binary off a laptop meant excluding the tool from laptops
+ * altogether — which is how `bws` and `gh` came to be required on a developer
+ * machine and installable only in a container.
  * @param {{name: string}} proposal One detected tool.
  * @returns {{install: object[], require: object[]}} Manifest skeletons.
  */
@@ -394,23 +396,33 @@ export function proposedEntries(proposal) {
       require: [],
     };
   }
-  // A release archive is built for one platform, so it is proposed as
-  // remote-install plus a local `require`. Proposing only the install entry
-  // produced a manifest that either offered a Linux binary to a laptop or —
-  // once narrowed to remote — stopped checking for the tool locally at all.
-  // Both halves or neither.
+  // A release archive is built for one platform, so every platform the project
+  // is developed or built on needs its own block — with its own install method,
+  // because a vendor may ship a tarball for one and a zip for another, as gh
+  // does. Both containers and laptops are proposed: a tool the manifest can
+  // only install remotely is one every developer installs by hand or does
+  // without.
+  //
+  // The placeholders stay unresolved on purpose. A guessed URL is an artifact
+  // the checksum cannot vouch for, which is the one property that makes a
+  // pinned entry worth reviewing.
+  const archive = platform => ({
+    install: "<release-tar or release-zip, whichever this platform ships>",
+    url: `<release url for this exact version, for ${platform}>`,
+    sha256: `<sha256 published with the ${platform} release>`,
+  });
   return {
     install: [
       {
         name: proposal.name,
         version: "<pin>",
-        install: "release-tar",
-        url: "<release url for this exact version, for the remote platform>",
-        sha256: "<sha256 published with that release>",
-        surfaces: ["remote"],
+        platforms: {
+          "linux-x64": archive("linux-x64"),
+          "darwin-arm64": archive("darwin-arm64"),
+        },
       },
     ],
-    require: [{ name: proposal.name, surfaces: ["local"] }],
+    require: [],
   };
 }
 

package/plugins/lisa/skills/lisa-github-validate-issue/SKILL.md

@@ -251,7 +251,7 @@ PASS (the childless-parent exception) when the issue is build-ready and is a **l
 | Epic | no | yes | **FAIL** (childless Epic — pure rollup container, exception does not apply) |
 | any | any | no | **N/A** (not build-ready) |
 
-Remediation (render `<READY_ROLE>` as the resolved configured label, never as a hard-coded default): `"Build-ready (<READY_ROLE>; status:ready by default) is leaf-only per leaf-only-lifecycle. Move <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."`
+Remediation (render `<READY_ROLE>` as the resolved configured label, never as a hard-coded default): `"Build-ready is leaf-only per leaf-only-lifecycle. Move <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.
 

package/plugins/lisa/skills/lisa-jira-build-intake/SKILL.md

@@ -189,7 +189,7 @@ The childless-parent exception promotes every childless type **except Epic** to
 Post via `lisa-atlassian-access` `operation: comment key: <TICKET> body: "<message>"` with:
 
 ```text
-[claude-build-intake] Not claimed: this ticket carries the build-ready status ($READY) but is a container with open child work (or a childless Epic), which violates the leaf-only-lifecycle rule. Build-ready (status:ready) is leaf-only per leaf-only-lifecycle — an agent claims and implements leaves, never a container. Repair: move $READY off this parent 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.
+[claude-build-intake] Not claimed: this ticket carries the build-ready status ($READY) but is a container with open child work (or a childless Epic), which violates the leaf-only-lifecycle rule. Build-ready is leaf-only per leaf-only-lifecycle — an agent claims and implements leaves, never a container. Repair: move $READY off this parent 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.
 ```
 
 This gate never blocks a legitimate flat Task/Bug: those have no open children and a leaf type, so they fall straight through to the claim in 3b.

package/plugins/lisa/skills/lisa-jira-validate-ticket/SKILL.md

@@ -252,7 +252,7 @@ PASS (the childless-parent exception) when the ticket is build-ready and is a **
 | Epic | no | yes | **FAIL** (childless Epic — 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.
 

package/plugins/lisa/skills/lisa-linear-access/SKILL.md

@@ -18,9 +18,11 @@ operation: get-team id:<ID>
 operation: list-projects [team:<KEY>] [label:<NAME>] [state:<arr>]
 operation: get-project id:<ID>
 operation: save-project payload:{...}
-operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state_type:<arr>]
+operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state:<NAME>] [state_type:<arr>]
 operation: get-issue id:<ID>
 operation: save-issue payload:{...}
+operation: list-workflow-states team:<ID>
+operation: create-workflow-state payload:{...}
 operation: list-comments issue_id:<ID>
 operation: save-comment issue_id:<ID> body:"..."
 operation: history id:<ID>
@@ -118,15 +120,24 @@ query($id:String!){
   `toState.name`, `createdAt` (ISO timestamp), `actor.name`. Nodes with no
   `fromState`/`toState` are non-state edits (label-only, assignee, etc.); keep
   them for the label stream, skip them for workflow-state ordering.
-- **Label history (honest caveat).** Linear's build lanes are **label-driven**
-  (`lisa-linear-build-intake` keys the queue on `status:*` labels), so label
-  moves matter as much as workflow-state moves. `IssueHistory` carries label
-  changes as `addedLabelIds` / `removedLabelIds` — arrays of label **IDs**, not
-  names. It does **not** inline label names, and it does not carry the label's
-  full prior/next set — only the per-event deltas. Resolve IDs → names by
+- **Build lanes are STATE-driven, so the `from`/`to` stream above is the primary
+  signal.** `lisa-linear-build-intake` keys the queue on workflow states
+  (`linear.workflow`), and `IssueHistory` inlines `fromState.name` /
+  `toState.name` directly — no catalog cross-reference, no ID resolution, no
+  reconstruction. Callers needing lifecycle transitions read them straight off
+  the node. This is strictly better than the label stream below and is why the
+  Linear adapter moved to states.
+- **Label history (honest caveat, still needed for MARKERS and the PRD lane).**
+  `human_needed` is a label, and the PRD lifecycle rides on project labels, so
+  label moves still matter for those. `IssueHistory` carries label changes as
+  `addedLabelIds` / `removedLabelIds` — arrays of label **IDs**, not names. It
+  does **not** inline label names, and it does not carry the label's full
+  prior/next set — only the per-event deltas. Resolve IDs → names by
   cross-referencing `list-issue-labels`. Do not overclaim: a caller that needs
-  `status:*` label transitions reconstructs them from the ID deltas plus the
-  label catalog, not from an inline name on the history node.
+  label transitions reconstructs them from the ID deltas plus the label catalog,
+  not from an inline name on the history node. A caller reading a **build**
+  lifecycle transition should not be in this bullet at all — use the state
+  stream.
 - **Empty is valid.** An Issue that never changed state returns an **empty**
   history — an empty history is a valid result, not an error.
 - **Graceful degrade — never block the build.** A failed history fetch returns