@codyswann/lisa 2.189.7 → 2.189.8

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

@@ -0,0 +1,346 @@
+---
+name: lisa-linear-build-intake
+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 the first eligible Issue by relabeling to the configured `claimed` label, runs the implementation/build flow via lisa-linear-agent, relabels to the configured `done` label on completion, then exits. Enforces the claim-time arm of the `leaf-only-lifecycle` rule: a parent/container with open child work (or a childless Epic) that still carries a stale build-ready label is skipped or safe-blocked with a lifecycle-repair comment, never claimed. 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"]
+---
+
+# Linear Build Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+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. The first eligible ready Issue is claimed, built via the `lisa-linear-agent` flow, relabeled to the configured `done` label on completion, then the cycle exits. Remaining ready Issues stay queued for later scheduler invocations.
+
+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 until terminal completion; at the true terminal `done` value, the `leaf-only-lifecycle` rule requires native closure by moving the Issue to a configured Done / Completed workflow state when one exists.
+
+## Configuration
+
+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 and dispatch the first eligible Issue through `lisa-linear-agent`, transition a successful build to `$DONE`, write the summary, and exit. The caller (a human or a cron) has already authorized the run by invoking the skill.
+
+Specifically forbidden:
+
+- Previewing projected scope (Issue count, projected PR count, build duration) and asking whether to continue.
+- Offering A/B/C-style choices like "proceed / skip a few / dry-run only" — the documented behavior IS the default.
+- Pausing because the queue is large, items look complex, or items are likely to be `status:blocked` by `lisa-linear-agent`'s pre-flight gate. The pre-flight `status:blocked` outcome is a valid terminal state of the per-Issue lifecycle.
+- Pausing because the build flow looks expensive.
+
+The only legitimate reasons to stop early:
+
+- Missing team key or required configuration. Surface and exit.
+- 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
+ready → claimed → review → done(env-keyed) (downstream)
+(human/PM)    (us claim)    (us PR ready)    (us build done)
+```
+
+(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 `$READY`, `$CLAIMED`, and the relevant `$DONE` variants exist on the team via `lisa-linear-access operation: list-issue-labels`. If `$READY` is missing, stop and report adoption needed. The other labels can be created on demand.
+
+## Phases
+
+### Phase 1 — Resolve scope
+
+1. Parse `$ARGUMENTS`:
+   - Bare team key → use as-is.
+   - Literal `linear` → fall back to `linear.teamKey` from config.
+2. Resolve team ID via `lisa-linear-access operation: list-teams({query: <teamKey>})`.
+
+### Phase 2 — Find ready Issues
+
+Query: `lisa-linear-access operation: list-issues({team: <teamId>, label: "$READY"})`.
+
+Capture each Issue's: identifier, title, type label, priority, assignee, project, labels, description summary.
+
+> **No query-time repo pre-filter here (by design).** Unlike `lisa-jira-build-intake`, which narrows its JQL with `AND (labels = "repo:<current>" OR labels IS EMPTY)` (the query-time arm of `repo-scope-split`), the Linear `list_issues` label filter is an AND-of-labels and cannot express "current-repo **or** unlabeled" in one query. Adding `repo:<current>` to this query would strand unlabeled Issues the determine + stamp path must see. So the Linear scanner keeps this query broad and relies on the per-candidate 3a.0 gate below for repo scoping.
+
+If empty, report `"No Linear Issues labeled $READY. Nothing to do."` and exit. Common idle case.
+
+### Phase 3 — Process the first eligible ready Issue
+
+#### 3a.0 Repo-scope gate (claim only current-repo Issues)
+
+A Linear team can oversee multiple repos (`frontend` / `backend` / `infrastructure`). This skill claims only Issues for the repo it is running in. Run this gate **before** the leaf-only gate (3a) and the claim (3b), per the `repo-scope-split` rule's "Claim-time repo scoping" section (cite it by slug; do not restate its decision table).
+
+1. **Resolve the current repo** per `config-resolution` "Repo scoping" (`.repo` → `.github.repo` → `git remote get-url origin` basename). If unresolvable, stop and report.
+2. **Cheap path first.** Prefer candidates already carrying the `repo:<current>` label. Keep the Phase 2 scan broad so unlabeled Issues are still seen, determined, and stamped.
+3. **Per candidate, apply the repo-scope decision (`repo-scope-split`):**
+   - Carries `repo:<other>` → **skip** (leave it `ready` for that repo's own intake); next candidate.
+   - **Unlabeled** → determine the target repo(s) from the Issue + code surfaces, then **stamp** `repo:<name>` via `lisa-linear-access operation: save-issue` (resolve/create the label via `list_issue_labels`/`create_issue_label`) so later cycles filter cheaply; re-apply with the now-known repo.
+   - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
+   - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
+4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the ready set is exhausted — exit cleanly with `"No ready Issues for repo <current>. Nothing to do."`.
+
+#### 3a. Leaf-only claim gate (skip / safe-block containers)
+
+Build intake claims **only independently implementable leaf work units**. This enforces the claim-time arm of the vendor-neutral `leaf-only-lifecycle` rule: a parent/container that still carries a stale build-ready label (e.g. `status:ready` applied before this rule existed, or hand-applied to a Project-grouped parent Issue) is **never claimed** — intake skips it or safe-blocks it with a clear lifecycle-repair message. It is the claim-time complement to the write-time labeling in `lisa-linear-write-issue` and the validate-time S15 gate in `lisa-linear-validate-issue`; all three cite the same rule so the classification never drifts. **Never silently implement a container.**
+
+Run this gate **before** the claim relabel, starting with the oldest/highest-priority ready candidate. Do NOT relabel, comment "Claimed", or invoke `lisa-linear-agent` for an Issue that fails the gate.
+
+**Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an Issue is a **container** if it has **open** child work, whatever its declared type; otherwise the **type label** decides. Resolve child work using the same hierarchy `lisa-linear-read-issue` uses — Linear's native parentage: an Issue groups **sub-issues** via `parentId`, and a **Project** (the Epic equivalent) groups Issues via `projectId`. Relations (`save_issue_relation` — `blocks` / `is blocked by`) express dependencies and are **not** parentage — do not count them as children.
+
+Fetch the Issue's sub-issues via `lisa-linear-access operation: get-issue` (which returns the children) or `lisa-linear-access operation: list-issues({parentId: <issueId>})`, then count those still open (Linear `state.type` not in the completed/canceled set):
+
+```text
+# Children of <issueId>: native sub-issues via parentId.
+# Count children whose Linear state.type is NOT terminal ("completed" / "canceled").
+# A parent whose children are all completed is no longer holding open work and
+# rolls up via leaf-only-lifecycle's rollup, not here.
+OPEN_CHILDREN = count(list_issues({parentId: <issueId>})
+                       where state.type not in {"completed", "canceled"})
+```
+
+For a Project-level parent (an Issue that itself anchors a `projectId` grouping rather than a `parentId` tree), resolve membership the same way `lisa-linear-read-issue` does and treat the parent as a container if any grouped Issue is still open. If sub-issue resolution is unavailable, fall back to the parentage `lisa-linear-read-issue` derives and treat the Issue as a container if any derived child is open. Note "sub-issues unavailable — parentage derived" so the operator knows how children were resolved.
+
+Classify and act (first match wins). The type comes from the Issue's `type:` label (`type:Epic`, `type:Story`, `type:Spike`, `type:Bug`, `type:Task`, `type:Sub-task`, `type:Improvement`):
+
+| Condition | Class | Action |
+|---|---|---|
+| `OPEN_CHILDREN > 0` (open child work, any type) | **Container** | **Skip / safe-block — do NOT claim** |
+| no open children AND type = Epic (a Linear Project) | **Childless Epic/Project (pure rollup container)** | **Skip / safe-block — do NOT claim** |
+| no open children AND type ≠ Epic (Bug, Task, Sub-task, Improvement, Story, Spike, or no `type:` label) | **Leaf work unit** | **Proceed to 3b claim** |
+
+The childless-parent exception promotes every childless type **except Epic** to a claimable leaf: a childless Story is a directly shippable increment and a childless Spike *is* the investigation unit, so neither is stranded. Only a childless **Epic** (a Linear Project) stays unclaimed — it is a pure rollup container by design, and a childless one is an incomplete decomposition or a mis-applied role, never an implementable unit.
+
+**Safe-block (default action for a flagged container).** Leave the build-ready label in place (don't silently strip it — that hides the lifecycle error), post a single lifecycle-repair comment, record the Issue under "Skipped (container)" in the summary, and end the cycle. Do NOT relabel to `$CLAIMED`. Keep the comment idempotent — skip posting if an identical `[claude-build-intake]` lifecycle-repair comment already exists on the Issue, so a re-entrant cycle doesn't spam it.
+
+Post via `lisa-linear-access operation: save-comment` with:
+
+```text
+[claude-build-intake] Not claimed: this Issue carries the build-ready label ($READY) but is a container with open child work (or a childless Epic), which violates the leaf-only-lifecycle rule. Build-ready (status:ready) is leaf-only per leaf-only-lifecycle — an agent claims and implements leaves, never a container. Repair: move $READY off this parent onto its leaf children (or, for a childless Epic, decompose it into leaf children or reclassify it to a leaf type). A parent's lifecycle state rolls up from its children and is never set to ready directly.
+```
+
+This gate never blocks a legitimate flat Task/Bug: those have no open children and a leaf `type:`, so they fall straight through to the claim in 3b.
+
+#### 3b. Claim
+
+Update labels via `lisa-linear-access operation: save-issue`: remove `$READY`, add `$CLAIMED`. Resolve label IDs via `list_issue_labels` (create `$CLAIMED` if missing).
+
+**Assign to the authenticated user when the Issue is unassigned.** A claim must be attributable. If the Issue has no assignee, set its `assigneeId` to the authenticated viewer (resolve the viewer's id via the Linear MCP identity — e.g. `get_user` for the current actor) through `lisa-linear-access operation: save-issue`. Leave an already-assigned Issue's assignee untouched — never reassign work that already has an owner.
+
+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: $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.**
+
+#### 3c. Return or run the build delegation
+
+After the claim succeeds, the per-Issue build must run under `lisa-linear-agent` (the per-Issue lifecycle agent), but a teammate running this skill must not spawn that named peer itself. Claude teams are flat: only the lead can add a named teammate. Therefore:
+
+- If you are the team lead/root agent, spawn or invoke `lisa-linear-agent` with the Issue identifier and wait for its structured result.
+- If you are a teammate, stop this skill's direct work and return a structured `delegation-request` to the lead instead of calling `Agent` with `name` or otherwise spawning `linear-agent` as a named peer.
+- A private anonymous helper is allowed only when the helper is not a roster peer and the `Agent` call omits `name`; it must not replace this `linear-agent` delegation.
+
+Return this payload shape to the lead:
+
+```json
+{
+  "type": "delegation-request",
+  "agent": "linear-agent",
+  "workItem": "<ISSUE-ID>",
+  "context": {
+    "claimedLabel": "$CLAIMED",
+    "doneResolution": "Resolve $DONE from the PR base branch per this skill's Workflow resolution section"
+  },
+  "onSuccess": "Confirm the returned PR is merged, then apply Phase 3d and Phase 3d.1",
+  "onBlockedOrError": "Leave the Issue where linear-agent left it and record the surfaced outcome"
+}
+```
+
+`lisa-linear-agent` owns:
+- Reading the full Issue graph (`lisa-linear-read-issue`)
+- Running its own pre-flight quality gate (`lisa-linear-verify`)
+- Running ticket triage (`lisa-ticket-triage`)
+- Routing to the appropriate flow (Build / Fix / Investigate / Improve based on type)
+- Posting progress comments via `lisa-linear-sync`
+- Posting evidence via `lisa-linear-evidence`
+
+The lead waits for `lisa-linear-agent` to return, then resumes this scanner with the returned outcome:
+- **Success** — the build flow completed and a PR exists; evidence posted. The PR may already be **merged** or still **open** (auto-merge enabled, awaiting checks/merge). "Success" means the build work is sound — it does **not** assert the change reached an environment. The env transition in 3d gates on the PR actually being merged; an open PR does not advance the Issue to a `done` env 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.
+- **Duplicate already fixed** — `lisa-linear-agent` / `lisa-ticket-triage` returned `DUPLICATE_ALREADY_FIXED` with a canonical Issue reference and empirical base-branch evidence. Post the triage finding, ensure the native `duplicates <canonical>` relationship exists when Linear exposes it (otherwise leave an explicit relation/comment reference), apply the terminal `$DONE` label, move the native Issue to the configured canceled-as-duplicate or completed terminal state, and do not open a PR. If the canonical fix is merged but not yet on the production branch, the close comment must say the production error can recur until the canonical Issue promotes and that recurrence is tracked by the canonical Issue; do not reopen this duplicate for that recurrence.
+- **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.1 Close duplicate already fixed
+
+Run this only when the returned triage verdict is exactly `DUPLICATE_ALREADY_FIXED`.
+
+1. Verify the structured result includes a canonical Issue reference, the canonical PR/commit, and empirical evidence that the canonical fix is present on the base branch. If any piece is missing, treat the outcome as Held instead of closing.
+2. Post or preserve the triage-finding comment that explains why this Issue is a duplicate and names the canonical Issue.
+3. Ensure a native `duplicates <canonical>` relationship exists when Linear exposes one; if this workspace cannot create that relationship, leave an explicit relation/comment reference and record the limitation in the summary.
+4. Resolve the terminal `$DONE` value exactly as in Phase 3d. For env-keyed workflows, duplicate closeout uses the production/final done label, not an intermediate `status:on-dev`/`status:on-stg` waypoint.
+5. Update labels by removing `$CLAIMED` and adding terminal `$DONE`, then move the native Linear state to the configured canceled-as-duplicate state. If no duplicate/canceled state is configured, use the configured terminal completed state only when that is the project's duplicate-close convention; otherwise record setup as an Error rather than inventing a state.
+6. Post a close comment naming the canonical Issue, PR/commit, and base-branch evidence.
+
+If the canonical fix is merged but not yet present on the production branch, append the production-promotion caveat to the close comment: the production error can recur until the canonical Issue promotes, and recurrence is tracked by the canonical Issue rather than by reopening this duplicate.
+
+This path is distinct from `BLOCKED`: ambiguity, open blockers, and duplicate-of-open findings remain held for human action and must not be auto-closed.
+
+#### 3d. Relabel to $DONE (only after the PR is merged)
+
+A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) asserts that the code has actually reached that environment. Never set it for a PR that is merely open: auto-merge can be blocked indefinitely (a required rebase / `BEHIND` branch, failing checks, an unaddressed review), and the change may never land. Relabeling an Issue `status:on-stg` on an open PR makes it *claim* a deploy that never happened. Transition only after confirming the PR merged.
+
+If `lisa-linear-agent` returned Success:
+1. **Confirm the PR merged.** Read the live state of the Issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before relabeling; a still-running deploy is treated like an open PR (leave at `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the Issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it at `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or change the native state.
+   - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the Issue at `$CLAIMED`.
+2. 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.
+3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
+   - If `linear.labels.build.done` is a string, that string is terminal.
+   - If `linear.labels.build.done` is an object, only the production/final environment value is terminal (default: `status:done`). Intermediate env values such as `status:on-dev` and `status:on-stg` are not terminal and must keep the native Issue open.
+   - If the project uses a different final environment name, resolve it from the configured deployment topology; if ambiguous, record an Error and do not change the native state.
+4. Update labels via `lisa-linear-access operation: save-issue`: remove `$CLAIMED` (or `$REVIEW` if `lisa-linear-evidence` already moved it forward), add `$DONE`.
+5. If `$DONE` is terminal, move the native Linear Issue state to the configured Done / Completed state. Resolve that state from project configuration if present; otherwise inspect the team workflow for a terminal state with `state.type = "completed"` and a name such as `Done` or `Completed`. If no terminal state can be resolved, record an Error and leave the labels as the source of truth — do not invent a state name.
+6. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL> merged. Transitioned to $DONE."` Include whether native closure was applied, already satisfied, skipped for an intermediate env, or unavailable for setup reasons.
+
+For any non-Success outcome, do NOT transition. The Issue sits where the agent left it — humans take it from there.
+
+#### 3d.1 Roll up the parent chain (forward rollup)
+
+Run this **only after a successful `$DONE` transition in 3d**. This is the **forward** arm of the `leaf-only-lifecycle` rule's *"rollup is evaluated whenever a child transitions"* requirement: a leaf reaching `$DONE` may complete its parent Issue, which may in turn complete its Project. Without this step a fully-built parent stays open until the recovery `lisa-repair-intake` cron happens to run.
+
+1. Resolve the Issue's parent using the same hierarchy `lisa-linear-read-issue` uses — native parentage: a sub-issue's `parentId`, and Project membership via `projectId` for the Epic-equivalent. If the Issue has no parent, skip — nothing to roll up.
+2. Walk **up the ancestor chain bottom-up** (sub-issue → parent Issue → Project): for each ancestor invoke `lisa-linear-sync <ANCESTOR-ID> --rollup`. That skill derives the ancestor's `status:*` from its children per `leaf-only-lifecycle`, applies it via `lisa-linear-access operation: save-issue` only when it differs (never `status:ready`), and moves the native Linear `state` to the configured Done / Completed state when the derived env is the terminal `$DONE`. It is idempotent and safe-defaults (suggests, does not guess) when the rolled state is ambiguous.
+3. Stop walking up when an ancestor has no parent, or when `--rollup` reports no change. Record each rolled-up ancestor and its derived state in the summary.
+
+This does not re-implement the state machine — it delegates to `lisa-linear-sync --rollup`, the single rollup implementation `lisa-repair-intake` also uses, so the forward and recovery paths can never drift. Children closed **outside** this flow are not observed here; `lisa-repair-intake` remains the recovery net for those.
+
+#### 3e. Stop
+
+Stop immediately after the first claimed, skipped, blocked, held, or errored Issue. Later scheduler invocations process the remaining ready Issues.
+
+### Phase 4 — Summary report
+
+```text
+## linear-build-intake summary
+
+Team: <teamKey>
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+Issues processed: <n>
+- $DONE (build complete, PR merged): <n>
+  - <ID> <title> → PR <URL>
+- PR open — awaiting merge (left at $CLAIMED for repair-intake): <n>
+  - <ID> <title> → PR <URL> (mergeStateStatus: <state>)
+- Skipped (container — leaf-only-lifecycle): <n>
+  - <ID> <title> — build-ready on a parent with open child work; lifecycle-repair comment posted
+- Duplicate already fixed (closed as duplicate): <n>
+  - <ID> <title> — duplicate of <canonical>; no PR opened
+- status:blocked (pre-flight verify failed): <n>
+  - <ID> <title> — see Issue comments
+- Held (triage found ambiguities): <n>
+  - <ID> <title> — see Issue comments
+- Errors: <n>
+  - <ID> <title> — <reason>
+
+Total PRs opened: <n>
+```
+
+## Idempotency & safety
+
+- **Leaf-only claim gate runs first**: Phase 3a classifies each candidate before any claim; a container with open child work (or a childless Epic) is skipped/safe-blocked, never claimed (the `leaf-only-lifecycle` rule's claim-time arm). The safe-block comment is idempotent — a re-entrant cycle does not re-post it.
+- **Claim-first ordering**: `$CLAIMED` set BEFORE agent invocation — no double-pickup.
+- **No writes outside the lifecycle**: this skill only adds/removes `$READY`, `$CLAIMED`, `$DONE`, plus terminal-only native state completion required by `leaf-only-lifecycle`. Every other label change (and non-terminal native state change) is owned by the agent or `lisa-linear-evidence`.
+- **Duplicate terminal exception**: `DUPLICATE_ALREADY_FIXED` is the only triage outcome that may close a claimed Issue without a PR from this cycle. It must include a canonical Issue reference and empirical base-branch evidence, and it closes through the configured duplicate/canceled terminal path rather than as completed build work.
+- **Terminal native closure**: after the `$DONE` label is applied, move the Linear Issue to a native completed state only when `$DONE` is the true terminal done value; intermediate env labels stay open / active.
+- **One item per cycle**: per-Issue exceptions are caught and recorded, then the cycle exits. The scheduler owns retrying or moving on to the next ready item.
+- **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 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). 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
+
+- **Claim leaves only.** Per the `leaf-only-lifecycle` rule, never claim a container — an Issue with open child work, or a childless Epic — even if it carries the build-ready label. Skip or safe-block it (Phase 3a); never silently implement a container.
+- 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 `$DONE`. Downstream labels are owned by QA / product / a future verification-intake skill.
+- Never move the native Linear state to Done / Completed for intermediate env states (`status:on-dev`, `status:on-stg`, or configured equivalents). Native completion happens only at the terminal `done` value.
+- 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/lisa/skills/lisa-linear-build-intake/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Build Intake"
+short_description: "Symmetric counterpart to lisa-jira-build-intake on the Linear side"
+default_prompt:
+  - "Use $lisa-linear-build-intake: Symmetric counterpart to lisa-jira-build-intake on the Linear side."

package/plugins/lisa/skills/lisa-linear-create/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: lisa-linear-create
+description: "Creates Linear Projects (Epic-equivalent), Issues (Story / Task / Bug / Spike), and sub-Issues (Sub-task) from code files or descriptions. Analyzes the input, determines the appropriate hierarchy, and creates items with comprehensive quality requirements including test-first development and Validation Journey. The Linear counterpart of lisa-jira-create — delegates every write to lisa-linear-write-issue."
+allowed-tools: ["Read", "Glob", "LS", "Skill"]
+---
+
+# Create Linear Work Items from $ARGUMENTS
+
+Analyze the provided file(s) and plan a Linear hierarchy. **This skill plans structure only — every individual write is delegated to `lisa-linear-write-issue`.** Do not call `lisa-linear-access operation: save-project` or `lisa-linear-access operation: save-issue` from this skill; those write tools are intentionally not in `allowed-tools`.
+
+This skill is the destination of the `lisa-tracker-create` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Process
+
+1. **Analyze**: Read `$ARGUMENTS` to understand scope.
+2. **Extract source artifacts**: invoke `lisa-tracker-source-artifacts`, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke `lisa-product-walkthrough` to capture current behavior, design-vs-product divergence, and reuse candidates. Skip when the work is purely backend or affects a screen that does not yet exist.
+4. **Determine structure**:
+   - Project (Epic) needed if: multiple features, major changes, >3 related files
+   - Direct Issues if: bug fix, single file, minor change
+5. **Plan hierarchy**:
+   ```text
+   Project (Epic) → Issue (Story) → sub-Issue (Sub-task)
+   ```
+   Mapping per Linear best practices: Epic → Linear Project, Story → Issue with `projectId`, Sub-task → Issue with `parentId`. See `config-resolution.md` "Linear destination semantics".
+6. **Delegate every write to `lisa-linear-write-issue`** in dependency order (Project first, then Issues with `projectId` set, then sub-Issues with `parentId`). Pass artifacts (filtered by domain per `lisa-tracker-source-artifacts` inheritance rules) and walkthrough findings (under `## Current Product`).
+7. **Run the artifact preservation gate** (`lisa-tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created items. Fail loudly if anything was dropped.
+
+## Mandatory for Every Code Issue
+
+- **Test-First**: Write tests before implementation
+- **Quality Gates**: All tests / checks must pass, no SonarCloud violations
+- **Documentation**: Check existing, update / create new, remove obsolete
+- **Cleanup**: Remove temporary code, scripts, dev configs
+
+## Validation Journey
+
+Items that change runtime behavior should include a `## Validation Journey` section. This section is consumed by `lisa-linear-journey` to automate verification.
+
+### When to Include
+
+- API endpoint changes (new, modified, or removed routes)
+- Database schema changes (migrations, new columns, index changes)
+- Background job / queue processing changes
+- Library / utility function changes that affect exports
+- Security fixes (authentication, authorization, input validation)
+- Performance-critical changes requiring measurement
+
+### When to Skip
+
+- Documentation-only changes
+- Config-only changes (env vars, CI/CD, feature flags with no code)
+- Type-definition-only changes
+
+### How to Write
+
+Design the journey based on the **change type**. Place `[EVIDENCE: name]` markers at key verification points.
+
+```markdown
+## Validation Journey
+
+### Prerequisites
+- Local dev server running
+- Database accessible
+- Required environment variables set
+
+### Steps
+1. Verify the current state before changes
+2. Apply the change (run migration, deploy, etc.)
+3. Verify the expected new state [EVIDENCE: state-after-change]
+4. Test error/edge cases [EVIDENCE: error-handling]
+5. Verify rollback or cleanup if applicable [EVIDENCE: rollback-check]
+
+### Assertions
+- Describe what must be true after verification
+- Each assertion is verified against the captured evidence
+```
+
+## Source Artifacts
+
+If `$ARGUMENTS` includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as attachments / remote links on the created items. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke `lisa-tracker-source-artifacts`** for the canonical rules: domains, per-tool classification, source precedence, conflict handling under `## Open Questions`, inheritance from Project → Issue → sub-Issue, and the existing-component reuse expectation. Do not restate the rules here — invoke the skill so any rule change propagates uniformly.
+
+When delegating actual writes to `lisa-linear-write-issue`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke `lisa-product-walkthrough` before drafting items. The walkthrough findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the item plan and surface under `## Current Product` on the resulting items. Skip only when the work is purely backend or affects a screen that does not yet exist.
+
+## Item Requirements
+
+Each item must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default team: from `linear.teamKey` config (override via arguments).
+
+## Delegation to linear-write-issue
+
+**Mandatory.** Every item created by this skill MUST go through `lisa-linear-write-issue`. This skill never performs Linear save operations itself — those tools are intentionally excluded from `allowed-tools` so the gate cannot be bypassed.
+
+`lisa-linear-write-issue` enforces:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Project parent for Stories; parentId for Sub-tasks
+- Explicit relationship discovery (`blocks` / `blocked_by` / `relates_to` / `duplicates`)
+- Remote links / attachments
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+### Invocation order
+
+Items must be created in parent-before-child order so each child can be passed its parent ID:
+
+1. Invoke `lisa-linear-write-issue` for the Epic (Project). Capture the returned Project ID.
+2. For each Story, invoke `lisa-linear-write-issue` with the Project ID as `parent_project_id`. Capture each Issue identifier.
+3. For each Sub-task, invoke `lisa-linear-write-issue` with the Story Issue ID as `parent_issue_id`.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, team key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent ID (Project for Stories; Story for Sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules
+- For items that change runtime behavior: the Validation Journey draft (or instruct it to call `lisa-linear-add-journey` after create)
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's a Project vs. Issue vs. sub-Issue)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent IDs through subsequent writes
+- Running the Phase 5.5-style preservation check after all writes complete
+
+It does not own the actual Linear write — that's `lisa-linear-write-issue`'s job.

package/plugins/lisa/skills/lisa-linear-create/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Create"
+short_description: "Creates Linear Projects (Epic-equivalent), Issues (Story / Task / Bug / Spike), and sub-Issues (Sub-task) from code files or descriptions"
+default_prompt:
+  - "Use $lisa-linear-create: Creates Linear Projects (Epic-equivalent), Issues (Story / Task / Bug / Spike), and sub-Issues (Sub-task) from code files or descriptions."

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

@@ -0,0 +1,103 @@
+---
+name: lisa-linear-evidence
+description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from the configured `claimed` label to the configured `review` label. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa-jira-evidence and lisa-github-evidence."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Linear Evidence: $ARGUMENTS
+
+Post verification evidence to a Linear Issue and transition it from the configured `claimed` build label to the configured `review` build label. This skill is the destination of the `lisa-tracker-evidence` shim when `tracker = "linear"`.
+
+`$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`, and `linear.labels.build.*` from `.lisa.config.json` (with `.local` override).
+
+## Inputs (in `<evidence-dir>`)
+
+The caller must produce:
+
+- `evidence/comment.txt` — the human-readable comment body posted on the Linear Issue.
+- `evidence/code-blocks.md` — fenced code blocks (test outputs, command output, log excerpts) appended to the comment.
+- `evidence/files/` (optional) — any text files that should be uploaded to the GitHub `pr-assets` release for permalink-style references.
+
+If any of these are missing, stop and report.
+
+## Phase 1 — Resolve Linear Issue
+
+1. Parse the identifier from `$ARGUMENTS`.
+2. Fetch via `lisa-linear-access operation: get-issue` to confirm it exists and capture its current state, label set, and Project membership.
+
+## Phase 2 — Upload Evidence Files (optional)
+
+If `evidence/files/` is non-empty, upload each text file to the GitHub `pr-assets` release on the current repo via `gh release upload`. The release is the permalink store — keeps the Linear comment lightweight while preserving large outputs.
+
+For each uploaded file, capture the public release URL.
+
+## Phase 3 — Update PR Description
+
+If a PR is open on the current branch (`gh pr view --json url,number,body 2>/dev/null`), append an "Evidence" section to its description with:
+
+- The Linear identifier and URL (constructed as `https://linear.app/<workspace>/issue/<IDENTIFIER>`).
+- Links to any uploaded evidence files.
+- A short summary line (first 2 lines of `evidence/comment.txt`).
+
+If no PR is open, skip this phase.
+
+## Phase 4 — Post Linear Comment
+
+Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <body>})` where `<body>` is:
+
+```markdown
+[<comment.txt contents verbatim>]
+
+<details>
+<summary>Evidence</summary>
+
+[<code-blocks.md contents verbatim>]
+
+</details>
+
+[<bullet list of uploaded evidence file URLs, if any>]
+```
+
+Linear comments support markdown including `<details>` collapsibles, fenced code, and links — preserve the formatting.
+
+## Phase 5 — Transition Status
+
+Update labels via `lisa-linear-access operation: save-issue` to remove `$CLAIMED` and add `$REVIEW`. Resolve label IDs first via `lisa-linear-access operation: list-issue-labels` (create the label via `create_issue_label` if it doesn't exist on the team).
+
+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.
+
+## Phase 6 — Report
+
+Return:
+
+- Linear Issue URL with new label state
+- PR URL (if updated)
+- List of uploaded evidence file URLs
+
+## 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 the configured `linear.labels.build.*` labels; an item that ships without transitioning is invisible to monitoring.
+- If `lisa-linear-access operation: 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.

package/plugins/lisa/skills/lisa-linear-evidence/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Evidence"
+short_description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with…"
+default_prompt:
+  - "Use $lisa-linear-evidence: Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with…."