@codyswann/lisa 4.27.1 → 4.27.3

package/plugins/lisa/scripts/linear-state-write-target.mjs

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+/**
+ * Linear state-write target resolution — the access-bound guard for #3356.
+ *
+ * ## The defect this closes
+ *
+ * `lisa-linear-access operation: save-issue` accepted a raw `stateId` and
+ * dispatched it. Nothing in the chokepoint knew which lifecycle role the caller
+ * believed it was applying, so nothing could refuse: the resolver added in
+ * #3288 could be bypassed by any caller that had an ID in hand. A caller repo in
+ * the portfolio watched an issue move straight from its `ready` lane into a
+ * review-shaped state that its `linear.workflow` map deliberately does not name.
+ *
+ * The exact historical writer is not established, and this module does not
+ * claim one. The defect being closed is structural: the single chokepoint every
+ * Linear write must pass through had no role argument, and therefore had no
+ * possible refusal.
+ *
+ * ## Why this RESOLVES rather than VALIDATES
+ *
+ * The obvious shape — a validator placed in front of the existing `stateId`
+ * argument — is the shape that already failed in #3321: the value that is
+ * checked and the value that is sent are two different things, so any path that
+ * reaches the send without the check is still a bypass, and the guard's
+ * existence reads as safety.
+ *
+ * So this module does not take a target and approve it. It takes a lifecycle
+ * ROLE and PRODUCES the only ID that may be written. The access layer sends
+ * what this returns. A caller may still pass the ID it read from the board, but
+ * only as an ASSERTION compared against the resolved one — it is never the
+ * value dispatched. There is consequently no channel through which an
+ * unvalidated state write can be expressed.
+ *
+ * ## What it refuses
+ *
+ * Everything that is not an exact, configured, unambiguous match: a state write
+ * with no declared role, an env-indexed `done` with no environment key, a role
+ * the project never bound (required or optional), a fallback value the resolver
+ * refused for write intent, a malformed catalog, a configured name absent from
+ * the team's catalog, a configured name that matches more than one state, and a
+ * caller-asserted ID that differs from the resolved one.
+ *
+ * Every refusal names the lifecycle role and the configured value, because the
+ * operator standing at the gate is the one who has to fix the config.
+ * @module scripts/linear-state-write-target
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import {
+  GLOBAL_CONFIG,
+  LOCAL_CONFIG,
+  OUTCOMES,
+  parseArgs,
+  parseConfig,
+  readPath,
+  resolveRole,
+} from "./resolve-lifecycle-role.mjs";
+
+/** The config path Linear's build lifecycle roles are bound at. */
+export const LINEAR_WORKFLOW_ROOT = "linear.workflow";
+
+/**
+ * Every way a state write can be refused.
+ *
+ * Named rather than collapsed into one `refused`, so a caller can tell a setup
+ * defect (fix the config) from a caller defect (fix the skill) without parsing
+ * prose, and so a test can pin the specific path it drove.
+ */
+export const REFUSALS = Object.freeze({
+  MISSING_ROLE: "missing-lifecycle-role",
+  MISSING_ENV: "missing-environment-key",
+  UNEXPECTED_ENV: "unexpected-environment-key",
+  ROLE_UNCONFIGURED: "role-unconfigured",
+  CATALOG_MALFORMED: "catalog-malformed",
+  STATE_ABSENT: "configured-state-absent",
+  STATE_AMBIGUOUS: "configured-state-ambiguous",
+  TARGET_MISMATCH: "target-mismatch",
+});
+
+/** Prefix every refusal carries, so a caller can grep one string for all of them. */
+export const REFUSAL_PREFIX = "Refusing the Linear state write";
+
+/**
+ * Build a refusal result.
+ *
+ * @param {string} refusal one of {@link REFUSALS}
+ * @param {string} detail operator-readable explanation
+ * @returns {{ok: false, refusal: string, message: string}} refusal
+ */
+const refuse = (refusal, detail) => ({
+  ok: false,
+  refusal,
+  message: `${REFUSAL_PREFIX} (${refusal}): ${detail}`,
+});
+
+/**
+ * Normalize a team workflow-state catalog into a flat node list.
+ *
+ * Accepts the three shapes the access layer can hand over: the flat array its
+ * `list-workflow-states` operation returns, the `{nodes:[…]}` connection the
+ * GraphQL adapter reads, and the raw `{team:{states:{nodes:[…]}}}` envelope.
+ * Anything else — including a node missing a string `id` or `name` — is
+ * malformed, not empty: an empty catalog and an unreadable one must not produce
+ * the same answer.
+ *
+ * @param {unknown} catalog raw catalog
+ * @returns {{nodes: Array<{id: string, name: string}>} | {error: string}} normalized nodes
+ */
+export const normalizeStateCatalog = catalog => {
+  const nodes = Array.isArray(catalog)
+    ? catalog
+    : (readPath(catalog, "nodes") ?? readPath(catalog, "team.states.nodes"));
+  if (!Array.isArray(nodes))
+    return {
+      error:
+        "the team workflow-state catalog is not a list of states. " +
+        "Pass the result of `lisa-linear-access operation: list-workflow-states`.",
+    };
+  for (const node of nodes) {
+    const id = readPath(node, "id");
+    const name = readPath(node, "name");
+    if (typeof id !== "string" || id.length === 0)
+      return { error: "a state in the catalog has no string `id`." };
+    if (typeof name !== "string" || name.length === 0)
+      return { error: `state '${id}' in the catalog has no string \`name\`.` };
+  }
+  return { nodes };
+};
+
+/**
+ * Decide whether `done` needs an environment key for this project.
+ *
+ * `done` is env-indexed on every vendor, so a bare `done` write is ambiguous
+ * whenever the project bound a map. A project that bound a plain string has one
+ * terminal and needs no key — refusing that would be inventing a requirement
+ * the config does not have.
+ *
+ * @param {object|undefined} local parsed local config
+ * @param {object|undefined} globalConfig parsed committed config
+ * @returns {string[]} configured environment keys, empty when `done` is flat
+ */
+export const envIndexedDoneKeys = (local, globalConfig) => {
+  for (const source of [local, globalConfig]) {
+    const done = readPath(source, `${LINEAR_WORKFLOW_ROOT}.done`);
+    if (typeof done === "string" && done.length > 0) return [];
+    if (done && typeof done === "object") return Object.keys(done);
+  }
+  return [];
+};
+
+/**
+ * Resolve the one workflow-state ID a lifecycle role may be written to.
+ *
+ * @param {object} options inputs
+ * @param {string} [options.role] lifecycle role being applied
+ * @param {string} [options.env] environment key for an env-indexed `done`
+ * @param {unknown} [options.states] team workflow-state catalog
+ * @param {object} [options.local] parsed local config
+ * @param {object} [options.global] parsed committed config
+ * @param {string} [options.assertStateId] ID the caller believes it is writing
+ * @returns {{ok: true, role: string, stateId: string, stateName: string} | {ok: false, refusal: string, message: string}} outcome
+ */
+export const resolveStateWriteTarget = ({
+  role,
+  env,
+  states,
+  local,
+  global: globalConfig,
+  assertStateId,
+}) => {
+  if (typeof role !== "string" || role.length === 0)
+    return refuse(
+      REFUSALS.MISSING_ROLE,
+      "no lifecycle role was declared. Every `stateId` write must name the role " +
+        "it is applying (ready | claimed | blocked | review | done | qa.queue | " +
+        "qa.certified) so the configured target can be resolved instead of trusted."
+    );
+
+  // The environment key belongs to exactly one shape: an env-indexed `done`.
+  // Anywhere else it is a caller defect that would otherwise pass silently —
+  // `resolveRole` simply ignores `env` off the `done` path, so a call carrying
+  // a stray one succeeds while asserting an environment nobody checked. A
+  // guard that accepts an argument it does not honour is teaching the caller
+  // something false.
+  const envKeys = envIndexedDoneKeys(local, globalConfig);
+  if (env && role !== "done")
+    return refuse(
+      REFUSALS.UNEXPECTED_ENV,
+      `lifecycle role '${role}' takes no environment key. Only the env-indexed ` +
+        "`done` role is keyed by environment; passing one here asserts a " +
+        "deployment this write does not report."
+    );
+  if (env && envKeys.length === 0)
+    return refuse(
+      REFUSALS.UNEXPECTED_ENV,
+      `${LINEAR_WORKFLOW_ROOT}.done is a single state on this project, not a ` +
+        `map of environments, so there is no '${env}' rung to write. Drop the ` +
+        "environment key, or bind the env-indexed map if this project really " +
+        "does promote through environments."
+    );
+  if (role === "done" && !env && envKeys.length > 0)
+    return refuse(
+      REFUSALS.MISSING_ENV,
+      `role 'done' is env-indexed at ${LINEAR_WORKFLOW_ROOT}.done ` +
+        `(${envKeys.join(", ")}). Name the environment being reported.`
+    );
+
+  const resolved = resolveRole({
+    role,
+    vendor: "linear",
+    intent: "write",
+    env,
+    local,
+    global: globalConfig,
+  });
+  if (resolved.outcome === OUTCOMES.UNSET_OPTIONAL)
+    return refuse(
+      REFUSALS.ROLE_UNCONFIGURED,
+      `optional lifecycle role '${role}' is not bound at ` +
+        `${LINEAR_WORKFLOW_ROOT}.${role}, so this project SKIPS that transition. ` +
+        "That is a supported configuration, not an error — but it means there is " +
+        "no target to write. The caller must skip the write; this layer will not " +
+        "invent one, and a state resolved by type or board position is how " +
+        "agent-owned work reaches a human-only lane."
+    );
+  if (resolved.outcome !== OUTCOMES.CONFIGURED)
+    return refuse(REFUSALS.ROLE_UNCONFIGURED, resolved.message);
+
+  const normalized = normalizeStateCatalog(states);
+  if (normalized.error)
+    return refuse(REFUSALS.CATALOG_MALFORMED, normalized.error);
+
+  const matches = normalized.nodes.filter(node => node.name === resolved.value);
+  if (matches.length === 0)
+    return refuse(
+      REFUSALS.STATE_ABSENT,
+      `lifecycle role '${role}' is configured as '${resolved.value}', but the ` +
+        "team has no workflow state with that exact name. This is a setup " +
+        "defect — run /lisa:setup:linear, or correct " +
+        `${LINEAR_WORKFLOW_ROOT}.${role}. Never create or guess a state here.`
+    );
+  if (matches.length > 1)
+    return refuse(
+      REFUSALS.STATE_AMBIGUOUS,
+      `lifecycle role '${role}' is configured as '${resolved.value}', which ` +
+        `matches ${matches.length} states on this team ` +
+        `(${matches.map(node => node.id).join(", ")}). An ambiguous target is ` +
+        "a setup defect; rename one state or bind the role to a unique name."
+    );
+
+  const target = matches[0];
+  if (typeof assertStateId === "string" && assertStateId.length > 0)
+    if (assertStateId !== target.id)
+      return refuse(
+        REFUSALS.TARGET_MISMATCH,
+        `the caller asked to write state '${assertStateId}' while applying ` +
+          `lifecycle role '${role}', but ${LINEAR_WORKFLOW_ROOT}.${role} is ` +
+          `configured as '${resolved.value}' (id ${target.id}). A state absent ` +
+          "from the configured workflow map is never a valid write target — " +
+          "that is how agent-owned work reaches a human-only lane."
+      );
+
+  return {
+    ok: true,
+    role,
+    stateId: target.id,
+    stateName: target.name,
+  };
+};
+
+/**
+ * Read the state catalog named on the command line, or from stdin.
+ *
+ * @param {string | undefined} file path, `-`, or undefined for stdin
+ * @returns {{value: unknown} | {error: string}} parsed catalog
+ */
+export const readCatalog = file => {
+  let raw;
+  try {
+    raw = readFileSync(!file || file === "-" ? 0 : file, "utf8");
+  } catch (cause) {
+    return { error: `could not read the state catalog: ${cause.message}` };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (cause) {
+    return { error: `the state catalog is not valid JSON: ${cause.message}` };
+  }
+};
+
+/**
+ * CLI entry point.
+ *
+ * Exit codes are the contract the access layer branches on:
+ * - `0` — the write is permitted; the ONE permissible state ID is on stdout.
+ * - `2` — refused; the operator-readable reason is on stderr and NOTHING may
+ *   be dispatched.
+ *
+ * There is deliberately no "allowed with warnings" rung. A state write either
+ * targets the configured role or it does not happen.
+ *
+ * @param {string[]} argv arguments after the script name
+ * @returns {number} process exit code
+ */
+export const main = argv => {
+  const args = parseArgs(argv);
+  // A `--state-id` with no `--role` is not a usage slip, it is the defect this
+  // guard exists for: a state write nobody declared a lifecycle role for.
+  // Answer it with the refusal, so the caller reads why rather than how.
+  if (!args.role) {
+    process.stderr.write(
+      args["state-id"]
+        ? `${refuse(REFUSALS.MISSING_ROLE, "no lifecycle role was declared, but a state was supplied to write. Every state write must name the role it is applying so the configured target can be resolved instead of trusted.").message}\n`
+        : "usage: linear-state-write-target.mjs --role <name> [--env <key>] " +
+            "[--states <file|->] [--state-id <asserted-id>] [--json]\n"
+    );
+    return 2;
+  }
+
+  const local = parseConfig(args.local ?? LOCAL_CONFIG);
+  const globalConfig = parseConfig(args.config ?? GLOBAL_CONFIG);
+  for (const parsed of [local, globalConfig])
+    if (parsed.error) {
+      process.stderr.write(`${parsed.error}\n`);
+      return 2;
+    }
+
+  const catalog = readCatalog(args.states);
+  const result = catalog.error
+    ? refuse(REFUSALS.CATALOG_MALFORMED, catalog.error)
+    : resolveStateWriteTarget({
+        role: args.role,
+        env: args.env,
+        states: catalog.value,
+        local: local.value,
+        global: globalConfig.value,
+        assertStateId: args["state-id"],
+      });
+
+  if (args.json === "true") process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.ok) {
+    if (args.json !== "true") process.stdout.write(`${result.stateId}\n`);
+    return 0;
+  }
+  process.stderr.write(`${result.message}\n`);
+  return 2;
+};
+
+const invokedDirectly = (() => {
+  try {
+    return (
+      realpathSync(process.argv[1] ?? "") ===
+      realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) process.exit(main(process.argv.slice(2)));

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

@@ -20,7 +20,7 @@ operation: get-project id:<ID>
 operation: save-project payload:{...}
 operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state:<NAME>] [state_type:<arr>]
 operation: get-issue id:<ID>
-operation: save-issue payload:{...}
+operation: save-issue payload:{...} [lifecycle_role:<ROLE>] [env:<KEY>]
 operation: list-workflow-states team:<ID>
 operation: create-workflow-state payload:{...}
 operation: list-comments issue_id:<ID>
@@ -184,6 +184,82 @@ linear_graphql() {
 Map operation names to Linear GraphQL queries/mutations in this access skill.
 Consumers pass business-shaped arguments only; they do not embed GraphQL.
 
+## `save-issue` — a state write is RESOLVED here, never accepted here
+
+**This layer does not accept a state to write. It resolves one.** A `save-issue`
+that changes the workflow state declares `lifecycle_role:<ROLE>` — the semantic
+role it is applying (`ready`, `claimed`, `blocked`, `review`, `done`,
+`qa.queue`, `qa.certified`) — plus `env:<KEY>` when the role is the env-indexed
+`done`. This layer then resolves that role against config and the team's own
+catalog, and sends the ID **it** resolved.
+
+```bash
+# The team's own catalog, read through this layer's `list-workflow-states`
+# operation for the IDENTITY-MATCHED team, and written to a file so the
+# resolver judges the same bytes the caller looked at. A catalog fetched from
+# some other team is not a smaller catalog, it is the wrong one.
+STATES=$(mktemp)
+linear_list_workflow_states "$TEAM_ID" >"$STATES"
+
+# Same trusted ladder `read_linear_key` walks, and for the same reason: a
+# `.opencode`-layout repo that was never handed CLAUDE_PLUGIN_ROOT has no route
+# to the script at all, and a guard that cannot be found is a guard that does
+# not run. Machine-managed rungs only — a checkout-local `plugins/lisa` is
+# repository-controlled executable code, not trusted merely by path.
+resolve_state_guard() {
+  local candidate
+  for candidate in \
+    "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/scripts/linear-state-write-target.mjs}" \
+    "${PLUGIN_ROOT:+$PLUGIN_ROOT/scripts/linear-state-write-target.mjs}" \
+    node_modules/@codyswann/lisa/plugins/lisa/scripts/linear-state-write-target.mjs; do
+    [ -n "$candidate" ] && [ -f "$candidate" ] && { echo "$candidate"; return; }
+  done
+  # Fail CLOSED and name every path. An unfindable guard must never degrade
+  # into an unguarded write.
+  echo "Error: could not locate linear-state-write-target.mjs; refusing the state write." >&2
+  return 1
+}
+
+linear_state_target() {  # role [env] -> the ONE writable state id, or exit 2
+  local guard
+  guard=$(resolve_state_guard) || return 1
+  node "$guard" \
+    --role "$1" ${2:+--env "$2"} --states "$STATES" \
+    ${LIFECYCLE_ASSERT_STATE_ID:+--state-id "$LIFECYCLE_ASSERT_STATE_ID"}
+}
+
+STATE_ID=$(linear_state_target "$LIFECYCLE_ROLE" "$LIFECYCLE_ENV") || {
+  # Nothing is dispatched. The script already named the role and the
+  # configured value it expected on stderr; surface that verbatim.
+  exit 2
+}
+```
+
+Run it **before** either transport — before `linear_graphql`, before any
+`mcp__linear-server__*` call. A refusal is a hard stop that sends zero
+mutations, not a warning.
+
+Why the layer resolves instead of validating: a validator standing in front of a
+caller-supplied `stateId` checks one value and dispatches another, which is
+exactly the shape that let a caller reach a human-only review lane in the first
+place. Here the checked value and the sent value are the same object — there is
+no channel through which an unvalidated state write can be expressed.
+
+A caller that already read an ID off the board MAY pass it as `stateId` in the
+payload. It is treated as an **assertion**, never as the value to send: the
+layer resolves the role's target independently and refuses the call if the two
+differ, naming the role and the configured value. Two further refusals matter:
+
+- `stateId` in a payload with **no** `lifecycle_role` is refused. There is no
+  such thing as a state write that does not apply a lifecycle role.
+- An **optional role the project never bound** (`review`, `qa.*`) is refused,
+  not defaulted. Absent means *skip the transition*, per `config-resolution` R1
+  — the caller skips the write entirely rather than asking for one here.
+
+**Metadata-only `save-issue` is untouched.** A payload with no `stateId` and no
+`lifecycle_role` — description, assignee, labels, `projectId`, `parentId` — runs
+exactly as before; lifecycle validation has nothing to say about it.
+
 ## `list-workflow-states` — the team's states, and which one it creates into
 
 `list-workflow-states team:<ID>` returns one node per state with `id`, `name`,
@@ -295,3 +371,10 @@ query($id:String!){
 - Missing token plus missing MCP is a hard failure naming `LINEAR_API_KEY`.
 - Mutations send only the fields being changed, matching existing Linear skill
   guidance that `save_*` style updates should not clobber unrelated fields.
+- Every workflow-state write is resolved by
+  `scripts/linear-state-write-target.mjs` from a declared `lifecycle_role`,
+  before either transport. The ID dispatched is the ID that script returned —
+  never one a caller supplied. A caller-supplied `stateId` is an assertion that
+  must match, and a `stateId` with no declared role is refused.
+- A refusal is fail-closed and operator-readable: it names the lifecycle role
+  and the configured value, exits nonzero, and sends nothing.

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

@@ -246,10 +246,10 @@ This gate never blocks a legitimate flat Task/Bug: those have no open children a
 
 **The two `claim-time-guards` run third and fourth — still before the transition below.** Both semantics live in that one vendor-neutral slug; do not restate them here. Linear wiring only:
 
-1. **`two-failed-attempts` valve.** Count `[lisa-build-attempt]` markers on the Issue from the read bundle's comments (match on the marker, never the title). With two or more, do **not** claim: set `stateId` to the configured blocked state via `lisa-linear-access operation: save-issue` (resolved from `linear.workflow.blocked` per `config-resolution`), post the operator-readable comment naming both attempts via `save-comment`, and **stop the cycle** at Phase 3e. Every non-success terminal outcome recorded in 3c/3d also appends a fresh `<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->` marker so the next cycle can count it.
+1. **`two-failed-attempts` valve.** Count `[lisa-build-attempt]` markers on the Issue from the read bundle's comments (match on the marker, never the title). With two or more, do **not** claim: invoke `lisa-linear-access operation: save-issue lifecycle_role: blocked` (the access layer resolves `linear.workflow.blocked` itself per `config-resolution`; this skill supplies the role, never a state ID), post the operator-readable comment naming both attempts via `save-comment`, and **stop the cycle** at Phase 3e. Every non-success terminal outcome recorded in 3c/3d also appends a fresh `<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->` marker so the next cycle can count it.
 2. **`already-implemented` check.** Probe for this Issue's own key — `git log --all --grep "<IDENTIFIER>"` and the merged/open PRs referencing `<IDENTIFIER>` (`gh pr list --state all --search "<IDENTIFIER>"` in the bound repo; Linear's own GitHub attachments in the read bundle are the cheaper first look). On a hit, claim as normal but route 3c to **verify-and-close** instead of `lisa-implement`: verify what shipped against the Issue's acceptance criteria, post evidence via `lisa-linear-evidence` naming the shipping PR/commit, then run the ordinary 3d transition and rollup. A partial hit implements only the remaining gap. An unreadable history degrades to "no hit" and the ordinary path proceeds — the guard never blocks the claim. This is not `DUPLICATE_ALREADY_FIXED` (a *different* canonical Issue) and not `claim-archaeology` (a *different* ancestor Issue); it is this Issue's own work already having shipped without a transition.
 
-Transition the Issue via `lisa-linear-access operation: save-issue` by setting `stateId` to the `$CLAIMED` state. Resolve state IDs via `list-workflow-states`; a missing `$CLAIMED` state is a setup defect (see the pre-flight check) — never create one here.
+Transition the Issue via `lisa-linear-access operation: save-issue lifecycle_role: claimed`. The access layer resolves the `claimed` role's exact configured state against the team catalog and dispatches that ID; a missing or ambiguous `$CLAIMED` state is a setup defect it refuses on (see the pre-flight check) — never create one here.
 
 **Assign to the authenticated user when the Issue is unassigned.** A claim must be attributable. If the Issue has no assignee, set its `assigneeId` to the authenticated viewer (resolve the viewer's id via the Linear MCP identity — e.g. `get_user` for the current actor) through `lisa-linear-access operation: save-issue`. Leave an already-assigned Issue's assignee untouched — never reassign work that already has an owner.
 
@@ -339,7 +339,7 @@ If the lifecycle run returned Success:
    - If `linear.workflow.done` is a string, that state is terminal.
    - If `linear.workflow.done` is an object, only the production/final environment value is terminal (default: `Done`). Intermediate env states such as `On Dev` and `On Stg` are not terminal — they are typed `started`, so the Issue correctly stays open and on the board.
    - If the project uses a different final environment name, resolve it from the configured deployment topology; if ambiguous, record an Error and do not change the native state.
-4. Transition via `lisa-linear-access operation: save-issue`, setting `stateId` to the `$DONE` state (from `$CLAIMED`, or from `$REVIEW` if `lisa-linear-evidence` already moved it forward).
+4. Transition via `lisa-linear-access operation: save-issue lifecycle_role: done env: <resolved-env-key>` (from `$CLAIMED`, or from `$REVIEW` if `lisa-linear-evidence` already moved it forward). Pass `env` **only where `linear.workflow.done` is a map of environments**: there the key is mandatory and the access layer refuses a bare `done`; where `done` is a single state the project has no environment rungs and the layer refuses a stray key just as firmly. Either way the layer resolves `$DONE` itself rather than accepting the ID this phase computed.
 5. **That single write IS the native closure** when `$DONE` is terminal — there is no second step, because the role and the native state are now the same field. When `$DONE` is an intermediate env (`On Dev` / `On Stg`), the state is typed `started`, so the Issue stays open and active by construction rather than by a compensating repair. If a git automation or magic word has already front-run the Issue into a `completed` state while the resolved env is intermediate, reconcile it back via `lisa-linear-sync` Phase 4b — and treat a recurrence as a setup defect, since `/lisa:setup:linear` offers to remove the `merge → Done` automation that causes it.
 6. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL> merged. Transitioned to $DONE."`
 

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

@@ -8,11 +8,11 @@ allowed-tools: ["Bash", "Skill", "Read"]
 
 Claim exactly one canonical Linear identifier such as `ENG-123`. All Linear access goes through `lisa-linear-access`. This is the reusable direct-session counterpart of `lisa-linear-build-intake` Phase 3b.
 
-1. Resolve merged `linear.workspace`, `linear.teamKey`, and the Linear build-lifecycle roles from local-over-global config. Require the identifier's team key to equal the configured team. Resolve ready and claimed roles from `linear.workflow` (defaults `Ready` and `In Progress`); do not hardcode lifecycle decisions.
+1. Resolve merged `linear.workspace`, `linear.teamKey`, and the Linear build-lifecycle roles from local-over-global config. Require the identifier's team key to equal the configured team. Resolve the `ready` and `claimed` roles through `scripts/resolve-lifecycle-role.mjs` (`--vendor linear`). Both are REQUIRED roles with **no built-in default** — an unset one is a setup defect to report, never a name to substitute. Do not hardcode lifecycle decisions.
 2. Invoke `lisa-linear-read-issue <identifier>` immediately before mutation. Reject a completed/canceled issue, active blocker, `repo:<other>` issue, any issue with open sub-Issues, or an Epic per `repo-scope-split` and `leaf-only-lifecycle`.
 3. Inspect the Issue's live workflow **state**:
    - Already claimed, review, environment-done, or another configured later non-terminal role -> preserve it and set `claim_outcome: reused`.
-   - In the configured `ready` state -> invoke `lisa-linear-access operation: save-issue` setting `stateId` to the `claimed` state (resolve state IDs with `list-workflow-states`; a missing state is a setup defect, never created here). This is the idempotency lock.
+   - In the configured `ready` state -> invoke `lisa-linear-access operation: save-issue lifecycle_role: claimed`. The access layer resolves the `claimed` role's exact configured state itself and dispatches that ID; this skill never hands it a state ID to trust. A missing or ambiguous configured state is a setup defect the layer refuses on, never created here. This is the idempotency lock.
    - In any OTHER non-terminal state -> reject. An Issue that is not in the `ready` state has not been sanctioned for build, and absence of a lifecycle marker is no longer evidence of readiness: since the lane moved to states, every Issue always has one, so "no lifecycle label" is not a state this can observe.
    - Terminal/completed -> reject; never regress completed work.
 4. If and only if the Issue is unassigned, resolve the authenticated viewer and set its `assigneeId` through `lisa-linear-access operation: save-issue`. Leave an existing assignee untouched.

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

@@ -1,12 +1,12 @@
 ---
 name: lisa-linear-evidence
-description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from the configured `claimed` label to the configured `review` label. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa-jira-evidence and lisa-github-evidence."
+description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from the configured `claimed` workflow state to the configured `review` workflow state. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa-jira-evidence and lisa-github-evidence."
 allowed-tools: ["Bash", "Skill"]
 ---
 
 # Linear Evidence: $ARGUMENTS
 
-Post verification evidence to a Linear Issue and transition it from the configured `claimed` build label to the configured `review` build label. This skill is the destination of the `lisa-tracker-evidence` shim when `tracker = "linear"`.
+Post verification evidence to a Linear Issue and transition it from the configured `claimed` workflow **state** to the configured `review` workflow **state**. Linear's build lane is state-driven, not label-driven — `linear.labels.build.{ready,claimed,review,done}` is inert and nothing reads it (see `lisa-validate-tracker-mapping`). This skill is the destination of the `lisa-tracker-evidence` shim when `tracker = "linear"`.
 
 `$ARGUMENTS` is the Linear Issue identifier (e.g. `ENG-123`) and the path to the evidence directory. Caller passes both: `<IDENTIFIER> <evidence-dir>`.
 
@@ -104,15 +104,15 @@ Linear comments support markdown including `<details>` collapsibles, fenced code
 
 **If `$REVIEW` is empty, skip this phase entirely** — post the evidence comment and leave the Issue in `$CLAIMED`. Report it plainly (`No linear.workflow.review configured; leaving <ID> in its current (claimed) state`) so the skip is visible rather than silent. This is a supported configuration, not a failure.
 
-When `$REVIEW` is non-empty, update labels via `lisa-linear-access operation: save-issue` to remove `$CLAIMED` and add `$REVIEW`. Resolve label IDs first via `lisa-linear-access operation: list-issue-labels` (create the label via `create_issue_label` if it doesn't exist on the team).
+When `$REVIEW` is non-empty, invoke `lisa-linear-access operation: save-issue lifecycle_role: review`. That is the whole transition: the Linear build lane is the native workflow **state**, so there is no accompanying label move — do not remove a `claimed` label or add a `review` one, and do not create either. Those keys are inert.
 
-The native Linear `state` field is updated to `$REVIEW` **only when the resolver returned it from config**. Never resolve the state by searching the team for something review-shaped: on a board with more than one review-ish state that picks by position, not by intent, and the states most likely to be found that way are the human-only ones a project deliberately kept out of its config.
+The access layer resolves `$REVIEW`'s exact configured state itself and dispatches that ID; this skill never hands it one. Never resolve the state by searching the team for something review-shaped: on a board with more than one review-ish state that picks by position, not by intent, and the states most likely to be found that way are the human-only ones a project deliberately kept out of its config. The access layer refuses such a write outright — an unbound optional `review` is a refusal there, not a guess.
 
 ## Phase 6 — Report
 
 Return:
 
-- Linear Issue URL with new label state
+- Linear Issue URL with its new workflow state
 - PR URL (if updated)
 - List of uploaded evidence file URLs
 

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

@@ -122,7 +122,7 @@ Run it whenever the resolved env is **intermediate** (below the production termi
 
 1. Resolve the merged PR's base branch to its env via `.lisa.config.json` `deploy.branches` (`config-resolution`). If it maps to the production/terminal `done`, this phase is a **no-op** — native completion is correct there.
 2. **Uniform / single-environment no-op.** When the project's env-keyed `done` map is uniform — every environment resolves to the same `Done`, as in this repo (`production: main` only) — dev-merge == terminal, so native completion is correct. Do nothing. Only a **non-uniform** env→`done` map (distinct `On Dev`/`On Stg`/`Done` rungs) can desync.
-3. Otherwise (non-uniform map, resolved env intermediate): re-read the Issue's `state`. If it sits in a `completed`-typed state while the derived role is a lower env rung, **re-open** the native state by moving it back to the correct env rung (via `lisa-linear-access operation: save-issue`) and post a short `[lisa-linear-sync]` reconciliation comment **naming the likely cause** — a live `merge → Done` git automation, or a magic word in the PR body. This applies the `leaf-only-lifecycle` "Terminal native closure" rule — closure fires **only** at the production terminal `done`. Cite the rule by slug; do not restate it.
+3. Otherwise (non-uniform map, resolved env intermediate): re-read the Issue's `state`. If it sits in a `completed`-typed state while the derived role is a lower env rung, **re-open** the native state by moving it back to the correct env rung (via `lisa-linear-access operation: save-issue lifecycle_role: done env: <resolved-rung>` — the backstop names the role and the rung like every other lifecycle write; it never re-derives a state ID itself) and post a short `[lisa-linear-sync]` reconciliation comment **naming the likely cause** — a live `merge → Done` git automation, or a magic word in the PR body. This applies the `leaf-only-lifecycle` "Terminal native closure" rule — closure fires **only** at the production terminal `done`. Cite the rule by slug; do not restate it.
 4. **Safe default.** If the true terminal cannot be resolved (ambiguous env or unresolvable `done` map), do not change the `state` — post a `[lisa-linear-sync]` reconciliation-suggestion comment and leave it untouched, mirroring the Phase 5 safe default.
 
 ## Phase 5 — Parent Status Rollup (`--rollup`)
@@ -148,7 +148,10 @@ When the caller passes `--rollup`, this skill **derives a parent/container's wor
 
 **Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to the single `Done` state, the only env rung is production, and the lifecycle is `ready → claimed → done` with **no** dev/staging promotion hops and no configured `review` rung; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to the intermediate env states.
 
-**Apply the derived state** via `lisa-linear-access operation: save-issue` (Project or Issue), setting the parent's `stateId` to the derived role. Post an idempotent rollup comment naming the derived state and the child tally. Because the terminal `done` state is itself typed `completed`, a parent rolled to terminal is natively closed by the same write — there is no second closure step. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's state untouched.
+**Apply the derived state**, naming the derived role — the access layer resolves the configured state for that role and dispatches it. This skill never computes a `stateId` of its own; a role the project never bound is refused there rather than approximated here.
+
+- **Issue parent** → `lisa-linear-access operation: save-issue lifecycle_role: <derived role> [env: <key>]`. An Issue's lane IS a team workflow state, so this is the guarded write.
+- **Project parent** → `lisa-linear-access operation: save-project`. A Linear Project has no team workflow state — it carries its own coarse project status — so there is no `stateId` and no `lifecycle_role` to declare. Map the derived role onto the Project's own status and say in the rollup comment which role produced it. Do not send `lifecycle_role` here; the workflow-state guard governs Issues and has nothing to resolve for a Project. Post an idempotent rollup comment naming the derived state and the child tally. Because the terminal `done` state is itself typed `completed`, a parent rolled to terminal is natively closed by the same write — there is no second closure step. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's state untouched.
 
 ## Rules
 

package/plugins/lisa/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 |
 
-The build lifecycle uses native **workflow states** (`Ready`, `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 **leaf** work unit is created in the configured `ready` state only on explicit `build_ready: true`; omitted or `false` leaves it in the team's default backlog state, and a container is never put in `ready` at all (see the Build-ready control input below).
+The build lifecycle uses native **workflow states** (`Ready`, `In Progress`, `Blocked`, `On Dev`, `On Stg`, `Done`, plus an optional review state a project may bind), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new **leaf** work unit is created in the configured `ready` state only on explicit `build_ready: true`; omitted or `false` leaves it in the team's default backlog state, and a container is never put in `ready` at all (see the Build-ready control input below).
 
 ## Phase 1 — Resolve Intent
 
@@ -271,7 +271,7 @@ For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
 
 - **Omitted** → **not build-ready**: the leaf is left in the team's default backlog state. Ready is an explicit claim, never a vendor default. **This is a breaking change** — Linear previously created a leaf directly in the `ready` state on omission, so a caller that relied on that must now pass `build_ready: true`.
 - **`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.
+- **`build_ready: true`** → declare `lifecycle_role: ready` so the access layer resolves `.linear.workflow.ready` and places the leaf there, and `lisa-intake` / `lisa-linear-build-intake` auto-picks it up. Best-effort **for the lane, never for the guard**: an access-layer refusal (`ready` unbound, absent from the team, ambiguous) is fail-closed and is never worked around here — surface its message verbatim, do not fail the write, leave the Issue in its default state and record the reason. The Issue is still created; what is refused is the unproven lane placement, which is the safe half to lose.
 
 **A filing with neither is an incomplete handoff.** A leaf that is not build-ready must carry an explicit `human_gate: "<why a human must judge this first>"`; nothing in the ready lane means nothing ever claims it. When `human_gate` is supplied, stamp the hold on the Issue so it is auditable — a visible line plus the verbatim marker:
 
@@ -306,7 +306,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 (`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.
+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, place a **leaf** work unit in the `ready` lane by passing `lifecycle_role: ready` on the create call below — and only on **explicit `build_ready: true`**, per the Build-ready control input below. Omit the role for a container, and for a leaf whose `build_ready` is `false` or omitted, which then waits in the team's default backlog state for a human to promote it. Ready is an explicit claim, never an omission's default. Never resolve a state ID here and pass it as `stateId`: the access layer resolves the configured `ready` state itself and refuses anything else.
 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.
@@ -314,8 +314,8 @@ If the validator reports `PASS`, continue to Phase 6.
 
 ### CREATE — Sub-task (Issue with parentId)
 
-1. Resolve labels as above.
-2. Call `lisa-linear-access operation: save-issue` with: `team` (teamId), `title` (`[<repo>] <summary>` prefix is mandatory), `description` (markdown), `parentId` (the Story Issue ID), `projectId` (inherit from parent), `priority`, `estimate`, `labelIds`.
+1. Resolve labels as above. A Sub-task is a **leaf**, so the same ready-lane rule applies: pass `lifecycle_role: ready` on the create call below only on explicit `build_ready: true`, and omit it otherwise. Never resolve a state ID here.
+2. Call `lisa-linear-access operation: save-issue` with: `team` (teamId), `title` (`[<repo>] <summary>` prefix is mandatory), `description` (markdown), `parentId` (the Story Issue ID), `projectId` (inherit from parent), `priority`, `estimate`, `labelIds`, plus `lifecycle_role: ready` when `build_ready` is explicitly `true`.
 3. Capture identifier.
 4. Add relationships via Phase 4b.
 

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

@@ -729,8 +729,9 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/rollup-blocker-classification.mjs" \
 
 3. **If the derived state differs from the parent's current state, apply it** via the vendor's
    lifecycle write: a JIRA transition; a GitHub label swap in the item's own lifecycle namespace;
-   or a Linear `save-issue` update that writes the resolved workflow `stateId`, never a lifecycle
-   label. For GitHub, resolve the lane before writing: PRD parents use the configured `prd.*`
+   or a Linear `save-issue lifecycle_role: <derived role> [env: <key>]` update, which resolves the
+   configured workflow state in the access layer and writes that — never a lifecycle label, and
+   never a state ID this skill picked. For GitHub, resolve the lane before writing: PRD parents use the configured `prd.*`
    roles, while build tickets use the configured build roles. Keep exactly one lifecycle label in
    that selected namespace and never substitute or overlap the other namespace. When applying any
    of these writes, remove conflicting stale lifecycle roles — **including a stale `ready`** the