@codyswann/lisa 2.10.1 → 2.11.1

package/plugins/lisa/skills/linear-read-issue/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: linear-read-issue
+description: "Fetches the full scope of a Linear work item — Issue or Project — including metadata, description, acceptance criteria, all comments, attachments, native relations (blocks/blocked_by/relates_to/duplicates), Project parent (if any) with siblings, and sub-Issues. Produces a consolidated context bundle that downstream agents consume so they never act on a single item in isolation."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__get_project", "mcp__linear-server__list_issues", "mcp__linear-server__list_comments", "mcp__linear-server__list_documents", "mcp__linear-server__get_document"]
+---
+
+# Read Linear Work Item: $ARGUMENTS
+
+Fetch the full scope of the item AND its related graph. Downstream agents must never act on an item in isolation — always call this skill first so they see blockers, project siblings, linked PRs, and historical comments.
+
+This skill is the destination of the `lisa:tracker-read` shim when `tracker = "linear"`. Read-only.
+
+Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Phase 1 — Resolve Context
+
+1. If `$ARGUMENTS` matches `<TEAM>-<n>` → Issue mode.
+2. If `$ARGUMENTS` is a URL containing `/project/<slug>-<short-id>` → Project mode (extract `<short-id>`).
+3. Otherwise stop and report. Do NOT guess.
+4. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
+
+## Phase 2 — Fetch Primary Item
+
+### Issue mode
+
+Call `mcp__linear-server__get_issue`. Extract and preserve:
+
+**Metadata**
+- Identifier, title, issue type (typically a label or workflow state), state, priority (0–4)
+- Assignee, creator, subscribers
+- Labels (capture full names — `status:*`, `component:*`, `priority:*`, `prd-*`)
+- Project (parent), parent Issue (if Sub-task), cycle, milestone (ProjectMilestone)
+- Estimate, due date
+- Created, updated, completed dates
+
+**Body**
+- Full description (preserve markdown)
+- **Validation Journey** section if present (pass verbatim to downstream)
+- Attachment URLs (capture, do not download unless needed)
+
+**Comments**
+Fetch ALL comments via `mcp__linear-server__list_comments({issueId: <id>})` in chronological order. Walk thread parents/children — Linear comments are threaded via `parentId`. Do not truncate. For each comment:
+- Author, timestamp, body
+- Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers.
+
+### Project mode
+
+Call `mcp__linear-server__get_project` with `includeMilestones: true`, `includeResources: true`. Extract:
+
+**Metadata**
+- ID, slug, name, state, priority, lead, color
+- Teams, labels, milestones, target date, start date
+- Created, updated dates
+
+**Body**
+- Description (markdown)
+- Attached documents — call `mcp__linear-server__list_documents({projectId})` then `get_document` per result. Treat each as additional spec content.
+
+**Member Issues**
+- Call `mcp__linear-server__list_issues({project: <id>})` to enumerate the Project's Issues. Capture identifier, title, state, parent Issue (for sub-Issue tree).
+
+## Phase 3 — Fetch Attachments / Remote Links
+
+Linear stores remote URLs as attachments on the Issue. For each:
+
+- **GitHub PR or commit**: run `gh pr view <url> --json title,state,body,mergedAt,reviewDecision,comments,reviews` (PRs) or `gh api repos/<owner>/<repo>/commits/<sha>` (commits). Capture title, state, unresolved review comments, merge status.
+- **Confluence page**: capture title and URL. Do not fetch body unless a downstream task explicitly needs it.
+- **Dashboard / log link / external URL**: capture title and URL only.
+
+If `gh` is not authenticated, note "gh auth required" and continue — do not abort.
+
+## Phase 4 — Fetch Relations
+
+Linear native Issue relations are returned in the `get_issue` response under `relations`. Group by type:
+
+- `blocks` / `blocked_by`
+- `relates_to`
+- `duplicates` / `duplicated_by`
+
+For each related Issue, call `mcp__linear-server__get_issue` and capture:
+- Identifier, title, state, priority, assignee
+- Description (full, unless cancelled — then summary only)
+- Acceptance Criteria section
+- Last 10 comments (chronological)
+- Attachments (URLs only — skip deep PR fetch unless the relation is `blocks` or `blocked_by`)
+
+**Special handling for `blocked_by`:** fetch full PR details via `gh` for each blocker's GitHub attachments so the agent knows whether the blocker is actually shipped.
+
+For Project-level relationships (Project ↔ Project), Linear doesn't model native relations — check the Project description and resources for cross-references and capture them as plain links.
+
+## Phase 5 — Fetch Project Context
+
+If the primary Item is an Issue with a Project parent:
+
+1. Fetch the Project via `mcp__linear-server__get_project` — full description, milestones, labels, lead.
+2. Fetch Project documents (Phase 2 procedure).
+3. Find Project siblings via `mcp__linear-server__list_issues({project: <projectId>})` excluding the primary identifier.
+4. For each sibling, capture: identifier, title, state, priority, assignee, summary (first paragraph of description).
+5. If a sibling is `Started` or `In Review` with a different assignee, flag it prominently.
+
+If the primary Item IS a Project, Phase 5 is the same as fetching all member Issues (already done in Phase 2 Project mode).
+
+## Phase 6 — Fetch Sub-Issues
+
+If the primary Issue has children (sub-Issues), fetch each via `mcp__linear-server__get_issue`: identifier, title, state, assignee, description (first paragraph), Acceptance Criteria.
+
+## Phase 7 — Assemble Context Bundle
+
+Produce a single structured output the caller can pass verbatim to downstream agents.
+
+```text
+# Linear Work Item Context: <IDENTIFIER>
+
+## Primary Item
+- Identifier: <ID>
+- Type: <Issue | Project>
+- State: <state>
+- Priority: <0–4 or named>
+- Assignee: <name or none>
+- Project (parent): <project-slug — name> or none
+- Parent Issue: <ID — title> or none (Sub-task only)
+- Cycle: <name or none>
+- Milestone: <project-milestone or none>
+- Labels: <comma-separated>
+- Estimate: <points>
+
+### Description
+<full description>
+
+### Acceptance Criteria
+<criteria>
+
+### Validation Journey
+<section or "None">
+
+### Comments (<count>)
+<chronological comments, flagged items called out>
+
+### Attachments
+<list of URLs with titles>
+
+## Remote Links
+### Pull Requests (<count>)
+- <url> — <title> — <state> — <reviewDecision>
+  <body summary + unresolved review comments>
+
+### Confluence
+- <title> — <url>
+
+### Other
+- <title> — <url>
+
+## Relations
+### Blocks (<count>)
+<per-issue block>
+
+### Blocked By (<count>)
+<per-issue block with PR state>
+
+### Relates To (<count>)
+<per-issue block>
+
+### Duplicates / Duplicated By
+<per-issue block>
+
+## Project Context (when primary is an Issue under a Project)
+### Project <slug> — <name>
+- State: <state>
+- Description: <full markdown>
+- Milestones: <list>
+- Documents: <list of doc titles + identifiers>
+
+### Siblings In-Flight (<count>)
+- <ID> — <state> — <assignee> — <title>  **[FLAG: in progress by other assignee]**
+
+### Other Siblings (<count>)
+- <ID> — <state> — <title>
+
+## Sub-Issues (<count>)
+- <ID> — <state> — <assignee> — <title>
+
+## Summary for Downstream
+- Full item count pulled: <N>
+- Blockers still open: <list>
+- Related in-flight work: <list>
+- Relevant PRs: <list with state>
+```
+
+## Rules
+
+- Never summarize or truncate the primary item's description or Validation Journey.
+- Never skip a relation type, even if it seems unrelated — the downstream agent decides relevance.
+- If a related item returns an access error, capture the error and continue. Do not abort the read.
+- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
+- If the Issue has no Project parent, state this explicitly — do not silently skip Phase 5.
+- Output is pure context. This skill never modifies the item.

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

@@ -0,0 +1,89 @@
+---
+name: linear-sync
+description: "Syncs plan progress to a linked Linear Issue. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep Linear Issues in sync. The Linear counterpart of lisa:jira-sync and lisa:github-sync."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__save_issue"]
+---
+
+# Sync Plan to Linear: $ARGUMENTS
+
+Post milestone updates to the linked Linear Issue at key plan-lifecycle moments. This skill is the destination of the `lisa:tracker-sync` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## When to invoke
+
+Callers (planning skills, lifecycle skills) invoke this skill at:
+
+| Milestone | What to post |
+|-----------|--------------|
+| Plan created | Plan contents (sections + ordered tasks) as a comment, suggest transition `Backlog → Todo` (label: `status:ready`) |
+| Implementation in progress | Branch URL + first commit, suggest transition `Todo → In Progress` (label: `status:in-progress`) |
+| PR ready for review | PR URL + summary, the implementation handoff comment, suggest transition `In Progress → In Review` (label: `status:code-review`) |
+| PR merged | Merge SHA + deploy environment (if known), suggest transition `In Review → Done` (label: `status:done`) |
+
+This skill **suggests** transitions but does not auto-transition the native Linear `state` field. It DOES update the `status:*` label set when the caller asks (the build queue is keyed off labels). Native state transitions remain a human / triage decision.
+
+## Input
+
+`$ARGUMENTS` is `<IDENTIFIER> <milestone>` where:
+
+- `<IDENTIFIER>` is the Linear Issue identifier (e.g. `ENG-123`). If not provided, the skill searches the active plan file for a linked Linear Issue.
+- `<milestone>` is one of `plan-created`, `implementation-in-progress`, `pr-ready`, `pr-merged`.
+
+## Phase 1 — Resolve Issue
+
+1. If `$ARGUMENTS` includes an identifier, parse it.
+2. Else search for the active plan file (most recent file under `plans/`) and extract the linked Linear Issue identifier from its frontmatter.
+3. Fetch the Issue via `mcp__linear-server__get_issue` to confirm it exists.
+
+## Phase 2 — Compose Milestone Comment
+
+Per the milestone, build the comment body. Include:
+
+- A milestone header (e.g. `**Plan created** — <plan-file>`)
+- Relevant links (plan file, branch, PR)
+- A short summary (first 5 lines of the plan section / commit message / PR description)
+- The suggested status transition
+
+Example for `plan-created`:
+
+```markdown
+**Plan created** — `plans/feat-X.md`
+
+Sections:
+- Phase 1: Schema doc
+- Phase 2: Linear destination skills
+- ...
+
+Tasks: 7 ordered items.
+
+Next: implementation begins. Suggested status: **Todo** (label: `status:ready`).
+```
+
+## Phase 3 — Post Comment
+
+Call `mcp__linear-server__save_comment({issueId: <id>, body: <comment>})`.
+
+## Phase 4 — Update Status Label (when caller requests)
+
+If the caller passes `--update-label`, update the `status:*` label set via `mcp__linear-server__save_issue`:
+
+- `plan-created` → add `status:ready`
+- `implementation-in-progress` → remove `status:ready`, add `status:in-progress`
+- `pr-ready` → remove `status:in-progress`, add `status:code-review`
+- `pr-merged` → remove `status:code-review`, add `status:done`
+
+If the requested label doesn't exist on the team, create it via `mcp__linear-server__create_issue_label`.
+
+Verify exactly one `status:*` label remains after the update — having two simultaneously breaks the build-queue invariant.
+
+Without `--update-label`, this skill posts the comment only and does NOT touch labels.
+
+## Rules
+
+- Never auto-transition the native Linear `state` — only the label, and only when the caller explicitly asks.
+- Never post empty or minimal comments — if a milestone has no meaningful content, skip the post.
+- Do not delete prior milestone comments. They are the audit trail.
+- If `save_comment` fails, retry once. If it fails again, surface the error.

package/plugins/lisa/skills/linear-to-tracker/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: linear-to-tracker
 description: >
-  Break down a Linear PRD (a Linear Project) into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA or GitHub Issues per .lisa.config.json). Use this skill
+  Break down a Linear PRD (a Linear Project) into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json). Use this skill
   whenever the user shares a Linear project URL and wants it converted into tracker tickets, or asks to
   "break down this Linear project", "create tickets from a Linear project", "turn this Linear PRD into tickets", or similar. This skill mirrors `lisa:notion-to-tracker` and `lisa:confluence-to-tracker` for projects
   whose PRDs live in Linear — the workflow, gates, dry-run mode, and validation rules are identical;
@@ -11,7 +11,7 @@ allowed-tools: ["Skill", "Bash", "mcp__linear-server__get_project", "mcp__linear
 
 # Linear PRD to Tracker Breakdown
 
-Convert a Linear PRD (a Linear **Project**) into a structured ticket hierarchy in the configured destination tracker (JIRA or GitHub Issues per .lisa.config.json): Epics > Stories > Sub-tasks.
+Convert a Linear PRD (a Linear **Project**) into a structured ticket hierarchy in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json): Epics > Stories > Sub-tasks.
 Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
 
 This skill is the Linear counterpart of `lisa:notion-to-tracker` and `lisa:confluence-to-tracker`. The three skills share the same phases, gates, dry-run contract, and per-ticket validation logic. Only the PRD-side fetch tools differ. When changing workflow logic, change ALL THREE skills together so the source vendors stay behaviorally identical.
@@ -101,13 +101,20 @@ Extract the trailing `<short-id>` (the alphanumeric segment after the last `-` i
 
 ## Configuration
 
-This skill reads project-specific configuration from environment variables. If these are not set, ask the user for the values before proceeding.
+This skill reads project configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key) and operational E2E test config from environment variables. See the `config-resolution` rule for the full schema.
+
+### From `.lisa.config.json`
+
+This skill is a **PRD source** (Linear); destination tracker resolution is handled by `lisa:tracker-write` and `lisa:tracker-validate` internally — this skill does NOT read `tracker` directly. The relevant config for the source side:
+
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `linear.workspace` | Linear workspace slug (used for URL synthesis on remote links) | always |
+
+### From environment variables (E2E test config — operational, not tracker)
 
 | Variable | Purpose | Example |
 |----------|---------|---------|
-| `JIRA_PROJECT` | JIRA project key for ticket creation | `SE` |
-| `JIRA_SERVER` | Atlassian instance URL (site host) | `mycompany.atlassian.net` |
-| `LINEAR_WORKSPACE` | Linear workspace slug (used for URL synthesis on JIRA remote links) | `acme` |
 | `E2E_TEST_PHONE` | Test user phone number for verification plans | `0000000099` |
 | `E2E_TEST_OTP` | Test user OTP code | `555555` |
 | `E2E_TEST_ORG` | Test organization name | `Arsenal` |
@@ -144,17 +151,17 @@ PRDs typically reference external design, UX, and data artifacts (Figma files, L
    - Embedded images and file attachments referenced in the project / documents
    - Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
 
-2. **Classify each artifact and apply taxonomy rules** by invoking the `lisa:jira-source-artifacts` skill. That skill is the single source of truth for: domains (`ui-design` / `ux-flow` / `data` / `ops` / `reference`), per-tool classification rules (Figma `/proto/` vs design, Lovable as `ux-flow`, Loom, screenshots), and coverage smells. Do not restate the rules here — invoke the skill so any drift in the rules propagates uniformly.
+2. **Classify each artifact and apply taxonomy rules** by invoking the `lisa:tracker-source-artifacts` skill. That skill is the single source of truth for: domains (`ui-design` / `ux-flow` / `data` / `ops` / `reference`), per-tool classification rules (Figma `/proto/` vs design, Lovable as `ux-flow`, Loom, screenshots), and coverage smells. Do not restate the rules here — invoke the skill so any drift in the rules propagates uniformly.
 
 3. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable. The `source_page` lets you trace each reference back to where it appeared (project description vs a specific document title vs a specific sub-issue comment).
 
-4. **Surface coverage smells** as defined in `lisa:jira-source-artifacts` §5. Record any detected smells on the epic.
+4. **Surface coverage smells** as defined in `lisa:tracker-source-artifacts` §5. Record any detected smells on the epic.
 
 ### Phase 1.6: Source Precedence & Conflict Resolution
 
-Source precedence rules and cross-axis conflict handling are defined in `lisa:jira-source-artifacts` §3 and §4. Apply them during ticket synthesis: every conflict between artifacts must be recorded under `## Open Questions` on the affected ticket, never silently reconciled.
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-source-artifacts` §3 and §4. Apply them during ticket synthesis: every conflict between artifacts must be recorded under `## Open Questions` on the affected ticket, never silently reconciled.
 
-The existing-component reuse expectation is defined in `lisa:jira-source-artifacts` §7. Encode it on every UI-touching story.
+The existing-component reuse expectation is defined in `lisa:tracker-source-artifacts` §7. Encode it on every UI-touching story.
 
 ### Phase 2: Codebase + Live Product Research
 
@@ -174,7 +181,7 @@ Walkthrough findings are surfaced back to product via the orchestrating intake s
 
 For each epic identified in Phase 1, **invoke the `lisa:tracker-write` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
 
-- `project_key`: from `JIRA_PROJECT` config
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
 - `issue_type`: `Epic`
 - `summary`: epic title from the PRD
 - `description_body`: a draft of the 3-audience description containing:
@@ -202,7 +209,7 @@ For each Epic, plan two kinds of stories:
 
 For each story, **invoke `lisa:tracker-write`** with:
 
-- `project_key`: from `JIRA_PROJECT` config
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
 - `issue_type`: `Story`
 - `epic_parent`: the Epic key captured in Phase 3 (mandatory)
 - `summary`: prefixed per the naming convention above
@@ -230,7 +237,7 @@ Sub-tasks inherit their parent story's artifacts by reference (the parent link).
 
 ### Phase 5.5: Artifact Preservation Gate (mandatory)
 
-Run the preservation gate defined in `lisa:jira-source-artifacts` §8 against the artifacts extracted in Phase 1.5 and the tickets just created. Do NOT restate or modify the gate logic here — invoke the rules from `lisa:jira-source-artifacts`.
+Run the preservation gate defined in `lisa:tracker-source-artifacts` §8 against the artifacts extracted in Phase 1.5 and the tickets just created. Do NOT restate or modify the gate logic here — invoke the rules from `lisa:tracker-source-artifacts`.
 
 To run the gate, this skill must:
 

package/plugins/lisa/skills/linear-validate-issue/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: linear-validate-issue
+description: "Validates a proposed Linear work item spec (Project, Issue, or sub-Issue) — or an existing Linear item — against the organizational quality gates without writing anything. Returns a structured PASS/FAIL report per gate with concrete remediation. Single source of truth for what makes a valid Linear item — both the write path (linear-write-issue runs it pre-write) and the dry-run path (linear-to-tracker runs it during PRD intake) call this skill so the bar can never drift."
+allowed-tools: ["Bash", "mcp__linear-server__list_teams", "mcp__linear-server__get_team", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+---
+
+# Validate Linear Work Item: $ARGUMENTS
+
+Run all organizational quality gates against a Linear work item spec OR an existing Linear item. **This skill is read-only — it never writes to Linear.** The output is a structured report consumed by callers (`lisa:linear-write-issue` for pre-write gating, `lisa:linear-to-tracker` for PRD dry-run, `lisa:linear-verify` for post-write checks).
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override) for any feasibility lookups.
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+1. **An existing Linear identifier** (e.g. `ENG-123` for an Issue, or `<workspace>/project/<slug>-<id>` for a Project): fetch and validate the live state.
+2. **A proposed item spec** (YAML block, see schema below): validate as-is without touching Linear.
+
+### Spec schema
+
+```yaml
+issue_type: Story          # Epic | Story | Task | Bug | Spike | Sub-task | Improvement
+team_key: ENG
+summary: "[CU-1.2] Upload contract PDF from settings"
+priority: 3                # Linear native: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low
+parent_project_id: <uuid>  # Required for Story/Task/Improvement when in Epic context
+parent_issue_id: <uuid>    # Required for Sub-task (the Story Issue)
+description: |             # Full description text — every required section
+  ## Context / Business Value
+  ...
+
+  ## Technical Approach
+  ...
+
+  ## Acceptance Criteria
+  1. Given <precondition>
+     When <action>
+     Then <observable outcome>
+
+  ## Out of Scope
+  ...
+
+  ## Target Backend Environment
+  dev
+
+  ## Sign-in Required
+  Account: ...
+
+  ## Repository
+  backend-api
+
+  ## Validation Journey
+  ...
+
+# Behavioral flags — caller asserts these so the validator picks the right gates
+runtime_behavior_change: true     # → requires Target Backend Environment + Validation Journey
+authenticated_surface: true       # → requires Sign-in Required
+artifacts_attached: true          # → requires Source Precedence section
+relations: [{ id: "ENG-99", type: "blocked_by" }]   # known issue relations (may be empty)
+remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
+```
+
+If the caller passes only an identifier, fetch the item via `mcp__linear-server__get_issue` (Issue) or `mcp__linear-server__get_project` (Project), derive the same fields from the fetched data, then run gates.
+
+## Gates
+
+Gates are grouped into **Specification** (spec-only checks, no Linear lookups) and **Feasibility** (requires Linear lookups). The dry-run path may opt to run Specification gates only; the write path runs both.
+
+Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Categories drive how downstream callers (notably `lisa:linear-prd-intake`) translate failures into product-facing comments; `product_relevant=false` failures indicate internal data-quality problems the agent should fix itself rather than ask product to clarify.
+
+| Gate | Category | Product-relevant |
+|------|----------|------------------|
+| S1 Required core fields | `structural` | false |
+| S2 Summary format | `structural` | false |
+| S3 Description three audiences | `product-clarity` | true |
+| S4 Acceptance criteria in Gherkin | `acceptance-criteria` | true |
+| S5 Bug-specific content | `product-clarity` | true |
+| S6 Spike-specific content | `scope` | true |
+| S7 Project parent declared | `structural` | false |
+| S8 Target Backend Environment | `technical` | false |
+| S9 Sign-in Required | `technical` | false |
+| S10 Single-repo scope | `scope` | true |
+| S11 Validation Journey | `acceptance-criteria` | true |
+| S12 Source Precedence | `design-ux` | true |
+| S13 Relationship Search | `dependency` | true |
+| F1 Issue type valid in team | `structural` | false |
+| F2 Project parent exists and is in same team | `structural` | false |
+| F3 Linked items exist | `structural` | false |
+| F4 Required labels exist (or can be created) | `structural` | false |
+
+Category values are the same fixed set as `lisa:jira-validate-ticket`:
+
+- `product-clarity` — feature behavior or user intent unclear in the PRD
+- `acceptance-criteria` — pass/fail conditions missing or ambiguous
+- `design-ux` — visual or interaction spec missing
+- `scope` — boundary unclear, items overlap, split needed
+- `dependency` — blocked by another team / system / decision
+- `data` — data source / shape / volume unspecified
+- `technical` — engineering decision required
+- `structural` — internal data-quality problem the agent must fix itself, not surface to product
+
+### Specification Gates
+
+#### S1 — Required core fields
+
+`team_key`, `issue_type`, `summary`, `priority`, `description` must all be present and non-empty.
+
+#### S2 — Summary format
+
+- Single line, ≤ 100 characters
+- Imperative voice ("Add X", "Fix Y", not "Adding X" or "X is broken")
+- Bug / Task / Sub-task summaries SHOULD start with a `[repo-name]` prefix when the project convention uses one
+
+#### S3 — Description has all three audiences
+
+Description text must include all of these sections (case-insensitive `##` markdown headings):
+- `Context / Business Value` — stakeholder-facing
+- `Technical Approach` — developer-facing
+- `Acceptance Criteria` — coding-assistant-facing
+- `Out of Scope` — explicit non-coverage list
+
+Missing any → FAIL with name of missing section.
+
+#### S4 — Acceptance criteria in Gherkin
+
+Applies when `issue_type ∈ {Story, Task, Bug, Sub-task, Improvement}`.
+
+The `Acceptance Criteria` section must contain at least one criterion in `Given / When / Then` form. Reject prose-only criteria, "should work" language, or numbered lists without Given/When/Then verbs.
+
+#### S5 — Bug-specific content
+
+When `issue_type = Bug`, description must additionally include:
+- Reproduction steps
+- Expected vs. actual behavior
+- Environment where reproduced
+
+#### S6 — Spike-specific content
+
+When `issue_type = Spike`, description must include:
+- The question being answered
+- Definition of done (decision doc / prototype / findings deliverable)
+
+#### S7 — Project parent declared
+
+When `issue_type ∈ {Story, Task, Improvement}` AND the item is part of an Epic context, `parent_project_id` must be set. When `issue_type = Sub-task`, `parent_issue_id` must be set. (Validity of the IDs is checked in feasibility gates.)
+
+For top-level Bug / Spike not under an Epic, this gate is N/A.
+
+#### S8 — Target Backend Environment
+
+When `runtime_behavior_change = true`, description must contain `## Target Backend Environment` with one of `dev`, `staging`, `prod`. Skipped for doc-only / config-only / type-only / Epic.
+
+#### S9 — Sign-in Required
+
+When `authenticated_surface = true`, description must contain `## Sign-in Required` naming the account/role and credential source.
+
+If the spec doesn't set `authenticated_surface`, infer it: scan the description and AC for sign-in / login / "as a {role} user" / authenticated route signals. If signals present and no `Sign-in Required` section: FAIL.
+
+#### S10 — Repository section, single-repo scope
+
+When `issue_type ∈ {Bug, Task, Sub-task}`, description must contain `## Repository` naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation to split.
+
+Story / Epic / Spike / Improvement: skipped (may span repos).
+
+#### S11 — Validation Journey present
+
+When `runtime_behavior_change = true`, description must contain `## Validation Journey`. Skipped for doc-only / config-only / type-only / Epic.
+
+The caller controls strictness via `journey_followup: "auto"` or `"none"`:
+- `auto` (default): missing section returns `FAIL` with remediation `"Invoke lisa:linear-add-journey to append the section after create"`. The write path auto-fixes; dry-run path leaves it as a FAIL the caller must address.
+- `none`: missing section is a `FAIL` the caller will not auto-fix.
+
+#### S12 — Source Precedence (when artifacts attached)
+
+When `artifacts_attached = true`, description must include source-precedence guidance covering: business rules → PRD body, visual treatment → mocks, flow → prototypes, API/data → data artifacts. Cross-axis conflicts surfaced under `## Open Questions`.
+
+Accept either placement:
+- A dedicated `## Source Precedence` subsection, OR
+- A "Source Precedence" / "authoritative source" paragraph under `Technical Approach` covering the four axes.
+
+Detect by scanning for the phrase `Source Precedence` (case-insensitive) anywhere in the description AND verifying the four axes are each named. Missing the phrase OR any axis: FAIL with remediation naming the missing axes.
+
+#### S13 — Relationship Search documented
+
+The item must EITHER have at least one entry in `relations`, OR the description / a comment must contain a `## Relationship Search` block listing the git history queries and Linear MCP queries that were run with their outcomes.
+
+An item with zero relations and no documented search: FAIL.
+
+### Feasibility Gates (require Linear lookups; skip in dry-run if requested)
+
+#### F1 — Issue type valid in team
+
+For Issue types: confirm the team supports the issue type via `mcp__linear-server__get_team`. Linear issue types are typically per-team; check that the requested type exists.
+
+For Epic (Project): confirm the team allows projects.
+
+#### F2 — Project parent exists and is in same team
+
+When `parent_project_id` is set: fetch via `mcp__linear-server__get_project`, confirm it exists and belongs to the configured team.
+
+When `parent_issue_id` is set (Sub-task case): fetch via `mcp__linear-server__get_issue`, confirm the issue is non-Sub-task and in the same team / project.
+
+#### F3 — Linked items exist
+
+For each entry in `relations`, call `mcp__linear-server__get_issue` to confirm the identifier resolves. Flag broken identifiers.
+
+#### F4 — Required labels exist (or can be created)
+
+For each label referenced (`status:*`, `component:<name>`, `prd-*`), confirm via `mcp__linear-server__list_issue_labels` (or `list_project_labels` for Project labels) that it exists OR is creatable. Linear labels are team-scoped or workspace-scoped; flag if the requested scope is wrong.
+
+## Execution
+
+1. Parse `$ARGUMENTS`. If it's an identifier, fetch the item and derive the spec from the fetched fields. Otherwise parse the YAML spec.
+2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})` if any feasibility gate will run.
+3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
+4. Unless the caller passed `--spec-only` (dry-run), run every Feasibility gate. Collect results.
+5. Emit the report below.
+
+## Output
+
+Output is a single fenced text block. Callers parse it; do not add free-form prose around it.
+
+```text
+## linear-validate-issue: <IDENTIFIER-or-SUMMARY>
+
+### Specification Gates
+- [PASS|FAIL|N/A] S1 Required core fields — <one-line reason>
+- [PASS|FAIL|N/A] S2 Summary format — <one-line reason>
+- [PASS|FAIL|N/A] S3 Description three audiences — <one-line reason>
+- [PASS|FAIL|N/A] S4 Acceptance criteria in Gherkin — <one-line reason>
+- [PASS|FAIL|N/A] S5 Bug-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S6 Spike-specific content — <one-line reason>
+- [PASS|FAIL|N/A] S7 Project parent declared — <one-line reason>
+- [PASS|FAIL|N/A] S8 Target Backend Environment — <one-line reason>
+- [PASS|FAIL|N/A] S9 Sign-in Required — <one-line reason>
+- [PASS|FAIL|N/A] S10 Single-repo scope — <one-line reason>
+- [PASS|FAIL|N/A] S11 Validation Journey — <one-line reason>
+- [PASS|FAIL|N/A] S12 Source Precedence — <one-line reason>
+- [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
+
+### Feasibility Gates  (omit when --spec-only)
+- [PASS|FAIL|N/A] F1 Issue type valid in team — <one-line reason>
+- [PASS|FAIL|N/A] F2 Project parent exists and is in same team — <one-line reason>
+- [PASS|FAIL|N/A] F3 Linked items exist — <one-line reason>
+- [PASS|FAIL|N/A] F4 Required labels exist (or can be created) — <one-line reason>
+
+### Verdict: PASS | FAIL
+### Failures: <count>
+### Failure details
+- gate: <gate-id>
+  category: <category>
+  product_relevant: <true|false>
+  what: <plain-language description, no gate-IDs, no Linear jargon>
+  recommendation: <1–3 concrete options>
+- gate: ...
+```
+
+The verdict is `PASS` if and only if every applicable gate is `PASS`. Any `FAIL` makes the verdict `FAIL`. `N/A` does not affect the verdict.
+
+## Rules
+
+- Never write to Linear. The `allowed-tools` list intentionally excludes any `save_*` tool.
+- Never auto-fix the spec. This skill reports gaps; callers decide what to do.
+- Never silently skip a gate. If a gate genuinely doesn't apply, return `N/A` with the reason.
+- The `what` and `recommendation` fields must be concrete and product-readable — the dry-run path turns each failure into a Linear comment. Vague guidance is useless; always give 1–3 candidate resolutions.
+- Never emit a category outside the fixed set.
+- `product_relevant` is determined by the gate, not by the failure context.