@codyswann/lisa 2.119.1 → 2.121.0

package/plugins/lisa-copilot/hooks/install-pkgs.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+
+# Only run package installation when node_modules are missing.
+# This covers remote environments, new worktrees, fresh clones, and CI.
+if [ -d "node_modules" ]; then
+  exit 0
+fi
+
+# Detect package manager based on lock file presence
+if [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then
+  bun install
+elif [ -f "pnpm-lock.yaml" ]; then
+  pnpm install
+elif [ -f "yarn.lock" ]; then
+  yarn install
+elif [ -f "package-lock.json" ]; then
+  npm install
+else
+  npm install
+fi
+
+# The tools below use Linux-specific binaries and paths — skip on other platforms.
+if [ "$(uname -s)" != "Linux" ]; then
+  exit 0
+fi
+
+# Install Gitleaks for secret detection (pre-commit hook)
+echo "Installing Gitleaks for secret detection..."
+GITLEAKS_VERSION="8.18.4"
+curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" | tar -xz -C /usr/local/bin gitleaks
+echo "Gitleaks installed: $(gitleaks version)"
+
+# Install jira-cli for JIRA integration
+# The tarball nests the binary at jira_VERSION_linux_x86_64/bin/jira,
+# so we extract to a temp dir and copy the binary out.
+echo "Installing jira-cli for JIRA integration..."
+JIRA_CLI_VERSION="1.7.0"
+JIRA_TMPDIR=$(mktemp -d)
+curl -sSfL "https://github.com/ankitpokhrel/jira-cli/releases/download/v${JIRA_CLI_VERSION}/jira_${JIRA_CLI_VERSION}_linux_x86_64.tar.gz" \
+  | tar -xz -C "${JIRA_TMPDIR}"
+cp "${JIRA_TMPDIR}/jira_${JIRA_CLI_VERSION}_linux_x86_64/bin/jira" /usr/local/bin/jira
+chmod +x /usr/local/bin/jira
+rm -rf "${JIRA_TMPDIR}"
+echo "jira-cli installed: $(jira version)"
+
+# Install Chromium for Lighthouse CI (pre-push hook)
+# Playwright's bundled Chromium works with @lhci/cli
+echo "Installing Chromium for Lighthouse CI..."
+npx playwright install chromium
+
+# Find and export CHROME_PATH for Lighthouse CI
+# Use sort to ensure deterministic selection of the latest version
+CHROME_PATH=$(find ~/.cache/ms-playwright -name "chrome" -type f 2>/dev/null | grep "chrome-linux" | sort | tail -n 1)
+if [ -n "$CHROME_PATH" ]; then
+  # Append to ~/.bashrc for shell sessions (idempotent)
+  if ! grep -q "export CHROME_PATH=" ~/.bashrc 2>/dev/null; then
+    echo "export CHROME_PATH=\"$CHROME_PATH\"" >> ~/.bashrc
+  else
+    # Update existing CHROME_PATH in bashrc
+    sed -i "s|^export CHROME_PATH=.*|export CHROME_PATH=\"$CHROME_PATH\"|" ~/.bashrc
+  fi
+
+  export CHROME_PATH="$CHROME_PATH"
+  echo "Chromium installed at: $CHROME_PATH"
+fi
+
+exit 0

package/plugins/lisa-copilot/hooks/notify-ntfy.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# =============================================================================
+# ntfy.sh Notification Hook for Claude Code
+# =============================================================================
+# Sends desktop and mobile notifications via ntfy.sh when Claude needs
+# attention or finishes a task.
+#
+# Setup:
+#   1. Install ntfy app on mobile (iOS App Store / Android Play Store)
+#   2. Subscribe to your unique topic in the app
+#   3. Set NTFY_TOPIC environment variable (e.g., in ~/.bashrc or ~/.zshrc):
+#      export NTFY_TOPIC="my-claude-alerts-xyz123"
+#
+# @see https://ntfy.sh
+# =============================================================================
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract hook event name
+HOOK_EVENT=$(echo "$INPUT" | grep -o '"hook_event_name"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+
+# Extract notification type (for Notification hooks)
+NOTIFICATION_TYPE=$(echo "$INPUT" | grep -o '"notification_type"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+
+# Extract message if available
+MESSAGE=$(echo "$INPUT" | grep -o '"message"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+
+# Extract session ID (first 8 chars for brevity)
+FULL_SESSION_ID=$(echo "$INPUT" | grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+SESSION_ID="${FULL_SESSION_ID:0:8}"
+
+# Extract transcript path for task summary
+TRANSCRIPT_PATH=$(echo "$INPUT" | grep -o '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+
+# Determine source (Web vs Local)
+if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
+    SOURCE="Web"
+else
+    SOURCE="Local"
+fi
+
+# Get project name from current directory
+PROJECT_NAME=$(basename "$CLAUDE_PROJECT_DIR" 2>/dev/null || basename "$(pwd)")
+
+# Load NTFY_TOPIC from local config if not already set
+if [ -z "$NTFY_TOPIC" ]; then
+    # Check for project-local config (gitignored)
+    if [ -f "$CLAUDE_PROJECT_DIR/.claude/env.local" ]; then
+        # shellcheck source=/dev/null
+        source "$CLAUDE_PROJECT_DIR/.claude/env.local"
+    fi
+    # Check for user-global config
+    if [ -z "$NTFY_TOPIC" ] && [ -f "$HOME/.claude/env.local" ]; then
+        # shellcheck source=/dev/null
+        source "$HOME/.claude/env.local"
+    fi
+fi
+
+# Exit silently if still not configured
+if [ -z "$NTFY_TOPIC" ]; then
+    exit 0
+fi
+
+# Extract task summary from transcript (last assistant message, truncated)
+TASK_SUMMARY=""
+if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+    # Get the last assistant message from the JSONL transcript
+    # The transcript contains lines with "type":"assistant" and "message" content
+    # Use awk for cross-platform compatibility (tac is not available on macOS)
+    LAST_ASSISTANT=$(awk '/"type"[[:space:]]*:[[:space:]]*"assistant"/{line=$0} END{if(line) print line}' "$TRANSCRIPT_PATH" 2>/dev/null)
+    if [ -n "$LAST_ASSISTANT" ]; then
+        # Extract the message content - look for text content in the message
+        # Format: {"message":{"content":[{"type":"text","text":"..."}]}}
+        # Use jq for robust JSON parsing when available, fallback to grep/sed
+        if command -v jq >/dev/null 2>&1; then
+            RAW_SUMMARY=$(echo "$LAST_ASSISTANT" | jq -r '.message.content[] | select(.type == "text") | .text' 2>/dev/null | head -1)
+        else
+            # Fallback: simple regex extraction (may fail on escaped quotes)
+            RAW_SUMMARY=$(echo "$LAST_ASSISTANT" | grep -o '"text"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//' | sed 's/"$//')
+        fi
+        if [ -n "$RAW_SUMMARY" ]; then
+            # Truncate to 100 chars and clean up newlines
+            TASK_SUMMARY=$(echo "$RAW_SUMMARY" | tr '\n' ' ' | cut -c1-100)
+            # Add ellipsis if truncated
+            if [ ${#RAW_SUMMARY} -gt 100 ]; then
+                TASK_SUMMARY="${TASK_SUMMARY}..."
+            fi
+        fi
+    fi
+fi
+
+# Build session info string (shown in body)
+SESSION_INFO=""
+if [ -n "$SESSION_ID" ]; then
+    SESSION_INFO="Session: $SESSION_ID"
+fi
+
+# Determine notification title and body based on hook type
+case "$HOOK_EVENT" in
+    "Notification")
+        case "$NOTIFICATION_TYPE" in
+            "permission_prompt")
+                TITLE="Claude [$SOURCE] - Permission Required"
+                BODY="${MESSAGE:-Claude needs your permission to continue}"
+                if [ -n "$SESSION_INFO" ]; then
+                    BODY="$SESSION_INFO
+$BODY"
+                fi
+                PRIORITY="high"
+                TAGS="warning"
+                ;;
+            "idle_prompt")
+                TITLE="Claude [$SOURCE] - Waiting"
+                BODY="${MESSAGE:-Claude is waiting for your input}"
+                if [ -n "$SESSION_INFO" ]; then
+                    BODY="$SESSION_INFO
+$BODY"
+                fi
+                PRIORITY="default"
+                TAGS="hourglass"
+                ;;
+            *)
+                TITLE="Claude [$SOURCE] - Attention"
+                BODY="${MESSAGE:-Claude needs your attention}"
+                if [ -n "$SESSION_INFO" ]; then
+                    BODY="$SESSION_INFO
+$BODY"
+                fi
+                PRIORITY="default"
+                TAGS="bell"
+                ;;
+        esac
+        ;;
+    "Stop")
+        TITLE="Claude [$SOURCE] - Finished"
+        BODY="$PROJECT_NAME"
+        if [ -n "$SESSION_INFO" ]; then
+            BODY="$SESSION_INFO | $BODY"
+        fi
+        if [ -n "$TASK_SUMMARY" ]; then
+            BODY="$BODY
+$TASK_SUMMARY"
+        fi
+        PRIORITY="default"
+        TAGS="white_check_mark"
+        ;;
+    "SubagentStop")
+        TITLE="Claude [$SOURCE] - Subagent Done"
+        BODY="$PROJECT_NAME"
+        if [ -n "$SESSION_INFO" ]; then
+            BODY="$SESSION_INFO | $BODY"
+        fi
+        if [ -n "$TASK_SUMMARY" ]; then
+            BODY="$BODY
+$TASK_SUMMARY"
+        fi
+        PRIORITY="low"
+        TAGS="checkered_flag"
+        ;;
+    *)
+        TITLE="Claude [$SOURCE]"
+        BODY="${MESSAGE:-Event: $HOOK_EVENT}"
+        if [ -n "$SESSION_INFO" ]; then
+            BODY="$SESSION_INFO
+$BODY"
+        fi
+        PRIORITY="default"
+        TAGS="robot"
+        ;;
+esac
+
+# Send notification via ntfy.sh
+curl -s \
+    -H "Title: $TITLE" \
+    -H "Priority: $PRIORITY" \
+    -H "Tags: $TAGS" \
+    -d "$BODY" \
+    "https://ntfy.sh/$NTFY_TOPIC" > /dev/null 2>&1
+
+exit 0

package/plugins/lisa-copilot/hooks/setup-jira-cli.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+##
+# Writes the JIRA CLI config file from environment variables.
+# Runs on SessionStart so the config is available for every session.
+#
+# Required env vars (must be created in your Claude Code Web environment):
+#   JIRA_INSTALLATION - cloud or local
+#   JIRA_SERVER       - Atlassian instance URL
+#   JIRA_LOGIN        - login email
+#   JIRA_PROJECT      - default project key
+#   JIRA_API_TOKEN    - already expected by jira-cli natively
+#
+# Optional env vars:
+#   JIRA_BOARD        - default board name
+##
+
+set -euo pipefail
+
+# Fix jira-cli installation if install-pkgs.sh failed to extract correctly.
+# Only attempt on Linux — the binary download is Linux-only.
+if [[ "$(uname -s)" == "Linux" ]] && ! command -v jira &>/dev/null; then
+  JIRA_CLI_VERSION="1.7.0"
+  TMPDIR=$(mktemp -d)
+  curl -sSfL "https://github.com/ankitpokhrel/jira-cli/releases/download/v${JIRA_CLI_VERSION}/jira_${JIRA_CLI_VERSION}_linux_x86_64.tar.gz" \
+    | tar -xz -C "${TMPDIR}"
+  cp "${TMPDIR}/jira_${JIRA_CLI_VERSION}_linux_x86_64/bin/jira" /usr/local/bin/jira
+  chmod +x /usr/local/bin/jira
+  rm -rf "${TMPDIR}"
+fi
+
+CONFIG_DIR="${HOME}/.config/.jira"
+CONFIG_FILE="${CONFIG_DIR}/.config.yml"
+
+# Skip config write if required vars are missing
+if [[ -z "${JIRA_SERVER:-}" || -z "${JIRA_LOGIN:-}" ]]; then
+  exit 0
+fi
+
+mkdir -p "${CONFIG_DIR}"
+
+cat > "${CONFIG_FILE}" << EOF
+installation: ${JIRA_INSTALLATION:-cloud}
+server: ${JIRA_SERVER}
+login: ${JIRA_LOGIN}
+project: ${JIRA_PROJECT:-}
+board: "${JIRA_BOARD:-}"
+auth_type: basic
+epic:
+  name: Epic Name
+  link: Epic Link
+EOF

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

@@ -0,0 +1,70 @@
+# Base Rules (load-bearing)
+
+These are mandatory disciplines that apply to every session. Full prose, JIRA dev-status query, ADF templates, etc. live in [reference/base-rules.md](../reference/base-rules.md).
+
+## Requirement Verification
+
+Treat every request as potentially underspecified. Before starting any work:
+
+1. Identify ambiguities that would prevent completion. If any exist, stop and ask.
+2. Identify open questions whose answers would change your approach. If any exist, stop and ask.
+3. Define how you will empirically verify the work is complete by USING the resulting software, not just running tests. If you cannot define this, stop and ask.
+4. If a request contradicts existing code/architecture/conventions, raise the contradiction and confirm intent before proceeding.
+
+Do not begin work if there are blockers, ambiguities, access requirements, or unanswered questions. Identify these before starting, not during implementation.
+
+## Code Quality
+
+- Atomic commits with conventional commit messages.
+- Document the **why**, not the what.
+- Add new imports and their first usage in the same edit (the lint-on-edit hook strips unused imports).
+- Delete old code completely when replacing it. No deprecation comments unless asked.
+- Fix bugs at root cause. Never work around them or assume a failure is "pre-existing."
+- Test empirically. Never assume test expectations before observing actual behavior.
+
+## Git Discipline
+
+- **Never use `--no-verify`** or bypass any git hook.
+- **Never bypass branch protection** — no `--admin`, `--force`, no merging a PR with failing CI. "Green in CI" is the definition of done.
+- Never commit directly to environment branches (`dev`, `staging`, `main`).
+- Prefix `git push` with `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"`.
+- When opening a PR, watch it. Fix every failing check and every valid bot review comment. Resolve threads. Loop until merged.
+- After merging into an environment branch, watch the deploy. If it fails, fix it and open a new PR.
+- **Promotion PRs** (env→env) MUST use `gh pr merge --merge` (regular merge commit), NEVER squash. Squashing strips `[skip ci]` markers and breaks promotion detection. Feature PRs also use `--merge`.
+- Always include the PR URL when referencing a PR.
+
+## Testing Discipline
+
+- Never skip or disable tests. Never add skip directives without explicit instruction.
+- Never lower coverage thresholds to pass a hook — raise coverage instead.
+
+## JIRA Discipline
+
+- Read **all** comments on a ticket, not just the description.
+- When clarifying, comment via ADF and @mention the Reporter.
+- Establish issue link relationships (`blocks`, `is blocked by`, `relates to`) — search git history AND Jira before declaring "no related work."
+- Single-repo invariant: Bug/Task/Sub-task MUST be single-repo. Epic/Story/Spike MAY span repos. Cross-repo leaves are split per the `repo-scope-split` rule.
+- Pre-flight gate: BLOCK + reassign-to-Reporter if a ticket is missing target backend env, sign-in credentials, Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence.
+
+## Pace
+
+Never rush. A fast wrong answer is worse than a slow correct one. Surface difficulty to the user instead of compressing the work.
+
+## NEVER
+
+- Modify this file directly.
+- Touch files inside `node_modules`, `.venv`, `vendor`, `target`.
+- Delete anything untracked, or anything outside this project.
+- Create placeholders, TODOs, versioned copies (`V2`, `processNew`, `handleOld`).
+- Write migration code unless explicitly requested.
+- Update CHANGELOG yourself.
+
+## ASK FIRST
+
+- Before adding a lint/formatter suppression (`eslint-disable`, `biome-ignore`, `noqa`, etc.).
+- Before adding a type-check suppression (`ts-ignore`, `ts-expect-error`, `# type: ignore`).
+- Lint suppression in test files is OK without asking only when comprehensive coverage genuinely requires it.
+
+## Multi-Repository Awareness
+
+If you see imports that don't resolve, API calls without a contract, shared libs not present, env vars naming foreign services, stack traces pointing out-of-repo, or ticket references to other components — stop guessing. Identify the repo, add it to the session, or ask.

package/plugins/lisa-copilot/rules/eager/coding-philosophy.md

@@ -0,0 +1,27 @@
+# Coding Philosophy (load-bearing)
+
+When writing or modifying code, follow these principles. Examples, hook structure templates, and anti-pattern catalogs live in [reference/coding-philosophy.md](../reference/coding-philosophy.md).
+
+## Principle priority
+
+**KISS is the tiebreaker.** When principles conflict, choose the simpler solution.
+
+1. **YAGNI** — Don't build features, abstractions, or flexibility you don't need right now. Solve today's problem.
+2. **KISS** — Choose the simpler option.
+3. **DRY** — Extract only when (a) the same logic appears 3+ times, (b) the abstraction is simpler than the duplication, and (c) the extracted code has a clear single purpose.
+4. **SOLID** — Apply pragmatically. Split a function only when it does 2+ unrelated things AND splitting reduces complexity. Use composition over inheritance.
+
+## Mandatory practices
+
+- **Immutability first.** Never mutate. Spread/clone to create new references.
+- **TDD is mandatory.** Write the failing test BEFORE the implementation. Red → Green → Refactor.
+- **Function structure order**: (1) variables & derived state, (2) side effects, (3) return. Never interleave.
+- **Functional transformations.** Prefer `map`/`filter`/`reduce` over imperative loops with mutation.
+- **Clean deletion.** When replacing code, delete the old version completely. No `V2`/`Old`/`New` suffixes, no `@deprecated` comments, no migration shims unless explicitly requested. Trust git history.
+
+## What NOT to write
+
+- Comments that explain WHAT the code does (well-named identifiers do that).
+- Error handling, fallbacks, or validation for scenarios that can't happen.
+- Backwards-compatibility shims, feature flags, or unused `_var` renames when you can just change the code.
+- Half-finished implementations, placeholders, or TODOs.

package/plugins/lisa-copilot/rules/eager/config-resolution.md

@@ -0,0 +1,28 @@
+# Config Resolution (load-bearing)
+
+Lisa configuration lives in `.lisa.config.json` (committed) and `.lisa.config.local.json` (gitignored, per-developer). The local file wins where they overlap. Developer-specific identity (`atlassian.email`, etc.) MUST live in the local file, never committed.
+
+## Atlassian access — assistant-level rule
+
+When the user asks about Atlassian (Jira / Confluence) connection state, or you are about to run a Jira/Confluence operation, and `acli` is installed:
+
+1. Run `acli auth status` and read the active `Site:`.
+2. Read `atlassian.site` from `.lisa.config.json` (and `atlassian.email` from `.lisa.config.local.json` if present).
+3. **If the active site does not match config, do NOT report "not connected." Run:**
+   ```sh
+   acli auth switch --site "$ATLASSIAN_SITE" --email "$ATLASSIAN_EMAIL"
+   ```
+   acli supports multiple authenticated profiles; the switch is fast and non-interactive when a profile already exists.
+4. Only after the switch fails (no matching profile) should you report not-connected and suggest `/lisa:setup:atlassian` to add one.
+
+This applies before declaring connection state, before running any `acli jira *` / `acli confluence *` command, and before falling back to the Atlassian MCP or curl substrates. Identity mismatch is treated as silent-misroute risk, not as a hard not-connected.
+
+## Tracker selection
+
+Project tracker (`jira` / `github` / `linear`) is read from `.lisa.config.json` `tracker`. Vendor-neutral skills MUST dispatch through the configured tracker, never infer it from arguments. Missing `tracker` → stop and instruct the user to run the matching `/lisa:setup:*` skill.
+
+## Repo identity
+
+`repo:<name>` is the canonical label for which repo a work item belongs to. Resolve current-repo identity in this priority order: `.lisa.config.local.json` `repo` → `.lisa.config.json` `repo` → `.lisa.config.json` `github.repo` → `basename -s .git "$(git remote get-url origin)"`. If none resolve, stop with a clear error.
+
+Full reference: [reference/config-resolution.md](../reference/config-resolution.md).

package/plugins/lisa-copilot/rules/eager/documentation-source-paths.md

@@ -0,0 +1,13 @@
+# Documentation Source Paths (load-bearing)
+
+Do not treat `docs/`, `research/`, `transcripts/`, or other source-material directories as disposable duplicates just because a project also has a `wiki/`. They may be ingestion inputs, executable fixtures, runtime inputs, or historical evidence.
+
+Before moving, absorbing, or deleting documentation-like paths:
+
+1. Classify each path: durable wiki content, reader-safe source note, executable test fixture, runtime scratch/input, generated output, or obsolete.
+2. Use `rg` to find every code, test, script, config, README, rule, skill, agent, and wiki reference to the path.
+3. Preserve executable fixtures and runtime inputs OUTSIDE the wiki — they are project behavior, not documentation.
+4. When absorbing into `wiki/`, update source notes, indexes, logs, README links, rule references, and runtime defaults that pointed at the old path.
+5. Delete a path only AFTER references are updated and verification proves the project no longer reads it.
+
+Full context (Lisa-wiki specifics, `wiki/sources/` evidence layout): [reference/documentation-source-paths.md](../reference/documentation-source-paths.md).

package/plugins/lisa-copilot/rules/eager/empirical-inquiry.md

@@ -0,0 +1,22 @@
+# Empirical Inquiry — Test, Don't Guess (load-bearing)
+
+When a decision depends on a fact you are not certain of — how a tool, API, harness, runtime, or dependency actually behaves — **find out empirically before you act.** Run the smallest experiment that settles the question, observe the real result, and proceed from what you observed.
+
+Do not reason your way to a confident-sounding answer from documentation, prior assumption, or training knowledge when the real system is right there and a quick probe would tell you the truth.
+
+## How to apply
+
+1. **State the uncertain fact** explicitly, so you know what the experiment must resolve.
+2. **Run the cheapest probe** that produces real evidence — a single command, a one-shot subagent, a tiny script, a direct API call against a scratch input.
+3. **Report the raw result** (verbatim output or error), then your conclusion. Distinguish observation from inference.
+4. **Encode the verified fact**, and when non-obvious or contradicting docs, record WHY so the next agent inherits the finding.
+
+## Forbidden
+
+- Presenting a guess, recollection, or doc summary as established fact when it was cheap to verify and you did not.
+- "Should work" / "probably" / "the docs say" as the basis for a load-bearing decision an experiment could have settled.
+- Skipping the probe because the answer "seems obvious" — those are exactly the ones that quietly drift from reality.
+
+This is the inquiry counterpart to the `verification` rule (which proves completed work behaves correctly). Both reject "it looks correct" as evidence.
+
+Full prose: [reference/empirical-inquiry.md](../reference/empirical-inquiry.md).

package/plugins/lisa-copilot/rules/eager/intent-routing.md

@@ -0,0 +1,18 @@
+# Intent Routing (load-bearing)
+
+**On the first user message of a session**, before responding to the substance of the request, before running any tool, before asking any clarifying question:
+
+1. **Classify the flow.** One of: Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), Verify, Monitor, Intake, Debrief, or No flow. If a slash command was invoked, the flow is already determined.
+2. **Echo the chosen flow** with a one-sentence justification. Example:
+   > **Flow: Implement/Fix** — bug report with reproduction steps.
+3. **Echo orchestration mode in the same message.** One of:
+   > **Orchestration: agent team** — Research, Plan, Implement, Intake, Debrief, and any flow that invokes Review.
+   > **Orchestration: single agent** — Verify (standalone), Monitor (standalone), product-walkthrough standalone, debrief-apply, one-off diagnostic sessions.
+4. **Check the readiness gate.** If gate fails interactively, ask for what's missing with recommended answers; do not start work. Headless/`-p` sessions infer from available context instead of blocking.
+5. **Cascade rule.** If you are already inside an agent team (a TeamCreate succeeded earlier this session, or you were spawned into a team context), do **not** create a second team. Add specialists through the existing lead. On Claude, teams are flat — message the lead with teammate + assignment. On Codex, use `multi_agent_v1.spawn_agent`.
+
+Once a flow is established, **do not re-classify** on later messages, even if a follow-up looks vague ("now run the tests", "thanks"). Subsequent messages inherit the established flow unless the user explicitly changes scope.
+
+Skipping classification or orchestration echo leads to unstructured responses that bypass readiness gates.
+
+Full reference (flow definitions, readiness gates, orchestration matrix, sub-flows): [reference/intent-routing.md](../reference/intent-routing.md).

package/plugins/lisa-copilot/rules/eager/leaf-only-lifecycle.md

@@ -0,0 +1,39 @@
+# Leaf-Only Build-Ready Invariant (load-bearing)
+
+**Build-ready means a directly implementable leaf work unit.** Containers never carry build-ready.
+
+A leaf is structurally defined: **no child work** AND a leaf-typed item (Bug, Task, Sub-task, Improvement). A container is a parent with children — Epic, Story, Spike, or any item that has acquired sub-items.
+
+## Invariant
+
+- **At decomposition/write time** — only leaves receive the `ready` role. Parent containers are created in their non-ready state.
+- **At validate time** — `*-validate-*` FAILs any container carrying the build-ready role.
+- **At claim time** — build-intake claims leaves only. A container with a stale build-ready role is rolled up or safe-blocked, NEVER implemented.
+
+## Childless-parent exception
+
+A container *type* with no children is structurally a leaf — and may be build-ready iff its type is itself a leaf type:
+
+- **Task or Bug with no children** → leaf → may be build-ready.
+- **Epic, Story, or Spike with no children** → still NOT build-ready. These are coordination containers by design; an empty one is incomplete decomposition. Repair: decompose into leaves, or reclassify to a leaf type.
+
+## Parent state rollup (priority order, first match wins)
+
+1. Any leaf is **blocked** → parent rolls up to **blocked / attention-needed**.
+2. Else any leaf is **claimed or in review** → parent is **in-progress**.
+3. Else all required leaves are **terminal (`done`)** → parent reaches the configured rollup terminal (env-keyed `done`).
+4. Else (leaves exist but none started) → parent unchanged.
+
+**Blocked dominates.** Optional/won't-do children do not hold a parent open. Rollup is recursive — bottom-up. The parent never carries `ready`.
+
+## Terminal native closure
+
+When a leaf reaches the true terminal `done` (the production / final-env value), also finalize via the tracker's native completion mechanism:
+
+- **GitHub** — `gh issue close <n> --reason completed` after the terminal label.
+- **Linear** — move workflow `state` to the team's Done.
+- **JIRA** — transition to terminal Done/Resolved/Closed; verify `statusCategory = Done`.
+
+Intermediate env-keyed states (`status:on-dev`, `On Stg`, etc.) remain open. Idempotent — if already closed, report and continue.
+
+Full vendor mechanics + the state machine in prose: [reference/leaf-only-lifecycle.md](../reference/leaf-only-lifecycle.md).

package/plugins/lisa-copilot/rules/eager/prd-lifecycle-rollup.md

@@ -0,0 +1,31 @@
+# PRD Lifecycle Rollup & Generated-Top-Level-Work Contract (load-bearing)
+
+The vendor-neutral source of truth for how a PRD owns the work it generated and how its lifecycle rolls up to `shipped`. Companion to `leaf-only-lifecycle` (which governs build-lifecycle of leaves); this rule governs PRD lifecycle and rollup from generated top-level children.
+
+## Generated top-level work (the contract)
+
+A PRD owns the work units it created **at the top of the hierarchy** — the Epic(s) and any top-level Story it created directly. It does NOT own descendants (Sub-tasks, Stories under an Epic, leaves under a top-level unit) — those are owned by their top-level parent and roll up via `leaf-only-lifecycle`.
+
+Leaf Sub-tasks are **never** direct children of a PRD when a top-level Epic/Story hierarchy exists.
+
+## How each vendor records the PRD→child link
+
+**Native hierarchy first**, machine-readable fallback section always written:
+
+- **GitHub Issues** — native sub-issues when source and tracker are the same repo + supports sub-issues.
+- **Linear** — `parentId` or generated Project grouping where the PRD also lives in Linear.
+- **JIRA** — Epic link / parent field, or documented issue-link type.
+- **Confluence / Notion** — no native issue hierarchy; the documented `## Tickets` / `## Generated Work` section IS the source of truth.
+- **Cross-vendor** (e.g. Notion PRD → JIRA tracker) — always documented section in the PRD source.
+
+The documented `## Tickets` section is ALWAYS written (additive to native links) so the generated set is readable without parsing comments.
+
+## Rollup transition
+
+PRD rolls from `ticketed` to `shipped` when every required generated top-level child is terminal. The PRD remains open for `/lisa:verify-prd` after `shipped` — verified PASS performs native closure (archive/close/transition), verified FAIL re-opens to `ticketed` with build-ready fix tickets (never `blocked`).
+
+## Idempotency dedupe key
+
+Re-runs of intake/backlink must dedupe by child-ref identity (e.g. `owner/repo#number` for GitHub, Linear issue UUID, JIRA key) — never by URL string, which varies by formatting.
+
+Full vendor matrix, predicate definitions, non-goals: [reference/prd-lifecycle-rollup.md](../reference/prd-lifecycle-rollup.md).

package/plugins/lisa-copilot/rules/eager/repo-scope-split.md

@@ -0,0 +1,39 @@
+# Repo Scope & Work-Time Splitting (load-bearing)
+
+**Leaf work units are single-repo.** A leaf is an individually implementable ticket with no children — types **Bug, Task, Sub-task, Improvement**. Each names exactly one repo. **Epic, Story, Spike** are coordination containers and may span repos.
+
+Enforced at four points: gate **S10** (`*-validate-*`, write time), `task-decomposition` step 1.5 (PRD-decomposition time), claim-time repo scoping (`*-build-intake`), and the work-time split procedure (an existing ticket about to be implemented).
+
+## Choose the right strategy
+
+- **Decomposition-time (no tickets exist yet):** use `task-decomposition` step 1.5 — one work unit per repo under a parent Story.
+- **Work-time (a ticket already exists):** narrow the original to one repo, spin off a sibling per additional repo, link by dependency. Do NOT invent a new parent — siblings inherit the original's existing parent.
+
+## Work-time split (pre-flight gate, agent-performed)
+
+1. **Detect repos.** Parse description + AC + approach, confirm against actual code surfaces. If single-repo, no split.
+2. **Pick the keeper.** Default: the original keeps the consumer / user-facing repo.
+3. **Create one sibling per extra repo**, cloning metadata (re-prefix summary, scope AC, carry parent, env, sign-in).
+4. **Link by dependency.** Producer **blocks** consumer (`is blocked by` on consumer / `blocks` on producer). No clear direction → `relates to`.
+5. **Narrow the original.** Edit summary prefix, Repository section, AC; remove cross-repo references.
+6. **Comment** on the original noting the split, linking each sibling.
+7. **Re-validate.** Run `tracker-verify` (S10) on the original and every sibling. All must PASS single-repo.
+8. **Proceed in dependency order.** Producer siblings first.
+
+## When to BLOCK instead of split
+
+Fall back to the standard BLOCK + reassign-to-Reporter path when:
+
+- Repos cannot be determined confidently from ticket + code.
+- Splitting would strand stakeholder context only the reporter can re-scope.
+- Required clone metadata (parent, env, credentials) is itself missing.
+
+## Claim-time repo scoping (build-intake)
+
+A tracker can oversee multiple repos. Build-intake claims only current-repo tickets. Resolve current repo per `config-resolution` (config `repo` → `github.repo` → git remote basename). For each ready candidate:
+
+1. **Read `repo:<name>` label.** Wrong repo → skip. Current repo → leaf-only gate + claim. Unlabeled → determine + stamp + re-apply.
+2. **Multi-repo leaf → split, never claim.** Each split sibling is created build-ready and stamped with its own `repo:<name>`.
+3. **Wrong-repo single-repo leaf → skip** (label keeps it cheap next cycle).
+
+Vendor mechanics (JIRA/GitHub/Linear) and full procedure: [reference/repo-scope-split.md](../reference/repo-scope-split.md).

package/plugins/lisa-copilot/rules/eager/security-audit-handling.md

@@ -0,0 +1,29 @@
+# Security Audit Handling (load-bearing)
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, follow the rules below. **Never use `--no-verify`** to bypass the security audit.
+
+## Core rule
+
+Override the actually-vulnerable **leaf package**, not its parent. The audit chain shows `parent › intermediate › vulnerable` — only the vulnerable leaf needs the override.
+
+**Never override a parent package to force a lower major version.** Other packages may depend on the newer major; a forced downgrade breaks them.
+
+Before adding any override, verify:
+- You are targeting the actually-vulnerable package, not a parent in the chain.
+- The override is compatible with all dependents (check via `bun why <pkg>` or `npm ls <pkg>`).
+- The override does not downgrade across a major version boundary other deps require.
+
+## Node.js (GHSA)
+
+1. Note GHSA ID, package, advisory URL.
+2. If a patched version exists: add a resolution AND override in `package.json` for the leaf package, regenerate the lockfile, commit, retry.
+3. If no patch but safe (transitive, no untrusted input, dev/build only): add an exclusion to `audit.ignore.local.json` with `{"id", "package", "reason"}`, commit, retry.
+
+## Rails (bundler-audit)
+
+1. Note advisory ID, gem, URL.
+2. If direct dep with patch: update Gemfile constraint, `bundle update <gem>`, commit, retry.
+3. If transitive with patch: `bundle update <gem>` to bump the lockfile only, commit, retry.
+4. If no patch but safe: document the exception, retry.
+
+Full procedure with examples: [reference/security-audit-handling.md](../reference/security-audit-handling.md).