@codyswann/lisa 2.119.1 → 2.121.1

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

@@ -0,0 +1,156 @@
+# PRD Lifecycle Rollup & Generated-Top-Level-Work Contract
+
+This is the single vendor-neutral source of truth for how a PRD owns the work it generates and how its lifecycle rolls up to `shipped` from that work. Every PRD-source and PRD-intake skill (`prd-backlink`, `prd-ticket-coverage`, `*-prd-intake`, `*-to-tracker`) cites this rule by slug rather than restating it, so PRD→child linking and PRD closure rollup behave identically across GitHub, Linear, JIRA/Atlassian, Confluence, and Notion instead of drifting per vendor.
+
+It defines four coupled things:
+
+1. **Generated top-level work** — what a PRD owns as children (its created Epics / top-level Stories), explicitly **excluding** leaf Sub-tasks.
+2. **Per-vendor terminal-state predicate** — how "this generated child is done" is decided for each source/tracker.
+3. **PRD `shipped` transition + verified native closure** — when and how a PRD rolls up to shipped, remains eligible for verification, and closes only after verified.
+4. **Idempotency dedupe key** — the child-ref identity that makes linking and rollup safe to re-run.
+
+This is the PRD-level companion to `leaf-only-lifecycle`: that rule governs the *build* lifecycle of leaf work units and how a **parent container** rolls up from its leaf children; this rule governs the *PRD* lifecycle and how the **PRD** rolls up from its generated top-level children. The two share the rollup shape (terminal children → parent advances) and the multi-env terminal handling, applied at different levels of the hierarchy.
+
+## Why this exists
+
+PRD intake currently comments back with created ticket links, but the PRD is not necessarily the structural parent of the work it generated. That makes lifecycle rollup weaker than it should be: humans cannot always navigate from PRD to generated top-level work using the host tool's hierarchy UI, agents must parse free-form comments instead of reading a first-class relationship, and PRD shipped/closed state is not automatically derived from whether its generated work is done. Worst of all, cross-vendor implementations drift in how they record the PRD-to-work relationship and when they close a PRD.
+
+The desired model is vendor-neutral: **the PRD is the source-of-truth parent for the top-level work it generated, and PRD lifecycle completion rolls up from that child set.** That belongs here, in a cross-vendor rule, and every backlink / intake / coverage path enforces it.
+
+This surfaced in real GitHub-backed PRD intake (`CodySwannGT/advisory-rankings`): PRD issue #64 generated top-level Epic #65 plus child Stories/Sub-tasks. #65 should be a child/sub-issue of #64, and #64 should eventually transition/close when #65 and its descendants are complete — not before, and not twice.
+
+## Generated top-level work (the contract)
+
+**Generated top-level work** is the set of work units a PRD's intake/decomposition *directly created at the top of the hierarchy* and now owns as children:
+
+| Class | Examples by type | Owned by the PRD as a child? |
+|---|---|---|
+| **Generated top-level work** | the created **Epic(s)**, and any **top-level Story** created directly under the PRD (a Story with no parent Epic) | **Yes** — these are the PRD's children for rollup |
+| **Descendant work** | **Sub-tasks**, and **Stories that hang under a generated Epic**, and any leaf (Bug/Task/Improvement) under a top-level unit | **No** — owned by their top-level parent, not by the PRD directly |
+
+The boundary is **structural, mirroring `leaf-only-lifecycle`'s container/leaf taxonomy but one level up**:
+
+- A PRD owns its **top-level** generated units. Those top-level units own their own descendants (per `leaf-only-lifecycle`'s parent-status-rollup state machine).
+- Leaf Sub-tasks are **never** direct children of the PRD when a top-level Epic/Story hierarchy exists (PRD #525 non-goal: "Do not make leaf implementation tasks direct children of the PRD when a top-level Epic/Story hierarchy exists"). The PRD owns top-level generated work; those top-level work units own their descendants.
+- When a PRD decomposes into a flat set with no Epic (e.g. a few top-level Stories or a single leaf Task and nothing under it), the **top-level** items it created are its generated top-level work, whatever their type. The rule is "what the PRD created at the top," not "only Epics."
+
+### How each vendor records the PRD→child relationship
+
+The relationship is recorded with the source tool's **native hierarchy first**, falling back to a **durable documented section** in the PRD where native hierarchy is unavailable or the source and destination are different systems (PRD #525: vendors need not all expose identical native hierarchy):
+
+- **GitHub Issues** — native **sub-issues**: the generated Epic issue becomes a sub-issue of the PRD issue when the repo supports sub-issues and source and tracker are the same repo. Otherwise a documented `## Tickets` / generated-work section.
+- **Linear** — native **parent / project** relationships: a generated top-level Issue uses `parentId`, or a generated Project groups generated Issues; the PRD's relationship to its top-level Project/Issues is recorded natively where the PRD also lives in Linear.
+- **JIRA** — native **Epic link / parent field** or a documented issue-link type for the PRD→Epic relationship where available.
+- **Confluence / Notion** — no native issue hierarchy for tracker work: the PRD page carries a stable, machine-readable **generated-work section** (e.g. `## Tickets` / `## Generated Work`) listing the top-level refs and URLs.
+- **Cross-vendor** (e.g. Notion PRD → JIRA tracker) — the destination ticket cannot become a native child of the PRD, so the relationship is **always** recorded in the PRD source artifact's documented section.
+
+The documented-section fallback is always written so the generated child set is readable later without relying only on free-form comments. Comment summaries are still useful human-facing audit trails and are not removed (PRD #525 non-goal).
+
+### Vendor relationship and closure matrix
+
+Use this matrix when implementing or auditing a PRD-source integration. It describes the native relationship to prefer, the documented fallback that must remain durable, and the closure behavior after the all-terminal rollup condition is met.
+
+| PRD source / tracker shape | Native hierarchy mechanism | Documented fallback | Closure behavior |
+|---|---|---|---|
+| **GitHub Issues (source and tracker in the same repo)** | Link generated top-level work as native sub-issues of the PRD issue when the repo supports GitHub sub-issues. The PRD's direct sub-issues are the generated top-level child set; descendants under those children are excluded from PRD rollup. | Always maintain the machine-readable `## Tickets` / `## Generated Work` section keyed by `owner/repo#number`, and use it when sub-issues are unavailable, disabled, or incomplete. | Rollup changes the PRD lifecycle label from `prd-ticketed` to `prd-shipped` when every required generated top-level issue is terminal and leaves the issue open for `/lisa:verify-prd`. Verified PASS closes the issue natively. |
+| **Linear** | Use Linear native grouping where the PRD also lives in Linear: generated top-level Issues are related through `parentId`, or a generated Project groups the generated Issues. Read only top-level Issues for PRD rollup. | Use the PRD's machine-readable generated-work section when the destination tracker is not Linear or native project / parent relationships cannot represent the PRD-to-work link. Entries are keyed by Linear issue or project identifier / UUID. | Rollup removes `prd-ticketed` and adds `prd-shipped` to the PRD project when every required generated top-level Issue / Project is completed and leaves it active for `/lisa:verify-prd`. Verified PASS archives/completes it natively. |
+| **JIRA / Atlassian tracker work** | Prefer native Epic / parent fields, or a documented issue-link type where the PRD-to-Epic relationship can be represented in JIRA. JIRA child terminal state is read from the issue's Done status category. | If the PRD source is not JIRA or the native link cannot attach tracker work to the PRD artifact, record generated top-level JIRA issue keys in the PRD's generated-work section. | Rollup may transition a JIRA-hosted PRD to the configured shipped status only after all required generated top-level issues are in the Done status category. Verified PASS performs native completion where supported. |
+| **Confluence PRDs** | No native issue hierarchy for tracker work. Confluence's native structure is used for PRD lifecycle lanes by parent page, not for destination work children. | The Confluence page's machine-readable `## Tickets` / `## Generated Work` section is the primary child source. Top-level generated work entries are keyed by destination ticket ref. | Rollup re-parents the PRD page from the `ticketed` parent to the `shipped` parent when every required generated-work entry is marked done and leaves the page active for `/lisa:verify-prd`. Verified PASS archives it where supported. |
+| **Notion PRDs** | No native issue hierarchy for tracker work. Notion's native status/select property stores PRD lifecycle state, not generated ticket parentage. | The Notion page's machine-readable `## Tickets` / `## Generated Work` section is the primary child source. Top-level generated work entries are keyed by destination ticket ref. | Rollup sets the configured Notion status/select value to `Shipped` when every required generated-work entry is marked done and leaves the page active for `/lisa:verify-prd`. Verified PASS archives it where supported. |
+| **Cross-vendor PRD -> tracker** | Native hierarchy cannot cross systems, so the destination ticket is not expected to become a native child of the PRD artifact. Native tracker hierarchy still applies inside the destination system among generated Epics, Stories, and Sub-tasks. | The source PRD artifact's generated-work section is authoritative for the PRD-to-top-level-work child set, and each entry links to the destination ticket URL / key. | The PRD source owns the lifecycle transition. It evaluates terminal state using the destination tracker's predicate, applies the source vendor's `shipped` transition, leaves the PRD open/active, then `/lisa:verify-prd` owns verified native closure. |
+
+## Per-vendor terminal-state predicate
+
+A generated top-level child is **terminal** (counts as done for rollup) when it reaches the source/tracker's done/shipped state. The predicate is vendor-specific; the *semantics* ("this child has shipped") are not:
+
+| Vendor | A generated top-level child is terminal when… |
+|---|---|
+| **GitHub Issues** | the issue is **closed** *and* (where the build-status label is used) carries the resolved `done` role label (`status:done` by default — env-keyed; see below). A closed-as-not-planned issue is terminal-but-dropped: it does not hold the PRD open but is excluded from "shipped" (treated like a won't-do leaf). |
+| **Linear** | the Issue/Project is in a **completed** workflow state (`done`-category), **or** a **canceled** state (terminal-but-dropped, like not-planned — does not hold the PRD open, excluded from shipped). |
+| **JIRA** | the issue's status is in the **Done status category** (`statusCategory.key == "done"`). |
+| **Confluence / Notion** | the documented generated-work entry is marked **done** in the PRD's machine-readable section (the durable equivalent of a closed ticket, since these sources have no native ticket state). |
+
+Notes:
+
+- **Required vs. optional children.** Only the generated top-level children that must ship for the PRD to be complete are counted toward the all-terminal check. Won't-do / canceled / not-planned children are terminal-but-dropped: they do not hold the PRD open and are excluded from the shipped set. This mirrors `leaf-only-lifecycle`'s "required leaves" qualifier.
+- **Recursion is delegated, not duplicated.** A generated Epic is terminal only when *it* has rolled up to its own terminal state per `leaf-only-lifecycle`'s parent-status-rollup (all its required Stories/Sub-tasks terminal). This rule does not re-derive an Epic's state from its leaves — it reads the top-level child's own resolved state and trusts `leaf-only-lifecycle` to have rolled that up bottom-up.
+- **Blocked dominates at the report level.** If any required generated top-level child is blocked or incomplete, rollup leaves the PRD open and reports the incomplete child set (PRD #525: "rollup leaving a PRD open when at least one generated top-level child is incomplete"). The PRD is only advanced when **all** required top-level children are terminal.
+
+### The terminal `done` is the configured, env-keyed value — multi-env capable
+
+Where a vendor's terminal predicate references the build-status `done` role (GitHub/Linear labels), that value is the project's configured `done` — which is **env-keyed** (`config-resolution` "Env-keyed `done`"): a 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; a multi-env project counts a child as terminal when it reaches whichever `done` value matches the environment it shipped to.
+
+**Single-environment collapse (this repo).** Lisa's own deploy has only `main`/`production` (`deploy.branches = production: main`, no dev/staging), so `done` is a single value, not a map, and the build lifecycle collapses to one chain: `ready → claimed (in-progress) → review (code-review) → done`. A generated top-level child is terminal when it reaches the single `status:done`; rollup never resolves a `dev` or `staging` `done` in this repo. This is the *collapsed* case of the generic rule, not a different rule — projects with more environments keep the env-keyed map.
+
+## PRD `shipped` transition and verified native closure
+
+When **all required** generated top-level children are terminal, the PRD rolls up to its `shipped` PRD-lifecycle state and remains open/active for the initiative-level verification loop:
+
+1. **Transition to `shipped`.** Set the PRD to the configured `shipped` role (`config-resolution` PRD-lifecycle roles: `prd-shipped` label for GitHub/Linear, `Shipped` status for Notion, the shipped parent page for Confluence). The PRD lifecycle is `ready → in_review → (blocked | ticketed) → shipped → verified`; rollup performs the `ticketed → shipped` hop only, and only on the all-terminal condition. The subsequent `shipped → verified` (pass) / `shipped → ticketed` (fail) hops are owned by PRD-level verification (`/lisa:verify-prd`), **not** by this rollup — see "PRD-level verification vs ticket verification" below.
+2. **Leave `shipped` open for verification.** Rollup never closes, archives, or completes the PRD at the `shipped` hop. `shipped` is the queue for `/lisa:verify-prd`, so closing here would hide the PRD from the acceptance gate.
+3. **Verified closes natively.** When `/lisa:verify-prd` passes, it transitions `shipped → verified` and then closes, archives, or completes the PRD where the source tool supports a native terminal action. The verified native close is mandatory and idempotent; there is no project-configurable close-on-verified escape hatch.
+4. **Partial completion is a no-op + report.** If only some required children are terminal, leave the PRD in its current state and report the incomplete/blocked child set. Do not advance, do not close.
+
+The PRD never advances to `shipped` on its own authority — it is **derived** from the generated-top-level-child set, exactly as a container's state is derived from its leaves in `leaf-only-lifecycle`.
+
+## PRD-level verification vs ticket verification
+
+`shipped` and `verified` are two different terminal facts about a PRD, and they are established by two different flows. Keeping them distinct is the whole point of the `verified` state:
+
+| | `shipped` | `verified` |
+|---|---|---|
+| **Meaning** | All generated top-level work is terminal — the work graph is *complete* | The shipped product has been *empirically checked against the PRD itself* |
+| **Established by** | This rollup (`ticketed → shipped`), derived from child-ticket state | `/lisa:verify-prd`, the initiative-level acceptance gate |
+| **Evidence** | The terminal-child set (closed issues / done labels / completed states) | Spec-conformance against the PRD's requirements + empirical proof (browser/computer use, API/CLI/DB checks, screenshots, logs) |
+| **Ownership** | Set by the intake rollup phase; product may also set by hand | Product-owned, like `draft` and `shipped`; set only by `/lisa:verify-prd` |
+
+`shipped` is **necessary but not sufficient** for `verified`: a PRD can have every ticket closed while still missing a requirement, diverging from its acceptance criteria, or failing a real user workflow. `verified` is what proves the shipped product actually matches the PRD.
+
+**`/lisa:verify` (one work item) vs `/lisa:verify-prd` (the whole initiative).** These are deliberately separate scopes:
+
+- **`/lisa:verify`** empirically verifies a **single work item** (a ticket / story / sub-task) in its target environment as part of that item's Build/Fix/Improve flow. It is what drives a build ticket to its `done` state; it operates at the *leaf/build* level (see `leaf-only-lifecycle`). It does **not** read the PRD or judge initiative-level acceptance, and it is **not** replaced by PRD verification.
+- **`/lisa:verify-prd`** is the **initiative-level acceptance gate**. It runs *after* the PRD is `shipped` (all generated top-level work terminal), reads the PRD and its generated child set, confirms the children are terminal, then runs spec-conformance against the original PRD requirements plus empirical verification of the shipped surface. On pass it transitions the PRD `shipped → verified` and posts evidence; on fail it **re-opens the PRD `shipped → ticketed`** (never `blocked`), creates **build-ready fix tickets** for the missing or incorrect behavior (registered as the PRD's generated work) and posts a product-readable failure report — the fix tickets auto-build, rollup re-ships the PRD once they are terminal, and a later cycle re-verifies (self-healing; see "Closing the loop" below). Re-runs are idempotent (no duplicate evidence, fix tickets, or lifecycle transitions).
+
+**No extra failure states, and verification never uses `blocked`.** A failed PRD verification does **not** move the PRD to `blocked`; it re-opens the PRD `shipped → ticketed` and creates build-ready fix tickets (see "Closing the loop"), forming a self-healing loop rather than parking the PRD for a human. It introduces no `prd-verifying` or `prd-verification-failed` state — the lifecycle stays intentionally small, and `blocked` remains the *intake* (ready-stage validation) failure state, not the verification one. `verified` is terminal and product-owned (like `draft` and `shipped`); a PRD is never moved to `verified` solely because its tickets are closed, and a PRD is never closed/archived before verification has passed. The vendor maps for the `verified` role (`prd-verified` label for GitHub/Linear, `Verified` status for Notion, the verified parent page for Confluence) live in the `config-resolution` rule.
+
+### Closing the loop: PRD intake dispatches `/lisa:verify-prd` for shipped PRDs
+
+`shipped → verified` does not happen on its own — something has to run the acceptance gate. The PRD-intake scanners close that loop: in addition to the `ticketed → shipped` rollup, each PRD-intake cycle **dispatches `/lisa:verify-prd` for a shipped PRD** so a shipped PRD does not sit unverified forever. This is a **dispatch**, not a transition — the intake scanner still never *sets* the verification outcome itself; `/lisa:verify-prd` (which it invokes) performs the `shipped → verified` (pass) or, on fail, the `shipped → ticketed` re-open (it **never** uses `blocked`), with its own guard, evidence, and build-ready fix-ticket creation.
+
+**The self-healing FAIL loop.** When verify-prd fails it re-opens the PRD `shipped → ticketed` and creates **build-ready** fix tickets (registered as the PRD's generated work). Because the fix tickets are build-ready they are auto-claimed by the build queue with no human promotion; once they reach terminal, the `ticketed → shipped` rollup (Phase 3f) re-ships the PRD, and the next cycle's verify dispatch (Phase 3g) re-verifies. PASS ends at `verified`; FAIL starts another round. The loop **never auto-halts** (the failure report carries a verification-round count for human visibility) and **never** parks the PRD in `blocked`.
+
+Bounded, like the ready claim: `/lisa:verify-prd` is a heavy full flow (spec-conformance + empirical verification + fix-ticket creation), so a scanner verifies **one shipped PRD per cycle** and lets the scheduler drain the rest — the same one-item-per-cycle discipline the `ready` claim uses. After verify-prd runs, the PRD leaves `shipped` (to `verified` on pass, or `ticketed` on fail), so it is not re-picked by the shipped query that cycle; a PRD whose generated work is not actually terminal is guard-stopped by verify-prd and left `shipped` (verify-prd's gate, not the scanner's). This dispatch is **behaviorally identical across all four PRD-intake skills** (the `github` / `linear` / `notion` / `confluence` `*-prd-intake` Phase 3g); only the `shipped`-role query surface differs.
+
+## Idempotency dedupe key
+
+Linking and rollup MUST be safe to re-run: re-running intake, backlink, or rollup never produces duplicate child links, duplicate sub-issues, duplicate generated-work entries, or a double `shipped` transition (PRD #525: "Re-running backlink or rollup is idempotent").
+
+The dedupe key is **child-ref identity** — the stable, vendor-native identifier of each generated top-level child:
+
+- **GitHub** — `owner/repo#number` (the issue ref).
+- **Linear** — the issue/project identifier (e.g. `TEAM-123`) or its UUID.
+- **JIRA** — the issue key (e.g. `PROJ-123`).
+- **Confluence / Notion** — the destination ticket ref recorded in the generated-work entry (the entry is keyed by that ref, not by list position).
+
+**Match by stable ref, never by title.** Identity is the child-ref above and *only* the child-ref — never the child's title, summary, or any other mutable field. A child whose **title changed but whose ref is unchanged is the same child**: re-running linking/backlink matches it by ref, updates the displayed title in place, and does **not** create a second link or a duplicate generated-work entry. Conversely, two distinct refs are two distinct children even if their titles happen to be identical. Title-based matching would both miss a renamed child (duplicating it) and falsely collapse two same-named children, so it is never used as the dedupe key (PRD #525: "Dedupe matches by stable ref not title").
+
+Apply it as follows:
+
+- **Linking** is keyed by child-ref: before adding a native child link or a documented generated-work entry, check whether that exact child-ref is already linked/listed; if so, it's a no-op. The documented generated-work section is **regenerated** from the current child set on each run rather than appended, so re-planning never accumulates stale or duplicate entries (the same regenerate-don't-append discipline `prd-backlink` already uses for its `## Tickets` section).
+- **Rollup** is keyed by the PRD's current state: a PRD already in `shipped` (and closed, when closure is configured) is a no-op — rollup does not re-transition or re-close it. Computing the all-terminal condition over the child-ref set is itself idempotent (a pure function of the children's current states).
+
+## Citation
+
+Skills that link generated work to a PRD or roll a PRD up cite this rule by slug (the `prd-lifecycle-rollup` rule) instead of restating it:
+
+- **PRD backlink / native linking** (`prd-backlink`) — record generated top-level work as native PRD children where supported; always write the documented generated-work fallback; dedupe by child-ref. *(LPC-1.1 #580, LPC-1.2 #582)*
+- **PRD coverage** (`prd-ticket-coverage`) — read the generated top-level child set deterministically from the recorded relationship, not from free-form comments.
+- **GitHub PRD shipped rollup** (`github-prd-intake`) — detect terminal/incomplete/blocked child sets, transition to `prd-shipped`, and leave the PRD open for `/lisa:verify-prd`. *(LPC-1.3 #583)*
+- **Linear / Confluence / Notion PRD shipped rollup** (`linear-prd-intake`, `confluence-prd-intake`, `notion-prd-intake`) — mirror the GitHub shipped rollup with each vendor's terminal predicate and keep the PRD active for verification. *(LPC-1.3 #584)*
+- **Repair close-out** (`repair-intake`) — re-run the same generated-top-level-work terminal
+  predicate to close out PRDs that were left open after all associated child work became terminal,
+  without setting the product-owned `verified` role.
+- **Idempotency** (all of the above) — dedupe-by-ref linking and no-op already-shipped rollup. *(LPC-1.4 #585)*
+- **Vendor matrix documentation** — describe native-hierarchy vs documented-link fallback per supported vendor against this contract. *(LPC-1.5 #586)*
+
+This is the PRD-level companion to `leaf-only-lifecycle` (which governs the build lifecycle and parent-from-leaves rollup); together they define the full hierarchy: a PRD owns its generated top-level work, which owns its leaves, and terminal state rolls up bottom-to-top — leaf → top-level unit → PRD.

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

@@ -0,0 +1,58 @@
+# Repo Scope & Work-Time Splitting
+
+Leaf work units are single-repo. A **leaf work unit** is an individually implementable ticket with no child tickets — issue types **Bug, Task, Sub-task, Improvement**. Each must name exactly one repository. **Epic, Story, Spike** are coordination containers and may span repos.
+
+This invariant is enforced at four points: gate **S10** in the `*-validate-*` skills (write time), `task-decomposition` step 1.5 (PRD-decomposition time), **claim-time repo scoping** in the build-intake skills (when intake decides whether to claim a ready ticket for the current repo — see below), and the work-time split procedure below (when an agent picks up an existing ticket to implement it).
+
+## Two splitting strategies, by phase
+
+The strategy depends on whether the tickets exist yet. Do not mix them.
+
+- **Decomposition-time (greenfield — no tickets exist yet).** Use `task-decomposition` step 1.5: create one work unit per repo and group them under a **parent Story** (the cross-repo coordination container). Children are per-repo; the parent stays cross-repo. This is the right shape when you are creating the tickets from a PRD in the first place.
+- **Work-time (a ticket already exists and an agent is about to implement it).** Use the procedure below: keep the original ticket, **narrow it to one repo**, spin off a **sibling** per additional repo, and link them with a dependency. Do **not** invent a new parent Story — re-homing an in-flight ticket's hierarchy is more disruptive than narrowing it. The siblings inherit the original's existing parent (Epic/Story/Project) if it has one.
+
+## Work-time split procedure
+
+When an agent reads an existing leaf work unit at the pre-flight gate (before any code is written) and the work touches more than one repo, it must STOP and split before proceeding. This is an agent-performed fix, not a product question — like auto-transitioning status, auto-splitting a cross-repo work unit is explicitly allowed (S10 is `product_relevant: false`: a cross-repo work unit is a decomposition error the agent owns, not something to bounce to the reporter).
+
+1. **Detect the repos.** Parse the description, acceptance criteria, and technical approach for repo references, and confirm against the actual code surfaces the change requires. If the work fits in one repo, proceed normally — no split.
+2. **Pick the repo the original keeps.** Default: the original retains the **consumer / user-facing repo** (e.g. frontend), because that is usually the ticket a stakeholder is watching and the one whose acceptance criteria describe the user-visible outcome. Each **producer repo** (e.g. backend) becomes a new sibling.
+3. **Create one sibling per additional repo, cloning the original's metadata.** Carry over: summary (re-prefixed `[repo-name]`), the three audience sections, priority, labels/components, parent (Epic/Story/Project) if the original has one, target backend environment, sign-in requirements, and a Validation Journey scoped to that repo. Scope the acceptance criteria to that repo only.
+4. **Link by dependency.** The producer repo **blocks** the consumer repo (`is blocked by` on the consumer / `blocks` on the producer), so execution order is explicit: the producing sibling ships first. When there is no clear producer/consumer direction, use `relates to`.
+5. **Narrow the original.** Edit its summary prefix, its `Repository` section, and its acceptance criteria down to the retained repo only. Remove every cross-repo reference ("and the backend should also…").
+6. **Comment on the original.** Note the split and link each new sibling so the history is auditable.
+7. **Re-validate.** Run `tracker-verify` (which runs S10) against the original and each new sibling. Every one must now PASS single-repo scope. If any still fails, the split was incomplete — fix it before proceeding.
+8. **Proceed in dependency order.** Implement the producer sibling(s) first, then the consumer (the narrowed original), respecting the `blocks` links.
+
+### When to block instead of split
+
+Auto-split only when the split is unambiguous. Fall back to the standard BLOCK + reassign-to-reporter path (see the pre-flight gate in `base-rules`) when:
+
+- The repos touched cannot be determined confidently from the ticket and the code.
+- Splitting would strand stakeholder context that only the reporter can re-scope (e.g. the acceptance criteria describe a single indivisible cross-repo behavior with no clean per-repo boundary).
+- The metadata required to clone (parent, environment, credentials) is itself missing — block on the missing metadata first; do not propagate gaps into the siblings.
+
+## Claim-time repo scoping (build-intake)
+
+A ticketing system can oversee multiple repos (one JIRA project / Linear team for `frontend`, `backend`, `infrastructure`). When `lisa:*-build-intake` runs inside one repo, it claims only tickets for **that** repo — it never pulls a ready ticket meant for a sibling repo. This is the fourth enforcement point of the single-repo-leaf invariant; it runs in each vendor build-intake's claim gate (Phase 3a), **before** the leaf-only container gate and the claim.
+
+Resolve the current repo per the `config-resolution` "Repo scoping" section (config `repo` → `github.repo` → git remote basename; stop with a clear error if unresolvable). Then walk the ready candidates in priority order and apply the **repo-scope decision** to each before claiming:
+
+1. **Read the candidate's repo marker** — the `repo:<name>` label (JIRA: also a component equal to a repo name).
+   - **Labeled for another repo** → **skip** cheaply (do not claim, do not re-determine); it stays `ready` for that repo's own intake. Move to the next candidate.
+   - **Labeled for the current repo** → proceed to the leaf-only gate + claim (the cheap, common path once labels exist).
+   - **Unlabeled** → **determine** the target repo(s) from the ticket (description, acceptance criteria, technical approach) confirmed against the actual code surfaces the change requires — the same detection as step 1 of the work-time split. Then **stamp** the resolved `repo:<name>` label(s) so future cycles filter cheaply, and re-apply this decision with the now-known repo.
+2. **Multi-repo leaf → split, never claim.** If determination finds the leaf touches more than one repo, run the **work-time split procedure** below to break it into single-repo siblings — each created **build-ready** (`build_ready: true`, so the build queue auto-claims it) and stamped with its own `repo:<name>`. After the split, the current repo's sibling (if any) becomes a normal current-repo candidate; the others are separate single-repo `ready` leaves for their repos. A multi-repo leaf is never claimed as-is.
+3. **Wrong repo → skip.** A single-repo leaf whose `repo:<name>` ≠ the current repo is left `ready` (and labeled) and skipped; intake moves on until it finds a claimable current-repo leaf, then stops (one item per cycle).
+
+**Cost.** Only **unlabeled** candidates need content determination; once stamped, wrong-repo candidates are skipped by label alone. Prefer candidates already labeled `repo:<current>` first (cheap claim), falling through to unlabeled candidates (determine + stamp) only when no pre-labeled current-repo leaf is ready.
+
+A container (Epic/Story/Spike) is handled by the leaf-only gate, not here — containers may span repos, may keep multiple `repo:<name>` labels for visibility, and are never claimed/built directly. Only a leaf work unit is split or skipped by repo scope.
+
+## Vendor mechanics
+
+The procedure is vendor-neutral; the create + link + edit mechanics differ:
+
+- **JIRA** — create via `mcp__atlassian__createJiraIssue` (clone fields, set the same epic parent); link via `mcp__atlassian__createIssueLink` with `Blocks` / `is blocked by` (resolve names via `mcp__atlassian__getIssueLinkTypes`); narrow the original via `mcp__atlassian__editJiraIssue`; comment via `mcp__atlassian__addCommentToJiraIssue`. See `jira-write-ticket` Phase 6.
+- **GitHub** — create the sibling issue with the same labels and parent sub-issue; encode the dependency in the body (`Blocked by #<n>` / `Blocks #<n>`) and via the sub-issue/parent graph where used; edit the original's body to narrow scope. See `github-write-issue` Phase 6.
+- **Linear** — create via `mcp__linear-server__save_issue` (clone fields, set the same `projectId`); add a blocking relation via the `relations` field or a paired relation call; edit the original to narrow scope. See `linear-write-issue` Phase 6.

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

@@ -0,0 +1,30 @@
+# Security Audit Handling
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, follow these steps. Never use `--no-verify` to bypass the security audit.
+
+## Node.js Projects (GHSA advisories)
+
+1. Note the GHSA ID(s), affected package(s), and advisory URL from the error output
+2. Check the advisory URL to determine if a patched version of the vulnerable package exists
+3. If a patched version exists: add a resolution/override in package.json to force the patched version (add to both `resolutions` and `overrides` sections), then run the package manager install command to regenerate the lockfile, commit the changes, and retry the push
+4. If no patched version exists and the vulnerability is safe for this project (e.g., transitive dependency with no untrusted input, devDeps only, or build tool only): add an exclusion entry to `audit.ignore.local.json` with the format `{"id": "GHSA-xxx", "package": "pkg-name", "reason": "why this is safe for this project"}`, then commit and retry the push
+
+### Critical: Override the vulnerable package, not its parent
+
+When the audit output shows a dependency chain like `@expo/cli › glob › minimatch`, the vulnerable package is **minimatch**, not glob. Always override the **leaf package** that has the actual vulnerability.
+
+**Never override a parent package to force a lower major version** — other packages in the project may depend on a newer major version, and a resolution/override forces ALL installations to the specified version. For example, overriding `glob` to `^8.1.0` will break `@expo/cli` which requires `glob@^13.0.0`, causing `expo prebuild` to fail with `files.map is not a function`.
+
+Before adding a resolution/override, verify:
+- You are targeting the **actually vulnerable package**, not a parent in the chain
+- The override version is **compatible with all dependents** (check with `bun why <package>` or `npm ls <package>`)
+- The override does not **downgrade** a package across a major version boundary that other dependencies require
+
+## Rails Projects (bundler-audit)
+
+1. Note the advisory ID, affected gem, and advisory URL from the error output
+2. Check if a patched version of the gem exists
+3. If a patched version exists:
+   - If the gem is a **direct dependency** (listed in Gemfile): update its version constraint in Gemfile, run `bundle update <gem>`, commit the changes, and retry the push
+   - If the gem is a **transitive dependency** (not in Gemfile, only in Gemfile.lock): run `bundle update <gem>` to pull the patched version without changing the Gemfile, commit the lockfile change, and retry the push
+4. If no patched version exists and the vulnerability is safe for this project: document the exception and retry the push

package/plugins/lisa-copilot/rules/reference/usage-accounting.md

@@ -0,0 +1,144 @@
+# Usage Accounting
+
+Lisa usage accounting is a vendor-neutral contract for attaching AI usage and cost telemetry to the artifacts Lisa creates or updates. It governs the section shape, machine-readable tokens, source/pricing semantics, rollup behavior, and idempotent rewrite rules. Writer skills and lifecycle skills attach telemetry by following this contract; they do not invent artifact-local formats.
+
+## Managed section
+
+Artifacts that support inline body/description content use a single managed section:
+
+```markdown
+## Lisa Usage
+```
+
+The section is canonical. Rewrite it in place; never append a second usage section under a different heading. If an artifact host cannot safely edit the body, write the same section format in a comment instead and treat that comment body as the managed usage artifact for future rewrites.
+
+The visible body is for humans; the hidden tokens are for machines. Both are required.
+
+## Direct-entry schema
+
+Each direct usage entry records one logical Lisa run or sub-run on one artifact. The required semantic fields are:
+
+| Field | Meaning |
+|---|---|
+| `entry_id` | Stable dedupe key for this logical usage entry. Unique within the artifact graph. |
+| `flow` | `research`, `plan`, `implement`, `verify`, `debrief`, `intake`, `repair-intake`, `monitor`, or a command slug. |
+| `run_id` | Runtime/session identifier when available; empty only when the runtime exposes no stable run id. |
+| `provider` | Model provider name. |
+| `model` | Model identifier. |
+| `source` | `observed`, `estimated`, or `unavailable`. |
+| `input_tokens` | Prompt/input tokens, or `null` when unavailable. |
+| `cached_input_tokens` | Cached/reused input tokens, or `null` when unavailable/not exposed. |
+| `output_tokens` | Output/completion tokens, or `null` when unavailable. |
+| `reasoning_tokens` | Reasoning/internal tokens, or `null` when unavailable/not exposed. |
+| `total_tokens` | Total trustworthy tokens for the entry, or `null`. |
+| `cost` | Observed or estimated cost for this entry, or `null`. |
+| `currency` | ISO currency code when `cost` is known, otherwise `null`. |
+| `pricing_status` | `observed`, `estimated`, `missing`, or `unavailable`. |
+| `pricing_source` | Runtime billing source, config/pricing snapshot ref, or `null`. |
+| `artifact_ref` | Canonical ref of the artifact carrying the entry. |
+| `parent_artifact_ref` | Canonical parent artifact ref when the entry is attached below a parent, otherwise empty. |
+
+`entry_id` must be stable across rewrites of the same logical run. Rewriting an existing entry with the same `entry_id` updates it in place. A different run gets a different `entry_id` and is appended as a new direct entry.
+
+## Source semantics
+
+`source` describes how trustworthy the token counts are:
+
+- `observed`: the runtime supplied the usage directly. Do not replace observed counts with estimates.
+- `estimated`: Lisa derived counts or cost from trustworthy runtime metadata plus an explicit pricing contract. Estimates are allowed only when the derivation inputs are real and attributable to the run.
+- `unavailable`: Lisa could not obtain trustworthy usage data. Write the entry anyway with `null` token/cost fields rather than silently omitting the row.
+
+The absence of data is never treated as zero. `null` means unknown; `0` means explicitly observed or derived zero.
+
+For example, an unavailable Verify run still records a direct entry with `source = unavailable`,
+`pricing_status = unavailable`, and `null` token/cost fields so downstream readers can distinguish
+"missing telemetry" from "zero usage."
+
+## Pricing semantics
+
+`pricing_status` describes how trustworthy the money fields are:
+
+- `observed`: runtime supplied a trustworthy monetary cost.
+- `estimated`: Lisa calculated cost from trustworthy token counts plus explicit pricing metadata.
+- `missing`: token counts are known but no trustworthy price source exists yet.
+- `unavailable`: the runtime exposed neither trustworthy cost nor enough trustworthy token data to estimate cost.
+
+Runtime-observed cost always wins over estimates. Estimated cost never overwrites an observed value. Missing pricing preserves token counts and a `null` cost.
+
+## Machine-readable tokens
+
+Every visible direct entry row ends with exactly one machine-readable token:
+
+```text
+<!-- lisa:usage-entry entry_id=<id> flow=<flow> run_id=<run-id> provider=<provider> model=<model> source=<source> input_tokens=<n|null> cached_input_tokens=<n|null> output_tokens=<n|null> reasoning_tokens=<n|null> total_tokens=<n|null> cost=<decimal|null> currency=<code|null> pricing_status=<status> pricing_source=<ref|null> artifact_ref=<ref> parent_artifact_ref=<ref-or-empty> -->
+```
+
+Field order is fixed. A reader parses the usage ledger by matching `<!-- lisa:usage-entry ` lines only; it never needs to scrape prose or table cell positions. String fields are percent-encoded before rendering and decoded after parsing, so whitespace, commas, and HTML comment terminators inside source values cannot split or truncate the token.
+
+Every managed section also ends with exactly one rollup token:
+
+```text
+<!-- lisa:usage-rollup direct_entry_ids=<csv> child_entry_ids=<csv> child_refs=<csv> direct_tokens=<n|null> child_tokens=<n|null> total_tokens=<n|null> direct_cost=<decimal|null> child_cost=<decimal|null> total_cost=<decimal|null> currency=<code|null> -->
+```
+
+- `direct_entry_ids` enumerates the entries attached directly to the current artifact.
+- `child_entry_ids` enumerates deduped descendant entry ids included in the rollup.
+- `child_refs` enumerates the child artifacts consulted for the rollup.
+- `total_*` fields equal direct plus child totals over the deduped entry set.
+
+The rollup token is the machine-readable summary. The visible rollup table mirrors it for humans. List fields are comma-delimited after encoding each item independently; commas inside an item are encoded as data, not treated as separators.
+
+## Visible rendering contract
+
+The canonical body layout is:
+
+```markdown
+## Lisa Usage
+
+_Managed by Lisa. Regenerated on each usage update; do not edit by hand._
+
+### Direct Usage
+
+| Flow | Model | Source | Tokens | Cost |
+|---|---|---|---:|---:|
+| ...human-readable rows ending with `lisa:usage-entry` tokens... |
+
+### Rollup
+
+| Scope | Tokens | Cost |
+|---|---:|---:|
+| Direct | ... | ... |
+| Child | ... | ... |
+| Total | ... | ... |
+
+<!-- lisa:usage-rollup ... -->
+```
+
+Writers may add host-specific surrounding prose, but they must preserve the heading, the managed-note line, the direct-entry tokens, and the single rollup token.
+
+## Rollup and dedupe behavior
+
+Rollups aggregate descendant usage from native tracker hierarchy, documented generated-work references, and explicit `parent_artifact_ref` links. Within one artifact rollup:
+
+- Dedupe strictly by stable `entry_id`.
+- Count each `entry_id` at most once even if the same descendant is discoverable through more than one path.
+- Preserve direct totals separately from child totals.
+- Exclude descendant entries whose `entry_id` is already present in the artifact's direct-entry set.
+
+Concrete example: if child artifact A and child artifact B both surface descendant entry
+`verify-123`, the parent rollup lists `verify-123` once in `child_entry_ids`. If the parent also
+records `verify-123` directly, exclude that descendant copy from child totals and keep the entry in
+the direct half only.
+
+The rollup contract is additive across the hierarchy: PRDs may roll up Epics/Stories/leaves, and leaves may roll up evidence or verification artifacts, without double counting shared descendants.
+
+## Idempotent rewrite rules
+
+- There is exactly one managed `## Lisa Usage` section per artifact body/comment.
+- Recompute the entire section on every write; never append ad hoc rows.
+- Sort direct entries deterministically by `(flow, run_id, entry_id)`.
+- Preserve existing entries with unchanged `entry_id` and refreshed field values.
+- Re-running with the same logical entry set must produce byte-identical output.
+- Do not include timestamps in the section preamble or token lines.
+
+Idempotency is enforced by `entry_id` for direct entries and by the fixed rollup token field order for totals.

package/plugins/lisa-copilot/rules/reference/verification.md

@@ -0,0 +1,124 @@
+# Empirical Verification
+
+This repository supports AI agents as first-class contributors.
+
+This file is the operational contract that defines how agents plan work, execute changes, verify outcomes, and escalate when blocked.
+
+If anything here conflicts with other repo docs, treat this file as authoritative for agent behavior.
+
+---
+
+## Core Principle
+
+Agents must close the loop between code changes and observable system behavior.
+
+No agent may claim success without evidence from runtime verification.
+
+Never assume something works because the code "looks correct." Run a command, observe the output, compare to expected result.
+
+**Verification is not linting, typechecking, or testing.** Those are **quality checks** — prerequisites that must pass before verification begins, but they are NOT verification themselves. Running `bun run test`, `bun run typecheck`, `bun run lint`, or `bun run format` is a quality check. Verification is using the resulting software the way a user would — interacting with the UI, calling the API, running the CLI command, observing the behavior. Tests pass in isolation; verification proves the system works as a whole.
+
+**If all you did was run tests, typecheck, and lint — you have NOT verified.** You have only confirmed quality checks pass. Verification requires running the actual system and observing the results: making HTTP requests, clicking through the UI, executing CLI commands, querying the database, or otherwise interacting with the running software as an end user would.
+
+Verification is mandatory. Never skip it, defer it, or claim it was unnecessary. Every task must be verified before claiming completion.
+
+Before starting implementation, state your verification plan — how you will use the resulting software to prove it works. A verification plan that only lists test/typecheck/lint commands is not a verification plan. Do not begin implementation until the plan is confirmed.
+
+After verifying a change empirically, encode that verification as an automated regression test via the `codify-verification` skill. The manual proof that something works must become a repeatable test that catches future regressions — Playwright for UI/browser flows, integration test for API/DB/auth, benchmark for performance, etc. Codification is mandatory for every empirical verification type except the inherently non-behavioral ones (PR, Documentation, Deploy) and Investigate-Only spikes. If codification is genuinely impossible, escalate via the Escalation Protocol — never silently skip.
+
+Every pull request must include step-by-step instructions for reviewers to independently replicate the verification. These are not test commands — they are the exact steps a human would follow to use the software and confirm the change works. If a reviewer cannot reproduce your verification from the PR description alone, the PR is incomplete.
+
+---
+
+## Roles
+
+### Builder Agent
+
+Implements the change in code and infrastructure.
+
+### Verifier Agent
+
+Acts as the end user (human user, API client, operator, attacker, or system) and produces proof artifacts.
+
+Verifier Agent must be independent from Builder Agent when possible.
+
+### Human Overseer
+
+Approves risky operations, security boundary crossings, and any work the agents cannot fully verify.
+
+---
+
+## Verification Levels
+
+Agents must label every task outcome with exactly one of these:
+
+- **FULLY VERIFIED**: Verified in the target environment with end-user simulation and captured artifacts.
+- **PARTIALLY VERIFIED**: Verified in a lower-fidelity environment or with incomplete surfaces, with explicit gaps documented.
+- **UNVERIFIED**: Verification blocked, human action required, no claim of correctness permitted.
+
+---
+
+## Quality Gates (Prerequisites)
+
+These are NOT verification. They are prerequisites that must pass before verification begins. Running these does not constitute verification — it only confirms code quality.
+
+| Gate | What to prove | Acceptable proof |
+|------|---------------|------------------|
+| **Test** | Unit and integration tests pass for all changed code paths | Test runner output showing all relevant tests green with no skips |
+| **Type Safety** | No type errors introduced by the change | Type checker exits clean on the full project |
+| **Lint/Format** | Code meets project style and quality rules | Linter and formatter exit clean on changed files |
+
+Quality gates are enforced automatically by the self-correction loop (hooks, pre-commit, pre-push). Passing all quality gates is necessary but NOT sufficient — you must still verify empirically.
+
+---
+
+## Verification Types
+
+Every change requires one or more verification types. Classify the change first, then verify each applicable type by **running the actual system and observing results**.
+
+| Type | When it applies | What to prove | Acceptable proof |
+|------|----------------|---------------|------------------|
+| **UI** | Change affects user-visible interface | Feature renders correctly and interactions work as expected | Automated session recording or screenshots showing correct states; for cross-platform changes, evidence from each platform or explicit gap documentation |
+| **API** | Change affects HTTP/GraphQL/RPC endpoints | Endpoint returns correct status, headers, and body for success and error cases | Request/response capture showing schema and data match expectations |
+| **Database** | Change involves schema, migrations, or queries | Schema is correct after migration; data integrity is maintained | Query output showing expected schema and data state |
+| **Auth** | Change affects authentication or authorization | Correct access for allowed roles; rejection for disallowed roles | Request traces showing enforcement across at least two roles |
+| **Security** | Change involves input handling, secrets, or attack surfaces | Exploit is prevented; safe handling is enforced | Reproduction of attack pre-fix failing post-fix, or evidence of sanitization/rejection |
+| **Performance** | Change claims performance improvement or affects hot paths | Measurable improvement in latency, throughput, or resource usage | Before/after benchmarks with methodology documented |
+| **Infrastructure** | Change affects deployment, scaling, or cloud resources | Resources are created/updated correctly; system is stable | Infrastructure state output showing expected configuration; stability metrics during transition |
+| **Observability** | Change affects logging, metrics, or tracing | Events are emitted with correct structure and correlation | Log or metric output showing expected entries with correlation IDs |
+| **Background Jobs** | Change affects queues, workers, or scheduled tasks | Job enqueues, processes, and reaches terminal state correctly | Evidence of enqueue, processing, and final state; idempotency check when relevant |
+| **Configuration** | Change affects config files, feature flags, or environment variables | Configuration is loaded and applied correctly at runtime | Application output showing the configuration taking effect |
+| **Documentation** | Change affects documentation content or structure | Documentation is accurate and matches implementation | Content inspection confirming accuracy against actual behavior |
+| **Cache** | Change affects caching behavior or invalidation | Cache hits, misses, and invalidation work as expected | Evidence of cache behavior (hit/miss logs, TTL verification, key inspection) |
+| **Email/Notification** | Change affects outbound messages | Message is sent with correct content to correct recipient | Captured message content or delivery log showing expected output |
+| **PR** | Shipping code (always applies when opening a PR) | PR includes goal summary, verification level, proof artifacts, and reproduction steps | PR description containing all required sections |
+| **Deploy** | Shipping code to an environment | Deployment completes and application is healthy in the target environment | Deployment output and health check evidence from the target environment |
+
+---
+
+## Per-Work-Unit Evidence Contract
+
+Every **leaf work unit** — an individually implementable ticket with no child tickets (issue types Bug, Task, Sub-task, Improvement) — that changes runtime behavior must declare, at creation time, the exact evidence that proves it is done. Epics, Stories, and Spikes are coordination containers, not work units: their evidence is the rollup of their children, so this contract does not apply to them.
+
+The declaration is not a separate field — it is the set of `[EVIDENCE: name]` markers in the work unit's **Validation Journey**. Those markers are the work unit's **evidence manifest**: an enumerated, named list of the artifacts a verifier must capture. The manifest binds both ends of the ticket lifecycle:
+
+- **At creation** — the work unit cannot be written without a Validation Journey that names at least one `[EVIDENCE: name]` artifact (enforced by gate S14 in `tracker-validate` and the vendor `*-validate-*` skills). A behavior-changing unit should name both a success artifact and an error/edge artifact.
+- **At completion** — the work unit cannot be marked complete, nor transitioned to its review/Done state, until every `[EVIDENCE: name]` marker in its manifest has a captured, non-empty artifact attached to the ticket (enforced by the Task Completion Rules and Definition of Done in `verification-lifecycle`, and by the evidence-manifest gate in `tracker-evidence`). A manifest with a missing or empty artifact blocks completion exactly like a failed verification.
+
+The manifest is the single source of truth for "what evidence is required": authored once in the Validation Journey, enforced at write time, replayed during `tracker-journey`, and checked again before the ticket closes. There is no second list to keep in sync.
+
+---
+
+## Local vs Remote Verification
+
+Verification happens at two stages in the workflow:
+
+- **Quality gates** (enforced automatically): Tests, typecheck, lint, and format run via hooks at write-time, commit-time, and push-time. These are prerequisites, not verification.
+- **Local verification** (part of the Implement flow): After quality gates pass, empirically verify the change by running the actual system in a local or preview environment — make HTTP requests, interact with the UI, execute CLI commands, query the database. This proves the change works before shipping. After local verification succeeds, invoke `codify-verification` to encode it as a regression test (Playwright for UI, integration test for API/DB/auth, benchmark for performance, etc.) and commit the test in the same PR.
+- **Remote verification** (part of the Verify flow): After the PR is merged and deployed, repeat the same empirical verification against the target environment. This proves the change works in production, not just locally. If remote verification fails, fix and re-deploy.
+
+Both levels use the same verification types table above. The difference is the environment, not the rigor.
+
+---
+
+For the full verification lifecycle (classify, check tooling, plan, execute, loop), surfaces, escalation protocol, and proof artifact requirements, see the `verification-lifecycle` skill loaded by the `verification-specialist` agent.

package/plugins/lisa-copilot/rules/reference/wiki-knowledge-source.md

@@ -0,0 +1,14 @@
+# Wiki as Knowledge Source
+
+If this project has an LLM Wiki (a `wiki/` directory with an `index.md`), treat it as the canonical source of durable project knowledge. The wiki is curated and current; ad-hoc scraping of code, tickets, chat history, or stale READMEs is not.
+
+Before researching project background, conventions, ownership, architecture, glossary terms, or "how/why does X work here":
+
+1. Consult the wiki first. Start from `wiki/index.md` and follow links, or use the wiki query skill (`/lisa-wiki-query`, or the runtime's wiki query skill) to find the relevant page.
+2. Use what the wiki says as the authoritative answer when it covers the question. Do not re-derive it from raw sources when the wiki already documents it.
+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 in the code.
+4. If you find the wiki is wrong, stale, or missing knowledge that belongs there, surface the gap — and where the project's workflow supports it, capture the correction back into the wiki via its ingestion path (`/lisa-wiki-ingest` or equivalent) rather than leaving the knowledge only in this session.
+
+The wiki documents knowledge; it does not override executable behavior. When the wiki and the running code disagree about what the system actually does, trust the code and treat the wiki as out of date. See the `documentation-source-paths` rule for how source-material directories relate to the wiki.
+
+If the project has no `wiki/`, this rule does not apply.