@codyswann/lisa 4.22.7 → 4.22.9

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/publish-aws-bootstrap.mjs

@@ -56,6 +56,11 @@ const ROLE_ARN =
   /^arn:(?:aws|aws-us-gov|aws-cn):iam::\d{12}:role\/[\w+=,.@/-]+$/;
 const PUBLICATION_COORDINATION_SCOPE = "AWS_BOOTSTRAP_";
 const PUBLICATION_LOCK_TTL_MS = 30 * 60 * 1000;
+// Every provider and AWS child has its own 30-second deadline. Stop starting
+// target mutations five minutes before another publisher may reap this lock,
+// leaving ample room for the in-flight child to finish. This is a monotonic
+// duration budget, not a wall clock used to order or expire provider records.
+const PUBLICATION_CRITICAL_SECTION_BUDGET_MS = 25 * 60 * 1000;
 
 /**
  * Validate and normalize one complete bundle without changing its serialized
@@ -257,6 +262,22 @@ function writeProviderValue(cfg, id, value, write) {
   }
 }
 
+function publicationBudgetGuard(startedAt, monotonicNow) {
+  return () => {
+    const elapsed = monotonicNow() - startedAt;
+    if (!Number.isFinite(elapsed) || elapsed < 0) {
+      throw new Error(
+        "publication lock monotonic timer became invalid; refusing further provider mutation"
+      );
+    }
+    if (elapsed >= PUBLICATION_CRITICAL_SECTION_BUDGET_MS) {
+      throw new Error(
+        "publication lock execution budget exceeded; refusing further provider mutation"
+      );
+    }
+  };
+}
+
 /**
  * Enter the provider election for one AWS bootstrap record.
  *
@@ -427,23 +448,29 @@ export function releasePublicationLock(cfg, lock, operations = {}) {
  * snapshot can never overwrite a publication that finished while this process
  * was entering the election.
  */
-function withPublicationLock(cfg, operations, task) {
+function withPublicationLock(cfg, operations, task, completedMessage) {
   const fetch = operations.fetch ?? fetchAll;
   const acquire = operations.acquireLock ?? acquirePublicationLock;
   const release = operations.releaseLock ?? releasePublicationLock;
+  const monotonicNow = operations.monotonicNow ?? (() => performance.now());
+  const startedAt = monotonicNow();
+  const assertWithinBudget = publicationBudgetGuard(startedAt, monotonicNow);
   const target = currentEntry(cfg, fetch);
   const lock = acquire(cfg, target, operations);
   let result;
   let taskError;
 
   try {
+    assertWithinBudget();
     const current = currentEntry(cfg, fetch);
     if (current.id !== target.id || current.projectId !== target.projectId) {
       throw new Error(
         `${BOOTSTRAP_KEY} moved after publication lock acquisition; retry from the new provider record`
       );
     }
-    result = task(current);
+    assertWithinBudget();
+    result = task(current, assertWithinBudget);
+    assertWithinBudget();
   } catch (error) {
     taskError = error;
   }
@@ -455,15 +482,18 @@ function withPublicationLock(cfg, operations, task) {
     if (taskError) {
       throw new Error(`${firstLine(taskError)}; ${releaseReason}`);
     }
-    throw new Error(releaseReason);
+    throw new Error(
+      `${completedMessage}; ${releaseReason}; remove the coordination record before the next publication`
+    );
   }
 
   if (taskError) throw taskError;
   return result;
 }
 
-function preflightUnderLock(cfg, entry, write) {
+function preflightUnderLock(cfg, entry, write, assertWithinBudget) {
   try {
+    assertWithinBudget();
     writeProviderValue(cfg, entry.id, entry.value, write);
   } catch (error) {
     throw new Error(
@@ -482,8 +512,12 @@ function preflightUnderLock(cfg, entry, write) {
  */
 export function preflightAwsBootstrap(cfg, operations = {}) {
   const write = operations.write ?? writeSecret;
-  return withPublicationLock(cfg, operations, entry =>
-    preflightUnderLock(cfg, entry, write)
+  return withPublicationLock(
+    cfg,
+    operations,
+    (entry, assertWithinBudget) =>
+      preflightUnderLock(cfg, entry, write, assertWithinBudget),
+    "preflight completed"
   );
 }
 
@@ -496,12 +530,20 @@ export function preflightAwsBootstrap(cfg, operations = {}) {
  * @param {Function} write Provider writer.
  * @returns {string} Human-readable rollback outcome with no secret material.
  */
-function rollback(cfg, previous, candidateRaw, fetch, write) {
+function rollback(
+  cfg,
+  previous,
+  candidateRaw,
+  fetch,
+  write,
+  assertWithinBudget
+) {
   try {
     const current = currentEntry(cfg, fetch);
     if (current.value !== candidateRaw) {
       return "rollback skipped because the provider changed after this publication";
     }
+    assertWithinBudget();
     writeProviderValue(cfg, previous.id, previous.value, write);
     const restored = currentEntry(cfg, fetch);
     if (restored.value !== previous.value) {
@@ -528,47 +570,56 @@ export function publishAwsBootstrap(raw, cfg, operations = {}) {
   const write = operations.write ?? writeSecret;
   const verify = operations.verify ?? verifyAwsBootstrap;
   const candidate = validateAwsBootstrap(raw);
-  return withPublicationLock(cfg, operations, previous => {
-    preflightUnderLock(cfg, previous, write);
-
-    // Verify before the write. A candidate that cannot assume one of its roles
-    // never becomes the value every new remote session receives.
-    verify(candidate);
-
-    if (candidate.raw === previous.value) {
-      return {
-        changed: false,
-        profiles: candidate.profiles.map(profile => profile.name),
-      };
-    }
+  return withPublicationLock(
+    cfg,
+    operations,
+    (previous, assertWithinBudget) => {
+      preflightUnderLock(cfg, previous, write, assertWithinBudget);
+
+      // Verify before the write. A candidate that cannot assume one of its roles
+      // never becomes the value every new remote session receives.
+      verify(candidate);
+      assertWithinBudget();
+
+      if (candidate.raw === previous.value) {
+        return {
+          changed: false,
+          profiles: candidate.profiles.map(profile => profile.name),
+        };
+      }
 
-    try {
-      writeProviderValue(cfg, previous.id, candidate.raw, write);
-      const stored = currentEntry(cfg, fetch);
-      if (stored.value !== candidate.raw) {
+      try {
+        assertWithinBudget();
+        writeProviderValue(cfg, previous.id, candidate.raw, write);
+        const stored = currentEntry(cfg, fetch);
+        if (stored.value !== candidate.raw) {
+          throw new Error(
+            "provider read-back did not match the candidate exactly"
+          );
+        }
+        const storedCandidate = validateAwsBootstrap(stored.value);
+        verify(storedCandidate);
+        assertWithinBudget();
+        return {
+          changed: true,
+          profiles: storedCandidate.profiles.map(profile => profile.name),
+        };
+      } catch (error) {
+        const rollbackOutcome = rollback(
+          cfg,
+          previous,
+          candidate.raw,
+          fetch,
+          write,
+          assertWithinBudget
+        );
         throw new Error(
-          "provider read-back did not match the candidate exactly"
+          `${BOOTSTRAP_KEY} publication failed: ${firstLine(error)}; ${rollbackOutcome}`
         );
       }
-      const storedCandidate = validateAwsBootstrap(stored.value);
-      verify(storedCandidate);
-      return {
-        changed: true,
-        profiles: storedCandidate.profiles.map(profile => profile.name),
-      };
-    } catch (error) {
-      const rollbackOutcome = rollback(
-        cfg,
-        previous,
-        candidate.raw,
-        fetch,
-        write
-      );
-      throw new Error(
-        `${BOOTSTRAP_KEY} publication failed: ${firstLine(error)}; ${rollbackOutcome}`
-      );
-    }
-  });
+    },
+    "publication completed"
+  );
 }
 
 /** Read a candidate from stdin without ever placing it in argv. */

package/plugins/lisa/.codex-plugin/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/rules/reference/config-resolution.md

@@ -352,7 +352,7 @@ When `github.projects.v2` is present, later setup/doctor and writer preflight va
 |-------|---------------|-------|
 | `linear.workspace` | `tracker = "linear"`, `source = "linear"`, or any `linear-*` skill is invoked | Linear workspace slug (e.g. `acme`). |
 | `linear.teamKey` | `tracker = "linear"` | Linear team key (e.g. `ENG`). The team owns the destination Issues. For source mode, projects are workspace-scoped or team-scoped per the URL passed. |
-| `linear.workflow` | `tracker = "linear"` | Workflow **state** name per build lifecycle role — the Linear analogue of `jira.workflow`, not of `github.labels`. Defaults `{ ready: "Ready", claimed: "In Progress", review: "In Review", blocked: "Blocked", done: { dev: "On Dev", staging: "On Stg", production: "Done" } }`. **`ready` is a dedicated state, never the team's default** — see below. Resolve and verify with `/lisa:setup:linear`. |
+| `linear.workflow` | `tracker = "linear"` | Workflow **state** name per build lifecycle role — the Linear analogue of `jira.workflow`, not of `github.labels`. Defaults `{ ready: "Ready", claimed: "In Progress", blocked: "Blocked", done: { dev: "On Dev", staging: "On Stg", production: "Done" } }` — **no `review` key**, because it is optional and a default would be materialized into the project's config by `lisa sync`. **`ready` is a dedicated state, never the team's default** — see below. Resolve and verify with `/lisa:setup:linear`. |
 | `linear.labels` | `tracker = "linear"` or `source = "linear"` | **Markers and the PRD lane only.** `build.human_needed` (default `human-needed`) and the `prd.*` map. The build lifecycle does **not** live here — see `linear.workflow`. |
 
 ##### Why Linear uses states, not labels
@@ -439,13 +439,40 @@ Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`,
 |---|---|---|---|---|
 | `ready` | Human signal "this is buildable; agent may claim" | `Ready` (status) | `Ready` (state) | `status:ready` (label) |
 | `claimed` | Agent has picked the item up | `In Progress` (status) | `In Progress` (state) | `status:in-progress` (label) |
-| `review` | Optional post-build review hold, when a tracker/project still uses one | `Code Review` (status) | `In Review` (state) | no default review label |
+| `review` | Optional post-build review hold, when a tracker/project still uses one | **no default** | **no default** | **no default** |
 | `blocked` | Agent stopped on triage ambiguities or external blocker | `Blocked` (status) | `Blocked` (state) | `status:blocked` (label) |
 | `done` | Terminal state for this work, **env-keyed** | map of env → status | map of env → state | map of env → label |
 
 **JIRA and Linear resolve roles to native workflow statuses/states** (`jira.workflow`, `linear.workflow`); **GitHub resolves them to labels** (`github.labels.build`) because GitHub Issues has no workflow-state field at all. A role transition is therefore a *state move* on JIRA and Linear, and a *label swap* on GitHub. Skills operate on roles and never hardcode either form.
 
-`review` is optional. GitHub build intake skips it by default and moves successful builds directly from `claimed` to the configured `done` label. Linear and JIRA projects that still use a post-build review hold can configure `review`; projects that keep the ticket in `claimed` until terminal can omit it and lifecycle skills will skip the intermediate transition.
+### R1 — an absent OPTIONAL role means SKIP, never a default
+
+`ready`, `claimed`, `blocked` and `done` are **required**; omitting one is a setup defect and a skill must say so. `review`, the `qa.*` roles and `human_needed` are **optional and carry no built-in default on any vendor**. Omitting one means the project does not run that step, and every lifecycle skill skips the transition — the item simply stays in its current role.
+
+A default on an optional role breaks this twice over. Vendor default maps are `defaultValue`s in `sync/registry`, so `lisa sync` **materializes** them into a project's `.lisa.config.json` — a project that deliberately omitted `review` finds it written back in. And as a resolution fallback, a default makes "unset" indistinguishable from "not customized", so no project can express *"we have no agent review step."*
+
+Measured downstream: a project bound no `review` role — its policy was that a PR-open ticket stays in `claimed` until it reaches an environment — and agents moved two issues into a human-only review state regardless, because every layer that could have honoured the omission supplied a default instead.
+
+GitHub has always been correct here (`BUILD_LABEL_DEFAULTS` seeds no `review`), and `lisa-jira-evidence/scripts/post-evidence.sh` has always implemented it correctly (`REVIEW=""`, explicit skip branch). The default maps for JIRA and Linear now agree with them.
+
+### R2 — a fallback may inform a READ, never supply a WRITE target
+
+Where a vendor exposes a fallback for a missing role — Linear resolves states by `type`, since Linear states carry one — it may be used to *read*. It must **never** supply a value to write.
+
+Such a fallback selects by **board position**, not intent. On a board carrying more than one plausible state it returns whichever sits earliest, and the states that surface that way are precisely the human-only lanes a project kept out of its config on purpose. Measured on one board: with `blocked` and `claimed` already bound, the lowest-position unbound `started` state was a human-only review lane, and that is exactly where two issues landed.
+
+`ready` has no fallback at all, in either direction — see below.
+
+### The single resolver
+
+Every skill resolves roles through `${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs`, never an inlined `read_role()` helper. Twelve skills previously inlined one and produced **eleven distinct implementations**; that copy-paste is what let the vendors drift apart on R1.
+
+```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 → configured. Exit `0` with **empty** output → an optional role is unset; skip the transition. Exit `2` → a required role is unset, or a write was refused a fallback value.
 
 **`ready` must never resolve to the team's DEFAULT state.** `Todo` is where Linear puts a brand-new issue, so using it for `ready` inverts the gate: the lane stops meaning "a human flipped this to build-ready" and starts meaning "nobody has touched this". Measured on the first team migrated: 20 issues in the lane, only 8 ever explicitly marked ready. JIRA avoids this because `jira.workflow.ready` is a dedicated `Ready` status while a fresh ticket lands in the project default.
 

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