@codyswann/lisa 2.326.3 → 2.327.0

package/plugins/lisa-copilot/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-copilot/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-copilot/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-copilot/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-copilot/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-copilot/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-copilot/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