@codyswann/lisa 1.93.0 → 1.95.0

package/package.json

@@ -78,7 +78,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/agents/jira-agent.md

@@ -34,13 +34,26 @@ Pass the resulting context bundle verbatim to every downstream agent. Extract cr
 
 **Never act on a ticket in isolation.** If the bundle shows open blockers, flag them and stop. If it shows an epic sibling in progress with a different assignee, surface that before proceeding so work isn't duplicated.
 
-### 2. Validate Ticket Quality
+### 2. Validate Ticket Quality (Pre-flight Gate)
 
-Use the `jira-verify` skill to check:
-- Epic relationship exists (ticket belongs to an epic)
-- Description is complete enough for a coding assistant to act on
+Use the `jira-verify` skill to check the ticket against organizational standards:
+- Epic relationship exists (non-bug, non-epic tickets)
+- Description quality (audience sections, Gherkin acceptance criteria)
+- Validation Journey present (runtime-behavior tickets)
+- Target backend environment named in description (runtime-behavior tickets)
+- Sign-in credentials named in description (when ticket touches authenticated surfaces)
+- Single-repo scope (Bug / Task / Sub-task)
+- Relationship discovery (≥1 link or documented git+JQL search)
 
-If validation fails, update the ticket with what's missing and escalate.
+**Gating behavior — this is the one place auto-transitioning is allowed:**
+
+If `jira-verify` returns `FAIL` on any of the above, do NOT continue:
+1. Transition the ticket status to `Blocked` (use `mcp__atlassian__transitionJiraIssue` or equivalent).
+2. Reassign the ticket to the **Reporter** (the human who filed it — not the Creator field, which may be a bot/integration).
+3. Post a comment using `mcp__atlassian__addCommentToJiraIssue` listing each missing requirement with a one-line remediation. Prefix with `[{repo}]`.
+4. Stop. Do not run triage, do not delegate to a flow, do not start work.
+
+If `jira-verify` returns `PASS`, proceed to Step 3.
 
 ### 3. Analytical Triage Gate
 
@@ -105,8 +118,8 @@ Based on the milestone, suggest (but don't auto-transition):
 
 ## Rules
 
-- Never auto-transition ticket status — always suggest and let the human confirm
+- Never auto-transition ticket status, with one explicit exception: when `jira-verify` returns `FAIL` for the pre-flight gate (Step 2), transition to `Blocked` and reassign to the Reporter. Every other status change remains a suggestion the human confirms.
 - Always read the full ticket graph via `jira-read-ticket` before determining intent — don't rely on ticket type alone
 - Never create or materially edit a ticket by calling MCP write tools directly — always delegate to `jira-write-ticket` so relationships, Gherkin criteria, and metadata gates are enforced
-- If sign-in credentials are in the ticket, extract and pass them to the flow
-- If the ticket has a Validation Journey section, pass it to the verifier agent
+- If sign-in credentials are in the ticket, extract and pass them to the flow. If the ticket touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.
+- If the ticket has a Validation Journey section, pass it to the verifier agent. The Validation Journey's local-verification step must point at the target backend environment named in the description (for FE work, that's the deployed backend QA reported against).

package/plugins/lisa/rules/base-rules.md

@@ -68,7 +68,15 @@ JIRA Discipline:
 - If working on a JIRA issue, update the issue as you work through it. For example, if working on a Bug Triage, update the issue with your questions/feedback/suggestions.
 - When reading a JIRA issue, always read ALL comments on the ticket — not just the description. Comments contain critical context: stakeholder decisions, scope changes, blockers, triage findings from other repos, and implementation notes. Use the Atlassian MCP or `jira issue view <TICKET_ID> --comments 100` to fetch them.
 - When requesting clarification on a JIRA issue, post the question as a comment using ADF (Atlassian Document Format) and @mention the Reporter so they receive a notification.
-- When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked.
+- When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked. Relationship discovery is mandatory on every create and update — search BOTH the local git history (`git log --all --grep=<keyword>`, `git log -- <path>`) AND Jira (JQL by component, keyword, label, epic siblings) before declaring "no related work." Record the searches you ran and their outcomes in the description (or a comment) so a reviewer can see the search was real.
+- Ticket scope by type: Bug, Task, and Sub-task tickets MUST be single-repo (one work unit, one repo). Epic, Spike, and Story tickets MAY span multiple repos. If a Bug/Task/Sub-task crosses repos, split it.
+- Ticket descriptions MUST contain everything an implementer needs to start work without asking the reporter. In particular:
+  - **Target backend environment** (`dev` / `staging` / `prod`) when the ticket has runtime behavior. QA/product report against a deployed env; the implementer verifies locally first against that backend before CI/CD. Skip only for doc-only, config-only, type-only, or Epic tickets.
+  - **Sign-in account / credentials** when the work requires being signed in. Name the account (or the source — 1Password item, env var, seeded fixture) and the role. Omit entirely when sign-in is not required.
+  - **Gherkin acceptance criteria** (Given/When/Then) so the implementer can verify behavior without guessing.
+  - **Relationship discovery evidence** — either an issue link to a related ticket, or a documented search showing none was found (see Relationship Discovery in jira-verify).
+- Ticket metadata MUST include an **epic parent** for non-bug, non-epic tickets so every Story/Task/Sub-task is traceable to a strategic goal.
+- Pre-flight gate before starting work on any ticket: if the description is missing target backend environment (when applicable), sign-in credentials (when applicable), Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence, transition the ticket to Blocked, reassign to the **Reporter**, and post a comment listing exactly what is missing. Do not start work. This is the one place where auto-transitioning status is allowed.
 - When checking for associated pull requests on a JIRA issue, check the **Development panel** — not just comments or description text. The Development panel shows PRs, commits, branches, and builds linked via the GitHub-Jira integration. Query it via the dev-status API:
   ```bash
   ISSUE_ID=$(curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \

package/plugins/lisa/skills/jira-verify/SKILL.md

@@ -43,6 +43,62 @@ This check is skipped for:
 - Type-definition-only tickets (no runtime effect)
 - Epic-level tickets (journeys belong on child stories/tasks)
 
+### 4. Target Backend Environment
+
+**Rule**: Tickets that change runtime behavior MUST name a target backend environment in the description.
+
+Look for an `h2. Target Backend Environment` section (or equivalent named callout) containing one of `dev`, `staging`, or `prod`. The check is skipped for the same exclusions as the Validation Journey (doc-only, config-only, type-only, Epic).
+
+- If present and valid: PASS
+- If missing or unparseable: FAIL — recommend adding the section. QA/product report against a deployed env; the implementer needs to know which backend to point local at before CI/CD.
+
+### 5. Sign-in Credentials (Conditional)
+
+**Rule**: If the ticket touches an authenticated surface, the description MUST name the account/role to sign in as and where to get credentials.
+
+A surface is "authenticated" if any of these signals are present in the description, acceptance criteria, or Validation Journey:
+- Verbs like "log in", "sign in", "as a {role} user", "authenticated"
+- Routes/screens that require auth in this product
+- Roles named (admin, customer, partner, etc.)
+
+If those signals are present, look for an `h2. Sign-in Required` section naming an account or credential source.
+
+- If signals absent: PASS (sign-in not required)
+- If signals present and section present: PASS
+- If signals present and section missing: FAIL — recommend adding it. Implementers must not have to guess which account to use.
+
+### 6. Single-Repo Scope (Bug / Task / Sub-task)
+
+**Rule**: Bug, Task, and Sub-task tickets MUST cover one repo. Epic, Spike, and Story may span multiple repos.
+
+Check by inspecting the description's `h2. Repository` section (or equivalent) and any explicit cross-repo references in the description / acceptance criteria.
+
+- Bug / Task / Sub-task that names exactly one repo: PASS
+- Bug / Task / Sub-task that names multiple repos OR has acceptance criteria spanning repos: FAIL — recommend splitting into per-repo tickets under a parent Story/Epic.
+- Other types: skipped.
+
+### 7. Relationship Discovery
+
+**Rule**: Every ticket MUST have either at least one issue link OR a documented relationship search showing none was found.
+
+- If the ticket has any issue link (`blocks`, `is blocked by`, `relates to`, `duplicates`, `clones`): PASS
+- If no links but the description (or a comment) contains a `## Relationship Search` block listing the git and JQL queries that were run with their outcomes: PASS
+- If no links and no documented search: FAIL — recommend running `/jira-write-ticket` (or its discovery phase) to capture the search.
+
 ## Execute Verification
 
-Retrieve ticket details, run all checks, and provide specific improvement recommendations for any failures.
+Retrieve ticket details, run all checks, and produce a single output block. For each FAIL include the specific remediation. The caller (typically `jira-agent`) uses the FAIL list to decide whether to gate work — see the agent's pre-flight gate.
+
+```text
+## jira-verify: <TICKET-KEY>
+- Epic parent: PASS | FAIL — <reason>
+- Description quality: PASS | FAIL — <reason>
+- Validation Journey: PASS | FAIL | N/A — <reason>
+- Target backend environment: PASS | FAIL | N/A — <reason>
+- Sign-in credentials: PASS | FAIL | N/A — <reason>
+- Single-repo scope: PASS | FAIL | N/A — <reason>
+- Relationship discovery: PASS | FAIL — <reason>
+
+## Verdict: PASS | FAIL
+## Missing requirements: [list of FAILed checks, or "none"]
+```

package/plugins/lisa/skills/jira-write-ticket/SKILL.md

@@ -26,13 +26,16 @@ Required fields (stop and ask if missing — do not invent values):
 | Field | Required For | Notes |
 |-------|--------------|-------|
 | Project key | CREATE | Call `getVisibleJiraProjects` if unknown |
-| Issue type | CREATE | Story, Task, Bug, Epic, Spike, Improvement |
+| Issue type | CREATE | Story, Task, Bug, Epic, Spike, Sub-task, Improvement |
 | Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
 | Description | CREATE, UPDATE | Multi-section — see Phase 3 |
 | Epic parent | Non-bug, non-epic | Enforced by `jira-verify` |
 | Priority | CREATE | Default to project default if unstated |
-| Acceptance criteria | Story, Task, Bug, Improvement | Gherkin — see Phase 3 |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 |
 | Validation Journey | Runtime-behavior changes | Delegate to `/jira-add-journey` |
+| Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only tickets. |
+| Sign-in account / credentials | Tickets that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description (Phase 3). Omit when sign-in is not required. |
+| Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
 
 Optional but recommended: assignee, components, fix versions, labels, sprint, story points, reporter.
 
@@ -62,6 +65,26 @@ h2. Acceptance Criteria
 h2. Out of Scope
 [Explicit list of what this ticket does NOT cover. Forces scope discipline.]
 
+h2. Target Backend Environment
+[Required when the ticket changes runtime behavior. One of: dev / staging / prod.
+ This is the environment QA/product reported against and the backend the
+ implementer points their local stack at during verification before CI/CD.
+ Backend-only tickets state the deployed env they target. Skip section
+ entirely for doc-only, config-only, or type-only tickets.]
+
+h2. Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role to sign in as, where to get the credentials
+ (1Password item name, env var, seeded fixture), and any MFA/SSO notes.
+ Omit the section entirely when sign-in is not required — its absence
+ means "no sign-in needed for this ticket."]
+
+h2. Repository
+[Required for Bug / Task / Sub-task. Name the single repo this ticket covers.
+ If the work spans repos, this ticket type is wrong — split into per-repo
+ Tasks/Subtasks under a parent Story or Epic. Epic / Spike / Story may
+ list multiple repos.]
+
 h2. Validation Journey
 [Delegate to /jira-add-journey if the ticket changes runtime behavior.
  Skip only for doc-only, config-only, or type-only tickets.]
@@ -72,6 +95,7 @@ Rules:
 - Every criterion is independently verifiable (UI, API, data, or performance check).
 - If the ticket is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
 - If the ticket is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings).
+- If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials.
 
 ## Phase 4 — Relationship Discovery (Mandatory)
 
@@ -91,7 +115,24 @@ If the ticket is not a Bug and not an Epic, it MUST have an epic parent:
 
 ### 4b. Related Tickets
 
-Run targeted JQL searches to surface candidate links. Present candidates to the human (or record them on the ticket as a comment) before skipping. Suggested searches:
+Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the ticket.
+
+**Search 1: local git history** (catches PRs/commits that touched the same area but were never linked to a ticket):
+
+```bash
+# Commits mentioning the keyword
+git log --all --oneline --grep="<keyword>"
+
+# Commits that touched the relevant paths
+git log --all --oneline -- <path-or-glob>
+
+# Recent activity in this area (last 90 days)
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling ticket worth linking.
+
+**Search 2: Jira JQL** (catches open and recently-closed tickets):
 
 ```jql
 # Open tickets touching the same component
@@ -105,8 +146,13 @@ project = <PROJECT> AND (summary ~ "<keyword>" OR description ~ "<keyword>") AND
 
 # Recent tickets touching the same labels
 project = <PROJECT> AND labels in (<labels>) AND updated >= -30d
+
+# Recently closed tickets in the same area (catches duplicates of work just shipped)
+project = <PROJECT> AND component = "<component>" AND status = Done AND updated >= -30d
 ```
 
+**Record the outcome.** Add a `## Relationship Search` subsection (or a comment if updating an existing ticket) listing the queries you ran and what they returned. If the searches yielded nothing, write that explicitly — "Searched git history for `<keywords>` and JQL for component=`X`, label=`Y`, epic siblings; no related work found." A ticket with zero links and no documented search is rejected.
+
 For each candidate, classify the relationship:
 
 | Link Type | When to Use |
@@ -194,7 +240,9 @@ Skip this step only on UPDATE when no material change was made.
 ## Rules
 
 - Never create a non-bug ticket without an epic parent.
-- Never skip relationship discovery — record "none found" explicitly if the search returned nothing.
+- Never skip relationship discovery — both the git history search AND the JQL search must run, and their outcomes must be recorded on the ticket. "None found" is acceptable only when it's documented.
+- Never create a Bug, Task, or Sub-task that spans multiple repos. Split it before creating.
+- Never include a runtime-behavior ticket without a target backend environment, and never include an authenticated-surface ticket without sign-in credentials in the description.
 - Never invent custom field values. If the project requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
 - All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `jira-create`) should delegate here rather than calling the MCP write tools directly.

package/plugins/lisa/skills/ticket-triage/SKILL.md

@@ -10,6 +10,22 @@ Perform analytical triage on the JIRA ticket. The caller MUST have run `jira-rea
 
 Repository name for scoped labels and comment headers: determine via `basename $(git rev-parse --show-toplevel)`.
 
+## Phase 0 -- Pre-flight Description Gate
+
+Before any analytical work, confirm the ticket carries the content an implementer needs to start. The caller should already have run `jira-verify`; this phase consumes its output. If `jira-verify` returned `FAIL` for any of the following, emit `BLOCKED` immediately with the missing-requirements list and skip to Phase 6:
+
+- Epic parent missing (non-bug, non-epic)
+- Description quality failures (no Gherkin acceptance criteria, missing audience sections)
+- Validation Journey missing on a runtime-behavior ticket
+- Target backend environment missing on a runtime-behavior ticket
+- Sign-in credentials missing on a ticket that touches authenticated surfaces
+- Single-repo scope violated (Bug / Task / Sub-task spanning repos)
+- Relationship discovery missing (no links AND no documented git+JQL search)
+
+The caller (jira-agent) is responsible for transitioning the ticket to `Blocked`, reassigning to the **Reporter**, and posting a comment listing the missing requirements. This skill only emits the verdict and the missing-requirements list.
+
+If `jira-verify` returned `PASS` for all the above, proceed to Phase 1.
+
 ## Phase 1 -- Relevance Check
 
 Search the local codebase using Glob and Grep for code related to the ticket's subject matter:
@@ -123,7 +139,7 @@ Every verification method must be specific enough that an automated agent could
 Evaluate the findings and produce exactly one verdict:
 
 - **`NOT_RELEVANT`** -- No relevant code was found in this repository (Phase 1). The caller should add the triage label and skip implementation in this repo.
-- **`BLOCKED`** -- Blocking conditions were found in Phase 1.5 (open blockers, duplicate-of-open) and/or ambiguities were found in Phase 3. Work MUST NOT proceed until resolved by a human. The caller should post findings, add the triage label, and STOP.
+- **`BLOCKED`** -- Blocking conditions were found in Phase 0 (missing required description content), Phase 1.5 (open blockers, duplicate-of-open), and/or Phase 3 (ambiguities). Work MUST NOT proceed until resolved by a human. When the block is from Phase 0, the caller (jira-agent) MUST transition the ticket to `Blocked` and reassign to the Reporter — not just leave it in place. For Phase 1.5 / Phase 3 blocks, post findings, add the triage label, and STOP.
 - **`PASSED_WITH_FINDINGS`** -- No ambiguities, but edge cases or verification findings were identified. Work can proceed. The caller should post findings and add the triage label.
 - **`PASSED`** -- No ambiguities, edge cases, or verification gaps found. Work can proceed. The caller should add the triage label.
 
@@ -159,4 +175,5 @@ Structure all output with clear section headers so the caller can parse and post
 The caller is responsible for:
 1. Posting the findings as comments on the ticket (using whatever Jira mechanism is available)
 2. Adding the `claude-triaged-{repo}` label to the ticket
-3. If `BLOCKED`: stopping all work and reporting the ambiguities to the human
+3. If `BLOCKED` due to Phase 0 (missing required description content): transitioning the ticket to `Blocked`, reassigning to the **Reporter**, posting a comment listing the missing requirements, and stopping all work.
+4. If `BLOCKED` due to Phase 1.5 (open blockers, duplicate-of-open) or Phase 3 (ambiguities): stopping all work and reporting to the human; do NOT auto-transition status in these cases.

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "1.93.0",
+  "version": "1.95.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/agents/jira-agent.md

@@ -34,13 +34,26 @@ Pass the resulting context bundle verbatim to every downstream agent. Extract cr
 
 **Never act on a ticket in isolation.** If the bundle shows open blockers, flag them and stop. If it shows an epic sibling in progress with a different assignee, surface that before proceeding so work isn't duplicated.
 
-### 2. Validate Ticket Quality
+### 2. Validate Ticket Quality (Pre-flight Gate)
 
-Use the `jira-verify` skill to check:
-- Epic relationship exists (ticket belongs to an epic)
-- Description is complete enough for a coding assistant to act on
+Use the `jira-verify` skill to check the ticket against organizational standards:
+- Epic relationship exists (non-bug, non-epic tickets)
+- Description quality (audience sections, Gherkin acceptance criteria)
+- Validation Journey present (runtime-behavior tickets)
+- Target backend environment named in description (runtime-behavior tickets)
+- Sign-in credentials named in description (when ticket touches authenticated surfaces)
+- Single-repo scope (Bug / Task / Sub-task)
+- Relationship discovery (≥1 link or documented git+JQL search)
 
-If validation fails, update the ticket with what's missing and escalate.
+**Gating behavior — this is the one place auto-transitioning is allowed:**
+
+If `jira-verify` returns `FAIL` on any of the above, do NOT continue:
+1. Transition the ticket status to `Blocked` (use `mcp__atlassian__transitionJiraIssue` or equivalent).
+2. Reassign the ticket to the **Reporter** (the human who filed it — not the Creator field, which may be a bot/integration).
+3. Post a comment using `mcp__atlassian__addCommentToJiraIssue` listing each missing requirement with a one-line remediation. Prefix with `[{repo}]`.
+4. Stop. Do not run triage, do not delegate to a flow, do not start work.
+
+If `jira-verify` returns `PASS`, proceed to Step 3.
 
 ### 3. Analytical Triage Gate
 
@@ -105,8 +118,8 @@ Based on the milestone, suggest (but don't auto-transition):
 
 ## Rules
 
-- Never auto-transition ticket status — always suggest and let the human confirm
+- Never auto-transition ticket status, with one explicit exception: when `jira-verify` returns `FAIL` for the pre-flight gate (Step 2), transition to `Blocked` and reassign to the Reporter. Every other status change remains a suggestion the human confirms.
 - Always read the full ticket graph via `jira-read-ticket` before determining intent — don't rely on ticket type alone
 - Never create or materially edit a ticket by calling MCP write tools directly — always delegate to `jira-write-ticket` so relationships, Gherkin criteria, and metadata gates are enforced
-- If sign-in credentials are in the ticket, extract and pass them to the flow
-- If the ticket has a Validation Journey section, pass it to the verifier agent
+- If sign-in credentials are in the ticket, extract and pass them to the flow. If the ticket touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.
+- If the ticket has a Validation Journey section, pass it to the verifier agent. The Validation Journey's local-verification step must point at the target backend environment named in the description (for FE work, that's the deployed backend QA reported against).

package/plugins/src/base/rules/base-rules.md

@@ -68,7 +68,15 @@ JIRA Discipline:
 - If working on a JIRA issue, update the issue as you work through it. For example, if working on a Bug Triage, update the issue with your questions/feedback/suggestions.
 - When reading a JIRA issue, always read ALL comments on the ticket — not just the description. Comments contain critical context: stakeholder decisions, scope changes, blockers, triage findings from other repos, and implementation notes. Use the Atlassian MCP or `jira issue view <TICKET_ID> --comments 100` to fetch them.
 - When requesting clarification on a JIRA issue, post the question as a comment using ADF (Atlassian Document Format) and @mention the Reporter so they receive a notification.
-- When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked.
+- When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked. Relationship discovery is mandatory on every create and update — search BOTH the local git history (`git log --all --grep=<keyword>`, `git log -- <path>`) AND Jira (JQL by component, keyword, label, epic siblings) before declaring "no related work." Record the searches you ran and their outcomes in the description (or a comment) so a reviewer can see the search was real.
+- Ticket scope by type: Bug, Task, and Sub-task tickets MUST be single-repo (one work unit, one repo). Epic, Spike, and Story tickets MAY span multiple repos. If a Bug/Task/Sub-task crosses repos, split it.
+- Ticket descriptions MUST contain everything an implementer needs to start work without asking the reporter. In particular:
+  - **Target backend environment** (`dev` / `staging` / `prod`) when the ticket has runtime behavior. QA/product report against a deployed env; the implementer verifies locally first against that backend before CI/CD. Skip only for doc-only, config-only, type-only, or Epic tickets.
+  - **Sign-in account / credentials** when the work requires being signed in. Name the account (or the source — 1Password item, env var, seeded fixture) and the role. Omit entirely when sign-in is not required.
+  - **Gherkin acceptance criteria** (Given/When/Then) so the implementer can verify behavior without guessing.
+  - **Relationship discovery evidence** — either an issue link to a related ticket, or a documented search showing none was found (see Relationship Discovery in jira-verify).
+- Ticket metadata MUST include an **epic parent** for non-bug, non-epic tickets so every Story/Task/Sub-task is traceable to a strategic goal.
+- Pre-flight gate before starting work on any ticket: if the description is missing target backend environment (when applicable), sign-in credentials (when applicable), Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence, transition the ticket to Blocked, reassign to the **Reporter**, and post a comment listing exactly what is missing. Do not start work. This is the one place where auto-transitioning status is allowed.
 - When checking for associated pull requests on a JIRA issue, check the **Development panel** — not just comments or description text. The Development panel shows PRs, commits, branches, and builds linked via the GitHub-Jira integration. Query it via the dev-status API:
   ```bash
   ISSUE_ID=$(curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \

package/plugins/src/base/skills/jira-verify/SKILL.md

@@ -43,6 +43,62 @@ This check is skipped for:
 - Type-definition-only tickets (no runtime effect)
 - Epic-level tickets (journeys belong on child stories/tasks)
 
+### 4. Target Backend Environment
+
+**Rule**: Tickets that change runtime behavior MUST name a target backend environment in the description.
+
+Look for an `h2. Target Backend Environment` section (or equivalent named callout) containing one of `dev`, `staging`, or `prod`. The check is skipped for the same exclusions as the Validation Journey (doc-only, config-only, type-only, Epic).
+
+- If present and valid: PASS
+- If missing or unparseable: FAIL — recommend adding the section. QA/product report against a deployed env; the implementer needs to know which backend to point local at before CI/CD.
+
+### 5. Sign-in Credentials (Conditional)
+
+**Rule**: If the ticket touches an authenticated surface, the description MUST name the account/role to sign in as and where to get credentials.
+
+A surface is "authenticated" if any of these signals are present in the description, acceptance criteria, or Validation Journey:
+- Verbs like "log in", "sign in", "as a {role} user", "authenticated"
+- Routes/screens that require auth in this product
+- Roles named (admin, customer, partner, etc.)
+
+If those signals are present, look for an `h2. Sign-in Required` section naming an account or credential source.
+
+- If signals absent: PASS (sign-in not required)
+- If signals present and section present: PASS
+- If signals present and section missing: FAIL — recommend adding it. Implementers must not have to guess which account to use.
+
+### 6. Single-Repo Scope (Bug / Task / Sub-task)
+
+**Rule**: Bug, Task, and Sub-task tickets MUST cover one repo. Epic, Spike, and Story may span multiple repos.
+
+Check by inspecting the description's `h2. Repository` section (or equivalent) and any explicit cross-repo references in the description / acceptance criteria.
+
+- Bug / Task / Sub-task that names exactly one repo: PASS
+- Bug / Task / Sub-task that names multiple repos OR has acceptance criteria spanning repos: FAIL — recommend splitting into per-repo tickets under a parent Story/Epic.
+- Other types: skipped.
+
+### 7. Relationship Discovery
+
+**Rule**: Every ticket MUST have either at least one issue link OR a documented relationship search showing none was found.
+
+- If the ticket has any issue link (`blocks`, `is blocked by`, `relates to`, `duplicates`, `clones`): PASS
+- If no links but the description (or a comment) contains a `## Relationship Search` block listing the git and JQL queries that were run with their outcomes: PASS
+- If no links and no documented search: FAIL — recommend running `/jira-write-ticket` (or its discovery phase) to capture the search.
+
 ## Execute Verification
 
-Retrieve ticket details, run all checks, and provide specific improvement recommendations for any failures.
+Retrieve ticket details, run all checks, and produce a single output block. For each FAIL include the specific remediation. The caller (typically `jira-agent`) uses the FAIL list to decide whether to gate work — see the agent's pre-flight gate.
+
+```text
+## jira-verify: <TICKET-KEY>
+- Epic parent: PASS | FAIL — <reason>
+- Description quality: PASS | FAIL — <reason>
+- Validation Journey: PASS | FAIL | N/A — <reason>
+- Target backend environment: PASS | FAIL | N/A — <reason>
+- Sign-in credentials: PASS | FAIL | N/A — <reason>
+- Single-repo scope: PASS | FAIL | N/A — <reason>
+- Relationship discovery: PASS | FAIL — <reason>
+
+## Verdict: PASS | FAIL
+## Missing requirements: [list of FAILed checks, or "none"]
+```

package/plugins/src/base/skills/jira-write-ticket/SKILL.md

@@ -26,13 +26,16 @@ Required fields (stop and ask if missing — do not invent values):
 | Field | Required For | Notes |
 |-------|--------------|-------|
 | Project key | CREATE | Call `getVisibleJiraProjects` if unknown |
-| Issue type | CREATE | Story, Task, Bug, Epic, Spike, Improvement |
+| Issue type | CREATE | Story, Task, Bug, Epic, Spike, Sub-task, Improvement |
 | Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
 | Description | CREATE, UPDATE | Multi-section — see Phase 3 |
 | Epic parent | Non-bug, non-epic | Enforced by `jira-verify` |
 | Priority | CREATE | Default to project default if unstated |
-| Acceptance criteria | Story, Task, Bug, Improvement | Gherkin — see Phase 3 |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 |
 | Validation Journey | Runtime-behavior changes | Delegate to `/jira-add-journey` |
+| Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only tickets. |
+| Sign-in account / credentials | Tickets that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description (Phase 3). Omit when sign-in is not required. |
+| Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
 
 Optional but recommended: assignee, components, fix versions, labels, sprint, story points, reporter.
 
@@ -62,6 +65,26 @@ h2. Acceptance Criteria
 h2. Out of Scope
 [Explicit list of what this ticket does NOT cover. Forces scope discipline.]
 
+h2. Target Backend Environment
+[Required when the ticket changes runtime behavior. One of: dev / staging / prod.
+ This is the environment QA/product reported against and the backend the
+ implementer points their local stack at during verification before CI/CD.
+ Backend-only tickets state the deployed env they target. Skip section
+ entirely for doc-only, config-only, or type-only tickets.]
+
+h2. Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role to sign in as, where to get the credentials
+ (1Password item name, env var, seeded fixture), and any MFA/SSO notes.
+ Omit the section entirely when sign-in is not required — its absence
+ means "no sign-in needed for this ticket."]
+
+h2. Repository
+[Required for Bug / Task / Sub-task. Name the single repo this ticket covers.
+ If the work spans repos, this ticket type is wrong — split into per-repo
+ Tasks/Subtasks under a parent Story or Epic. Epic / Spike / Story may
+ list multiple repos.]
+
 h2. Validation Journey
 [Delegate to /jira-add-journey if the ticket changes runtime behavior.
  Skip only for doc-only, config-only, or type-only tickets.]
@@ -72,6 +95,7 @@ Rules:
 - Every criterion is independently verifiable (UI, API, data, or performance check).
 - If the ticket is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
 - If the ticket is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings).
+- If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials.
 
 ## Phase 4 — Relationship Discovery (Mandatory)
 
@@ -91,7 +115,24 @@ If the ticket is not a Bug and not an Epic, it MUST have an epic parent:
 
 ### 4b. Related Tickets
 
-Run targeted JQL searches to surface candidate links. Present candidates to the human (or record them on the ticket as a comment) before skipping. Suggested searches:
+Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the ticket.
+
+**Search 1: local git history** (catches PRs/commits that touched the same area but were never linked to a ticket):
+
+```bash
+# Commits mentioning the keyword
+git log --all --oneline --grep="<keyword>"
+
+# Commits that touched the relevant paths
+git log --all --oneline -- <path-or-glob>
+
+# Recent activity in this area (last 90 days)
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling ticket worth linking.
+
+**Search 2: Jira JQL** (catches open and recently-closed tickets):
 
 ```jql
 # Open tickets touching the same component
@@ -105,8 +146,13 @@ project = <PROJECT> AND (summary ~ "<keyword>" OR description ~ "<keyword>") AND
 
 # Recent tickets touching the same labels
 project = <PROJECT> AND labels in (<labels>) AND updated >= -30d
+
+# Recently closed tickets in the same area (catches duplicates of work just shipped)
+project = <PROJECT> AND component = "<component>" AND status = Done AND updated >= -30d
 ```
 
+**Record the outcome.** Add a `## Relationship Search` subsection (or a comment if updating an existing ticket) listing the queries you ran and what they returned. If the searches yielded nothing, write that explicitly — "Searched git history for `<keywords>` and JQL for component=`X`, label=`Y`, epic siblings; no related work found." A ticket with zero links and no documented search is rejected.
+
 For each candidate, classify the relationship:
 
 | Link Type | When to Use |
@@ -194,7 +240,9 @@ Skip this step only on UPDATE when no material change was made.
 ## Rules
 
 - Never create a non-bug ticket without an epic parent.
-- Never skip relationship discovery — record "none found" explicitly if the search returned nothing.
+- Never skip relationship discovery — both the git history search AND the JQL search must run, and their outcomes must be recorded on the ticket. "None found" is acceptable only when it's documented.
+- Never create a Bug, Task, or Sub-task that spans multiple repos. Split it before creating.
+- Never include a runtime-behavior ticket without a target backend environment, and never include an authenticated-surface ticket without sign-in credentials in the description.
 - Never invent custom field values. If the project requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
 - All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `jira-create`) should delegate here rather than calling the MCP write tools directly.

package/plugins/src/base/skills/ticket-triage/SKILL.md

@@ -10,6 +10,22 @@ Perform analytical triage on the JIRA ticket. The caller MUST have run `jira-rea
 
 Repository name for scoped labels and comment headers: determine via `basename $(git rev-parse --show-toplevel)`.
 
+## Phase 0 -- Pre-flight Description Gate
+
+Before any analytical work, confirm the ticket carries the content an implementer needs to start. The caller should already have run `jira-verify`; this phase consumes its output. If `jira-verify` returned `FAIL` for any of the following, emit `BLOCKED` immediately with the missing-requirements list and skip to Phase 6:
+
+- Epic parent missing (non-bug, non-epic)
+- Description quality failures (no Gherkin acceptance criteria, missing audience sections)
+- Validation Journey missing on a runtime-behavior ticket
+- Target backend environment missing on a runtime-behavior ticket
+- Sign-in credentials missing on a ticket that touches authenticated surfaces
+- Single-repo scope violated (Bug / Task / Sub-task spanning repos)
+- Relationship discovery missing (no links AND no documented git+JQL search)
+
+The caller (jira-agent) is responsible for transitioning the ticket to `Blocked`, reassigning to the **Reporter**, and posting a comment listing the missing requirements. This skill only emits the verdict and the missing-requirements list.
+
+If `jira-verify` returned `PASS` for all the above, proceed to Phase 1.
+
 ## Phase 1 -- Relevance Check
 
 Search the local codebase using Glob and Grep for code related to the ticket's subject matter:
@@ -123,7 +139,7 @@ Every verification method must be specific enough that an automated agent could
 Evaluate the findings and produce exactly one verdict:
 
 - **`NOT_RELEVANT`** -- No relevant code was found in this repository (Phase 1). The caller should add the triage label and skip implementation in this repo.
-- **`BLOCKED`** -- Blocking conditions were found in Phase 1.5 (open blockers, duplicate-of-open) and/or ambiguities were found in Phase 3. Work MUST NOT proceed until resolved by a human. The caller should post findings, add the triage label, and STOP.
+- **`BLOCKED`** -- Blocking conditions were found in Phase 0 (missing required description content), Phase 1.5 (open blockers, duplicate-of-open), and/or Phase 3 (ambiguities). Work MUST NOT proceed until resolved by a human. When the block is from Phase 0, the caller (jira-agent) MUST transition the ticket to `Blocked` and reassign to the Reporter — not just leave it in place. For Phase 1.5 / Phase 3 blocks, post findings, add the triage label, and STOP.
 - **`PASSED_WITH_FINDINGS`** -- No ambiguities, but edge cases or verification findings were identified. Work can proceed. The caller should post findings and add the triage label.
 - **`PASSED`** -- No ambiguities, edge cases, or verification gaps found. Work can proceed. The caller should add the triage label.
 
@@ -159,4 +175,5 @@ Structure all output with clear section headers so the caller can parse and post
 The caller is responsible for:
 1. Posting the findings as comments on the ticket (using whatever Jira mechanism is available)
 2. Adding the `claude-triaged-{repo}` label to the ticket
-3. If `BLOCKED`: stopping all work and reporting the ambiguities to the human
+3. If `BLOCKED` due to Phase 0 (missing required description content): transitioning the ticket to `Blocked`, reassigning to the **Reporter**, posting a comment listing the missing requirements, and stopping all work.
+4. If `BLOCKED` due to Phase 1.5 (open blockers, duplicate-of-open) or Phase 3 (ambiguities): stopping all work and reporting to the human; do NOT auto-transition status in these cases.