@codyswann/lisa 4.27.2 → 4.27.3

package/plugins/src/base/agents/linear-agent.md

@@ -47,11 +47,11 @@ Use the `linear-verify` skill to check the item against organizational standards
 
 **Gating behavior — this is the one place auto-transitioning is allowed:**
 
-Resolve build-lifecycle STATES from `.lisa.config.json` `linear.workflow.*` (defaults: `Ready` / `In Progress` / `In Review`); resolve the `blocked` state from the same section (`linear.workflow.blocked`, default `Blocked`) and the `human_needed` marker label from the same section (`linear.labels.build.human_needed`, default `human-needed`).
+Resolve build-lifecycle STATES from `.lisa.config.json` `linear.workflow.*` through `scripts/resolve-lifecycle-role.mjs` (`--vendor linear`). `ready`, `claimed`, `blocked` and `done` are REQUIRED and have no built-in default — an unset one is a setup defect to report. `review` is OPTIONAL and deliberately has **no** default: an unset `review` means the project runs no agent review step and the transition is skipped, never substituted (`config-resolution` R1). Resolve the `human_needed` marker label from `linear.labels.build.human_needed` (default `human-needed`) — the one surviving build-lane label key.
 
 If `linear-verify` returns `FAIL` on any of the above, do NOT continue to build. **Draft the missing spec content first, then block for confirmation** — never bounce a raw "go write all this" checklist back to the creator:
 1. **Best-effort autofill (before blocking).** Run `pre-flight-autofill` for every work item. Preserve a human bare configured key or `Confirmed: <env>`; automation writes `Inferred: <env> — evidence: <title|body|reproduction|hostname>`, `Assumption: <env> — remote default branch <branch>` for a unique reverse-map, or `Assumption: remote default branch <branch>` otherwise. Human confirmation replaces the annotation with the bare key or `Confirmed: <env>`. For a legacy bare value, use managed draft markers and current ticket content only; provider edit history is not required. A marker proves automation and requires re-annotation; otherwise unknown provenance plus conflicting evidence stops for confirmation. Resolve one exact `deploy.branches` key from the human-authored title, body, and reproduction steps or URL hostname; exclude the complete `Target Backend Environment` section and other machine-authored metadata/draft blocks so annotations cannot become evidence. A reported bug environment is an example, not a restriction. Evidence supersedes only `Assumption:`. Normalize `prod` ↔ `production` only when exactly one is configured; no other aliases exist. Conflicts stop; never infer from arbitrary branch text, URL paths/query strings, or substrings. Write through `linear-write-issue`, never overwrite human prose, then re-run `linear-verify`.
-2. Update labels via `lisa-linear-access operation: save-issue`: remove the current build label, add the configured `blocked` label **and** the configured `human_needed` marker label. (Create either label via `create_issue_label` if needed.) Even after the agent drafted what it could, a pre-flight gate failure bounces the item back to its creator because it still needs a human to **confirm the drafted assumptions** or supply something no agent can invent — real missing credentials, access, or an irreducible product/scoping decision — so the marker tells a human scanning the board which blocked items are waiting on them. The marker is additive to `blocked`, not a replacement. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
+2. Move the Issue to the configured `blocked` **state** via `lisa-linear-access operation: save-issue lifecycle_role: blocked` (the access layer resolves the configured state itself; never hand it a state ID), and add the configured `human_needed` marker **label** in the same or a following metadata update. (Create either label via `create_issue_label` if needed.) Even after the agent drafted what it could, a pre-flight gate failure bounces the item back to its creator because it still needs a human to **confirm the drafted assumptions** or supply something no agent can invent — real missing credentials, access, or an irreducible product/scoping decision — so the marker tells a human scanning the board which blocked items are waiting on them. The marker is additive to `blocked`, not a replacement. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
 3. Reassign the item to the **Issue creator** (the human who filed it — Linear's `creator` field).
 4. Post the **confirmation comment** from the `pre-flight-autofill` rule via `lisa-linear-access operation: save-comment`, **not** a bare remediation checklist: disclose it is a Claude draft, give one line per drafted section naming the key assumption made, list any remaining human-only item as a specific question with a recommended default, and close with *"review the drafted sections, correct anything wrong, then flip back to Ready and it builds — or reply with corrections."* Prefix with `[{repo}]`.
 5. Stop. Do not run triage, do not delegate to a flow, do not start work.
@@ -116,23 +116,23 @@ Use the `linear-evidence` skill to:
 
 ### 8. Suggest Status Transition
 
-Based on the milestone, suggest (but don't auto-transition the native Linear `state`). Label role names are resolved from `.lisa.config.json` `linear.workflow.*`:
+Based on the milestone, name the lifecycle role the item has reached. This agent does not perform these transitions itself — the owning flow does (`linear-evidence` for `review`, `linear-build-intake` for `claimed` and `done`) — so this section is a suggestion surface, not a write surface. Role names are resolved from `.lisa.config.json` `linear.workflow.*`; there is no default column, because a role this project did not bind has no name to print:
 
-| Milestone | Suggested role | Default label |
-|-----------|----------------|---------------|
-| Plan created | `claimed` | `In Progress` |
-| PR ready | `review` | `In Review` |
-| PR merged | `done` (env-aware; build-intake performs if dispatched via that flow) | env-keyed variant per `linear.workflow.done` |
+| Milestone | Lifecycle role | Configured state |
+|-----------|----------------|------------------|
+| Plan created | `claimed` | `linear.workflow.claimed` (required) |
+| PR ready | `review` | `linear.workflow.review` — **optional**; unset means skip the step |
+| PR merged | `done` (env-aware; build-intake performs it if dispatched via that flow) | env-keyed variant per `linear.workflow.done` |
 
-Note: `done` may be a string or an env-keyed map (`{ dev, staging, production }`). When suggesting the PR-merged transition, the env is implied by the PR's base branch via `deploy.branches` — surface the resolved label name; do not auto-transition.
+Note: `done` may be a string or an env-keyed map (`{ dev, staging, production }`). When naming the PR-merged transition, the env is implied by the PR's base branch via `deploy.branches` — surface the resolved state name; do not perform the transition here.
 
-The label transitions ARE the canonical signal. The native `state` field stays as the human / triage decision.
+The native workflow **state** is the canonical build lane on Linear (`linear.labels.build.{ready,claimed,review,done}` is inert and nothing reads it). Suggesting a role never authorizes writing it: every state write goes through `lisa-linear-access` with a declared `lifecycle_role`, which resolves the target from config rather than trusting a supplied ID.
 
 ## Rules
 
-- Never auto-transition the native Linear `state`, with one explicit exception: when `linear-verify` returns `FAIL` for the pre-flight gate (Step 2), first run the `pre-flight-autofill` draft-then-block procedure (draft the authorable missing sections into the description as labeled assumptions), then update labels to the configured `blocked` label, add the configured `human_needed` marker label (`linear.labels.build.human_needed`, default `human-needed`), and reassign to the creator with a confirmation comment. Every other status change remains a label-driven suggestion.
+- **This agent** never transitions the native Linear `state`, with one explicit exception: when `linear-verify` returns `FAIL` for the pre-flight gate (Step 2), run the `pre-flight-autofill` draft-then-block procedure (draft the authorable missing sections into the description as labeled assumptions), then move the Issue to the configured `blocked` state via `lisa-linear-access operation: save-issue lifecycle_role: blocked`, add the configured `human_needed` marker label (`linear.labels.build.human_needed`, default `human-needed`), and reassign to the creator with a confirmation comment. Every other transition is a suggestion this agent surfaces and the owning lifecycle flow performs — it is not a claim that the lane is label-driven. It is not: on Linear the lane is the state.
 - Always read the full item graph via `linear-read-issue` before determining intent — don't rely on type labels alone.
-- Never create or materially edit an item by calling MCP write tools directly — always delegate to `linear-write-issue` so relationships, Gherkin criteria, and metadata gates are enforced. Two explicit exceptions are permitted: (1) the Step 2 pre-flight failure path (when `linear-verify` returns `FAIL`) may call `lisa-linear-access operation: save-issue` and `lisa-linear-access operation: save-comment` directly to set `Blocked`, add the configured `human_needed` marker label, and reassign to the creator — this narrow exception is already granted by the rule above; (2) the Step 3 triage path may call `lisa-linear-access operation: save-comment` to post triage findings and `lisa-linear-access operation: save-issue` to add the `claude-triaged-{repo}` label — these are lightweight metadata updates that do not create or materially edit ticket content and therefore do not need to route through `linear-write-issue`.
+- Never create or materially edit an item by calling MCP write tools directly — always delegate to `linear-write-issue` so relationships, Gherkin criteria, and metadata gates are enforced. Two explicit exceptions are permitted: (1) the Step 2 pre-flight failure path (when `linear-verify` returns `FAIL`) may call `lisa-linear-access operation: save-issue lifecycle_role: blocked` and `lisa-linear-access operation: save-comment` directly to move the Issue to the configured `blocked` state, add the configured `human_needed` marker label, and reassign to the creator — this narrow exception is already granted by the rule above; (2) the Step 3 triage path may call `lisa-linear-access operation: save-comment` to post triage findings and `lisa-linear-access operation: save-issue` to add the `claude-triaged-{repo}` label — these are lightweight metadata updates that do not create or materially edit ticket content and therefore do not need to route through `linear-write-issue`.
 - If sign-in credentials are in the item, extract and pass them to the flow. If the item touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.
 - If the item has a Validation Journey section, pass it to the verifier agent. The Validation Journey's local-verification step must point at the target backend environment named in the description.
 - The environment handoff for every work item uses the same durable grammar: human bare configured key or `Confirmed: <env>`; automated `Inferred: <env> — evidence: <title|body|reproduction|hostname>`, `Assumption: <env> — remote default branch <branch>` for a unique reverse-map, or `Assumption: remote default branch <branch>` otherwise. Human confirmation replaces an automated annotation with the bare key or `Confirmed: <env>`. For legacy bare values, managed draft markers and current ticket content decide provenance; provider edit history is not required. A marker proves automation; otherwise unknown provenance plus conflicting evidence stops for confirmation. Human-confirmed wins, then validated `Inferred:`; otherwise one exact `deploy.branches` key from the human-authored title, body, and reproduction steps or URL hostname drives the implementation base branch. Exclude the complete `Target Backend Environment` section and other machine-authored metadata/draft blocks so annotations cannot become evidence. Evidence supersedes only `Assumption:`. Normalize `prod` ↔ `production` only when exactly one is configured; no other aliases exist. Conflicts stop. Never infer from arbitrary branch text, URL paths/query strings, or substrings. With no signal, use the remote default and record the applicable assumption without blocking on a non-unique reverse-map. Require any selected mapping and remote branch. A reported bug environment is an example of the all-work-type rule. Non-integration fixes still require the linked forward cherry-pick.

package/plugins/src/base/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 in the configured `ready` workflow STATE, dispatch each through the build flow, transition successful builds to the configured (env-aware) `done` state — then report what happened.
 
-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: `Ready`, `In Progress`, `In Review`, `Blocked`, env-keyed `{ dev: "On Dev", staging: "On Stg", production: "Done" }`. `ready` is a DEDICATED state, never the team default (`Todo`) — mapping it to the default makes every untouched backlog item claimable.
+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: `Ready`, `In Progress`, `Blocked`, env-keyed `{ dev: "On Dev", staging: "On Stg", production: "Done" }`. **`review` has no default and is never seeded** — it is optional, and an unset `review` means the project runs no agent review step, so the transition is skipped rather than aimed at a review-shaped state nobody configured. `ready` is a DEDICATED state, never the team default (`Todo`) — mapping it to the default makes every untouched backlog item claimable.
 
 ## Confirmation policy
 

package/plugins/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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