@codyswann/lisa 4.22.6 → 4.22.8

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

@@ -21,7 +21,27 @@ See the `config-resolution` rule for configuration and dispatch table.
    - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
 3. Pass through the output.
 
-`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), the vendor lane-write flag (`--update-label` on GitHub, `--update-state` on Linear), `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+
+> **There is no per-milestone lane-write flag on any vendor.** This paragraph previously documented `--update-label` on GitHub and `--update-state` on Linear. `--update-label` was never implemented — `lisa-github-sync` says flatly *"This skill never relabels"* — so a caller passing it got a silent no-op on GitHub and a real write on Linear for the equivalent flag. Both are gone. `--rollup` is the only write path a sync skill has.
+
+## Tracker status vocabulary — binding on all three arms
+
+Every suggested or performed transition names **only a role the project configured**, never a status, state or label discovered from the tracker's live workflow (transition lists, board columns, `type`-derived matches, other tickets). This binds a lead performing tracker writes exactly as it binds a subagent.
+
+Two consequences the vendor arms must not restate differently:
+
+- **A milestone whose role is unset gets a comment, not a transition.** `review` and the `qa.*` roles are optional and carry **no default** — omitting one means the project does not run that step, and the lifecycle skips it. "Unset" must never resolve to a built-in name; that is the difference between "not customized" and "we deliberately don't do this".
+- **A fallback may inform a read; it may never supply a write target.** Where a vendor exposes one (Linear resolves states by `type`), it selects by board position rather than intent — so on a board carrying more than one plausible state it returns whichever sits earliest, which is exactly the human-only lane a project left out of its config on purpose.
+
+Resolve roles through the shared resolver rather than an inlined helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+  --role <role> --vendor <jira|linear|github> --intent <read|write> [--env <env>]
+```
+
+Exit `0` with a value means configured; exit `0` with **empty** output means an optional role is unset — skip the transition; exit `2` means a required role is unset or a write was refused a fallback value.
 
 If `$ARGUMENTS` is empty, all vendor skills auto-detect a ticket reference from the active plan file (most recently modified `.md` in `plans/`).
 
@@ -65,6 +85,6 @@ This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that me
 ## Rules
 
 - Idempotent updates — running sync at the same milestone twice should not produce duplicate comments. Vendor skills enforce this.
-- Never auto-transition a lane the caller did not ask for. On GitHub the canonical signal is the `status:*` label, written only with `--update-label`; on Linear it is the native workflow state, written only with `--update-state`. Without the flag, every vendor arm only suggests.
+- Never transition a leaf's lane from a sync milestone on any vendor. The canonical signal differs — the `status:*` label on GitHub, the workflow status on JIRA, the native workflow state on Linear — but the owner is the same everywhere: build-intake / the vendor agent. Every arm only suggests. `--rollup` (parent derivation) is the sole exception, and it derives the parent from its children rather than advancing a leaf.
 - Parent rollup derives state from children per the `leaf-only-lifecycle` rule; it never sets a parent to `ready` and never resolves a dev/staging `done` in this single-environment repo.
 - Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.22.6",
+  "version": "4.22.8",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/scripts/resolve-lifecycle-role.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+/**
+ * Lifecycle-role resolution — the single resolver for every vendor.
+ *
+ * ## The defect this replaces
+ *
+ * Twelve skills inlined their own `read_role()` bash helper. Hashing the
+ * function bodies produced ELEVEN distinct implementations — only
+ * `lisa-linear-build-intake` and `lisa-linear-evidence` agreed. Copy-paste with
+ * no shared source is why the three vendors drifted apart on the same contract.
+ *
+ * The drift was not cosmetic. `lisa-linear-evidence` resolved
+ * `read_role review "In Review"` — a NON-EMPTY default — while
+ * `lisa-jira-evidence/scripts/post-evidence.sh` resolved the same role with
+ * `REVIEW=""` and an explicit skip branch. Same role, opposite behaviour, on the
+ * question of whether an unconfigured review step exists at all.
+ *
+ * ## R1 — absent means SKIP, never default
+ *
+ * `ready`, `claimed`, `blocked` and `done` are REQUIRED: a project that omits
+ * them is misconfigured and the caller should say so. `review` and the `qa.*`
+ * roles are OPTIONAL and have NO built-in default, so omitting one means the
+ * lifecycle skips that transition entirely.
+ *
+ * This is the difference between "not customized" and "we don't do this step",
+ * which a defaulting resolver cannot express. Measured downstream: a project
+ * deliberately bound no `review` role — a PR-open ticket was meant to stay in
+ * `claimed` until it reached an environment — and agents moved issues into a
+ * human-only review state anyway, because every layer that could have honoured
+ * the omission supplied a default instead.
+ *
+ * ## R2 — a fallback may inform a READ, never supply a WRITE target
+ *
+ * Linear states carry a machine-readable `type`, so a skill may fall back to
+ * resolving a role by type when the configured name is missing — the
+ * `config-resolution` rule permits this "but only to *read* … it must never
+ * invent a state to write into."
+ *
+ * Nothing enforced that sentence. The fallback selects the lowest-position
+ * `started` state, and on the board where this was measured the states ranked
+ * `blocked` (-1989.26), `claimed` (-1478.50), then two unbound human-only review
+ * states at -1209.69 and -1079.70. With `blocked` and `claimed` already taken,
+ * the fallback returned the first unbound one — precisely where two issues
+ * landed. Not fuzzy matching; position ordering, used for a write.
+ *
+ * `--intent=write` therefore refuses to return a fallback value and reports a
+ * setup defect instead. `--intent=read` may use one, and always reports which.
+ *
+ * ## Why a script rather than a shared bash snippet
+ *
+ * A snippet is copy-paste, which is the disease. Skills shell out to
+ * `${CLAUDE_PLUGIN_ROOT}/scripts/…` for exactly this reason elsewhere
+ * (`lifecycle-label-trust.mjs`, `automation-run-record.mjs`), and a real process
+ * boundary means the resolution can be unit-tested rather than re-read.
+ * @module scripts/resolve-lifecycle-role
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Config file consulted first; its keys override the committed file. */
+export const LOCAL_CONFIG = ".lisa.config.local.json";
+
+/** The committed config file. */
+export const GLOBAL_CONFIG = ".lisa.config.json";
+
+/**
+ * Roles a project MUST bind. Omitting one is a setup defect, not a policy
+ * choice — there is no coherent lifecycle without a ready lane, a claimed lane,
+ * a blocked lane and a terminal.
+ */
+export const REQUIRED_ROLES = Object.freeze([
+  "ready",
+  "claimed",
+  "blocked",
+  "done",
+]);
+
+/**
+ * Roles a project MAY bind. Omitting one means the lifecycle skips that
+ * transition. These have NO built-in default — that is the whole point of R1.
+ */
+export const OPTIONAL_ROLES = Object.freeze([
+  "review",
+  "qa.queue",
+  "qa.certified",
+  "human_needed",
+]);
+
+/** Where each vendor keeps its build lifecycle role map. */
+export const VENDOR_ROOTS = Object.freeze({
+  jira: "jira.workflow",
+  linear: "linear.workflow",
+  github: "github.labels.build",
+});
+
+/** Resolution outcomes, reported so a caller never has to guess what happened. */
+export const OUTCOMES = Object.freeze({
+  CONFIGURED: "configured",
+  UNSET_OPTIONAL: "unset-optional",
+  UNSET_REQUIRED: "unset-required",
+  FALLBACK_REFUSED: "fallback-refused-for-write",
+});
+
+/**
+ * Read a dotted path out of a parsed config object.
+ *
+ * @param {unknown} source parsed config
+ * @param {string} path dotted key path, e.g. `linear.workflow.review`
+ * @returns {unknown} the value, or undefined when any segment is missing
+ */
+export const readPath = (source, path) => {
+  let cursor = source;
+  for (const segment of path.split(".")) {
+    if (cursor === null || typeof cursor !== "object" || !(segment in cursor))
+      return undefined;
+    cursor = cursor[segment];
+  }
+  return cursor;
+};
+
+/**
+ * Parse a config file, treating an unreadable or malformed file as absent.
+ *
+ * A malformed local override must not silently mask the committed file, so the
+ * caller is told which files actually parsed via the returned `sources`.
+ *
+ * @param {string} file path to read
+ * @returns {{ value: object | undefined, error: string | undefined }} parse result
+ */
+export const parseConfig = file => {
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return { value: undefined, error: undefined };
+  }
+  try {
+    return { value: JSON.parse(raw), error: undefined };
+  } catch (cause) {
+    return {
+      value: undefined,
+      error: `${file} is not valid JSON: ${cause.message}`,
+    };
+  }
+};
+
+/**
+ * Resolve one lifecycle role for one vendor.
+ *
+ * Resolution order is local config → global config → (nothing). There is no
+ * built-in default tier: see R1 in the module docblock.
+ *
+ * @param {object} options resolution inputs
+ * @param {string} options.role role name (`ready`, `review`, `qa.queue`, …)
+ * @param {string} options.vendor one of `jira` | `linear` | `github`
+ * @param {"read" | "write"} [options.intent] what the caller will do with it
+ * @param {string} [options.env] env key when resolving the env-keyed `done` map
+ * @param {object} [options.local] pre-parsed local config (tests)
+ * @param {object} [options.global] pre-parsed global config (tests)
+ * @param {string} [options.fallback] a value a vendor fallback would supply
+ * @returns {{ value: string, outcome: string, source: string, message: string }} resolution
+ */
+export const resolveRole = ({
+  role,
+  vendor,
+  intent = "read",
+  env,
+  local,
+  global: globalConfig,
+  fallback,
+}) => {
+  const root = VENDOR_ROOTS[vendor];
+  if (!root) {
+    return {
+      value: "",
+      outcome: OUTCOMES.UNSET_REQUIRED,
+      source: "none",
+      message: `Unknown vendor '${vendor}'. Expected one of: ${Object.keys(VENDOR_ROOTS).join(", ")}.`,
+    };
+  }
+
+  // `done` is env-keyed on every vendor; an env selects one rung of the map.
+  const path =
+    env && role === "done" ? `${root}.done.${env}` : `${root}.${role}`;
+
+  for (const [label, source] of [
+    ["local", local],
+    ["global", globalConfig],
+  ]) {
+    const found = readPath(source, path);
+    if (typeof found === "string" && found.length > 0) {
+      return {
+        value: found,
+        outcome: OUTCOMES.CONFIGURED,
+        source: label,
+        message: `${path} = ${found} (from ${label} config)`,
+      };
+    }
+  }
+
+  const optional = OPTIONAL_ROLES.includes(role);
+
+  // R2 — a fallback may inform a read, never supply a write target.
+  if (fallback && intent === "write") {
+    return {
+      value: "",
+      outcome: OUTCOMES.FALLBACK_REFUSED,
+      source: "none",
+      message:
+        `Refusing to write to '${fallback}': it was derived by fallback, not named at ${path}. ` +
+        `A fallback may inform a read but must never supply a write target (config-resolution). ` +
+        `Bind ${path} explicitly, or run /lisa:setup:${vendor}.`,
+    };
+  }
+  if (fallback) {
+    return {
+      value: fallback,
+      outcome: OUTCOMES.CONFIGURED,
+      source: "fallback",
+      message: `${path} is unset; using fallback '${fallback}' for a READ only.`,
+    };
+  }
+
+  if (optional) {
+    return {
+      value: "",
+      outcome: OUTCOMES.UNSET_OPTIONAL,
+      source: "none",
+      message:
+        `No ${path} configured; skipping the ${role} transition. ` +
+        `This is a supported configuration, not an error — the item stays in its current role.`,
+    };
+  }
+
+  return {
+    value: "",
+    outcome: OUTCOMES.UNSET_REQUIRED,
+    source: "none",
+    message: `Required role '${role}' is not configured at ${path}. Run /lisa:setup:${vendor}.`,
+  };
+};
+
+/**
+ * Parse `--key=value` / `--key value` argv into a plain object.
+ *
+ * @param {string[]} argv raw arguments
+ * @returns {Record<string, string>} parsed flags
+ */
+export const parseArgs = argv => {
+  const out = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const [key, inline] = token.slice(2).split("=");
+    if (inline !== undefined) {
+      out[key] = inline;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      out[key] = next;
+      index += 1;
+    } else {
+      out[key] = "true";
+    }
+  }
+  return out;
+};
+
+/**
+ * CLI entry point.
+ *
+ * Exit codes are the contract callers branch on:
+ * - `0` with a value on stdout — the role is configured (or a read fallback).
+ * - `0` with EMPTY stdout — an optional role is unset; skip the transition.
+ * - `2` — a required role is unset, or a write was refused a fallback value.
+ *
+ * The distinction between the two `0` cases is deliberate: an unset optional
+ * role is a supported configuration, so it must not look like a failure.
+ *
+ * @param {string[]} argv arguments after the script name
+ * @returns {number} process exit code
+ */
+export const main = argv => {
+  const args = parseArgs(argv);
+  if (!args.role || !args.vendor) {
+    process.stderr.write(
+      "usage: resolve-lifecycle-role.mjs --role <name> --vendor <jira|linear|github> " +
+        "[--intent read|write] [--env dev|staging|production] [--fallback <name>]\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 result = resolveRole({
+    role: args.role,
+    vendor: args.vendor,
+    intent: args.intent ?? "read",
+    env: args.env,
+    fallback: args.fallback,
+    local: local.value,
+    global: globalConfig.value,
+  });
+
+  if (args.json === "true") {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else if (result.value) {
+    process.stdout.write(`${result.value}\n`);
+  }
+
+  if (result.outcome === OUTCOMES.CONFIGURED) return 0;
+  if (result.outcome === OUTCOMES.UNSET_OPTIONAL) {
+    process.stderr.write(`${result.message}\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-agy/skills/lisa-github-build-intake/SKILL.md

@@ -38,11 +38,12 @@ Build-queue label names are read from `.lisa.config.json` `github.labels.build.*
 ```bash
 # Read role with default fallback. Local overrides global per-key.
 read_role() {
-  local role="$1" default="$2"
-  local local_v global_v
-  local_v=$(jq -r ".github.labels.build.${role} // empty" .lisa.config.local.json 2>/dev/null)
-  global_v=$(jq -r ".github.labels.build.${role} // empty" .lisa.config.json 2>/dev/null)
-  echo "${local_v:-${global_v:-$default}}"
+  # Single resolver — see config-resolution "The single resolver".
+  # Exit 0 + empty output means an OPTIONAL role is unset: skip that transition,
+  # never substitute the second argument. A default on an optional role is what
+  # made "unset" indistinguishable from "not customized".
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor github --intent "${3:-read}" 2>/dev/null
 }
 
 READY=$(read_role ready "status:ready")

package/plugins/lisa-agy/skills/lisa-github-prd-intake/SKILL.md

@@ -21,11 +21,12 @@ PRD label names are read from `.lisa.config.json` `github.labels.prd.*`, falling
 ```bash
 # Read role with default fallback. Local overrides global per-key.
 read_role() {
-  local role="$1" default="$2"
-  local local_v global_v
-  local_v=$(jq -r ".github.labels.prd.${role} // empty" .lisa.config.local.json 2>/dev/null)
-  global_v=$(jq -r ".github.labels.prd.${role} // empty" .lisa.config.json 2>/dev/null)
-  echo "${local_v:-${global_v:-$default}}"
+  # Single resolver — see config-resolution "The single resolver".
+  # Exit 0 + empty output means an OPTIONAL role is unset: skip that transition,
+  # never substitute the second argument. A default on an optional role is what
+  # made "unset" indistinguishable from "not customized".
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor github --intent "${3:-read}" 2>/dev/null
 }
 
 READY=$(read_role ready "prd-ready")

package/plugins/lisa-agy/skills/lisa-github-sync/SKILL.md

@@ -79,6 +79,8 @@ Based on the milestone, suggest (but do NOT automatically perform) a label trans
 
 The actual `status:in-progress` flip is owned by `lisa-github-build-intake` (claim) and `lisa-github-agent`. The configured `done` flip is owned by the build-intake owner after a successful build and evidence post. This skill never relabels.
 
+Every suggested transition is bound by the **Tracker status vocabulary** section of `lisa-tracker-sync` — cite it, do not restate the policy. GitHub has **no review lane** (`BUILD_LABEL_DEFAULTS` seeds no `review` key, and `config-resolution` records "no default review label"), so the `pr-ready` milestone suggests the configured `done` label directly; there is no intermediate hop to skip. Resolve every label through the shared resolver rather than an inlined helper.
+
 ### Step 5: Parent Status Rollup (`--rollup`)
 
 When invoked with `--rollup`, this skill **derives a parent/container issue's `status:*` label from the roll-up of its child sub-issues** instead of posting a milestone update on a leaf. This implements the GitHub sub-issue-completion arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy. It is the sync-side complement to the write-time labeling (`lisa-github-write-issue`), the validate-time S15 gate (`lisa-github-validate-issue`), and the claim-time gate (`lisa-github-build-intake`); all four cite the same rule so the classification never drifts.

package/plugins/lisa-agy/skills/lisa-github-write-prd/SKILL.md

@@ -20,9 +20,13 @@ ORG=$(jq -r '.github.org // empty' .lisa.config.local.json 2>/dev/null); ORG="${
 REPO=$(jq -r '.github.repo // empty' .lisa.config.local.json 2>/dev/null); REPO="${REPO:-$(jq -r '.github.repo // empty' .lisa.config.json)}"
 [ -z "$ORG" ] || [ -z "$REPO" ] && { echo "Error: github.org / github.repo not set in .lisa.config.json."; exit 1; }
 
-read_role() { # path default
-  local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null)
-  echo "${lv:-${gv:-$2}}"
+read_role() {
+  # Single resolver — see config-resolution "The single resolver".
+  # Exit 0 + empty output means an OPTIONAL role is unset: skip that transition,
+  # never substitute the second argument. A default on an optional role is what
+  # made "unset" indistinguishable from "not customized".
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor github --intent "${3:-read}" 2>/dev/null
 }
 # Resolve the FULL PRD lifecycle vocabulary from config (never hard-code names) — needed so the
 # "exactly one role" reconcile and the past-ready check work for projects that renamed any label.

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

@@ -22,11 +22,12 @@ Status names are read from `.lisa.config.json` `jira.workflow.*`, falling back t
 ```bash
 # Read role with default fallback. Local overrides global per-key.
 read_role() {
-  local role="$1" default="$2"
-  local local_v global_v
-  local_v=$(jq -r ".jira.workflow.${role} // empty" .lisa.config.local.json 2>/dev/null)
-  global_v=$(jq -r ".jira.workflow.${role} // empty" .lisa.config.json 2>/dev/null)
-  echo "${local_v:-${global_v:-$default}}"
+  # Single resolver — see config-resolution "The single resolver".
+  # Exit 0 + empty output means an OPTIONAL role is unset: skip that transition,
+  # never substitute the second argument. A default on an optional role is what
+  # made "unset" indistinguishable from "not customized".
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor jira --intent "${3:-read}" 2>/dev/null
 }
 
 READY=$(read_role ready "Ready")

package/plugins/lisa-agy/skills/lisa-jira-sync/SKILL.md

@@ -75,7 +75,9 @@ Based on the milestone, suggest (but don't automatically perform) a status trans
 | PR ready | configured `jira.workflow.review` status, or no transition when unconfigured |
 | PR merged | configured `jira.workflow.done` status for the PR's target environment (env-keyed `done` resolved via `deploy.branches`), or no transition when unconfigured |
 
-Every suggested or performed transition is bound by the **Tracker status vocabulary** section of the `config-resolution` rule: only statuses named in the configured workflow map, never statuses discovered from the tracker's live workflow (transition lists, board columns, other tickets) — and this binds the lead performing tracker writes exactly as it binds a subagent. A milestone with no configured status gets a comment, not a transition.
+Every suggested transition is bound by the **Tracker status vocabulary** section of `lisa-tracker-sync` — cite it, do not restate the policy. It is shared by all three vendor arms so the bar cannot drift between them, and it carries the two consequences that matter here: a milestone whose role is unset gets a comment rather than a transition, and a fallback may inform a read but never supply a write target.
+
+`review` is optional on JIRA and has no default. Resolve it through the shared resolver rather than an inlined helper — `lisa-jira-evidence/scripts/post-evidence.sh` already models the correct behaviour (empty default, explicit skip branch, `leaving <ID> in its current (claimed) status`).
 
 ### Step 5: Parent Status Rollup (`--rollup`)
 

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

@@ -23,11 +23,12 @@ Build-queue **workflow state** names are read from `.lisa.config.json` `linear.w
 ```bash
 # Read role with default fallback. Local overrides global per-key.
 read_role() {
-  local role="$1" default="$2"
-  local local_v global_v
-  local_v=$(jq -r ".linear.workflow.${role} // empty" .lisa.config.local.json 2>/dev/null)
-  global_v=$(jq -r ".linear.workflow.${role} // empty" .lisa.config.json 2>/dev/null)
-  echo "${local_v:-${global_v:-$default}}"
+  # Single resolver — see config-resolution "The single resolver".
+  # Exit 0 + empty output means an OPTIONAL role is unset: skip that transition,
+  # never substitute the second argument. A default on an optional role is what
+  # made "unset" indistinguishable from "not customized".
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor linear --intent "${3:-read}" 2>/dev/null
 }
 
 READY=$(read_role ready "Ready")

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

@@ -12,21 +12,20 @@ Post verification evidence to a Linear Issue and transition it from the configur
 
 ## Workflow resolution
 
-The `claimed` and `review` build labels are read from `.lisa.config.json` `linear.workflow.*`, falling back to the defaults documented in the `config-resolution` rule (`In Progress` and `In Review`).
+Resolve every lifecycle role through the shared resolver — never an inlined `read_role` helper. Twelve skills used to inline their own and produced **eleven different implementations**, which is how the vendors drifted apart on this exact contract.
 
 ```bash
-read_role() {
-  local role="$1" default="$2"
-  local local_v global_v
-  local_v=$(jq -r ".linear.workflow.${role} // empty" .lisa.config.local.json 2>/dev/null)
-  global_v=$(jq -r ".linear.workflow.${role} // empty" .lisa.config.json 2>/dev/null)
-  echo "${local_v:-${global_v:-$default}}"
+resolve() {  # role, intent -> value on stdout; empty when an optional role is unset
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor linear --intent "${2:-read}" 2>/dev/null
 }
 
-CLAIMED=$(read_role claimed "In Progress")
-REVIEW=$(read_role review "In Review")
+CLAIMED=$(resolve claimed write)
+REVIEW=$(resolve review write)
 ```
 
+**`review` is OPTIONAL and has no default.** An empty `REVIEW` means the project does not run an agent review step, and this skill **skips the transition entirely**, leaving the Issue in `claimed` — the same behaviour `lisa-jira-evidence/scripts/post-evidence.sh` has always had. Do not substitute `In Review`, and do not fall back to a state resolved by `type` or board position: a fallback may inform a read but must never supply a write target (`config-resolution`, R2). Resolving a state nobody configured is how agents reach human-only review lanes.
+
 ## Configuration
 
 Reads `linear.workspace`, `linear.teamKey`, and `linear.workflow.*` from `.lisa.config.json` (with `.local` override).
@@ -93,9 +92,11 @@ Linear comments support markdown including `<details>` collapsibles, fenced code
 
 ## Phase 5 — Transition Status
 
-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).
+**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).
 
-The native Linear `state` field is also updated to the team's "In Review" state if one exists — but the label remains the source of truth for cross-team consistency.
+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.
 
 ## Phase 6 — Report
 

package/plugins/lisa-agy/skills/lisa-linear-prd-intake/SKILL.md

@@ -21,11 +21,12 @@ PRD label names are read from `.lisa.config.json` `linear.labels.prd.*`, falling
 ```bash
 # Read role with default fallback. Local overrides global per-key.
 read_role() {
-  local role="$1" default="$2"
-  local local_v global_v
-  local_v=$(jq -r ".linear.labels.prd.${role} // empty" .lisa.config.local.json 2>/dev/null)
-  global_v=$(jq -r ".linear.labels.prd.${role} // empty" .lisa.config.json 2>/dev/null)
-  echo "${local_v:-${global_v:-$default}}"
+  # Single resolver — see config-resolution "The single resolver".
+  # Exit 0 + empty output means an OPTIONAL role is unset: skip that transition,
+  # never substitute the second argument. A default on an optional role is what
+  # made "unset" indistinguishable from "not customized".
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor linear --intent "${3:-read}" 2>/dev/null
 }
 
 READY=$(read_role ready "prd-ready")