@codyswann/lisa 2.21.1 → 2.23.1

package/plugins/src/base/skills/jira-write-ticket/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: jira-write-ticket
 description: "Creates or updates a JIRA ticket following organizational best practices. Enforces description quality (coding assistant / developer / stakeholder sections), Gherkin acceptance criteria, epic parent relationship, explicit link discovery (blocks / is blocked by / relates to / duplicates / clones), remote links (PRs, Confluence, dashboards), labels, components, fix version, priority, story points, and Validation Journey. Rejects thin tickets — use this skill any time a ticket is created or significantly edited."
-allowed-tools: ["Bash", "Skill", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__createJiraIssue", "mcp__atlassian__editJiraIssue", "mcp__atlassian__createIssueLink", "mcp__atlassian__getIssueLinkTypes", "mcp__atlassian__addCommentToJiraIssue", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+allowed-tools: ["Bash", "Skill"]
 ---
 
 # Write JIRA Ticket: $ARGUMENTS
 
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
 Create or update a JIRA ticket with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin tickets are rejected.
 
 Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
@@ -17,7 +19,7 @@ Determine from $ARGUMENTS and context whether this is a CREATE or UPDATE:
 - **CREATE**: no existing ticket key provided
 - **UPDATE**: ticket key provided — call `/jira-read-ticket <KEY>` first to load the full current state before editing. Never overwrite without reading.
 
-Resolve cloud ID via `mcp__atlassian__getAccessibleAtlassianResources`.
+Resolve the active Atlassian site via `lisa:atlassian-access` `operation: list-sites` (the access skill enforces connection match against `.lisa.config.json`).
 
 ## Phase 2 — Gather Required Inputs
 
@@ -25,7 +27,7 @@ Required fields (stop and ask if missing — do not invent values):
 
 | Field | Required For | Notes |
 |-------|--------------|-------|
-| Project key | CREATE | Call `getVisibleJiraProjects` if unknown |
+| Project key | CREATE | Resolve from `.lisa.config.json` (`jira.project`); ask the human if not configured |
 | Issue type | CREATE | Story, Task, Bug, Epic, Spike, Sub-task, Improvement |
 | Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
 | Description | CREATE, UPDATE | Multi-section — see Phase 3 |
@@ -39,7 +41,7 @@ Required fields (stop and ask if missing — do not invent values):
 
 Optional but recommended: assignee, components, fix versions, labels, sprint, story points, reporter.
 
-Use `mcp__atlassian__getJiraProjectIssueTypesMetadata` to verify the issue type exists in the project and discover required custom fields.
+Issue-type validity and required custom fields are enforced by `lisa:jira-validate-ticket`'s F1 / F4 gates (which run via `lisa:atlassian-access` under the hood). If you need to inspect the metadata directly, request a new operation in `atlassian-access` rather than calling MCP / acli yourself.
 
 ## Phase 3 — Description Quality
 
@@ -110,7 +112,7 @@ If the ticket is not a Bug and not an Epic, it MUST have an epic parent:
    ```jql
    project = <PROJECT> AND issuetype = Epic AND statusCategory != Done
    ```
-   via `mcp__atlassian__searchJiraIssuesUsingJql`. Match on keywords from the summary and description.
+   via `lisa:atlassian-access` `operation: search-issues jql: "<query>"`. Match on keywords from the summary and description.
 3. If no epic matches, stop and ask the human to create or pick one. Do NOT orphan the ticket.
 
 ### 4b. Related Tickets
@@ -184,7 +186,7 @@ For UI-touching tickets, include the existing-component reuse expectation per `l
 
 If the ticket modifies an existing user-facing surface, a `lisa:product-walkthrough` should already have been run upstream (by `lisa:notion-to-tracker` Phase 2b or `lisa:jira-create`). Inherit its findings under a `## Current Product` subsection in the ticket description so the implementer sees what's shipped today before changing it. If the upstream skill skipped the walkthrough but this ticket clearly modifies an existing surface, invoke `lisa:product-walkthrough` here before proceeding.
 
-Use Jira's web UI or `mcp__atlassian__editJiraIssue` to set the `Development` field / remote links where supported.
+Use Jira's web UI or `lisa:atlassian-access` `operation: write-ticket` (UPDATE form) to set the `Development` field / remote links where supported.
 
 ## Phase 5 — Set Metadata
 
@@ -207,7 +209,7 @@ The validator is the **single source of truth** for what makes a valid ticket. T
 If the validator reports `FAIL`:
 - Surface the failure list and the per-gate remediation to the user.
 - Do NOT proceed to Phase 6. Fix the spec (or stop and ask the human) and re-run validation.
-- Never call `mcp__atlassian__createJiraIssue` or `mcp__atlassian__editJiraIssue` while the validator's verdict is FAIL.
+- Never invoke `lisa:atlassian-access` with `operation: write-ticket` while the validator's verdict is FAIL.
 
 If the validator reports `PASS`, continue to Phase 6.
 
@@ -215,16 +217,16 @@ If the validator reports `PASS`, continue to Phase 6.
 
 ### CREATE
 
-1. Call `mcp__atlassian__createJiraIssue` with all Phase 2/3/5 fields and the epic parent from Phase 4a.
+1. Invoke `lisa:atlassian-access` via the Skill tool with `operation: write-ticket payload: {...}` containing all Phase 2/3/5 fields and the epic parent from Phase 4a (CREATE form — no existing key).
 2. Capture the returned ticket key.
-3. For each relationship from Phase 4b, call `mcp__atlassian__createIssueLink` with the correct link type (verify names via `mcp__atlassian__getIssueLinkTypes` if unsure).
-4. Attach remote links from Phase 4c.
+3. For each relationship from Phase 4b, invoke `lisa:atlassian-access` with `operation: link from: <K1> to: <K2> type: "<link-type>"`. Use the exact link-type names supported by the project; surface errors if an unknown type is passed.
+4. Attach remote links from Phase 4c (via `lisa:atlassian-access` `operation: write-ticket` UPDATE form or whatever remote-link operation is dispatched).
 5. If the ticket changes runtime behavior, invoke the `lisa:jira-add-journey` skill to append the Validation Journey section.
 
 ### UPDATE
 
-1. Call `mcp__atlassian__editJiraIssue` with only the fields being changed. Do NOT resend fields that weren't in the change set — it blows away history.
-2. Add new relationships via `mcp__atlassian__createIssueLink`. Existing links are not touched unless explicitly removed.
+1. Invoke `lisa:atlassian-access` with `operation: write-ticket payload: {key: <K>, ...fields-being-changed}`. Do NOT resend fields that weren't in the change set — it blows away history.
+2. Add new relationships via `lisa:atlassian-access` `operation: link from: <K1> to: <K2> type: "<link-type>"`. Existing links are not touched unless explicitly removed.
 3. If description changes, preserve sections you are not editing. Re-read via `/jira-read-ticket` first.
 
 ## Phase 7 — Verify
@@ -233,7 +235,7 @@ Call the `lisa:jira-verify` skill on the resulting ticket. `lisa:jira-verify` fe
 
 ## Phase 8 — Announce
 
-Post a creation comment via `mcp__atlassian__addCommentToJiraIssue` with:
+Post a creation comment via `lisa:atlassian-access` `operation: comment key: <K> body: "..."` with:
 - `[{repo}]` prefix if the ticket is repo-scoped
 - Who the ticket is assigned to (if known)
 - The relationships that were set (`blocks`, `is blocked by`, `relates to`) with links
@@ -249,5 +251,5 @@ Skip this step only on UPDATE when no material change was made.
 - Never include a runtime-behavior ticket without a target backend environment, and never include an authenticated-surface ticket without sign-in credentials in the description.
 - Never invent custom field values. If the project requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
-- All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:jira-create`) should delegate here rather than calling the MCP write tools directly.
+- All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:jira-create`) should delegate here rather than invoking `lisa:atlassian-access` write operations directly.
 - The gate logic (what makes a valid ticket) lives in `lisa:jira-validate-ticket`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:jira-verify` post-write). When a gate needs to change, change it in `lisa:jira-validate-ticket` — every caller (write path, dry-run path, post-write verify) picks it up automatically.

package/plugins/src/base/skills/linear-add-journey/SKILL.md

@@ -83,6 +83,7 @@ Linear descriptions are markdown. Use `##` and `###` headings — not Jira wiki
 4. **Evidence names in kebab-case** — `api-response`, `schema-check`, `rate-limit-hit`.
 5. **Assertions are measurable** — "Returns 200 with `{status: ok}`" not "API works correctly".
 6. **Cover happy path and error path** — At minimum, one success and one failure evidence marker.
+7. **On a leaf work unit, the markers are binding** — For a Bug / Task / Sub-task / Improvement, every `[EVIDENCE: name]` here is the item's evidence manifest: validation gate S14 requires at least one, and the item cannot be closed until each named artifact is captured and attached (see the "Per-Work-Unit Evidence Contract" in the `verification` rule). Name only evidence you intend to capture — and name all of it.
 
 ### Step 6: Present to User for Approval
 

package/plugins/src/base/skills/linear-build-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: linear-build-intake
-description: "Symmetric counterpart to lisa:jira-build-intake on the Linear side. Scans a Linear team for Issues labeled status:ready, claims each by relabeling to status:in-progress, runs the implementation/build flow via lisa:linear-agent, and relabels to status:on-dev on completion. status:ready is the human-flipped signal that an Issue is truly ready for development — mirroring how Notion PRDs work Draft → Ready → (us) In Review → Blocked|Ticketed."
+description: "Symmetric counterpart to lisa:jira-build-intake on the Linear side. Scans a Linear team for Issues carrying the configured `ready` build label, claims each by relabeling to the configured `claimed` label, runs the implementation/build flow via lisa:linear-agent, and relabels to the configured `done` label on completion. The `ready` label is the human-flipped signal that an Issue is truly ready for development — mirroring how Notion PRDs work Draft → Ready → (us) In Review → Blocked|Ticketed."
 allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_teams", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label"]
 ---
 
@@ -8,25 +8,78 @@ allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_teams", "mcp__linear-
 
 `$ARGUMENTS` is one of:
 
-1. A Linear team key (e.g. `ENG`) — scans that team for `status:ready` Issues.
+1. A Linear team key (e.g. `ENG`) — scans that team for ready Issues.
 2. The literal token `linear` — falls back to `linear.teamKey` from `.lisa.config.json`.
 3. A pre-built Linear MCP filter (advanced) — used as-is.
 
-Run one build-intake cycle. Each `status:ready` Issue is claimed, built via the `lisa:linear-agent` flow, and relabeled to `status:on-dev` on completion. The cycle is the symmetric mirror of `lisa:jira-build-intake` and `lisa:github-build-intake`: humans flip `status:ready`, agents pick up and progress.
+Run one build-intake cycle. Each ready Issue is claimed, built via the `lisa:linear-agent` flow, and relabeled to the configured `done` label on completion. The cycle is the symmetric mirror of `lisa:jira-build-intake` and `lisa:github-build-intake`: humans flip the `ready` label, agents pick up and progress.
 
 This skill is the destination of the `lisa:tracker-build-intake` shim when `tracker = "linear"`.
 
+## Workflow resolution
+
+Build-queue label names are read from `.lisa.config.json` `linear.labels.build.*`, falling back to defaults documented in the `config-resolution` rule. Bash pattern:
+
+```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.build.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".linear.labels.build.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+
+READY=$(read_role ready "status:ready")
+CLAIMED=$(read_role claimed "status:in-progress")
+REVIEW=$(read_role review "status:code-review")
+```
+
+For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
+
+1. Explicit caller arg (`target_env=staging`) wins.
+2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup).
+3. If `done` is a **string** in config, use it directly regardless of env.
+4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+
+```bash
+TARGET_ENV="${target_env:-}"
+if [ -z "$TARGET_ENV" ] && [ -n "$PR_BASE_BRANCH" ]; then
+  TARGET_ENV=$(jq -r --arg b "$PR_BASE_BRANCH" \
+    '.deploy.branches // {} | to_entries[] | select(.value == $b) | .key' \
+    .lisa.config.json 2>/dev/null | head -1)
+fi
+
+DONE_TYPE=$(jq -r '.linear.labels.build.done | type' .lisa.config.json 2>/dev/null)
+if [ "$DONE_TYPE" = "string" ]; then
+  DONE=$(jq -r '.linear.labels.build.done' .lisa.config.json)
+elif [ "$DONE_TYPE" = "object" ]; then
+  [ -z "$TARGET_ENV" ] && { echo "ERROR: linear.labels.build.done is env-keyed but env not resolvable"; exit 1; }
+  DONE=$(jq -r --arg e "$TARGET_ENV" '.linear.labels.build.done[$e] // empty' .lisa.config.json)
+  [ -z "$DONE" ] && { echo "ERROR: linear.labels.build.done has no entry for env '$TARGET_ENV'"; exit 1; }
+else
+  case "$TARGET_ENV" in
+    dev) DONE="status:on-dev" ;;
+    staging) DONE="status:on-stg" ;;
+    production) DONE="status:done" ;;
+    *) echo "ERROR: cannot resolve done label without env"; exit 1 ;;
+  esac
+fi
+```
+
+In prose below, the role names refer to the resolved labels: e.g. "the `ready` label" means whatever `linear.labels.build.ready` resolves to (default: `status:ready`).
+
 ## Why labels, not native states
 
 Linear's per-team workflow state names vary (`Todo` / `Backlog` / `Up Next` / etc.). Labels are workspace-scoped or team-scoped and stable across teams, so we drive the build queue off labels rather than chasing renamed native states. The native `state` field is informational only for this skill.
 
 ## Configuration
 
-Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+Reads `linear.workspace`, `linear.teamKey`, and `linear.labels.build.*` from `.lisa.config.json` (with `.local` override).
 
 ## Confirmation policy
 
-Do NOT ask the caller whether to proceed. Once invoked with a team key, run the cycle to completion — claim, dispatch each Issue through `lisa:linear-agent`, transition successful builds to `status:on-dev`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill.
+Do NOT ask the caller whether to proceed. Once invoked with a team key, run the cycle to completion — claim, dispatch each Issue through `lisa:linear-agent`, transition successful builds to `$DONE`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill.
 
 Specifically forbidden:
 
@@ -38,21 +91,23 @@ Specifically forbidden:
 The only legitimate reasons to stop early:
 
 - Missing team key or required configuration. Surface and exit.
-- Label convention not yet adopted (`status:ready` does not exist on the team's labels). Surface and exit with an Adoption hint.
-- Empty `status:ready` set. Exit cleanly with `"No Linear Issues labeled status:ready. Nothing to do."`
+- Label convention not yet adopted (the `ready` label does not exist on the team's labels). Surface and exit with an Adoption hint.
+- Empty ready set. Exit cleanly with `"No Linear Issues labeled $READY. Nothing to do."`
 
 ## Lifecycle assumed
 
 Linear build queue uses these issue-level labels:
 
 ```text
-status:ready → status:in-progress → status:code-review → status:on-dev → status:done
-(human/PM)    (us claim)            (us PR ready)        (us build done)  (downstream)
+ready → claimed → review → done(env-keyed) (downstream)
+(human/PM)    (us claim)    (us PR ready)    (us build done)
 ```
 
-This skill ONLY transitions `status:ready → status:in-progress` on claim, and `status:in-progress → status:on-dev` on completion. It never touches `status:done`, `status:code-review` (owned by `lisa:linear-agent` / `lisa:linear-evidence`), or `status:blocked` (owned by `lisa:linear-agent`'s pre-flight gate).
+(Defaults: `status:ready` / `status:in-progress` / `status:code-review` / `status:on-dev`/`status:on-stg`/`status:done`.)
+
+This skill ONLY transitions `$READY → $CLAIMED` on claim, and `$CLAIMED → $DONE` on completion. It never touches `status:done`-as-terminal, `$REVIEW` (owned by `lisa:linear-agent` / `lisa:linear-evidence`), or `status:blocked` (owned by `lisa:linear-agent`'s pre-flight gate).
 
-**Pre-flight check**: at start of each cycle, confirm `status:ready`, `status:in-progress`, `status:on-dev` exist on the team via `mcp__linear-server__list_issue_labels`. If `status:ready` is missing, stop and report adoption needed. The other labels can be created on demand.
+**Pre-flight check**: at start of each cycle, confirm `$READY`, `$CLAIMED`, and the relevant `$DONE` variants exist on the team via `mcp__linear-server__list_issue_labels`. If `$READY` is missing, stop and report adoption needed. The other labels can be created on demand.
 
 ## Phases
 
@@ -63,23 +118,23 @@ This skill ONLY transitions `status:ready → status:in-progress` on claim, and
    - Literal `linear` → fall back to `linear.teamKey` from config.
 2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
 
-### Phase 2 — Find Ready Issues
+### Phase 2 — Find ready Issues
 
-Query: `mcp__linear-server__list_issues({team: <teamId>, label: "status:ready"})`.
+Query: `mcp__linear-server__list_issues({team: <teamId>, label: "$READY"})`.
 
 Capture each Issue's: identifier, title, type label, priority, assignee, project, labels, description summary.
 
-If empty, report `"No Linear Issues labeled status:ready. Nothing to do."` and exit. Common idle case.
+If empty, report `"No Linear Issues labeled $READY. Nothing to do."` and exit. Common idle case.
 
-### Phase 3 — Process each Ready Issue (serial)
+### Phase 3 — Process each ready Issue (serial)
 
 #### 3a. Claim
 
-Update labels via `mcp__linear-server__save_issue`: remove `status:ready`, add `status:in-progress`. Resolve label IDs via `list_issue_labels` (create `status:in-progress` if missing).
+Update labels via `mcp__linear-server__save_issue`: remove `$READY`, add `$CLAIMED`. Resolve label IDs via `list_issue_labels` (create `$CLAIMED` if missing).
 
 Post a `[claude-build-intake]` comment via `save_comment`: `"Claimed by Claude. Starting build."`
 
-This is the idempotency lock — a re-entrant cycle's `label: status:ready` filter will not see this Issue again.
+This is the idempotency lock — a re-entrant cycle's `label: $READY` filter will not see this Issue again.
 
 If the relabel fails (permission, race), record under "Errors" and skip. **Do not invoke the build flow on an Issue you didn't successfully claim.**
 
@@ -96,20 +151,21 @@ Invoke `lisa:linear-agent` (per-Issue lifecycle agent) with the Issue identifier
 Wait for the agent to return. Capture its outcome:
 - **Success** — PR is ready (open or merged); evidence posted; ready for next status.
 - **Blocked by linear-verify pre-flight gate** — `lisa:linear-agent` itself relabels to `status:blocked` and assigns to creator. Let it stand. Record and move on.
-- **Blocked by ticket-triage ambiguities** — agent posts findings and stops. The Issue stays at `status:in-progress`. Surface to human; do not auto-transition. Record under "Errors".
-- **Errored** — exception, missing config, etc. Leave at `status:in-progress`. Record with exception summary.
+- **Blocked by ticket-triage ambiguities** — agent posts findings and stops. The Issue stays at `$CLAIMED`. Surface to human; do not auto-transition. Record under "Errors".
+- **Errored** — exception, missing config, etc. Leave at `$CLAIMED`. Record with exception summary.
 
-#### 3c. Relabel to status:on-dev (only on Success)
+#### 3c. Relabel to $DONE (only on Success)
 
 If `lisa:linear-agent` returned Success:
-1. Update labels via `mcp__linear-server__save_issue`: remove `status:in-progress`, add `status:on-dev`. (Note: at this point `lisa:linear-evidence` has typically already moved the Issue to `status:code-review` after PR creation. The transition is `status:code-review → status:on-dev` if that's the current state.)
-2. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. Transitioned to status:on-dev."`
+1. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Update labels via `mcp__linear-server__save_issue`: remove `$CLAIMED` (or `$REVIEW` if `lisa:linear-evidence` already moved it forward), add `$DONE`.
+3. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. Transitioned to $DONE."`
 
 For any non-Success outcome, do NOT transition. The Issue sits where the agent left it — humans take it from there.
 
 #### 3d. Continue
 
-Move to the next Ready Issue. One Issue failing does not stop others.
+Move to the next ready Issue. One Issue failing does not stop others.
 
 ### Phase 4 — Summary report
 
@@ -121,7 +177,7 @@ Cycle started: <ISO timestamp>
 Cycle completed: <ISO timestamp>
 
 Issues processed: <n>
-- status:on-dev (build complete, PR ready): <n>
+- $DONE (build complete, PR ready): <n>
   - <ID> <title> → PR <URL>
 - status:blocked (pre-flight verify failed): <n>
   - <ID> <title> — see Issue comments
@@ -135,26 +191,28 @@ Total PRs opened: <n>
 
 ## Idempotency & safety
 
-- **Claim-first ordering**: `status:in-progress` set BEFORE agent invocation — no double-pickup.
-- **No writes outside the lifecycle**: this skill only adds/removes `status:ready`, `status:in-progress`, `status:on-dev`. Every other label change (and the native state) is owned by the agent or `lisa:linear-evidence`.
+- **Claim-first ordering**: `$CLAIMED` set BEFORE agent invocation — no double-pickup.
+- **No writes outside the lifecycle**: this skill only adds/removes `$READY`, `$CLAIMED`, `$DONE`. Every other label change (and the native state) is owned by the agent or `lisa:linear-evidence`.
 - **Failure isolation**: per-Issue exceptions caught and recorded; the cycle continues.
 - **Single cycle per team**: do not run two concurrent cycles against the same team — concurrent claims could race.
 - **Single-label invariant**: after every transition, verify exactly one `status:*` label is present. Two simultaneously breaks the build queue.
+- **Never pick an arbitrary env for `$DONE`**. If `done` is a map and env is ambiguous, fail loudly.
 
 ## Adoption (one-time per team)
 
-Before this skill can run against a Linear team, the team must adopt the `status:*` issue-label convention:
+Before this skill can run against a Linear team, the team must adopt the build-queue label convention. Using the defaults:
 
-1. Create labels `status:ready`, `status:in-progress`, `status:code-review`, `status:on-dev`, `status:done`, `status:blocked` on the team (or workspace).
-2. Apply `status:ready` to Issues that are ready for development.
-3. Reserve `status:in-progress`, `status:code-review`, `status:on-dev` for Lisa — humans should not set them manually except to recover from an error.
+1. Create labels `status:ready`, `status:in-progress`, `status:code-review`, `status:on-dev`, `status:done`, `status:blocked` on the team (or workspace). If your project overrides any `linear.labels.build.*` role name in config, substitute the actual label names you configured.
+2. Apply the `$READY` label to Issues that are ready for development.
+3. Reserve `$CLAIMED`, `$REVIEW`, `$DONE` for Lisa — humans should not set them manually except to recover from an error.
 
 If the team hasn't adopted these labels, the first run exits with an adoption hint.
 
 ## Rules
 
-- Never relabel an Issue the cycle didn't claim. The `status:in-progress` transition is the signature of cycle ownership.
+- Never relabel an Issue the cycle didn't claim. The `$CLAIMED` transition is the signature of cycle ownership.
 - Never bypass `lisa:linear-agent` to do build work directly. The agent owns the per-Issue lifecycle.
-- Never auto-transition past `status:on-dev`. Downstream labels (`status:done`) are owned by QA / product / a future verification-intake skill.
+- Never auto-transition past `$DONE`. Downstream labels are owned by QA / product / a future verification-intake skill.
 - If the Issue has no Validation Journey or no sign-in credentials in its description, `lisa:linear-agent`'s pre-flight verify will catch it and relabel to `status:blocked` — don't try to fix the Issue from here.
 - On any unexpected response from `lisa:linear-agent` (label it doesn't claim, missing PR URL on success, etc.), record as Error and surface — never assume.
+- Never pick an arbitrary env for `$DONE` resolution. If `done` is a map and env is ambiguous, fail loudly.

package/plugins/src/base/skills/linear-evidence/SKILL.md

@@ -1,18 +1,35 @@
 ---
 name: linear-evidence
-description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from in-progress to code-review by relabeling. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa:jira-evidence and lisa:github-evidence."
+description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from the configured `claimed` label to the configured `review` label. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa:jira-evidence and lisa:github-evidence."
 allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label"]
 ---
 
 # Linear Evidence: $ARGUMENTS
 
-Post verification evidence to a Linear Issue and transition it to the code-review state. This skill is the destination of the `lisa:tracker-evidence` shim when `tracker = "linear"`.
+Post verification evidence to a Linear Issue and transition it from the configured `claimed` build label to the configured `review` build label. This skill is the destination of the `lisa:tracker-evidence` shim when `tracker = "linear"`.
 
 `$ARGUMENTS` is the Linear Issue identifier (e.g. `ENG-123`) and the path to the evidence directory. Caller passes both: `<IDENTIFIER> <evidence-dir>`.
 
+## Workflow resolution
+
+The `claimed` and `review` build labels are read from `.lisa.config.json` `linear.labels.build.*`, falling back to the defaults documented in the `config-resolution` rule (`status:in-progress` and `status:code-review`).
+
+```bash
+read_role() {
+  local role="$1" default="$2"
+  local local_v global_v
+  local_v=$(jq -r ".linear.labels.build.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".linear.labels.build.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+
+CLAIMED=$(read_role claimed "status:in-progress")
+REVIEW=$(read_role review "status:code-review")
+```
+
 ## Configuration
 
-Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+Reads `linear.workspace`, `linear.teamKey`, and `linear.labels.build.*` from `.lisa.config.json` (with `.local` override).
 
 ## Inputs (in `<evidence-dir>`)
 
@@ -66,7 +83,7 @@ Linear comments support markdown including `<details>` collapsibles, fenced code
 
 ## Phase 5 — Transition Status
 
-Update labels via `mcp__linear-server__save_issue` to remove `status:in-progress` and add `status:code-review`. Resolve label IDs first via `mcp__linear-server__list_issue_labels` (create the label via `create_issue_label` if it doesn't exist on the team).
+Update labels via `mcp__linear-server__save_issue` to remove `$CLAIMED` and add `$REVIEW`. Resolve label IDs first via `mcp__linear-server__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.
 
@@ -81,6 +98,6 @@ Return:
 ## Rules
 
 - Never modify the Issue description as part of evidence posting — comments only. Description edits go through `lisa:linear-write-issue`.
-- Never skip the label transition. The build queue is keyed off `status:*` labels; an item that ships without transitioning is invisible to monitoring.
+- Never skip the label transition. The build queue is keyed off the configured `linear.labels.build.*` labels; an item that ships without transitioning is invisible to monitoring.
 - If `mcp__linear-server__save_comment` fails, retry once. If it fails again, surface the error — don't pretend the comment was posted.
 - Do not delete prior comments. The history is the audit trail.