@codyswann/lisa 2.119.0 → 2.121.0

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

@@ -0,0 +1,13 @@
+# Documentation Source Paths
+
+Do not treat `docs/`, `research/`, `transcripts/`, or other source-material directories as disposable duplicates just because a project also has a `wiki/`.
+
+Before moving, absorbing, or deleting documentation-like paths:
+
+1. Classify each path as one of: durable wiki content, reader-safe source note, executable test fixture, runtime scratch/input path, generated output, or obsolete material.
+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 documentation into `wiki/`, also update source notes, indexes, logs, README links, rule references, and any runtime defaults that pointed at the old path.
+5. Delete a source path only after references are updated and verification proves the project no longer reads it.
+
+For Lisa wiki work specifically, `wiki/` is the durable knowledge source, but `docs/`, `research/`, `docs/wiki-inbox/`, and `transcripts/` may still be ingestion inputs, historical source evidence, fixtures, or runtime scratch locations. Preserve reader-safe evidence under `wiki/sources/` and record successful ingestions in `wiki/log.md`.

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

@@ -0,0 +1,27 @@
+# Empirical Inquiry — Test, Don't Guess
+
+When a decision depends on a fact you are not certain of — how a tool, API, harness, runtime, environment, or dependency actually behaves — **find out empirically before you act on it.** Run the smallest experiment that settles the question, observe the real result, and then 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.
+
+This is the inquiry counterpart to the `verification` rule: `verification` proves that *completed work* behaves correctly; this rule governs how you establish the *facts you build on* in the first place. Both reject "it looks correct" as evidence.
+
+## When this rule applies
+
+- A capability or limit is unclear ("can a teammate spawn another teammate?", "does this flag accept a list?", "is this endpoint paginated?"). Probe it with a throwaway call.
+- Documentation and observed behavior might disagree, or the docs are silent. Trust the observation; note the discrepancy.
+- You are about to encode an assumption into code, a workflow, a rule, or a ticket. Confirm the assumption holds before it becomes load-bearing.
+- A failure's cause is ambiguous. Reproduce it and read the actual error rather than inferring a likely cause.
+
+## How to apply it
+
+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. Keep it bounded and side-effect-free where possible.
+3. **Report the raw result** (the verbatim output or error), then the conclusion you draw from it. Distinguish what you observed from what you inferred.
+4. **Encode the verified fact**, and when it is non-obvious or contradicts the docs, record *why* alongside it so the next agent inherits the finding instead of re-deriving it.
+
+## What this rule forbids
+
+- Presenting a guess, a recollection, or a documentation 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 that an experiment could have settled.
+- Skipping the probe because the answer "seems obvious" — obvious answers are exactly the ones that quietly drift from reality.
+
+A false belief caught by a 30-second probe is cheap; the same false belief baked into a rule, a skill, or shipped code is expensive. Spend the 30 seconds.

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

@@ -0,0 +1,407 @@
+# Intent Routing
+
+MANDATORY: On the **first user message of a session**, classify the request using the Flow Classification Protocol below and state the chosen flow before doing any other work. Do not respond to the substance of the request, do not start work, do not ask questions until you have stated which flow applies. Once a flow is established, treat it as fixed for the remainder of the session — **do not re-classify on subsequent messages**, even if a follow-up looks vague or conversational ("wait, what did you just do?", "now run the tests", "thanks"). Subsequent messages operate within the established flow unless the user explicitly changes scope. Skipping classification leads to unstructured responses that bypass readiness gates.
+
+Each flow has a readiness gate that MUST pass before work begins. If the gate fails, stop and ask for what is missing.
+
+## Flow Classification Protocol
+
+This protocol runs **once per session**, on the first user message. After that, every later message inherits the established flow — do not re-run classification.
+
+1. If the user invoked a slash command (`/lisa:research`, `/lisa:plan`, `/lisa:implement`, `/lisa:verify`, `/lisa:monitor`, `/lisa:intake`, etc.), the flow is already determined -- skip classification.
+2. Read the user's request and match it against the flow definitions below.
+3. If you cannot confidently classify the request:
+   - **Interactive session** (user is present): present a multiple choice using AskUserQuestion with options: Research, Plan, Implement, Verify, Debrief, No flow.
+   - **Headless/non-interactive session** (running with `-p` flag, in a CI pipeline, or as a scheduled agent): do NOT ask the user. Classify to the best of your ability from available context (ticket content, prompt text, current branch state). If you truly cannot classify, default to "No flow" and proceed with the request as-is.
+4. Once a flow is selected, **echo it back explicitly** before doing anything else. State the flow, the work type (if applicable), and a one-sentence justification for why this flow was chosen. Example:
+
+   > **Flow: Implement/Fix**
+   > This is a bug report with a specific error and reproduction steps, so it routes to the Fix work type within the Implement flow.
+
+   This echo is mandatory. Do not skip it, abbreviate it, or bury it in other output. The user must see the flow classification before any work begins.
+5. If you are a subagent: your parent agent has already determined the flow -- do NOT ask the user to choose a flow. Execute your assigned work within the established flow context.
+
+## Orchestration Selection Protocol
+
+Orchestration is owned by the **lifecycle skill** for the chosen flow, not by this rule. Each top-level lifecycle skill (`lisa:research`, `lisa:plan`, `lisa:implement`, `lisa:verify`, `lisa:monitor`, `lisa:intake`) contains its own cascade-safe orchestration preamble — that's where the team is created (or skipped, if already inside one).
+
+What this rule still enforces:
+
+1. **Echo orchestration mode immediately after echoing the flow** (in the same message), so the user sees both before any work begins:
+
+   > **Orchestration: agent team** (or **single agent**)
+   > One-sentence justification.
+
+2. **Cascade rule (load-bearing)**: Before creating a team, check whether you are already operating inside an agent team. Signs you are inside a team: a prior successful team-creation tool call exists in this session; you were spawned into a team context; your context references a team lead. If any of these are true, **do NOT create a second team** — many harnesses reject double-creates and the work stalls — and do NOT collapse the nested flow into inline single-agent work. The nested flow must request the existing team lead add the specialist agent(s) it needs to the current team and coordinate through the shared task state. 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` the specialists; if no lead handle exists but spawning is available, spawn the bounded specialist agent(s), `wait_agent`, and relay results upward. Invoke flows via the Skill tool; never satisfy a team-first flow by doing all the work inline.
+
+3. **Default mode**: `Research`, `Plan`, `Implement`, `Intake`, and `Debrief` run as agent teams. The `Implement` flow — including every work type (`Build`, `Fix`, `Improve`, `Investigate-Only`) — is **always** a team flow. Bug fixes that "look simple" are not an exception: the Reproduce sub-flow, debug-specialist, bug-fixer, parallel reviewers, and verification-specialist all need to compose. `Debrief` runs as a team because tracker-mining and pr-mining parallelize cleanly and synthesis gates on both completing. `Verify` (standalone) and `Monitor` (standalone) use the One-shot Sub-agents pattern (see `## Orchestration` below) — these flows are linear with no parallelism and the team overhead is not warranted. Single-agent mode is otherwise reserved for: `product-walkthrough` invoked standalone (not as part of Research/Plan), `debrief-apply` (deterministic routing of human-marked dispositions), and one-off diagnostic Bash/Read sessions that don't invoke any lifecycle skill. When in doubt, use a team.
+
+The mechanical team bootstrap directive lives inside each lifecycle skill — see those skills' orchestration preambles for the exact wording. The Claude path uses `TeamCreate`; other runtimes must use their equivalent team-discovery and team-creation tools, or explicitly declare the no-team fallback when no such tool exists.
+
+## Readiness Gate Protocol
+
+Every flow begins with a gate check. The gate defines what information must be present before the flow can begin.
+
+If the gate fails:
+- **Interactive session** (user is present):
+  1. Identify exactly what is missing
+  2. Before asking the user, attempt to answer the questions yourself from available context (source code, docs, git history, project structure, config files). Only ask the user about information you genuinely cannot determine.
+  3. When you do ask the user, provide recommended answers to choose from based on what you found in the codebase. Do not ask open-ended questions when you can offer specific options.
+  4. Tell the user what is needed and why
+  5. Do NOT proceed until the missing information is provided or resolved
+  6. If the missing information can be obtained by running a preceding flow (e.g., Research before Plan), suggest that instead
+- **Headless/non-interactive session** (running with `-p` flag, in a CI pipeline, or as a scheduled agent): do NOT block on missing information. Infer what you can from available context (ticket content, prompt text, codebase state, git history). Proceed with best effort using what is available. If critical information is truly unobtainable, fail with a clear error message explaining what was missing.
+
+## Main Flows
+
+### Research
+
+When: "I need a PRD", "What should we build?", product discovery, requirements gathering, feature exploration, understanding a problem space, open-ended feature ideas.
+
+Gate:
+- A problem statement, feature idea, or business objective must be provided
+- If none is provided, ask: "What problem are you trying to solve or what capability are you trying to add?"
+
+Sequence:
+1. **Investigate sub-flow** -- gather context from codebase, git history, existing behavior, and external sources
+2. `product-specialist` -- define user goals, user flows (Gherkin), acceptance criteria, error states, UX concerns, and out-of-scope items
+3. **Edge Case Brainstorm sub-flow** -- run the PRD candidate through the edge-case checklist; fold accepted cases into acceptance criteria, out-of-scope, or open questions
+4. `architecture-specialist` -- assess technical feasibility, identify constraints, map existing system boundaries
+5. Synthesize findings into a PRD containing: problem statement, user stories, acceptance criteria, technical constraints, open questions, and proposed scope
+6. **Plan Phase Tooling** -- review all available skills and agents (project-defined, plugin-provided, and built-in) and determine which ones the Plan phase will need. For each recommended skill or agent, state why it is needed. If no skills or agents beyond the defaults are identified, explicitly justify why the standard set is sufficient. Include this as a "Recommended Tooling for Plan Phase" section in the PRD.
+7. **Create the PRD in the configured source** -- invoke `lisa:prd-source-write` with the synthesized PRD (`title`, `body`, `initial_role` resolved from the caller's `prd_ready` flag — `draft` by default, `ready` when `prd_ready=true`, plus any `dedupe_key`/`marker`/`source_ref` the caller passed). The PRD **lives in the source** (Notion page / Confluence page / GitHub issue / Linear project per `.lisa.config.json` `source`); there is no separate document artifact. A `source` must be configured — if it is not, stop and report it. `prd-source-write` dedupes by marker, so re-running against the same idea references the existing PRD instead of creating a duplicate.
+8. **Record Research usage on the PRD artifact** -- invoke `lisa:usage-accounting` against the created PRD/source artifact so it gains a direct `research` usage entry in the canonical `## Lisa Usage` section at creation time. If the runtime cannot provide trustworthy usage, still write the row with `source: unavailable` and nullable token/cost fields; missing usage is never treated as zero or silently omitted.
+9. `learner` -- capture discoveries for future sessions
+
+Output: A PRD created in the configured source, carrying a "Recommended Tooling for Plan Phase" section, in the `draft` role by default (or `ready` when `prd_ready=true`, so `lisa:intake` auto-claims it). If there is not enough context to produce a complete PRD, stop and report what is missing rather than creating an incomplete one. If no `source` is configured, stop and report it rather than emitting a loose document.
+
+### Plan
+
+When: "Break this down", "Create tickets", epic planning, large scope work, JIRA epic tickets, "Turn this PRD into work items".
+
+Gate:
+- A PRD, specification document, or equivalent detailed description must be provided
+- The specification must contain: clear scope, acceptance criteria, and enough detail to decompose into work items
+- If no specification exists, stop and suggest running the **Research** flow first
+- If the specification has unresolved ambiguities, stop and list them
+
+Sequence:
+1. **Investigate sub-flow** -- explore codebase for architecture, patterns, dependencies relevant to the spec
+2. `product-specialist` -- validate and refine acceptance criteria for the whole scope, including error states and UX concerns
+3. **Edge Case Brainstorm sub-flow** -- run the PRD as a whole through the checklist to catch scope-shaped gaps before decomposition
+4. `architecture-specialist` -- map dependencies, identify cross-cutting concerns, determine execution order
+5. **Implement/Verify Phase Tooling** -- review all available skills and agents (project-defined, plugin-provided, and built-in) and determine which ones the Implement and Verify phases will need for each work item. For each recommended skill or agent, state why it is needed and which work items it applies to. If no skills or agents beyond the defaults are identified for a work item, explicitly justify why the standard set is sufficient.
+6. Decompose into ordered work items (epics, stories, tasks, spikes, bugs). For each item, run the **Edge Case Brainstorm sub-flow** scoped to that item — accepted cases become additional acceptance criteria or sub-tasks; rejected ones are noted with a one-line reason. Each item carries:
+   - Type (epic, story, task, spike, bug)
+   - Acceptance criteria (including any added by the per-item brainstorm)
+   - Verification method
+   - Dependencies
+   - Skills and agents required (from step 5)
+7. Create work items in the tracker (JIRA, Linear, GitHub) with acceptance criteria, dependencies, and recommended skills/agents
+8. **Record Plan usage on the PRD and created work items** -- route all direct usage writes through `lisa:usage-accounting`: attach a `plan` entry to the source PRD/spec artifact and to each created work item. If runtime usage is unavailable, still write an explicit `source: unavailable` row with nullable token/cost fields instead of omitting the entry.
+9. **PRD back-link** -- update the source PRD with a `## Tickets` section listing every created work item (key, title, type, link), so the PRD becomes the canonical anchor for downstream flows (notably **Debrief**). Invoke `lisa:prd-backlink` with the PRD source and the created ticket list. The section is regenerated on each run, not appended, so re-planning never produces stale links.
+10. **Refresh the PRD usage rollup** -- re-invoke `lisa:usage-accounting` on the source PRD after `lisa:prd-backlink` regenerates child refs so the PRD `## Lisa Usage` rollup reflects the created ticket set.
+11. `learner` -- capture discoveries for future sessions
+
+Output: Work items in a tracker with acceptance criteria and recommended skills/agents, ordered by dependency. The source PRD carries a `## Tickets` section linking back to every created item. If the specification cannot be decomposed without further clarification, stop and report what is missing.
+
+### Implement
+
+When: Working on a specific ticket (story, task, bug, spike), implementing a well-defined piece of work.
+
+Gate:
+- A well-defined work item with acceptance criteria must be provided (ticket URL, file spec, or detailed description)
+- The work item must have clear scope, expected behavior, and verification method
+- If acceptance criteria are missing or ambiguous, stop and ask before proceeding
+- If the work item is too large (epic-level), stop and suggest running the **Plan** flow first
+
+Determine the work type and execute the matching variant:
+
+#### Build (features, stories, tasks)
+
+1. **Investigate sub-flow** -- explore codebase for related code, patterns, dependencies
+2. `product-specialist` -- define acceptance criteria, user flows, error states
+3. `architecture-specialist` -- design approach, map files to modify, identify reusable code
+4. `test-specialist` -- design test strategy (coverage, edge cases, TDD sequence)
+5. `builder` -- implement via TDD (acceptance criteria become tests)
+6. Run quality gates: lint, typecheck, tests (these are prerequisites, NOT verification)
+7. `verification-specialist` -- verify locally (run the software, observe behavior)
+8. `verification-specialist` -- invoke `codify-verification` skill per passing verification (Playwright for UI, integration test for API/DB/auth, etc.); commit each test in the same PR
+9. **Record Implement usage on the work artifact** -- invoke `lisa:usage-accounting` against the originating work item or implementation artifact so it gains a direct `implement` usage entry in the canonical `## Lisa Usage` section. If the hierarchy / parent refs are already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise record the direct entry and leave rollup for the next caller that has the child refs. If runtime usage is unavailable, still write `source: unavailable` with nullable token/cost fields instead of omitting the row.
+10. **Review sub-flow**
+11. `learner` -- capture discoveries
+
+#### Fix (bugs)
+
+1. **Reproduce sub-flow** -- write failing test or script that demonstrates the bug (MANDATORY before any fix is attempted)
+2. **Investigate sub-flow** -- git history, root cause analysis
+3. `debug-specialist` -- prove root cause with evidence
+4. `architecture-specialist` -- assess fix risk, identify files to change, check for ripple effects
+5. `test-specialist` -- design regression test strategy
+6. `bug-fixer` -- implement fix via TDD (reproduction becomes failing test)
+7. Run quality gates: lint, typecheck, tests (these are prerequisites, NOT verification)
+8. `verification-specialist` -- verify locally (prove the bug is fixed)
+9. `verification-specialist` -- invoke `codify-verification` skill to encode the fix as a regression test (mandatory for bug fixes — the test must fail against the pre-fix commit and pass against the fix); commit in the same PR
+10. **Record Implement usage on the work artifact** -- invoke `lisa:usage-accounting` against the originating work item or implementation artifact so it gains a direct `implement` usage entry in the canonical `## Lisa Usage` section. If the hierarchy / parent refs are already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise record the direct entry and leave rollup for the next caller that has the child refs. If runtime usage is unavailable, still write `source: unavailable` with nullable token/cost fields instead of omitting the row.
+11. **Review sub-flow**
+12. `learner` -- capture discoveries
+
+#### Improve (refactoring, optimization, coverage improvement)
+
+1. **Investigate sub-flow** -- understand current state, measure baseline
+2. `architecture-specialist` -- identify target, plan approach
+3. `test-specialist` -- ensure existing test coverage before refactoring (safety net)
+4. `builder` -- implement improvements via TDD
+5. Run quality gates: lint, typecheck, tests (these are prerequisites, NOT verification)
+6. `verification-specialist` -- measure again, prove improvement over baseline
+7. `verification-specialist` -- invoke `codify-verification` skill (typically a benchmark asserting against baseline for performance work, or a regression test for behavioral refactors); commit in the same PR
+8. **Record Implement usage on the work artifact** -- invoke `lisa:usage-accounting` against the originating work item or implementation artifact so it gains a direct `implement` usage entry in the canonical `## Lisa Usage` section. If the hierarchy / parent refs are already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise record the direct entry and leave rollup for the next caller that has the child refs. If runtime usage is unavailable, still write `source: unavailable` with nullable token/cost fields instead of omitting the row.
+9. **Review sub-flow**
+10. `learner` -- capture discoveries
+
+#### Investigate Only (spikes)
+
+1. **Investigate sub-flow** -- full investigation
+2. Report findings with evidence
+3. Recommend next action (Research, Plan, Implement, or escalate)
+4. `learner` -- capture discoveries
+
+Output: Code passing all quality gates + local empirical verification + codified regression test for each verification (except for spikes, which produce findings only, and non-behavioral verification types — PR / Documentation / Deploy — which carry their own proof).
+
+### Verify
+
+When: Code is ready to ship. All quality gates pass and local empirical verification is complete. Moving from "works on my machine" to "works in production".
+
+Gate:
+- Code must pass quality gates (lint, typecheck, tests)
+- Local empirical verification must be complete
+- Each passing local verification must be codified as a regression test (or carry a documented skip from the allowed set: PR / Documentation / Deploy / Investigate-Only). If verifications are not codified, return to the Implement flow's codify step before shipping
+- If quality gates fail, go back to **Implement**
+- If no code changes exist, there is nothing to verify
+
+Sequence:
+1. Commit -- atomic conventional commits via `git-commit` skill
+2. PR -- create/update pull request via `git-submit-pr` skill
+3. PR Watch Loop (repeat until mergeable):
+   - If status checks fail -- fix and push
+   - If merge conflicts -- resolve and push
+   - If bot review feedback (CodeRabbit, etc.):
+     - Valid feedback -- implement fix, push, resolve comment
+     - Invalid feedback -- reply explaining why, resolve comment
+   - Repeat until all checks pass and all comments are resolved
+4. Merge the PR
+5. Monitor deploy (watch the deployment action triggered by merge):
+   - If deploy fails -- fix, open new PR, return to step 3
+6. Remote verification:
+   - `verification-specialist` -- verify in target environment (same checks as local verification, but on remote)
+   - `ops-specialist` -- post-deploy health check, smoke test, monitor for errors in first minutes
+   - If remote verification fails -- fix, open new PR, return to step 3
+7. **Record Verify usage on the evidence artifact** -- invoke `lisa:usage-accounting` against the generated evidence artifact (comment body, PR evidence section, or markdown proof) so it gains a direct `verify` usage entry in the canonical `## Lisa Usage` section. If the originating work item or PRD parentage is known, prefer `record_and_rollup` so ancestor totals refresh in the same pass. If runtime usage is unavailable, still write `source: unavailable` with nullable token/cost fields instead of omitting the row.
+8. **Post evidence via the tracker surface** -- invoke `lisa:tracker-evidence` after the usage write so the same canonical evidence artifact is uploaded / posted without hand-editing a second format.
+
+Output: Merged PR, successful deploy, remote verification passing.
+
+### Debrief
+
+When: An initiative is fully shipped — every work item from the original Plan is in a terminal state and its PR is merged. The user wants to surface candidate learnings (edge cases, gotchas, friction, tooling gaps, convention drift) for human triage so future agents inherit what this initiative taught.
+
+Gate:
+- A PRD or epic must be provided as input — the PRD URL (Notion / Confluence / Linear / GitHub Issue / file), the epic key (JIRA), or the epic issue URL (GitHub). The PRD's `## Tickets` section (written by Plan step 8) is the canonical anchor for the work-item set; an epic's children are the equivalent.
+- Every work item linked from the input must be in a terminal state (Done / Closed / Cancelled). If any item is still open, stop and list the unfinished items.
+- Every Done item that was implementable must have at least one merged PR linked. If a Done item has no PR, surface it as a debrief anomaly rather than silently excluding it.
+- Headless / non-interactive sessions: do not block on missing input — if the input is ambiguous (e.g., only a vague initiative name), fail with a clear error listing what was needed.
+
+Sequence:
+1. **Resolve the work-item set** — read the input. If it's a PRD, follow its `## Tickets` section. If it's an epic, list its children. Build the canonical list of `(work_item, linked_PRs[])` tuples. If a work item has no `linked_PRs` and is not a spike, mark it as an anomaly to surface in step 4.
+2. **Mine in parallel** (run as concurrent tasks within the team):
+   - `tracker-mining-specialist` — for every work item, walk the description, every comment (human, agent evidence, CodeRabbit summary), status transitions and their durations, late-arriving bugs that reference the item, and child sub-tasks added during implementation. Output a structured per-ticket findings list.
+   - `pr-mining-specialist` — for every linked PR, walk the description, every review comment (general + inline; CodeRabbit + human), every commit on the branch (especially late `fix:` / `revert:` / follow-up commits), and every test file added. Output a structured per-PR findings list.
+3. `learnings-synthesizer` — consume both findings lists, deduplicate, and categorize each candidate learning into one of:
+   - **Edge case** — a failure mode that should have been caught at PRD/Plan time; candidate addition to the Edge Case Brainstorm checklist
+   - **Recurring gotcha** — a stack- or codebase-specific trap (e.g., "this ORM silently truncates X")
+   - **Process friction** — a step in the lifecycle that consistently slowed the work
+   - **Tooling gap** — missing skill, wrong agent assignment, broken hook, missing automation
+   - **Convention drift** — an unwritten rule revealed by review comments that should be codified
+4. **Produce the human-triage document** — a markdown file with one row per candidate learning showing: category, summary, evidence (links to the source ticket comment / PR comment / commit), recommended persistence destination, and a checkbox-style disposition field the human will mark (Accept / Reject / Defer). Surface step-1 anomalies (work items missing PRs, etc.) in a separate section. The document is exhaustive — it lists every candidate, even ones the synthesizer rates low confidence — because the human, not the agent, decides what is worth keeping.
+5. **Record Debrief usage on the triage document** — invoke `lisa:usage-accounting` against the generated markdown artifact so the document carries its own direct `debrief` usage entry in the canonical `## Lisa Usage` section. If runtime usage is unavailable, write the entry with `source: unavailable` and nullable token/cost fields rather than skipping it.
+6. **Stop and hand the document to the human.** Debrief does NOT persist accepted learnings itself. The human triages, marks dispositions, and runs the **`/lisa:debrief:apply`** command (skill: `debrief-apply`) to route the accepted items to their destinations.
+
+Output: A triage-ready learnings document covering every work item and PR in the initiative, with structured evidence and disposition fields. Persistence is deferred to `debrief-apply`, which the human invokes after triage.
+
+## Sub-flows
+
+Sub-flows are reusable sequences invoked by main flows. When a flow says "Investigate sub-flow", execute the full Investigate sequence.
+
+### Investigate
+
+Purpose: Gather context and evidence about code, behavior, or systems.
+
+Sequence:
+1. `git-history-analyzer` -- understand why affected code exists, find related past changes
+2. `debug-specialist` -- reproduce if applicable, trace execution, prove findings with evidence
+3. `ops-specialist` -- check logs, errors, health (if runtime issue)
+4. Report findings with evidence
+
+### Edge Case Brainstorm
+
+Purpose: Force explicit consideration of edge cases at PRD time and at work-item time, so failure modes that change scope or add acceptance criteria are caught before implementation rather than after a bug is filed in production.
+
+Invoked by: Research (against the PRD as a whole), Plan (once against the PRD before decomposition, then once per work item during decomposition), and Build / Fix sub-flows when a `product-specialist` or `test-specialist` step would otherwise rubber-stamp acceptance criteria.
+
+Sequence:
+1. Walk through the checklist below and propose every candidate edge case that plausibly applies to the scope under review. Aim for breadth, not pre-filtered relevance — propose first, judge second.
+2. For each candidate, take an explicit action and record it:
+   - **Accept** — fold into acceptance criteria (PRD-level or work-item level), or open a new work item / sub-task if the case is large enough to warrant one
+   - **Defer** — capture as an open question or `Out of Scope` line with a one-sentence reason
+   - **Reject** — note the case and a one-sentence reason it does not apply (e.g., "single-tenant, no concurrent edits possible")
+3. A silent skip is not allowed — every candidate from the checklist must end up Accepted, Deferred, or Rejected with a reason. "Considered edge cases" without a per-item disposition does not satisfy this sub-flow.
+4. If three or more candidates are Accepted at PRD time, treat that as a signal that the PRD scope is wider than originally framed and call it out in the synthesis step.
+
+Checklist (pattern + question form — ask each question literally of the scope under review):
+
+**Navigation & URL state**
+- *Reload persistence*: if the user reloads mid-task, do they land where they were — same tab, same filters, same scroll, same selection — or get bounced to a default?
+- *Deep linking*: can the URL alone reconstruct the screen, or does it require state from a previous click?
+- *Back / forward*: does browser history match what the user expects, or does it skip steps or re-trigger side effects?
+- *Parameter change then reload*: after the user changes filters / sort / tab / pagination, does a reload preserve those choices?
+
+**Data lifecycle**
+- *Empty state*: what does this look like the very first time, with zero data?
+- *Single vs. many*: does the UI degrade with 1 item, 10k items, or at pagination boundaries?
+- *Stale data*: if the user leaves the tab open for an hour, what is wrong when they come back?
+- *Concurrent edits*: two users (or two tabs) editing the same record — last-write-wins, conflict, or merge?
+- *Deletion mid-flow*: the resource the user is viewing gets deleted by someone else while they have it open.
+
+**Failure modes**
+- *Network*: offline, slow, intermittent, request mid-flight when the user navigates away.
+- *Partial success*: bulk action where 8 of 10 succeed — what does the user see and what state is the system in?
+- *Permission denied mid-flow*: token expires, role changes, resource becomes inaccessible.
+- *Idempotency*: double-click submit, retry after timeout — does the action happen twice?
+
+**Input boundaries**
+- *Text*: empty, max-length, unicode, whitespace-only, leading / trailing whitespace, emoji, RTL.
+- *Numeric*: zero, negative, very large, non-integer, floating-point precision.
+- *Date / time*: timezone, DST transition, leap day, "now" vs. server time skew.
+
+**Auth & session**
+- *Session expiry mid-action*: what happens to in-flight work?
+- *Role downgrade*: the user loses access to the screen they are currently on.
+- *Multi-tab session*: logout in one tab while another tab is mid-action.
+
+This list is non-exhaustive — agents should propose additional edge cases relevant to the domain (e.g., real-time / streaming, money / financial rounding, regulated data, multi-tenant isolation) and run them through the same Accept / Defer / Reject discipline.
+
+### Reproduce
+
+Purpose: Create a reliable reproduction that demonstrates a bug before fixing it.
+
+Sequence:
+1. Execute the exact scenario that triggers the bug
+2. Capture complete error output and evidence
+3. Write a failing test that captures the bug (preferred) or a minimal reproduction script
+4. Verify the reproduction is reliable (runs multiple times, consistently fails)
+
+A bug MUST be reproduced before any fix is attempted. If reproduction fails, report what was tried and stop.
+
+### Review
+
+Purpose: Multi-dimensional code review before shipping.
+
+Sequence:
+1. Run in parallel: `quality-specialist`, `security-specialist`, `performance-specialist`
+2. `product-specialist` -- verify acceptance criteria are met empirically
+3. `test-specialist` -- verify test coverage and quality
+4. Consolidate findings, ranked by severity
+
+### Monitor
+
+Purpose: Check application health and operational status. Can be invoked standalone or as part of Verify.
+
+Sequence:
+1. `ops-specialist` -- health checks, log inspection, error monitoring, performance analysis
+2. Report findings, escalate if action needed
+
+## Tracker Entry Point (JIRA, GitHub Issues, or Linear)
+
+When the request references a tracker ticket (a JIRA key like `PROJ-123`, a JIRA URL, a GitHub issue URL, an `org/repo#<n>` token, or a Linear identifier like `ENG-123` or a Linear project URL):
+
+1. Hand off to the matching vendor agent — `jira-agent` (JIRA refs), `github-agent` (GitHub Issue refs), or `linear-agent` (Linear identifier or project URL). The configured destination tracker (`.lisa.config.json` `tracker`) is the default when the ref shape is ambiguous.
+2. The agent reads the work item fully via the matching read skill (`jira-read-ticket` / `github-read-issue` / `linear-read-issue`) — description / body, comments, attachments, linked items, parent (Epic / Project / parent Issue), siblings.
+3. The agent validates item quality via the matching verify skill (`jira-verify` / `github-verify` / `linear-verify`).
+4. The agent runs analytical triage via the vendor-neutral `ticket-triage` skill.
+5. If triage finds unresolved ambiguities (`BLOCKED` verdict), the agent posts findings and STOPS -- no work begins.
+6. The agent determines intent and delegates to the appropriate flow:
+
+| Item kind | Flow | Work Type |
+|-----------|------|-----------|
+| Epic (JIRA Epic / GitHub Epic-labeled / Linear Project) | Plan | -- |
+| Story | Implement | Build |
+| Task | Implement | Build |
+| Bug | Implement | Fix |
+| Spike | Implement | Investigate Only |
+| Improvement | Implement | Improve |
+| Sub-task / sub-Issue | Implement | (per parent's intent) |
+
+For JIRA, the type comes from the ticket's issue type. For GitHub, the type comes from the `type:<value>` label. For Linear, the type typically comes from a label (`type:story`, `type:bug`) or is inferred from the description if unlabeled — `linear-agent` handles the inference.
+
+If the item type is ambiguous, read the description / body to classify. A "Task" that describes broken behavior is a Fix. A "Bug" that requests new functionality is a Build.
+
+7. The agent syncs progress at milestones via the matching sync skill (`jira-sync` / `github-sync` / `linear-sync`).
+8. The agent posts evidence at completion via the matching evidence skill (`jira-evidence` / `github-evidence` / `linear-evidence`).
+
+Vendor-neutral callers (e.g., `implement`, `verify`) should invoke the `tracker-*` shims — they dispatch to the right vendor automatically.
+
+## Flow Chaining
+
+Flows can chain naturally:
+- Research produces a PRD -- hand it to Plan
+- Plan produces work items (and writes a `## Tickets` back-link section into the PRD) -- hand each item to Implement
+- Implement produces verified code -- hand to Verify
+- Verify ships and confirms the deploy -- once every work item in the PRD is shipped, hand the PRD (or the epic) to Debrief
+- Debrief produces a triage-ready learnings document -- hand to the human, who marks dispositions and runs `debrief-apply` to persist accepted learnings
+- If any flow discovers it lacks what it needs, it stops and suggests the preceding flow
+
+The full lifecycle for a large initiative: Research -> Plan -> Implement (per item) -> Verify (per item) -> Debrief (once across the whole initiative) -> Debrief Apply (human-triggered, after triage).
+
+## Sub-flow Usage
+
+Flows reference sub-flows by name. When a flow says "Investigate sub-flow", execute the full Investigate sub-flow sequence. When it says "Review sub-flow", execute the full Review sequence. Sub-flows can be invoked by any main flow.
+
+## Orchestration
+
+> **Note**: Orchestration authority belongs to lifecycle skills (see `## Orchestration Selection Protocol` above). This section documents the patterns that lifecycle skills implement — it is reference material, not a directive for this rule to choose modes independently.
+
+Lifecycle skills dispatch their agents according to the flow's shape. The following patterns are how they do it — do not default to the heaviest one.
+
+### Agent Teams (default for multi-step flows)
+
+Use an **agent team** (runtime team creation + durable task state per step) for:
+
+- **Implement** (Build, Fix, Improve) — long sequences with parallel review and a real risk of compaction
+- **Plan** — multiple specialists feeding a shared decomposition
+- **Research** — multiple specialists feeding a shared PRD
+- **Debrief** — tracker-mining and pr-mining run in parallel and gate the synthesizer; the work-item set can be large, so durable task state matters
+- Any flow that invokes the **Review sub-flow** (the four review specialists run in parallel and gate a single follow-up task)
+
+Why: these flows have enough steps that context compaction is likely; the Review sub-flow is parallel-by-design and `blockedBy` expresses that cleanly; durable task state lets the team lead recover assignments after compaction.
+
+When using a team:
+
+1. Create one team per top-level flow invocation. Do not nest teams for sub-flows — sub-flow steps become tasks within the existing team.
+2. Express parallelism with `blockedBy`. The Review sub-flow's four specialists are independent; the "implement valid suggestions" task is `blockedBy` all four.
+3. On every TaskUpdate that sets `owner`, also store it in `metadata.owner` so the assignment survives context compaction.
+4. Re-read TaskList after any compaction event before assigning new work.
+
+### One-shot Sub-agents (for short or single-agent flows)
+
+Use direct `Agent` tool invocations (no team) for:
+
+- **Verify** when run standalone — it's a linear gate sequence with no parallelism
+- **Monitor** standalone — single specialist (`ops-specialist`) producing a report
+- **Investigate Only** spikes — single investigation, findings out
+- Any flow chained as a sub-flow inside a larger team — its agents become tasks in the parent team, not a new team
+
+Why: team creation plus per-step task state is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
+
+### When in doubt
+
+If the flow has more than three agent steps, or any parallel step, or is likely to span a compaction boundary, use a team. Otherwise, sub-agents are fine.

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

@@ -0,0 +1,120 @@
+# Leaf-Only Build-Ready Invariant, Parent Status Rollup & Terminal Native Closure
+
+This is the single vendor-neutral source of truth for three coupled lifecycle rules. Every `*-to-tracker`, `*-write-*`, `*-validate-*`, and `*-build-intake` skill cites this rule rather than restating it, so per-vendor logic does not drift.
+
+1. **Leaf-only invariant** — only an independently implementable **leaf work unit** may carry the build-ready role. A parent/container with child work is never directly build-ready.
+2. **Parent status rollup** — a parent/container's lifecycle state is *derived* from its children, never set independently.
+3. **Terminal native closure** — when a leaf work unit reaches the configured terminal `done` role, Lisa also closes / resolves / completes it using the provider's native mechanism where one exists. Intermediate done-like environment states stay open.
+
+The first two are the same idea seen from opposite ends: a parent never enters the build queue as work; it only ever *reflects* the state of the leaves underneath it. The third keeps the provider's native open/closed signal aligned with Lisa's terminal lifecycle state so finished work does not linger as open.
+
+## Why this exists
+
+Build intake processes whatever carries the build-ready role (the `ready` role — see `config-resolution`). A parent container (an Epic, a Story, a Linear Project, any issue with child work) is not a unit of implementation; it organizes work. If a parent is marked build-ready, an agent may try to implement the container itself unless intake gates it first — the wrong permission and lifecycle boundary. This surfaced in real PRD intake: a PRD decomposed into an Epic, Stories, and Sub-tasks, and *every* item received the build-ready label, so a subsequent build pass would have tried to "implement" the Epic.
+
+The fix is not vendor-specific. It belongs here, in a cross-vendor rule, and every writer / validator / intake path enforces it.
+
+## Container vs. leaf taxonomy
+
+A **leaf work unit** is an individually implementable item with **no child work** — issue types **Bug, Task, Sub-task, Improvement**. These are what an agent claims and implements. This is the same definition used by the `repo-scope-split` rule (a leaf work unit is also single-repo).
+
+A **container** organizes other work and is never directly implemented:
+
+| Class | Examples by type | May carry build-ready? |
+|---|---|---|
+| **Leaf work unit** | Bug, Task, Sub-task, Improvement — with no children | **Yes** |
+| **Container** | Epic, Story, Spike, or *any* item that has child work | **No** — state rolls up from children |
+
+The classification is **structural, not nominal**: an item is a container if it has child work, regardless of its declared type. A "Task" that has acquired sub-tasks is a container for rollup purposes. The type label is a strong default (Epic/Story/Spike are containers by design), but the presence of children is decisive. See the childless-parent exception below for the converse case.
+
+### How each vendor encodes hierarchy
+
+The invariant is vendor-neutral; the mechanics of "has child work" differ. A skill resolves child membership using the native hierarchy first, falling back to text/metadata links where the vendor has no native parent/child:
+
+- **GitHub Issues** — native **sub-issues** (parent ↔ child issue graph), plus task-list checkboxes and `Blocked by #<n>` / parent references in the body. Epic and Story are modeled as parent issues; their Sub-tasks are sub-issues.
+- **JIRA** — native **Epic → Story → Sub-task** hierarchy: Epic link / parent field for Stories under an Epic, and the subtask relationship for Sub-tasks under a Story/Task. Issue links (`blocks` / `is blocked by`) express cross-item dependencies but are not parentage.
+- **Linear** — **Project** (the Epic equivalent) groups **Issues** via `projectId`; an Issue groups **sub-issues** via `parentId`. Project state and Issue state are native. Relations (`save_issue_relation`) express dependencies, not parentage. (Initiatives are not used — see `config-resolution`.)
+
+Where a vendor lacks native hierarchy for a given pair, a text link or metadata marker establishes the relationship (per PRD #522 non-goals: vendors need not expose identical native hierarchy features).
+
+## Leaf-only invariant (the rule)
+
+**Build-ready means a directly implementable leaf work unit.** Therefore:
+
+- **At decomposition / write time** — when a PRD decomposes into a hierarchy, only the leaf work units receive the `ready` role (status/label). Parent containers (Epic, Story, Project, and any parent issue that has child work) are created in their normal non-ready state and never receive the build-ready role directly. The leaves are what downstream build intake will claim.
+- **At validate time** — the `*-validate-*` gate FAILs any container carrying the build-ready role. This is the symmetric write-side guard: a stale or hand-applied build-ready role on a parent is a lifecycle error.
+- **At claim time** — build intake scans for the `ready` role but dispatches **only leaf work units**. A container that still carries a stale build-ready role (e.g. applied before this rule existed) is **not dispatched**: intake either moves it into the vendor's parent/container progress state or safely blocks it with a clear lifecycle-repair message. Intake never silently implements a container.
+
+The permission boundary is the maintainer-applied build-ready role, not authorship — do not add author-based guards (PRD #522 non-goal). This rule narrows *what* may carry that role, not *who* may apply it.
+
+## Childless-parent exception
+
+A container *type* with **no child work** is, structurally, a leaf — and may be build-ready **iff its issue type is itself a valid leaf work unit**.
+
+- A **Task** or **Bug** with no children → leaf → may be build-ready. (Many real tickets are flat Tasks with no sub-tasks; this rule must not strand them.)
+- An **Epic, Story, or Spike** with no children → still **not** build-ready. These types are coordination containers by design; an empty one is an incomplete decomposition, not an implementable unit. The correct repair is to decompose it (add leaf children) or reclassify it to a leaf type — not to claim it.
+
+So the exception is narrow: childlessness *enables* build-ready only for types that are leaf work units to begin with. It never promotes an Epic/Story/Spike to directly implementable.
+
+## Parent status rollup (the state machine)
+
+A parent/container never sets its own lifecycle state; it **derives** it from the roll-up of its children's states. Rollup is evaluated whenever a child transitions (or when intake observes the child set). Using the canonical build-lifecycle roles from `config-resolution` (`ready`, `claimed`, `review`, `blocked`, `done`):
+
+Evaluate the children in priority order and take the **first** match:
+
+| If among the required leaves… | …the parent rolls up to | Role |
+|---|---|---|
+| any leaf is **blocked** | blocked / attention-needed | `blocked` |
+| else any leaf is **in progress** (claimed or in review) | active / in-progress | `claimed` |
+| else **all** required leaves are **terminal** (`done`) | the configured rollup terminal state | `done` (or `review` where supported — see below) |
+| else (leaves exist but none started) | unchanged (parent stays in its non-ready container state) | — |
+
+Notes:
+
+- **Blocked dominates.** A single blocked leaf surfaces blocked/attention on the parent even if other leaves are progressing, so a human sees the parent needs attention.
+- **"Required" leaves.** Optional or won't-do children do not hold a parent open; only the leaves that must ship for the parent to be complete are counted toward the all-terminal check.
+- **Rollup is recursive.** An Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up: a Story reaches `done` only when its leaves are all terminal; an Epic reaches `done` only when its Stories are all `done`.
+- **Vendor support varies.** Apply the rollup state the vendor can express. Where a vendor has no native intermediate state, use the nearest configured role or a metadata/comment signal rather than forcing a non-existent status (PRD #522 non-goal: vendors need not expose identical states).
+- **The parent never carries `ready`.** `ready` is a *human* "this is buildable, claim it" signal and only ever lives on leaves. Rollup moves a parent between non-ready container states (in-progress / blocked / terminal); it never sets the parent to `ready`.
+
+### The rollup terminal state is the configured "done" — multi-env capable
+
+The terminal rollup state is whatever the project configures for `done` — which is **env-keyed** (`config-resolution` "Env-keyed `done`"): a `done` map keyed by environment (`dev`, `staging`, `production`), resolved from the merged PR's base branch. This rule does **not** hardcode a `dev → staging → prod` promotion chain as required — that is a project-specific deploy topology. A downstream project with dev/staging/prod environments rolls a parent up to whichever terminal `done` value matches the environment its leaves shipped to. The rule stays generic and multi-env capable.
+
+**Single-environment collapse (this repo).** Lisa's own deploy has only `main`/`production` (no dev/staging), so `done` is a single value, not a map. For GitHub, the build lifecycle collapses to one chain: `ready → claimed (in-progress) → done`. The rollup terminal state is simply `done`. This is the *collapsed* case of the generic rule, not a different rule — projects with more environments keep the env-keyed map.
+
+## Terminal native closure
+
+The configured terminal `done` role is not just another label or status. Once a **leaf work unit** reaches the true terminal `done` value, Lisa must also finalize the item through the tracker's native completion mechanism when the tracker supports one:
+
+| Tracker | Terminal native action |
+|---|---|
+| GitHub Issues | `gh issue close <number> --reason completed` after applying the terminal `done` label |
+| Linear | move the Issue's native workflow `state` to the team's configured Done / Completed state after applying the terminal `done` label |
+| JIRA | transition to the configured terminal Done / Resolved / Closed status and verify the resulting issue is in `statusCategory = Done` with a resolution when the workflow requires one |
+| Provider without a close / archive concept | no-op; the terminal lifecycle role is sufficient |
+
+This action is **terminal-only**:
+
+- Intermediate env-keyed states such as `status:on-dev`, `status:on-stg`, `On Dev`, or `On Stg` remain open / unresolved / active. They are deployment waypoints, not terminal completion.
+- A single-environment project whose `done` resolves to one value treats that value as terminal. In this repo, `production: main` means `status:done` / `Done` is terminal.
+- A multi-environment project treats only the production / final environment's `done` value as terminal unless the project explicitly configures `done` as a single string. Do not close native work items at lower environments.
+- The native finalization must be idempotent. If the item is already closed / completed / resolved, report that and continue.
+- If a provider exposes no native close / archive operation, or a project has not configured the native Done state, record a capability-aware no-op or setup error according to the vendor skill. Do not invent a state name.
+
+## Citation
+
+Skills that enforce this invariant or perform rollup cite this rule by slug (the `leaf-only-lifecycle` rule) instead of restating it:
+
+- **Decomposition / write** (`*-to-tracker`, `*-write-*`) — apply the `ready` role to leaves only; never to containers.
+- **Validate** (`*-validate-*`) — FAIL a container carrying the build-ready role; FAIL a childless Epic/Story/Spike marked build-ready.
+- **Build intake** (`*-build-intake`, `tracker-build-intake`) — dispatch leaves only; move or safe-block containers with stale build-ready roles according to vendor lifecycle semantics.
+- **Rollup** — derive parent state from children per the state machine above. `repair-intake`
+  also uses this rule to close out parent/container rollups that were left open after every
+  required child became terminal.
+- **Terminal native closure** (`*-build-intake`, `repair-intake`, terminal helpers) — after a leaf
+  or all-terminal rollup parent reaches the true terminal `done` role, finalize it through the
+  provider's native close / complete / resolve mechanism where available; never do this for
+  intermediate env states.
+
+This is the inverse-direction companion to `repo-scope-split` (which governs a leaf's *repo* scope); together they define what a build-ready leaf work unit is: directly implementable, single-repo, childless-or-leaf-typed.