@codyswann/lisa 2.189.7 → 2.189.8

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

@@ -1,314 +0,0 @@
----
-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: ["Skill", "Bash"]
----
-
-# 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" }]
-build_ready: true                 # caller asserts the build-ready role (status:ready) is/would be applied — see S15
-child_refs: ["ENG-601", "ENG-602"]   # known child work (sub-issues / project-member issues / blocked_by parentage) — see S15
-```
-
-If the caller passes only an identifier, fetch the item via `lisa:linear-access operation: get-issue` (Issue) or `lisa:linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa:linear-read-issue`) so S15 can classify the item — 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` | false |
-| S11 Validation Journey | `acceptance-criteria` | true |
-| S12 Source Precedence | `design-ux` | true |
-| S13 Relationship Search | `dependency` | true |
-| S14 Evidence manifest binding (leaf work units) | `acceptance-criteria` | true |
-| S15 Leaf-only build-ready | `structural` | false |
-| 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.
-
-A **build-ready leaf work unit** that is not part of an Epic context stands alone: a flat `Task` / `Improvement`, or a childless `Story` / `Spike` (no open child work) with `build_ready = true`, is an independently claimable leaf per `leaf-only-lifecycle` ("must not be stranded"), so a missing `parent_project_id` is `N/A`, not a FAIL. A `Sub-task` is exempt from this exception — it always requires `parent_issue_id`. This mirrors the leaf carve-out already in S10/S15.
-
-#### 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, Improvement}` — or a **build-ready childless Story/Spike** (a claimable leaf per `leaf-only-lifecycle`) — description must contain `## Repository` naming exactly one repo. Multiple repos OR cross-repo references in AC: FAIL with recommendation `"Split into per-repo work units under a shared parent Story (see lisa:task-decomposition step 1.5)"`.
-
-An **Epic** (a Linear Project), or a **Story/Spike that still holds child work** (or is not build-ready): skipped (may span repos — coordination containers, not claimable leaf work units).
-
-This gate is `product_relevant: false` because cross-repo work units are not a product question — they are a decomposition error. Callers (`lisa:linear-to-tracker`, `lisa:notion-to-tracker`, etc.) MUST pre-split cross-repo work into per-repo work units during the decomposition phase per `lisa:task-decomposition` step 1.5; an S10 failure here indicates the agent skipped that step and must auto-split + revalidate before writing, not surface a clarifying comment to product.
-
-#### 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.
-
-#### S14 — Evidence manifest binding (leaf work units)
-
-When `issue_type ∈ {Bug, Task, Sub-task, Improvement}` AND `runtime_behavior_change = true`, the `## Validation Journey` must declare at least one `[EVIDENCE: name]` marker. Each marker name must be kebab-case and unique within the item. These markers are the work unit's **evidence manifest** — the exact, enumerated set of artifacts that must be captured and attached before the item may be closed (see the "Per-Work-Unit Evidence Contract" section of the `verification` rule, the Definition of Done in `verification-lifecycle`, and the evidence-manifest gate in `tracker-evidence`).
-
-FAIL when the Validation Journey is present but declares zero `[EVIDENCE: name]` markers, or when any marker name is empty, duplicated, or not kebab-case. A behavior-changing work unit SHOULD declare both a success marker and an error/edge marker; a journey with only one marker passes but the remediation should recommend adding the error/edge case.
-
-This gate depends on S11. It is `N/A` for containers — a **Project** (the Epic equivalent), or any item with open child work (coordination containers, not work units) — and for leaf units with `runtime_behavior_change = false` (doc-only / config-only / type-only). If S11 fails because the Validation Journey is absent, S14 also FAILs (there is no manifest to bind) with remediation pointing back to `lisa:linear-add-journey`.
-
-#### S15 — Leaf-only build-ready
-
-Enforces the build-side of the vendor-neutral `leaf-only-lifecycle` rule: **only a leaf work unit may carry the build-ready role.** This is the symmetric write-side guard for the Linear validator — a stale or hand-applied `status:ready` label on a container is a lifecycle error and must FAIL here, regardless of how the item was produced. (Mirrors the "Build-ready label is leaf-only" rule that `lisa:linear-write-issue` applies at write time.)
-
-**When the gate applies.** Run S15 whenever the item is build-ready — i.e. `build_ready = true`, or the spec/live labels include `status:ready`. If the item is not build-ready, S15 is `N/A` (nothing claims a non-ready item, so the invariant is vacuous).
-
-**Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an item is a **container** if it has child work, whatever its declared type; otherwise the **issue type** decides. Determine child work from (in order) `child_refs`, native sub-issues, project-member issues (an Epic is modeled as a Linear Project), and `blocked_by` / parent references — the same hierarchy resolution `lisa:linear-read-issue` uses. When validating a live identifier, query sub-issues / project members alongside the item fetch.
-
-Apply this decision and FAIL the two invariant-violating cases:
-
-1. **Container with child work + build-ready** — child work is present (any type that has open children), AND build-ready. FAIL. A parent organizes work; it is never claimed and implemented directly. Its lifecycle state rolls up from its children.
-2. **Childless Epic/Project + build-ready** — `issue_type = Epic` (a Linear Project) with **no** child work, AND build-ready. Still FAIL: an Epic/Project is a pure rollup container by design, and a childless one is an incomplete decomposition or a mis-applied role, not an implementable unit. (A childless Story or Spike is **not** failed here — the childless-parent exception in `leaf-only-lifecycle` promotes every childless non-Epic type to a build-ready leaf.)
-
-PASS (the childless-parent exception) when the item is build-ready and is a **leaf work unit**: it has **no** open child work and `issue_type ≠ Epic` (i.e. `Bug, Task, Sub-task, Improvement`, or a childless `Story` / `Spike`). A flat Task/Bug, or a childless Story/Spike with no sub-issues, is a valid build-ready leaf and must not be stranded.
-
-| issue_type | has child work | build-ready | S15 |
-|---|---|---|---|
-| Bug / Task / Sub-task / Improvement / Story / Spike | no | yes | **PASS** (leaf) |
-| any type | yes | yes | **FAIL** (structurally a container) |
-| Epic (Project) | no | yes | **FAIL** (childless Epic/Project — pure rollup container, exception does not apply) |
-| any | any | no | **N/A** (not build-ready) |
-
-Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle. Move status:ready off this container onto its leaf children (or, for a childless Epic, decompose it into leaf children or reclassify it to a leaf type); a parent's lifecycle state rolls up from its children and is never set to ready directly."`
-
-`product_relevant: false` — a build-ready container is a lifecycle/decomposition error for the caller to repair, not a product question.
-
-### 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 `lisa:linear-access operation: 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 `lisa:linear-access operation: get-project`, confirm it exists and belongs to the configured team.
-
-When `parent_issue_id` is set (Sub-task case): fetch via `lisa:linear-access operation: 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 `lisa:linear-access operation: 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 `lisa:linear-access operation: list-issue-labels` (or `lisa:linear-access operation: 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 — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa:linear-read-issue`) so S15 can classify the item. Otherwise parse the YAML spec.
-2. Resolve team ID via `lisa:linear-access operation: 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>
-- [PASS|FAIL|N/A] S14 Evidence manifest binding — <one-line reason>
-- [PASS|FAIL|N/A] S15 Leaf-only build-ready — <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.

package/plugins/lisa-copilot/skills/linear-verify/SKILL.md

@@ -1,51 +0,0 @@
----
-name: linear-verify
-description: "Verifies a Linear work item meets organizational standards by fetching the live item and running it through lisa:linear-validate-issue. Catches anything dropped or reformatted on write — same gates as the pre-write check, but applied to what Linear actually stored. Read-only."
-allowed-tools: ["Bash", "Skill"]
----
-
-# Verify Linear Work Item: $ARGUMENTS
-
-Fetch the live Linear work item and run it through `lisa:linear-validate-issue`. This catches any field that was dropped or reformatted between the pre-write spec and what Linear stored.
-
-This skill is the destination of the `lisa:tracker-verify` shim when `tracker = "linear"`. Read-only — never writes.
-
-## Configuration
-
-Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
-
-## Input
-
-`$ARGUMENTS` is a Linear identifier:
-- An Issue identifier (e.g. `ENG-123`)
-- A Project URL or slug (e.g. `https://linear.app/<workspace>/project/<slug>-<id>`)
-
-If `$ARGUMENTS` is not parseable, stop and report.
-
-## Phase 1 — Resolve Context
-
-1. Read `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
-2. Resolve team ID via `lisa:linear-access operation: list-teams({query: <teamKey>})`.
-3. Determine entity type from the identifier shape:
-   - `<TEAM>-<n>` → Issue
-   - URL containing `/project/<slug>-<id>` → Project
-
-## Phase 2 — Fetch Live State
-
-Call `lisa:linear-access operation: get-issue` (for Issues) or `lisa:linear-access operation: get-project` (for Projects). Capture every field, label, relation, comment, milestone, and project membership.
-
-## Phase 3 — Delegate to Validator
-
-Pass the fetched item to `lisa:linear-validate-issue` (in identifier mode — let it derive the spec from the live state). The validator runs both Specification AND Feasibility gates against what Linear actually stored.
-
-## Phase 4 — Report
-
-Return the validator's report verbatim — same structured format as `lisa:linear-validate-issue`. Callers (especially `lisa:linear-write-issue` Phase 7) parse the verdict to decide whether to declare success.
-
-If the verdict is `FAIL`, the caller should fix the item and re-run verify. Never declare success on a `FAIL` verdict.
-
-## Rules
-
-- Never write to Linear. Read-only.
-- Never short-circuit the validator. Always run the full gate set.
-- If `get_issue` / `get_project` returns an access error, surface it and exit — don't pretend the item is fine.