@codyswann/lisa 2.119.1 → 2.121.1

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

@@ -0,0 +1,283 @@
+---
+name: 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/Story/Spike) 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", "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"]
+---
+
+# 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 `mcp__linear-server__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 `mcp__linear-server__list_teams({query: <teamKey>})`.
+
+### Phase 2 — Find ready Issues
+
+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 $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 `mcp__linear-server__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 `mcp__linear-server__get_issue` (which returns the children) or `mcp__linear-server__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, Story, Spike} | **Childless container-type** | **Skip / safe-block — do NOT claim** |
+| no open children AND type ∈ {Bug, Task, Sub-task, Improvement} (or no `type:` label) | **Leaf work unit** | **Proceed to 3b claim** |
+
+The childless-parent exception is narrow: childlessness enables a claim **only** for types that are leaf work units to begin with. A childless Epic/Story/Spike is an incomplete decomposition, not an implementable unit — it is never claimed.
+
+**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 `mcp__linear-server__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/Story/Spike), 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/Story/Spike, 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 `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: $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. Run the build flow
+
+Invoke `lisa:linear-agent` (per-Issue lifecycle agent) with the Issue identifier. `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`
+
+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 `$CLAIMED`. Surface to human; do not auto-transition. Record under "Errors".
+- **Errored** — exception, missing config, etc. Leave at `$CLAIMED`. Record with exception summary.
+
+#### 3d. Relabel to $DONE (only on Success)
+
+If `lisa:linear-agent` returned Success:
+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. 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.
+3. Update labels via `mcp__linear-server__save_issue`: remove `$CLAIMED` (or `$REVIEW` if `lisa:linear-evidence` already moved it forward), add `$DONE`.
+4. 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.
+5. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. 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.
+
+#### 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 ready): <n>
+  - <ID> <title> → PR <URL>
+- Skipped (container — leaf-only-lifecycle): <n>
+  - <ID> <title> — build-ready on a parent with open child work; lifecycle-repair comment posted
+- 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/Story/Spike) 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`.
+- **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/Story/Spike — 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-agy/skills/linear-create/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: 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", "mcp__linear-server__list_teams", "mcp__linear-server__list_projects", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+---
+
+# 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 `mcp__linear-server__save_project` or `mcp__linear-server__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 calls `mcp__linear-server__save_*` 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-agy/skills/linear-evidence/SKILL.md

@@ -0,0 +1,103 @@
+---
+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 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 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 `mcp__linear-server__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 `mcp__linear-server__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 `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.
+
+## 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 `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.