@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/skills/lisa-tracker-evidence/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: lisa-tracker-evidence
+description: "Vendor-neutral wrapper for posting verification evidence. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-evidence, lisa-github-evidence, or lisa-linear-evidence. Uploads evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating ticket/issue, and leaves workflow transitions to the tracker-specific lifecycle owner."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Evidence: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor evidence skill.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+Apply `lisa-tracker-sync` — **Agent attribution** when composing evidence comments; a disclosure already present in the body needs no second trailer.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Missing / empty → stop and report `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+3. Before dispatching, update the generated evidence artifact through `lisa-usage-accounting` so the comment body / PR evidence section carries a direct `lisa-verify` usage entry in the canonical `## Lisa Usage` section. If the originating work item's parentage or child refs are already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise still write the direct entry, and if trustworthy runtime usage is unavailable, write `source: unavailable` with nullable token/cost fields instead of skipping the row.
+4. Dispatch:
+   - `jira` → invoke `lisa-jira-evidence` with `$ARGUMENTS` verbatim. Arg shape: `<TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>`.
+   - `github` → invoke `lisa-github-evidence` with `$ARGUMENTS` verbatim. Arg shape: `<ISSUE_REF> <EVIDENCE_DIR> <PR_NUMBER>` where `ISSUE_REF` is `org/repo#<number>` or a GitHub issue URL.
+   - `linear` → invoke `lisa-linear-evidence` with `$ARGUMENTS` verbatim. Arg shape: `<IDENTIFIER> <EVIDENCE_DIR>` where `IDENTIFIER` is a Linear Issue identifier (e.g., `ENG-123`).
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+5. Pass through the vendor skill's output.
+
+## Rules
+
+- The GitHub `pr-assets` release lives on the implementation repo (the one with the PR), regardless of which tracker hosts the ticket/issue. All vendor skills upload there.
+- Never post evidence to a different ticket than the one named — `$ARGUMENTS` is the source of truth.
+- Never invent a verify-specific usage footer. Evidence artifact usage must flow through `lisa-usage-accounting`, preserve the canonical `## Lisa Usage` section, and surface `source: unavailable` explicitly when the runtime cannot provide trustworthy numbers.
+- **Evidence-manifest gate (leaf work units).** Before dispatching to a vendor skill that transitions the ticket, confirm `EVIDENCE_DIR` contains a non-empty artifact **of the declared type** for every typed `[EVIDENCE: <artifact-type>: <name>]` marker declared in the ticket's Validation Journey — a `screenshot` marker needs an actual image, an `http-transcript` marker needs the request + response text, a `perf-trace` marker needs measured numbers; a prose claim satisfies nothing. If any declared marker has no captured artifact, an empty one, or one whose content/extension does not match its declared type, stop and report the offending markers by name instead of posting — a leaf work unit (Bug / Task / Sub-task / Improvement) may not advance to its review/Done state with an unsatisfied manifest (see the "Per-Work-Unit Evidence Contract" in the `verification` rule). Epics / Stories / Spikes, and leaf units without a Validation Journey, are exempt.
+- **Claim↔boundary binding (S14 upgrade).** Satisfying the manifest by *type* is not enough: each `[EVIDENCE: <artifact-type>: <name>]` marker is also cited for a **claim**, and the marker's artifact type must **reach the boundary that claim declares** per the `claim-evidence-mapping` rule's taxonomy. A `browser` claim (user-visible UI behavior) is reached by `screenshot` / `recording` and never by a unit `test-run-log`; an `http-api` claim needs an `http-transcript`; a `deploy-health` claim needs a `deploy-log` and no pre-deploy artifact. On a mismatch, report the offending marker **by name** together with the claim, its boundary, and the **required evidence kinds** for that boundary — e.g. `[EVIDENCE: test-run-log: unit-suite] cited for claim AC-2 [boundary browser] — required evidence kinds: screenshot, recording`. Swapping in a marker of a reaching kind with a real captured artifact satisfies the gate. **Advisory-first:** until `verification.gate.enforceBoundaries` is `true` in `.lisa.config.json` (the same ratchet flag the Stop-hook gate reads, default `false`), a boundary mismatch is reported to the operator but does not block the post; once ratcheted on it refuses the post exactly like a missing or wrong-type artifact. Missing/empty/wrong-type artifacts keep refusing the post regardless of the flag.
+- **The "Not established" section is required.** Before posting, confirm `evidence/comment.md` (and `comment.txt` where the vendor uses it) contains a `## Not established` heading and that the verdict carries `not_established_reviewed: true`. The heading is **never omitted and never blank**: with nothing outstanding it still renders `None outstanding — reviewed`; otherwise it lists, in plain operator language, each thing the verification did not prove — boundaries not exercised, environments not tested, behavior consciously out of scope. A comment with no such heading, a heading with nothing under it, or a verdict whose `not_established_reviewed` flag is absent is **refused**: stop and report the missing Not-established review instead of posting. (The list may be empty; the flag may never be omitted.) Definition and exemplars live in the `claim-evidence-mapping` rule; this generalizes `lisa-improve-harness`'s required, never-empty `Known limits` field.
+- **Artifact identity is required, with values (S14 extension).** Before posting, confirm the comment body carries a `## Artifact identity` heading populated with **values, not placeholders**: the `repository`, the `head_sha` the verification observed, the `environment`, and for each committed artifact its `sha256` digest and `captured_at`. Then check both identity failures. **`artifact_mismatch`** — an evidence entry whose recorded `artifact_head_sha` differs from the verdict's `artifact.head_sha`: refuse the post and report the offending evidence id together with **both SHAs** (the one the artifact was captured at and the one the verdict claims), e.g. `EV-2 captured at 4f1c9ab but artifact.head_sha is 9de0c31`. **`evidence_digest_mismatch`** — recompute the `sha256` of each committed evidence file on read; if the bytes no longer match the recorded digest (or the file is absent), stop and report the evidence id by name. Never summarize either as "verification failed" — name the field, the ids, and both SHAs so a non-engineer can read it at the gate. **Advisory-first:** until `verification.gate.enforceBoundaries` is `true` in `.lisa.config.json`, an identity failure is reported to the operator but does not block the post; once ratcheted on it refuses the post exactly like a missing artifact. Definition: the `claim-evidence-mapping` rule.
+- **Merge-race reconciliation (at completion, not at post).** The evidence's pinned `head_sha` is reconciled against the merged head using the ancestry + deploy-run definition of "what shipped" that `lisa-drive-pr-to-merge` already owns — cite that skill, never re-implement or restate its checks here. Pre-merge evidence counts for the merge commit only when its head is a parent of the merge, ancestry alone never justifies reporting shipped, and on a mismatch verification re-runs against the merged head before completion is declared.
+- **Evidence references are not manifest entries.** Extract obligations using the exact `[EVIDENCE:` prefix (and the legacy local `[SCREENSHOT:` form). Exclude both the canonical `[EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>]` and the Lisa 2.223.0 legacy alias `[EVIDENCE-REF: <tracker-ref>: <artifact-type>: <kebab-case-name>]` from artifact lookup, missing-artifact reporting, and duplicate-name checks: either belongs to another work item and cannot satisfy this item's S14 gate. A runtime-changing leaf with references but no local claiming marker must be rejected before dispatch.
+
+## UI Evidence Checklist (when work is UI-visible)
+
+Apply this when authoring `evidence/comment.md` (and `evidence/comment.txt` for JIRA wiki markup) for any ticket whose work touches a user-facing surface — bug fix, new component, new flow, UX polish, design implementation. Skip the checklist for non-UI work (API, infra, migrations, etc.); the plain-text evidence path is fine there.
+
+The checklist is tracker-agnostic — the same shape works on JIRA, GitHub Issues, and Linear. Vendor skills only own the post/transition mechanics; the comment body is your responsibility.
+
+1. **AI disclosure at the top.** Lead with "Update from <actual runtime name> (AI agent)" and address the reporter / QA / PM by name when known. This satisfies the shared attribution convention without a second trailer.
+2. **Own any prior mistake explicitly.** If an earlier triage or build pass got something wrong, say so up front. Don't bury it.
+3. **Numbered step-by-step walk** of what you actually did in the browser/app, in plain language a non-engineer can follow:
+   - Exact env (URL, viewport size — e.g. `402×874` for an iOS-sized mobile flow)
+   - Login creds shape — e.g. `(000) 000-0002` + OTP `555555`
+   - Exact record/player name, exact button labels as they appear on screen
+   - Full happy-path **and** any non-obvious edge state worth showing (empty state, loading, post-completion)
+4. **One screenshot per step**, captured live through the interactive browser controller at the matching viewport. The controller may be an in-app Browser/Chrome tool, interactive Playwright control, CDP, computer use, or an equivalent; do not require one named backend. Upload via `gh release upload pr-assets <files> --clobber` and reference each one as a **plain URL** in the comment body — *not* `![alt](url)` markdown embeds. Plain URLs render as smartlinks/auto-embeds across all three trackers and stay individually viewable; markdown embeds collapse on JIRA when there are ≥2.
+5. **"What this shows" section.** Tailor to ticket type:
+   - **Bug repro:** state plainly whether the bug reproduces or not, and the most likely 1–2 reasons their retest still failed (different env, native app vs. web, stuck backend row, etc.).
+   - **Feature/UX completion:** state plainly which acceptance criteria each screenshot covers, and call out any deferred or out-of-scope surface explicitly so QA/PM doesn't have to infer.
+6. **"Artifact identity" and "Not established" sections (both required).** Right after "What this shows":
+   - `## Artifact identity` — what the evidence was collected against, as **values, not placeholders**: the repository, the `head_sha` the verification observed, the `environment`, and per artifact its `sha256` digest and `captured_at`. A heading rendered with `<unknown>` in place of a SHA is not identity.
+   - `## Not established` — **never omitted, never blank.** List in plain language what this verification did *not* prove: boundaries not exercised (e.g. "the persisted order row was never queried"), environments not tested (e.g. "checked on desktop Chrome only — not mobile Safari"), and behavior consciously out of scope (e.g. "refunds were not touched or tested"). Name the specific thing, not a category. With nothing outstanding, the heading still renders a single line: `None outstanding — reviewed`. Never state a quality check as proof of behavior — "unit tests pass" belongs here as a limit, not above as evidence.
+7. **"What would help me confirm" (bug) / "How to QA" (feature) section.** Concrete actionable retest steps with the exact selection criteria (e.g., "pick a record whose Status column shows `—`, not `Processing` or `Pending Review`").
+8. **Explicit invitation to be corrected.** End with a line like *"If any of the steps I listed are different from what you expected / actually did, please tell me explicitly which step I got wrong."* Non-optional — small differences (which record, which device, exact tap order, expected behavior) change everything, and naming the door open short-circuits ticket bounce-loops.
+9. **Workflow transition** is the vendor skill's job, not yours — it'll move the ticket per the configured tracker (JIRA: Reassign to reporter for bug repro / move to the configured review status when one exists, otherwise leave it in `claimed`; GitHub: direct `claimed` → configured `done` after a successful build; Linear: equivalent state). You don't transition manually.
+
+**Why this format:** It (a) gives the reporter a frame-by-frame they can compare against, (b) avoids the JIRA image-collapse failure mode while still working everywhere else, (c) names the most plausible discrepancies up front so the loop short-circuits, (d) explicitly opens the door to being corrected so tickets don't bounce on assumed alignment. The same mechanics that resolve a stuck bug ticket also give QA an unambiguous handoff for a freshly-built feature.

package/plugins/lisa-devin/skills/lisa-tracker-journey/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: lisa-tracker-journey
+description: "Vendor-neutral wrapper for executing a ticket/issue's Validation Journey end-to-end. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-journey, lisa-github-journey, or lisa-linear-journey. Parses the journey, satisfies prerequisites, executes the steps, captures evidence at each marker, and posts results via tracker-evidence."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Journey: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor journey skill.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Dispatch:
+   - Missing / empty → stop and report `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+   - `jira` → invoke `lisa-jira-journey` with `$ARGUMENTS` verbatim. Arg shape: `<TICKET_ID> [PR_NUMBER]`.
+   - `github` → invoke `lisa-github-journey` with `$ARGUMENTS` verbatim. Arg shape: `<ISSUE_REF> [PR_NUMBER]`.
+   - `linear` → invoke `lisa-linear-journey` with `$ARGUMENTS` verbatim. Arg shape: `<IDENTIFIER> [PR_NUMBER]`.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the output.
+
+## Rules
+
+- The journey content is identical across vendors; only the parser source differs (the JIRA vendor reads description via Atlassian MCP; the GitHub vendor reads body via `gh issue view --json body`; the Linear vendor reads description via `lisa-linear-access operation: get-issue`).
+- Evidence posting always goes through `lisa-tracker-evidence` — never bypass.

package/plugins/lisa-devin/skills/lisa-tracker-read/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: lisa-tracker-read
+description: "Vendor-neutral wrapper for fetching the full scope of a ticket/issue and its related graph. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-read-ticket, lisa-github-read-issue, or lisa-linear-read-issue. Returns a consolidated context bundle so downstream agents never act on a single ticket in isolation."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Read: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor read skill.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Dispatch:
+   - Missing / empty → stop and report `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+   - `jira` → invoke `lisa-jira-read-ticket` with `$ARGUMENTS` verbatim. The argument is a JIRA key (e.g., `PROJ-123`).
+   - `github` → invoke `lisa-github-read-issue` with `$ARGUMENTS` verbatim. The argument is `org/repo#<number>` or a full GitHub issue URL.
+   - `linear` → invoke `lisa-linear-read-issue` with `$ARGUMENTS` verbatim. The argument is a Linear identifier (e.g., `ENG-123`) or a project URL.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Return the vendor skill's context bundle verbatim.
+
+## Rules
+
+- Read-only — never modify the ticket/issue.
+- The three vendors emit different context-bundle formats (because their data models differ). Callers must be tolerant of all — or, more precisely, agents at the next layer parse the per-vendor bundle.
+- If the input format doesn't match the configured tracker (e.g. tracker is jira but `$ARGUMENTS` looks like a Linear identifier), stop and report — never auto-translate.

package/plugins/lisa-devin/skills/lisa-tracker-source-artifacts/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: lisa-tracker-source-artifacts
+description: "Canonical, vendor-neutral taxonomy and rules for handling source artifacts (Figma, Lovable, Loom, screenshots, design docs, data samples) when generating or evaluating tracker tickets (JIRA, GitHub Issues, Linear). Defines: (1) artifact domains, (2) classification rules per tool, (3) source precedence (which artifact is authoritative for which question), (4) inheritance from epic to story to sub-task, (5) cross-axis conflict handling. Invoke this skill from any flow that extracts, attaches, or reasons about external design/UX/data artifacts so the rules don't drift across skills."
+allowed-tools: []
+---
+
+# Tracker Source Artifact Taxonomy and Rules
+
+This skill is doctrine, not action — it defines the rules. Skills that need to extract, classify, attach, or reason about external artifacts (design files, prototypes, recordings, data samples) invoke this skill to load the taxonomy and apply it. The taxonomy is vendor-neutral: it applies equally to JIRA tickets, GitHub Issues, and Linear Issues.
+
+The reason this lives in one place: silent drift across skills is the failure mode this body of rules exists to prevent. If the rules differ between `lisa-notion-to-tracker`, `lisa-tracker-create`, and `lisa-tracker-write`, agents will silently route artifacts wrong and developers will lose source of truth. Edit here, propagate everywhere.
+
+## 1. Domains
+
+Every artifact is classified into exactly one domain. The domain determines what the artifact is the source of truth for, and which tickets inherit it.
+
+| Domain | What it defines | Examples |
+|--------|-----------------|----------|
+| `ui-design` (mocks) | **Visual treatment only** — layout, spacing, typography, color, iconography | Figma design frames, Framer static frames, bare screenshots, mockup PNGs |
+| `ux-flow` (prototypes) | **Interaction and flow only** — navigation, transitions, state changes, timing, empty/error/loading states | Lovable output, Loom walkthroughs, Figma prototype links, annotated screenshots, Miro/Mural flow diagrams, user journey maps |
+| `data` | Request/response shape, schema constraints, contracts | Example JSON, SQL schemas, GraphQL snippets, API contracts, sample payloads |
+| `ops` | Deployment / runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
+| `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs, RFCs |
+
+## 2. Classification rules per tool
+
+These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped or misrouted context.
+
+- **Figma**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume; inspect the URL.
+- **Figma file with both design frames and a prototype**: emit two entries — one `ui-design` for the file, one `ux-flow` for the prototype URL — so both propagate correctly.
+- **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD body, not from Lovable.
+- **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's purely a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit).
+- **Screenshot**: bare unannotated screenshot → `ui-design`. Screenshot with arrows between frames, flow labels, or numbered steps → `ux-flow`. Side-by-side gallery of state variants (empty/error/loading) → `ui-design` with the state variants noted.
+- **Confluence / Notion peer / Google Doc**: `reference` unless it is specifically a runbook (`ops`) or contains canonical API contracts (`data`).
+- **Grafana / Datadog / Sentry**: `ops`.
+- **Code blocks with example payloads** (JSON, SQL, GraphQL, cURL): `data`.
+
+When an artifact could plausibly fit multiple domains and the rules above don't disambiguate, err on the side of inclusion — emit it under both, or use the broader domain. Misclassification is caught downstream by the preservation gate; underclassification is silent drop.
+
+## 3. Source precedence
+
+When artifacts disagree, silent reconciliation is a known failure mode. The rules below define which source wins which question. **Record this precedence on every ticket that carries design artifacts** (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't reconcile silently.
+
+| Question | Authoritative source |
+|----------|---------------------|
+| Does this field exist? Is it required? Who can see/edit it? What validation applies? Permission rules, edge cases, data constraints? | **Description / PRD body** (business rules) |
+| What does it look like — layout, spacing, typography, color, iconography? | **Mocks (`ui-design`)** |
+| How does it flow — navigation, transitions, state changes, timing, empty/error/loading states? | **Prototypes (`ux-flow`)** |
+| Where does the data come from, what shape is it, what are the API contracts? | **`data` artifacts** |
+| Where does it run, who's on call, what's the dashboard? | **`ops` artifacts** |
+
+## 4. Cross-axis conflict handling
+
+Conflicts MUST be surfaced under `## Open Questions` on the affected ticket — never silently reconciled.
+
+- Mock shows a field the description doesn't mention → BLOCKER: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation, permissions)."
+- Description mandates behavior the prototype contradicts → BLOCKER: "PRD says Y, prototype shows Z; which is correct?"
+- Prototype shows a flow the mocks don't cover (e.g., an error state) → Note: "Error state flow from prototype; no mock exists. Use existing error component or request mock."
+- Multiple artifacts of the same domain disagree (two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
+- Lovable output without a description covering business rules → BLOCKER: "Business rules missing. Lovable's embedded logic is not authoritative; PRD must explicitly state required fields, validation, permissions, and edge cases."
+
+## 5. Coverage smells
+
+Incomplete artifact sets are a common root cause of implementation drift. Surface these on the epic when extracting:
+
+- **Zero artifacts on a non-trivial PRD**: almost always an extraction bug, not a design decision. Say so explicitly.
+- **`ux-flow` present, `ui-design` absent**: flag "missing UI mocks". UI will be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth.
+- **`ui-design` present, `ux-flow` absent**: flag "missing UX prototype". UX will be inferred from static mock states (empty/error/loading/hover) — any flow not explicitly depicted must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
+
+## 6. Inheritance: epic → story → sub-task
+
+Artifacts attach as Jira remote links and propagate down the hierarchy.
+
+- **Epic**: gets EVERY artifact, regardless of domain. The epic is the canonical hub — anyone working on the epic or its descendants must reach the full set from one place. No filtering.
+- **Story**: inherits the artifacts whose domain matches its scope:
+
+  | Story type | Inherits domains |
+  |------------|------------------|
+  | Frontend / UI | `ui-design`, `ux-flow`, `reference` |
+  | Backend / API / data model | `data`, `reference` |
+  | Infrastructure | `ops`, `reference` |
+  | Mixed / setup ("X.0") | All domains |
+
+  When classification is ambiguous, err on the side of inclusion — a developer can ignore an extra link, but they can't follow one that wasn't attached.
+
+- **Sub-task**: inherits via the parent story link. Do NOT re-attach the same artifacts on every sub-task — that creates noise. Only attach an artifact directly on a sub-task when the sub-task depends on something the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame the broader story doesn't cite).
+
+## 7. Existing-component reuse (UI-touching tickets)
+
+Mocks define visual *intent*, not implementation shortcut. Every UI-touching ticket description must include:
+
+> Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling — flag the design-vs-code divergence as a discussion item on this ticket rather than pixel-matching from scratch.
+
+If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation. Lovable-generated components are never the reuse target — always use the project's own components.
+
+Before adding the code-side obligation to ticket or teammate instructions, read `designSource.enabled` in `.lisa.config.json`. Only boolean `false` opts out: omit the design-source step; do not request DESIGN-SOURCE markers, Figma nodes, or Figma access for this obligation. Absent, true, or invalid values keep enforcement enabled. Preserve supplied artifacts and component-reuse requirements regardless; `design-value-binding` remains independent.
+
+When enabled, the divergence note above covers the **ticket** side of this event. The **code** side is governed by the `design-source-of-truth` rule: a UI surface built with no Figma source behind it is either synced back to Figma and annotated `DESIGN-SOURCE: <figma-url>`, or explicitly marked `DESIGN-SOURCE: none — not in Figma`, and review fails closed if neither happened. Cite the rule for the code obligation rather than restating it here — a ticket comment closes with the ticket, the annotation stays with the surface.
+
+## 8. Preservation gate (run after creating tickets)
+
+Before declaring done, verify every extracted artifact is reachable from the created tickets.
+
+1. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
+2. For every artifact:
+   - It MUST appear on the epic it belongs to (no exceptions).
+   - It SHOULD appear on at least one story whose scope matches its domain (except `reference`-domain artifacts, which may be epic-only if no story is domain-matched).
+3. Any artifact with zero references anywhere, or missing from its epic: FAIL LOUDLY — list the dropped artifacts with domain, title, and source page; surface to the human; re-attach before continuing.
+4. If classification looks misrouted (e.g., a Figma link landed on a backend story and nowhere else), surface the misroute and offer to re-propagate.
+
+Skipping this gate is the most common cause of silent artifact loss. Do not skip it.

package/plugins/lisa-devin/skills/lisa-tracker-sync/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: lisa-tracker-sync
+description: "Vendor-neutral wrapper for posting milestone updates to the linked ticket/issue. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-sync, lisa-github-sync, or lisa-linear-sync. Posts at: plan created, implementation in progress, PR ready, PR merged. Suggests (never auto-transitions) the next status."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Sync: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor sync skill.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Agent attribution
+
+In agent-composed tracker comments and review messages, include one short plain-text attribution, such as `Agent-written by Codex.` Use the actual runtime's name; add a public lane name only when already known. An existing clear disclosure is enough. Do not publish session identifiers, invent a lane, alter supplied human text, or change machine-managed comment formats such as `[lisa-pr-link]`.
+
+The account avatar identifies the credential owner, not necessarily the writer. When relaying a human decision, attribute it to the person and its actual source (a linked decision or an instruction in the current conversation). Present your own judgement as agent analysis, never as an owner ruling. Attribution itself grants no authority.
+
+This is a writing convention: missing disclosure is not a reason to block work or file a compliance issue. Do not add identity infrastructure or extra audit comments just to supply it. Preserve an existing disclosure when a vendor skill posts or retries the same body.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Dispatch:
+   - Missing / empty → stop and report `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+   - `jira` → invoke `lisa-jira-sync` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa-github-sync` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa-linear-sync` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the output.
+
+`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+
+> **There is no per-milestone lane-write flag on any vendor.** This paragraph previously documented `--update-label` on GitHub and `--update-state` on Linear. `--update-label` was never implemented — `lisa-github-sync` says flatly *"This skill never relabels"* — so a caller passing it got a silent no-op on GitHub and a real write on Linear for the equivalent flag. Both are gone. `--rollup` is the only write path a sync skill has.
+
+## Tracker status vocabulary — binding on all three arms
+
+Every suggested or performed transition names **only a role the project configured**, never a status, state or label discovered from the tracker's live workflow (transition lists, board columns, `type`-derived matches, other tickets). This binds a lead performing tracker writes exactly as it binds a subagent.
+
+Two consequences the vendor arms must not restate differently:
+
+- **A milestone whose role is unset gets a comment, not a transition.** `review` and the `qa.*` roles are optional and carry **no default** — omitting one means the project does not run that step, and the lifecycle skips it. "Unset" must never resolve to a built-in name; that is the difference between "not customized" and "we deliberately don't do this".
+- **A fallback may inform a read; it may never supply a write target.** Where a vendor exposes one (Linear resolves states by `type`), it selects by board position rather than intent — so on a board carrying more than one plausible state it returns whichever sits earliest, which is exactly the human-only lane a project left out of its config on purpose.
+
+Resolve roles through the shared resolver rather than an inlined helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-plugins/lisa}}/scripts/resolve-lifecycle-role.mjs" \
+  --role <role> --vendor <jira|linear|github> --intent <read|write> [--env <env>]
+```
+
+Exit `0` with a value means configured; exit `0` with **empty** output means an optional role is unset — skip the transition; exit `2` means a required role is unset or a write was refused a fallback value. Any other exit is a resolver failure, never an unset role.
+
+If `$ARGUMENTS` is empty, all vendor skills auto-detect a ticket reference from the active plan file (most recently modified `.md` in `plans/`).
+
+## Parent status rollup (`--rollup`)
+
+When the caller passes `--rollup` after the milestone, the dispatch target additionally **derives the parent/container's lifecycle state from its children** instead of acting on the work item directly. This is the vendor-neutral implementation of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy here. The shim is dispatch only; the rollup mechanics live in the vendor sync skill (`lisa-github-sync`, `lisa-jira-sync`, `lisa-linear-sync`), which resolves child membership via its `*-read-*` skill and evaluates the state machine below.
+
+The state machine (first match wins, evaluated over the **required** leaves only, on the env ladder `in-progress < dev < staging < production` — the ordered keys of the project's env-keyed `done` map):
+
+| If among the required leaves… | …the parent rolls up to | Role |
+|---|---|---|
+| any leaf is **blocked** | blocked / attention-needed | `blocked` |
+| else **every** required leaf has shipped to some env (each at a `done`-map value) | the **least-advanced** env among them | `done[min-env]` (terminal `done` at production) |
+| else any leaf has **started** (claimed or in review, or shipped while a sibling has not) | active / in-progress | `claimed` (or `review` where supported) |
+| else (leaves exist, none started) | unchanged | — |
+
+- **Blocked dominates** — one blocked leaf surfaces blocked on the parent even while others progress. It never says *which* child or *which kind* of hold. Resolve the shared classifier with the trusted-root ladder below, run it over the resolved child graph, and carry its per-class report — blocking leaf, path, and who must act — into the rollup note. A missing, unusable, or non-zero classifier is a strict **no-write** result: no lifecycle mutation and no rollup comment. Its bounded diagnostic names attempted paths only; it never prints environment values or child payloads. Report the failure, never an all-clear. See `leaf-only-lifecycle` → **Classifying a hold**.
+
+```bash
+run_rollup_classifier() {
+  local input_path="$1"
+  local attempted_paths=""
+  local seen_root=""
+  local candidate_suffix="scripts/rollup-blocker-classification.mjs"
+  local root root_real candidate candidate_real expected_candidate
+  local classifier_output
+
+  for root in "${CLAUDE_PLUGIN_ROOT:-}" "${PLUGIN_ROOT:-}"; do
+    [ -n "$root" ] || continue
+    [ "$root" != "$seen_root" ] || continue
+    seen_root="$root"
+    case "$root" in
+      /*) ;;
+      *) continue ;;
+    esac
+    case "$root" in
+      */../*|*/..|*/./*|*/.) continue ;;
+    esac
+
+    candidate="${root%/}/$candidate_suffix"
+    if [ -z "$attempted_paths" ]; then
+      attempted_paths="$candidate"
+    else
+      attempted_paths="$attempted_paths, $candidate"
+    fi
+
+    root_real="$(realpath "$root" 2>/dev/null)" || continue
+    [ -f "$candidate" ] && [ -r "$candidate" ] || continue
+    candidate_real="$(realpath "$candidate" 2>/dev/null)" || continue
+    expected_candidate="${root_real%/}/$candidate_suffix"
+    [ "$candidate_real" = "$expected_candidate" ] || continue
+
+    if classifier_output="$(
+      node "$candidate" --input="$input_path" 2>/dev/null
+    )"; then
+      printf '%s\n' "$classifier_output"
+      return 0
+    fi
+
+    printf 'Rollup classifier failed at trusted path: %.4000s\n' \
+      "$candidate" >&2
+    return 1
+  done
+
+  printf 'No usable rollup classifier; attempted paths: %.4032s\n' \
+    "$attempted_paths" >&2
+  return 1
+}
+```
+- **Least-advanced env wins** — a parent reaches an env only once all required leaves have reached at least that env (all `On Stg` → `On Stg`; mixed dev/staging → the dev value). Native terminal closure fires only at the production `done`, never at an intermediate env.
+- **The parent never carries `ready`** — `ready` is a human "claim this leaf" signal; rollup only moves a parent between non-ready container states.
+- **Rollup is recursive** — an Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up.
+- **The env rungs are the configured env-keyed `done`** — multi-env projects roll up to whichever `done` value (including intermediate `On Dev`/`On Stg`) their leaves have collectively reached (see `config-resolution` "Env-keyed `done`"). **Single-environment collapse (this repo):** `deploy.branches` declares only `production: main`, so `done` is a single value, the only env rung is production, and the GitHub build lifecycle collapses to `ready → claimed (in-progress) → done`; the rollup terminal is simply `done` (or the PRD-side `ticketed` for PRD containers), with **no** dev/staging promotion hops and **no** env-keyed multi-entry chain to resolve.
+
+**Safe-by-default when not yet supported.** A vendor sync path that has not implemented native rollup MUST be a documented no-op that surfaces the derived state as a suggestion/comment rather than guessing a transition — never an unsafe default. Without `--rollup`, the sync skills behave exactly as before (milestone comment on the work item; no parent derivation).
+
+## Pull request backlinking
+
+When `$ARGUMENTS` includes `pr_url=<url>` with milestone `pr-ready` or `pr-merged`, the dispatch target must ensure ticket -> PR linkage, not just post a generic progress note:
+
+1. Prefer the provider's native development-link primitive when Lisa can write and verify it for that provider.
+2. Verify the native link using the provider read surface when available.
+3. Whether or not the native link exists or cannot be verified, establish the managed backlink comment with the one command that owns it:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+4. That command is idempotent by construction — it updates the existing `[lisa-pr-link]` comment rather than appending duplicates — and it refuses loudly for a tracker it cannot write. Do not restate its procedure in a vendor skill; the file that writes the comment is the file that checks it, and that is what stops the two from drifting.
+
+This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that mentions a ticket is not considered fully synced until the ticket also has either a verified native PR link or the managed fallback comment.
+
+## Rules
+
+- Idempotent updates — running sync at the same milestone twice should not produce duplicate comments. Vendor skills enforce this.
+- Never transition a leaf's lane from a sync milestone on any vendor. The canonical signal differs — the `status:*` label on GitHub, the workflow status on JIRA, the native workflow state on Linear — but the owner is the same everywhere: build-intake / the vendor agent. Every arm only suggests. `--rollup` (parent derivation) is the sole exception, and it derives the parent from its children rather than advancing a leaf.
+- Parent rollup derives state from children per the `leaf-only-lifecycle` rule; it never sets a parent to `ready` and never resolves a dev/staging `done` in this single-environment repo.
+- Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.

package/plugins/lisa-devin/skills/lisa-tracker-validate/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: lisa-tracker-validate
+description: "Vendor-neutral wrapper for the pre-write quality gate. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-validate-ticket, lisa-github-validate-issue, or lisa-linear-validate-issue. Read-only — never writes to any tracker. Used by tracker-write Phase 5.5 (pre-write gate), tracker-verify (post-write checks), and the *-to-tracker dry-run paths. Output is structured PASS/FAIL per gate so callers can parse it."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Validate: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor validator.
+
+See the `config-resolution` rule for the full configuration schema and skill-mapping table.
+
+## Workflow
+
+1. **Resolve tracker config** (same logic as `lisa-tracker-write` Step 1):
+
+   ```bash
+   local_tracker=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+   global_tracker=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+   tracker="${local_tracker:-$global_tracker}"
+   ```
+
+2. **Dispatch**
+
+   - Missing / empty → stop and report `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+   - `jira` → invoke `lisa-jira-validate-ticket` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa-github-validate-issue` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa-linear-validate-issue` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+3. **Pass through the validator's structured report unchanged.** Callers (e.g. `lisa-jira-write-ticket` Phase 5.5) parse the gate lines; do not paraphrase.
+
+## Rules
+
+- Read-only — never write to any tracker.
+- Never re-implement gate logic here. The gate definitions are the vendor validator's responsibility.
+- Never silently transform the input — pass `$ARGUMENTS` through verbatim.

package/plugins/lisa-devin/skills/lisa-tracker-verify/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: lisa-tracker-verify
+description: "Vendor-neutral wrapper for the post-write verification gate. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-verify, lisa-github-verify, or lisa-linear-verify. Fetches the live ticket/issue and runs the validator gates against the stored state — catches anything dropped or reformatted on write. Read-only."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Verify: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor post-write verifier.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Dispatch:
+   - Missing / empty → stop and report `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+   - `jira` → invoke `lisa-jira-verify` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa-github-verify` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa-linear-verify` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the verifier's structured report unchanged.
+
+## Rules
+
+- Read-only.
+- The same gates run pre-write and post-write — this shim simply chooses the vendor implementation.
+- If the vendor verify reports `FAIL`, callers must NOT auto-fix from this layer. Surface the failures to the caller and let the higher-level skill decide.
+- Duplicate closeout is not a verifier shortcut. A build-intake ticket may be auto-closed as duplicate only when downstream triage returns `DUPLICATE_ALREADY_FIXED` with a canonical ticket reference and empirical evidence that the canonical fix is present on the relevant base branch; ordinary verifier `FAIL`/`PASS` output never implies duplicate resolution.

package/plugins/lisa-devin/skills/lisa-tracker-write/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: lisa-tracker-write
+description: "Vendor-neutral wrapper for ticket creation and updates. Reads the required `tracker` from .lisa.config.json and dispatches to lisa-jira-write-ticket, lisa-github-write-issue, or lisa-linear-write-issue. Callers in vendor-neutral skills (notion-to-tracker, linear-to-tracker, confluence-to-tracker, github-to-tracker, implement, verify) MUST invoke this skill instead of the vendor-specific ones — that is what makes the tracker switchable per project. The Phase-5.5 validate-pre-write gate, post-write verify, and Phase-8 announce-comment behavior live in the vendor skills; this shim is dispatch only."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Write: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor
+write skill.
+
+When the incoming description/body already contains the canonical `## Lisa Usage` ledger, the vendor
+writer must preserve that managed section on update and use the `lisa-lisa-usage-accounting` contract for any
+body-vs-comment fallback. This shim only routes — it never edits tracker artifacts itself.
+
+See the `config-resolution` rule for the full configuration schema and skill-mapping table.
+
+## Workflow
+
+1. **Resolve tracker config**
+
+   Read `.lisa.config.local.json` first (if present), then `.lisa.config.json`. Local overrides global on a per-key basis. Use `jq` — never hand-parse JSON.
+
+   ```bash
+   local_tracker=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+   global_tracker=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+   tracker="${local_tracker:-$global_tracker}"
+   ```
+
+2. **Validate the value**
+
+   - Missing / empty → stop and report: `"No tracker configured in .lisa.config.json. Run /lisa:setup:jira, /lisa:setup:github, or /lisa:setup:linear first."`
+   - `jira` → confirm `atlassian.cloudId` and `jira.project` are present. If either is missing, stop and report: `"tracker=jira but atlassian.cloudId and jira.project are not set in .lisa.config.json."` Continue to Step 3a.
+   - `github` → confirm `github.org` and `github.repo` are present. If either is missing, stop and report: `"tracker=github but github.org and github.repo are not set in .lisa.config.json."` Continue to Step 3b.
+   - `linear` → confirm `linear.workspace` and `linear.teamKey` are present. If either is missing, stop and report: `"tracker=linear but linear.workspace and linear.teamKey are not set in .lisa.config.json."` Continue to Step 3c.
+   - Any other value → stop and report: `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+3. **Dispatch**
+
+   - **3a (jira):** Invoke `lisa-jira-write-ticket` via the Skill tool, passing `$ARGUMENTS` verbatim.
+   - **3b (github):** Invoke `lisa-github-write-issue` via the Skill tool, passing `$ARGUMENTS` verbatim.
+   - **3c (linear):** Invoke `lisa-linear-write-issue` via the Skill tool, passing `$ARGUMENTS` verbatim.
+
+4. **Surface the vendor skill's output unchanged.** Do not paraphrase; downstream callers parse the structured response.
+
+## Rules
+
+- Never bypass dispatch — calling the vendor skill directly from a vendor-neutral caller defeats the per-project switch.
+- Never drop, duplicate, or hand-rewrite an existing managed `## Lisa Usage` section in this shim.
+  Writer-specific preservation logic belongs in the vendor writers and follows the
+  `lisa-lisa-usage-accounting` contract.
+- Never accept a tracker value outside `{jira, github, linear}`.
+- Never mutate `$ARGUMENTS` between layers. The vendor skills define their own input contract.
+- Never inline gate logic here. All validation rules live in the vendor skills (`lisa-jira-validate-ticket` / `lisa-github-validate-issue` / `lisa-linear-validate-issue`); this skill only routes.
+- **Readiness is the caller's explicit claim, not this shim's default.** Per the `ready-role-filing` rule, an omitted `build_ready` is **not build-ready** on every vendor, so a caller filing work it expects build-intake to pick up must pass `build_ready: true`, and a caller deliberately holding work outside the queue must pass a `human_gate` reason. This shim normalizes nothing — it forwards `$ARGUMENTS` verbatim and the vendor writers enforce the contract — which is exactly why the caller cannot rely on a vendor default here.