@codyswann/lisa 2.119.1 → 2.121.1

package/plugins/lisa-cursor/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-cursor/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-cursor/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-cursor/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-cursor/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-cursor/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-cursor/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-cursor/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-cursor/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-cursor/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).

package/plugins/lisa-cursor/rules/eager/usage-accounting.md

@@ -0,0 +1,28 @@
+# Usage Accounting (load-bearing)
+
+Lisa attaches AI usage and cost telemetry to every artifact it creates/updates. The format is a single canonical managed section.
+
+## Managed section
+
+Every artifact with inline body content gets exactly one section:
+
+```markdown
+## Lisa Usage
+```
+
+**Canonical. Rewrite in place; never append a second usage section.** If the host can't safely edit body, write the same section in a comment and treat that comment as the managed artifact for future rewrites.
+
+## Required field semantics
+
+Each direct entry records ONE logical Lisa run on ONE artifact. `entry_id` is the stable dedupe key — rewriting the same logical run with the same `entry_id` updates in place; a different run gets a different `entry_id`.
+
+- **`source`**: `observed` (runtime supplied) / `estimated` (derived from trustworthy metadata + pricing contract) / `unavailable`.
+- **`pricing_status`**: same trinary plus `missing` (cost not known but should be).
+- **Absence ≠ zero.** `null` means unknown; `0` means explicitly zero. Always write the entry — never silently omit.
+- Do NOT replace observed counts with estimates.
+
+## Rollup
+
+Container artifacts (Epic, PRD, etc.) roll up usage from their direct children. Roll-up is recursive — a parent's `## Lisa Usage` aggregates its descendants' direct entries. Re-writes are idempotent: re-running an intake or lifecycle skill must not duplicate entries.
+
+Full schema (all 17 fields, pricing semantics, rollup math, idempotent-rewrite rules): [reference/usage-accounting.md](../reference/usage-accounting.md).

package/plugins/lisa-cursor/rules/eager/verification.md

@@ -0,0 +1,21 @@
+# Empirical Verification (load-bearing)
+
+**Verification is not linting, typechecking, or testing.** Those are *quality checks* — necessary prerequisites, but NOT verification.
+
+**Verification is using the resulting software the way a user would** — interacting with the UI, calling the API, running the CLI, observing behavior. Tests pass in isolation; verification proves the system works as a whole.
+
+## Mandatory
+
+- **Never claim success without runtime evidence.** "The code looks correct" is not evidence.
+- **If all you did was run tests, typecheck, and lint — you have NOT verified.**
+- **Before starting implementation, state your verification plan** — how you will USE the resulting software to prove it works. A plan that only lists `test`/`typecheck`/`lint` commands is not a plan. Do not begin until confirmed.
+- **After verifying empirically, codify it as a regression test** via the `codify-verification` skill — Playwright for UI, integration test for API/DB/auth, benchmark for performance. Codification is mandatory for every verification type except PR/Documentation/Deploy and Investigate-Only spikes.
+- **Every PR must include reviewer replay steps** — the exact human steps to use the software and confirm the change works. Not test commands. If a reviewer can't reproduce from the PR description alone, the PR is incomplete.
+
+## Roles
+
+- **Builder agent** — implements the change.
+- **Verifier agent** — acts as the end user / API client / operator. Independent from Builder when possible.
+- **Human overseer** — approves risky operations and anything agents cannot fully verify.
+
+Full operational contract (verification types, evidence formats, escalation protocol): [reference/verification.md](../reference/verification.md).

package/plugins/lisa-cursor/rules/eager/wiki-knowledge-source.md

@@ -0,0 +1,16 @@
+# Wiki as Knowledge Source (load-bearing)
+
+If the project has an LLM Wiki (a `wiki/` directory with `index.md`), treat it as the canonical source of durable project knowledge.
+
+Before researching background, conventions, ownership, architecture, glossary, or "how/why does X work here":
+
+1. **Consult the wiki first.** Start from `wiki/index.md` or use the wiki query skill (`/lisa-wiki-query`).
+2. **Use what the wiki says** as the authoritative answer when it covers the question — do not re-derive it from raw sources.
+3. **Fall back to primary sources** (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe.
+4. **Surface gaps.** If the wiki is wrong, stale, or missing knowledge that belongs there, flag it — and where the workflow supports it, capture the correction via `/lisa-wiki-ingest`.
+
+The wiki documents knowledge; it does NOT override executable behavior. When wiki and running code disagree about what the system does, trust the code and treat the wiki as out of date.
+
+If the project has no `wiki/`, this rule does not apply.
+
+Full prose: [reference/wiki-knowledge-source.md](../reference/wiki-knowledge-source.md).

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

@@ -0,0 +1,133 @@
+Intent Routing (FIRST — before anything else):
+
+Before starting any work in a session, classify the user's initial request using the Intent Routing rule. Determine which flow applies (Research, Plan, Implement, Verify, or None) and check its readiness gate. Once a flow is established, all subsequent messages operate within it. Do not skip this step — even if the request seems simple. See the `intent-routing` rule for the full protocol.
+
+Orchestration Selection (SECOND — immediately after classifying the flow):
+
+After echoing the chosen flow and BEFORE doing any work, state the orchestration mode explicitly — either `Orchestration: agent team` or `Orchestration: single agent` — with a one-sentence justification. This echo is mandatory and must appear in the same message as the flow classification.
+
+Default to an agent team for Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), and any flow that invokes the Review sub-flow. Use a single agent only for Verify (standalone) and Monitor (standalone). See the `intent-routing` rule's Orchestration section for the full decision matrix.
+
+When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST establish team orchestration before any content-gathering work. Use the team tool for the current runtime: Claude uses `TeamCreate` (first `ToolSearch` with `query: "select:TeamCreate"` if needed); Codex must not call `TeamCreate` because Codex does not expose that Claude tool. In Codex, use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation and treat the first successful `spawn_agent` call as establishing team orchestration. Other runtimes should use their current tool-discovery mechanism to discover and call the appropriate multi-agent/team tool. If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists, the first Codex teammate has been spawned, or the no-team fallback has been declared — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before orchestration exists. If you ARE already operating inside an agent team, do NOT create a second team and do NOT collapse into inline single-agent work; instead request the existing team lead add the specialist agent(s) this flow needs to the current team — on Claude, teammates cannot add named teammates (teams are flat), so message the lead with the teammate(s), assignments, and completion criteria; on Codex, ask the addressable lead/root to `multi_agent_v1.spawn_agent` them, or if no lead handle exists spawn the bounded specialists yourself, `wait_agent`, and relay results upward — then coordinate through the shared task state.
+
+Requirement Verification:
+
+Never assume the person providing instructions has given you complete, correct, or technically precise requirements. Treat every request as potentially underspecified. Before starting any work:
+
+1. Identify any ambiguities in the request that would prevent you from completing the work. If any exist, stop and ask for clarification.
+2. Identify any 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 — not by running tests or linters, but by using the resulting software the way a user would. If you cannot define this, stop and ask for clarification.
+4. If a request contradicts existing code, architecture, or conventions, do not silently comply. Raise the contradiction and confirm intent before proceeding.
+
+DO NOT START WORK if any of the above are unclear. Asking a clarifying question is always cheaper than implementing the wrong thing.
+
+Do not begin a task if there are any blockers, ambiguities, access requirements, unanswered questions, or unknowns that would prevent you from completing it. Identify these before starting — not during implementation. If you cannot confirm that you have everything needed to finish the work end-to-end, stop and surface what is missing.
+
+Project Discovery:
+- Determine the project's package manager before installing or running anything.
+- Read the project manifest (e.g. package.json, pyproject.toml, Cargo.toml, go.mod) to understand available scripts and dependencies.
+- Before defining a verification approach, check the `scripts` section of the project manifest for existing commands to start servers, run tests, seed databases, etc. Use existing scripts rather than inventing ad-hoc commands.
+- Read the project's linting and formatting configuration to understand its standards.
+- Regenerate the lockfile after adding, removing, or updating dependencies.
+- Ignore build output directories (dist, build, out, target, etc.) unless specified otherwise.
+- Ignore configuration linter hints/warnings — only fix actual unused exports/dependencies reported as errors.
+
+Code Quality:
+- Make atomic commits with clear conventional commit messages.
+- Create clear documentation preambles for new code. Update preambles when modifying existing code.
+- Document the "why", not the "what". Code explains what it does; documentation explains why it exists.
+- Always add new imports and their first usage in the same edit. The lint-on-edit hook runs `eslint --fix` after every Edit, which auto-removes unused imports. If you add an import in one edit and plan to use it in a second edit, the hook will strip the import before the second edit runs.
+- Add language specifiers to fenced code blocks in Markdown.
+- Use project-relative paths rather than absolute paths in documentation and Markdown.
+- Delete old code completely when replacing it. No deprecation unless specifically requested.
+- Fix bugs and issues properly. Never cover them up or work around them.
+- When a tool or build step fails, never assume the failure is pre-existing and work around it. Investigate the root cause first — check git history, find when it broke and why — before deciding how to proceed.
+- Test empirically to confirm something worked. Never assume.
+- Never assume test expectations before verifying actual implementation behavior. Run tests to learn the behavior, then adjust expectations to match.
+- Always provide a solution. Never dismiss something as "not related to our changes" or "not relevant to this task".
+
+Git Discipline:
+- Prefix git push with `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"`.
+- Never commit directly to an environment branch (dev, staging, main).
+- Never use --no-verify or attempt to bypass a git hook.
+- Never bypass branch protection. Never use `--admin`, `--force`, or any other flag to merge a PR that has failing CI checks. If CI fails, fix it. If you cannot fix it, escalate to the human. There are zero exceptions. "Green in CI" is the definition of done — not "green locally." A PR is not complete until CI passes on the actual PR branch.
+- Never stash changes you cannot commit. Either fix whatever is preventing the commit or fail out and let the human know why.
+- Never add "BREAKING CHANGE" to a commit message unless there is actually a breaking change.
+- When opening a PR, watch the PR. If any status checks fail, fix them. For all bot code reviews, if the feedback is valid, implement it and push the change to the PR. Then resolve the feedback. If the feedback is not valid, reply to the feedback explaining why it's not valid and then resolve the feedback. Do this in a loop until the PR is able to be merged and then merge it.
+- When merging a PR into an environment branch (dev, staging, main), watch the resultant deploy until it fully succeeds. If it fails for any reason, fix the failure and then open a new PR with the fix.
+- When referencing a PR in a response, always include the url
+- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use a regular merge commit (`gh pr merge --merge`) as well.
+
+Testing Discipline:
+- Never skip or disable any tests or quality checks.
+- Never add skip directives to a test unless explicitly asked to.
+- Never lower thresholds to pass a pre-push hook. Increase test coverage to make it pass.
+- Never duplicate test helper functions without appropriate lint suppression when duplication is intentional for test isolation.
+
+JIRA Discipline:
+- If working on a JIRA issue, make sure the branch you're working on references and is added to the JIRA issue.
+- 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. 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 per the `repo-scope-split` rule — at PRD-decomposition time via `task-decomposition` step 1.5 (parent Story + per-repo children); at work-time (an existing ticket an agent is about to implement) via the work-time split procedure (narrow the original to one repo, spin off a sibling per additional repo cloning its metadata, link the producer→consumer dependency, then proceed). A cross-repo work unit is a decomposition error the agent fixes by splitting, not a reason to bounce the ticket to the reporter.
+- 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}" \
+    "${JIRA_SERVER}/rest/api/2/issue/${TICKET_ID}?fields=id" | jq -r '.id')
+  curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \
+    "${JIRA_SERVER}/rest/dev-status/1.0/issue/detail?issueId=${ISSUE_ID}&applicationType=GitHub&dataType=pullrequest" \
+    | jq '.detail[].pullRequests[] | {title, status, url, source: .source.branch}'
+  ```
+
+Agent Behavior:
+- Never handle tasks yourself when working in a team of agents. Always delegate to a specialized agent.
+
+Pace:
+- Never rush. There is no pressure to finish quickly. Speed is not a measure of quality, and a fast wrong answer is worse than a slow correct one.
+- Take the time to read the relevant code in full, verify assumptions empirically, ask clarifying questions when something is ambiguous, and check your work before declaring it done.
+- Do not skip steps to save time — quality gates, verification, reading existing code, asking the user — these exist because shortcuts cost more than they save.
+- If a task feels like it's taking "too long," that is almost always a sign that the task is harder than it first appeared, not a sign that you should cut corners. Surface the difficulty to the user instead of compressing the work.
+- Optimize for being correct, thorough, and reversible. Time spent doing the work right is never wasted; time spent recovering from a rushed answer often is.
+
+NEVER:
+- Modify this file directly. To add a memory or learning, use the project's rules file or create a skill.
+- Directly modify files inside dependency directories (e.g. node_modules, .venv, vendor, target).
+- Delete anything that is not tracked in git.
+- Delete anything outside of this project's directory.
+- Create placeholder implementations.
+- Create TODOs.
+- Create versioned copies of files or functions (e.g. V2, Optimized, processNew, handleOld).
+- Write migration code unless explicitly requested.
+- Write functions or methods unless they are needed.
+- Write unhelpful comments like "removed code" or "old implementation".
+- Update CHANGELOG.
+
+ASK FIRST:
+- Before adding a lint or formatter suppression comment (e.g. eslint-disable, biome-ignore, prettier-ignore, noqa, #[allow(...)], @SuppressWarnings). These should be a last resort.
+- Before adding a type-checking suppression comment (e.g. ts-ignore, ts-expect-error, ts-nocheck, type: ignore).
+- Lint suppression in test files is acceptable without asking only when comprehensive test coverage requires it (e.g. file length limits) or when intentional duplication improves test isolation. Include matching re-enable comments where applicable.
+
+Multi-Repository Awareness:
+
+When working in a microservices architecture, the code you need may span multiple repositories. Watch for these signals that you're missing context:
+
+1. Import paths or package references that don't resolve in the current repository
+2. API calls to internal services where you can't find the contract, schema, or handler
+3. Shared libraries, SDKs, or proto/OpenAPI definitions referenced but not present
+4. Environment variables or config referencing service names you don't have code for
+5. Error messages or stack traces pointing to code outside the current repo
+6. JIRA issues or documentation referencing components in other repositories
+
+When you detect any of the above:
+1. Do NOT guess or make assumptions about what the external code does
+2. Identify which repository contains the missing code
+3. Add that repository to your current session before proceeding
+4. If you cannot determine which repository contains the code, ask — do not proceed without it