@codyswann/lisa 4.22.6 → 4.22.8

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

@@ -16,14 +16,25 @@ Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.loca
 
 Callers (planning skills, lifecycle skills) invoke this skill at:
 
-| Milestone | What to post |
-|-----------|--------------|
-| Plan created | Plan contents (sections + ordered tasks) as a comment, suggest transition `Backlog → Ready` (state: `Ready`) |
-| Implementation in progress | Branch URL + first commit, suggest transition `Ready → In Progress` (state: `In Progress`) |
-| PR ready for review | PR URL + summary, the implementation handoff comment, suggest transition `In Progress → In Review` (state: `In Review`) |
-| PR merged | Merge SHA + deploy environment (if known), suggest transition `In Review → Done` (state: `Done`), **then run Phase 4b — mandatory when the merge target is a non-terminal env branch** |
+| Milestone | What to post | Suggested role |
+|-----------|--------------|----------------|
+| Plan created | Plan contents (sections + ordered tasks) as a comment | `ready` |
+| Implementation in progress | Branch URL + first commit | `claimed` |
+| PR ready for review | PR URL + summary, the implementation handoff comment | `review` — **optional; omitted by most projects, in which case there is no transition to suggest** |
+| PR merged | Merge SHA + deploy environment (if known) | env-keyed `done`, **then run Phase 4b — mandatory when the merge target is a non-terminal env branch** |
+
+**Roles, never literal state names.** Resolve each through the shared resolver; the state names above are whatever the project configured, and a role the project did not configure has no suggestion at all:
+
+```bash
+resolve() {
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+    --role "$1" --vendor linear --intent read 2>/dev/null
+}
+```
+
+**This skill SUGGESTS transitions. It never writes the lane.** That matches `lisa-jira-sync` ("suggest, but don't automatically perform") and `lisa-github-sync` ("this skill never relabels"), and it is what this skill's own dispatcher already advertises: `lisa-tracker-sync`'s description reads *"Suggests (never auto-transitions) the next status."* Lane writes belong to the build-intake / agent owner, which is already true on the other two trackers.
 
-This skill **suggests** transitions and applies them to the native Linear `state` field when the caller asks — the build queue is keyed off states, so the state IS the lane. Without `--update-state` it only suggests; an unasked-for transition remains a human / triage decision.
+`--rollup` is the one exception and is documented in Phase 4b — parent derivation is its entire purpose and is separately gated.
 
 ## Input
 
@@ -82,20 +93,24 @@ When `$ARGUMENTS` includes `pr_url=<url>` for `pr-ready` or `pr-merged`, ensure
 
 The PR branch/title/body identifier is the PR -> Linear side. This phase is the required Linear -> PR side.
 
-## Phase 4 — Update Workflow State (when caller requests)
+## Phase 4 — Suggest the Next State (never write it)
+
+Name the suggested next state in the milestone comment and stop. **This skill does not set `stateId`.** The lane write belongs to `lisa-linear-build-intake` / `lisa-linear-agent`, exactly as the `status:*` write belongs to `lisa-github-build-intake` on GitHub.
 
-If the caller passes `--update-state`, set the Issue's `stateId` via `lisa-linear-access operation: save-issue`:
+Resolve the suggestion by role, and **say nothing when the role is unset**:
 
-- `plan-created` → set state `Ready`
-- `implementation-in-progress` → set state `In Progress`
-- `pr-ready` → set state `In Review`
-- `pr-merged` → set state `Done`
+| Milestone | Role to resolve | When the role is unset |
+|---|---|---|
+| `plan-created` | `ready` | required — report a setup defect |
+| `implementation-in-progress` | `claimed` | required — report a setup defect |
+| `pr-ready` | `review` | **optional — suggest no transition; the Issue stays in `claimed`** |
+| `pr-merged` | `done` for the PR's target env (via `deploy.branches`) | required — report a setup defect |
 
-If the requested STATE doesn't exist on the team, that is a setup defect — report it and point at `/lisa:setup:linear`. Never create a workflow state here: a state carries a `type` and a board position, and guessing either puts the Issue somewhere no human sanctioned.
+If a resolved state doesn't exist on the team, that is a setup defect — report it and point at `/lisa:setup:linear`. Never create a workflow state here: a state carries a `type` and a board position, and guessing either puts the Issue somewhere no human sanctioned. Equally, never *find* one: resolving a role by scanning the team for a state whose name or `type` looks right picks by board position, not intent, and the states that surface that way are the human-only lanes a project deliberately left out of its config.
 
-No single-lane verification is needed: an Issue holds exactly one workflow state by construction, so the two-lanes-at-once corruption the old label-driven lane could produce is unrepresentable. (It was not hypothetical — 16 issues carried two `status:*` labels at the time of the migration.)
+> **Removed: `--update-state`.** This flag previously let a caller make Phase 4 write the state. It was the only lane-write path in any sync skill, and combined with a defaulted `review` role it moved Issues into review states that projects had never configured. Callers that relied on it should let the build-intake owner make the transition; `--rollup` is unaffected.
 
-Without `--update-state`, this skill posts the comment only and does NOT touch the Issue's state.
+No single-lane verification is needed: an Issue holds exactly one workflow state by construction, so the two-lanes-at-once corruption the old label-driven lane could produce is unrepresentable. (It was not hypothetical — 16 issues carried two `status:*` labels at the time of the migration.)
 
 ## Phase 4b — Reconcile Native Auto-Close (Linear-specific)
 
@@ -116,13 +131,13 @@ When the caller passes `--rollup`, this skill **derives a parent/container's wor
 
 **Resolve the child set the same way `lisa-linear-read-issue` does** — `lisa-linear-access operation: list-issues({project: <id>})` for a Project's Issues, or `lisa-linear-access operation: get-issue` per child for an Issue's sub-Issues (via `parentId`). Capture each child's workflow state. If the item has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
 
-**Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the Linear env-keyed `done` map, e.g. `On Dev < On Stg < Done`) and take the first match** (canonical roles from `config-resolution`; the Linear state map is `Blocked`, `In Progress`, `In Review`, env-keyed `done`):
+**Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the Linear env-keyed `done` map) and take the first match** (canonical roles from `config-resolution`; the Linear state map is the configured `blocked`, `claimed`, optional `review`, and env-keyed `done` — resolve each by role, and treat an unset `review` as simply having no such rung):
 
 | If among the required child leaves… | Derived parent role | Linear state |
 |---|---|---|
 | any child carries `Blocked` | `blocked` | `Blocked` |
 | else **every** required child has shipped to some env (each at a `done`-map state, e.g. `On Dev`/`On Stg`/`Done`) | `done[min-env]` | the **least-advanced** env state among them (all `On Stg` → `On Stg`; mixed dev+staging → `On Dev`; all production → `Done`) |
-| else any child has **started** (`In Progress` / `In Review`, or shipped to an env while a sibling has not) | `claimed` | `In Progress` |
+| else any child has **started** (at the `claimed` state, at the `review` state where the project configures one, or shipped to an env while a sibling has not) | `claimed` | the configured `claimed` state |
 | else (children exist, none started) | — | unchanged — parent keeps its non-ready container state |
 
 - **Blocked dominates** — one blocked child surfaces `Blocked` on the parent even while siblings progress. It never says *which* child or *which kind* of hold; run `scripts/rollup-blocker-classification.mjs` over the resolved child graph and carry its per-class report — blocking leaf, path, and who must act — into the rollup note. A non-zero exit means it classified nothing; that is a failure to report, never an all-clear. See `leaf-only-lifecycle` → **Classifying a hold**.
@@ -131,13 +146,14 @@ When the caller passes `--rollup`, this skill **derives a parent/container's wor
 - **Recursive** — a Project reaches an env only when its Issues have themselves rolled up to at least that env. Evaluate bottom-up.
 - **Never roll a parent into the `ready` state** — `ready` is leaf-only. Rollup only moves the parent between non-ready container states.
 
-**Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to the single `Done` state, the only env rung is production, and the lifecycle is `Ready → In Progress → In Review → Done` with **no** dev/staging promotion hops; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to the intermediate env states (`On Dev`/`On Stg`).
+**Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to the single `Done` state, the only env rung is production, and the lifecycle is `ready → claimed → done` with **no** dev/staging promotion hops and no configured `review` rung; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to the intermediate env states.
 
 **Apply the derived state** via `lisa-linear-access operation: save-issue` (Project or Issue), setting the parent's `stateId` to the derived role. Post an idempotent rollup comment naming the derived state and the child tally. Because the terminal `done` state is itself typed `completed`, a parent rolled to terminal is natively closed by the same write — there is no second closure step. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's state untouched.
 
 ## Rules
 
-- Never transition the Issue's workflow `state` unless the caller explicitly asks (`--update-state`, or `--rollup` for parent derivation per the `leaf-only-lifecycle` rule). Without a flag this skill only SUGGESTS a transition in its comment. The state is the lifecycle lane now, so an unrequested write here would move the item in the build queue.
+- Never transition a leaf Issue's workflow `state` from this skill at all. `--rollup` (parent derivation, per the `leaf-only-lifecycle` rule) is the only write path that remains; every other milestone SUGGESTS a transition in its comment and nothing more. The state is the lifecycle lane, so a write here would move the item in the build queue.
+- Never resolve a role by searching the team's states. Only a name the project configured may be written; a `type`- or position-derived match may inform a read and must never supply a write target (`config-resolution`, R2).
 - Rollup derives a *parent's* workflow state from its children and never rolls a parent into the human-owned ready lane (never `$READY`). It cites the `leaf-only-lifecycle` rule by slug rather than restating the state machine.
 - Never post empty or minimal comments — if a milestone has no meaningful content, skip the post.
 - Do not delete prior milestone comments. They are the audit trail.

package/plugins/lisa-agy/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-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.22.6",
+  "version": "4.22.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.22.6",
+  "version": "4.22.8",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.22.6",
+  "version": "4.22.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.22.6",
+  "version": "4.22.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.22.6",
+  "version": "4.22.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/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-copilot/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-copilot/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-copilot/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-copilot/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")