@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/rules/reference/observability-audit.md

@@ -0,0 +1,146 @@
+# Observability Audit (load-bearing)
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Observability Audit (load-bearing)
+
+The **audit + file** arm of `lisa-monitor`. On top of its existing live-signal sweep, `monitor` audits how well the **current repo** is instrumented and files build-ready tickets for what it finds. `monitor` is **manual** (no cron) and **files only** — it never fixes; the `intake` / `tracker-build-intake` cron implements what it files.
+
+## Invariants
+
+- **Repo-scoped two ways.** Audit only the rubric dimensions in scope for the repo's detected profile (`frontend` / `backend` / `infra` — a frontend repo never evaluates backend tracing), and stamp every filed ticket `repo:<CURRENT_REPO>` as a single-repo leaf (resolve the repo via the `config-resolution` ladder; cannot resolve → report, do not file).
+- **Two finding types → build-ready leaves.** A live signal over the conservative bar → a `Bug` leaf; an in-scope MISSING instrumentation dimension (gap, e.g. "no DB/query analytics") → a `Task`/`Improvement` leaf. Always via `lisa-tracker-write` with `build_ready: true` (never a vendor write skill directly); never an Epic/container (gate S15).
+- **Conservative by default.** Only high-signal anomalies (over the documented thresholds) and `core` missing dimensions are filed. `--all-gaps` widens gap filing to `recommended` tiers; nothing lowers the anomaly bar.
+- **Idempotent.** Every ticket carries a `<!-- lisa:monitor-finding: <fingerprint> -->` sentinel; search-before-create (including closed tickets) means a re-run never duplicates a live or just-resolved finding.
+- **Capped.** At most `monitor.maxCandidates` tickets per run (default 20), highest-severity first; report filed-vs-dropped (and list the dropped) — never silently truncate.
+- **Gate-passing.** Each ticket is a real authored artifact: three-audience description, Gherkin AC, single-repo, Target Backend Environment, and a Validation Journey with a typed `[EVIDENCE: <artifact-type>: <name>]` marker (unique kebab-case name) — so `tracker-validate` (S1–S15) accepts it. A finding that cannot be made into a credible ticket is reported, not filed.
+- **Verify guard.** When `monitor` is the post-deploy step of `lisa-verify` it runs **report-only** — Verify invokes it as `lisa-monitor <env> --report-only`, so it never files there. Filing is a standalone-only action.
+
+---
+
+This rule is the single source of truth for the **audit + file** arm of the `lisa-monitor` skill. The `monitor` skill collects live signals (errors, logs, performance, health) via the stack `ops-specialist` exactly as before; this rule adds two things on top, both **repo-scoped**:
+
+1. **Audit** — score the repo against an observability-completeness rubric for its detected type, so a frontend repo is never dinged for missing backend tracing.
+2. **File** — turn both *anomalies* (a real bad live signal) and *gaps* (an in-scope observability dimension that isn't wired) into **build-ready leaf tickets** so the existing `intake` / `tracker-build-intake` cron picks them up and fixes them. `monitor` files only; it never fixes.
+
+`monitor` is **manual** — there is no cron for it. It is run by a human against a named environment.
+
+## Scope discipline (why this is repo-scoped)
+
+`monitor` runs **inside one repo** and audits/files **only for that repo**. Two mechanisms enforce it:
+
+- **Type-scoped rubric.** Only the dimensions in-scope for the detected repo type are audited (table below). A frontend-only repo never evaluates X-Ray tracing or DB-query analytics; a backend repo never evaluates Web Vitals or session replay.
+- **`repo:<name>` stamping.** Every filed ticket is a single-repo leaf stamped `repo:<CURRENT_REPO>` (per `repo-scope-split`). Resolve `CURRENT_REPO` with the standard ladder from `config-resolution` ("Current-repo resolution"): config `repo` → `github.repo` → `basename` of the git remote. If it cannot be resolved, **report and skip filing** rather than filing un-scoped tickets.
+
+## Repo-type detection (stack-agnostic)
+
+`monitor` is a base skill that ships to every project, so detection must not assume a stack plugin is present. Detect the repo's observability **profile** by reading manifests and key files — never by assuming. Classify into one or more of `frontend`, `backend`, `infra`. A repo may be more than one (a Rails or Next.js app is `frontend`+`backend` = "fullstack"); audit the union of the matched profiles' in-scope dimensions.
+
+| Profile | Positive signals (any) |
+|---|---|
+| `frontend` | `package.json` deps incl. `expo`, `react-native`, `next`, `react`, `vue`, `@angular/core`, `svelte`, `vite`; an `app.json` / `app/` route dir / `public/index.html`; a web/mobile build script |
+| `backend` | `package.json` deps incl. `@nestjs/core`, `express`, `fastify`, `koa`, `@apollo/server`; a `serverless.yml` / Lambda handlers; a `Gemfile` with `rails`; a `Procfile`; an API/server entrypoint |
+| `infra` | `aws-cdk-lib` + `cdk.json`; Terraform `*.tf`; Pulumi; a `serverless.yml` with no application code; a deploy-only repo |
+
+When the Lisa stack overlay is present its mapping is a strong prior (`expo`→frontend, `nestjs`→backend, `cdk`→infra, `rails`→frontend+backend, `typescript`→infer from the signals above), but always confirm against the actual files — the overlay is a hint, the files are truth.
+
+## The observability-completeness rubric
+
+Each dimension is **in scope** (`●`) or **out of scope** (`–`) per profile, and carries a **tier**: `core` (a blind spot here is a real operational risk → file when missing) or `recommended` (valuable but optional → file only when `--all-gaps` is passed; otherwise report as a WARN row, do not ticket).
+
+| Dimension | Tier | FE | BE | Infra | Detect via (presence ⇒ wired) |
+|---|---|:--:|:--:|:--:|---|
+| Error monitoring | core | ● | ● | – | `@sentry/*`, `.sentryclirc`, Sentry DSN in `.env*`; Bugsnag/Rollbar deps |
+| Structured logging | core | ● | ● | ● | `pino`/`winston`/`bunyan`; Rails `lograge`; CloudWatch log groups exist |
+| Distributed tracing | core | – | ● | ● | `aws-xray-sdk*`, OpenTelemetry deps/gems; X-Ray traces present |
+| Metrics & alarms | core | – | ● | ● | CloudWatch custom metrics + `describe-alarms` returns alarms; Datadog/Prometheus |
+| Health checks | core | ● | ● | – | a `/health`/`/up` endpoint; NestJS Terminus; uptime check config |
+| RUM / Web Vitals | recommended | ● | – | – | Sentry performance/browser tracing, `web-vitals`, Firebase Performance |
+| Product analytics | recommended | ● | – | – | `posthog-js`/`posthog-node`, Firebase Analytics, Amplitude, Segment |
+| Session replay / frustration | recommended | ● | – | – | Jam, PostHog session replay, LogRocket, Sentry replay |
+| DB / query analytics | recommended | – | ● | ● | slow-query logging, RDS/Aurora Performance Insights, query-timing middleware |
+| Synthetic / smoke UAT | recommended | ● | ● | – | Playwright/Cypress e2e, k6/Artillery load scripts, synthetic canaries |
+
+**Detection is read-then-probe, never assume.** For each in-scope dimension: read `package.json` deps + scripts (and `Gemfile`, `serverless.yml`, `docker-compose.yml`, `config/initializers/*`, `.env*`, `.sentryclirc`, `cdk.json`), then — only when credentials/tooling are already available — probe the live source (`command -v sentry-cli`, `aws sts get-caller-identity` before any `aws` call). Mirror the `ops-specialist` "Project Discovery" table where the stack overlay exists. **Absence of every signal for an in-scope dimension is the gap finding.** A dimension that is present but unreachable this run (e.g. PostHog wired but no API key available) is reported `PRESENT (unverified)`, **not** a gap.
+
+### Tools Lisa does not wire
+
+PostHog, Jam, and Firebase have **no Lisa MCP**. Detect them statically (deps/config) and pull their data only where a first-party API + credentials are already present in the environment (e.g. the PostHog API with a project key). Never invent credentials, and never treat "Lisa has no MCP for it" as "the repo lacks it" — judge by the repo's own deps/config.
+
+## Live-signal anomalies (conservative thresholds)
+
+Collect live signals via the stack `ops-specialist` when present (Expo/Rails), else via inline base probing (Sentry CLI/REST, `aws logs`, `aws cloudwatch`, `aws xray`, the Playwright MCP for client-side console/network). An observation becomes a **fileable anomaly** only when it clears the conservative bar — high-signal only, to keep the Ready queue clean. Defaults below (the keys live under `monitor.thresholds.*` in `config-resolution`; per-run nothing overrides them — tune in config):
+
+| Signal | Fileable when |
+|---|---|
+| Error event | Unresolved error/fatal signal **and** events in last 24h ≥ `monitor.thresholds.minEvents24h` (default 1). Skip resolved, ignored, muted, and below-floor noise. |
+| Error-rate spike | error rate ≥ `errorRateSpikeMultiplier`× (default 2×) the prior-window baseline **and** above an absolute floor (not 1-of-2 requests). |
+| Latency regression | p95 ≥ `p95LatencyMs` (default 1000ms) sustained, **or** p95 up ≥ 50% vs the prior window. |
+| CloudWatch alarm | any alarm in `ALARM` state. |
+| Fault rate | fault observations > `monitor.thresholds.faultRatePct` (default 5%) of observations in the window. |
+| Client-side (Playwright) | repeated console `error` or a 5xx network response on a smoke flow. |
+
+Everything below the bar is reported (so the human sees it) but **not** ticketed. `--all-gaps` does not lower anomaly thresholds — it only widens *gap* tiers.
+
+## Two finding types → build-ready leaf tickets
+
+Both finding types are filed through the vendor-neutral `lisa-tracker-write` shim with `build_ready: true` (never a vendor write skill directly — that is what keeps the destination switchable). Both are **leaf** work units (`Bug` for anomalies, `Task`/`Improvement` for gaps) — never an Epic or container (gate S15). Each must pass the `tracker-validate` gates S1–S15, so each ticket is a real authored artifact, not a template dump.
+
+### Required fields (so the gates pass)
+
+- **Three-audience description** (S3): coding-assistant (technical: stack trace / Sentry link / occurrence count / the missing dimension and how to wire it), developer (where it surfaces, suspected cause/affected files, the fix skill to reach for), stakeholder (user/SLO impact).
+- **Gherkin acceptance criteria** (S4).
+- **Single repo** (S10): stamped `repo:<CURRENT_REPO>`; scope the description to this repo only.
+- **Target Backend Environment** (S8) + **Validation Journey** carrying at least one typed `[EVIDENCE: <artifact-type>: <name>]` marker (S11/S14) — both anomaly fixes and gap wiring are runtime changes, so both need an env and a journey that proves the fix. The bracketed typed form is what the validator scans for; a bare `EVIDENCE:` line or an untyped assertion label (`[EVIDENCE: alert-fixed]`) fails S14 — for observability work the natural types are `log-snippet` and `state-dump`. Prefer two markers (a success and an error/edge case).
+- **Relationship search before write** (S13) — doubles as the dedup guard (next section).
+- **No parent/Epic required.** These are build-ready standalone leaves; S7's parent requirement is waived for a `build_ready: true` leaf (the leaf carve-out in `leaf-only-lifecycle` / `tracker-validate`). Do not fabricate an Epic parent.
+- A **priority** ordered by tier and severity: `core` gap / high-event anomaly → higher; `recommended` gap → lower.
+
+### Anomaly ticket (type: Bug)
+
+Title: `[observability] <signal summary> (<source>)` — e.g. `[observability] Unhandled TypeError in CheckoutScreen (Sentry)`. The coding-assistant section carries the Sentry/CloudWatch/X-Ray link, fingerprint, first/last seen, and occurrence count. AC: *Given* the repro context, *When* the action runs, *Then* the source reports zero new events for the fingerprint. The fix-skill hint points at `root-cause-analysis` / `reproduce-bug`.
+
+### Gap ticket (type: Task or Improvement)
+
+Title: `[observability-gap] Add <dimension> (<profile>)` — e.g. `[observability-gap] Add distributed tracing (backend)`. The description states which dimension is missing, **why the audit needed it** (the blind spot it leaves), and how to wire it — chaining the existing fix skills where they apply (`parity-sentry-sdk-setup` for error monitoring; the nestjs `typeorm-patterns` skill's `observability-patterns` reference for X-Ray/CloudWatch DB-query tracing; OTel→X-Ray for tracing). AC: *Given* the app runs in `<env>`, *When* the relevant signal occurs, *Then* the newly-wired dimension captures it (dashboard/endpoint/trace shows data).
+
+## Idempotency (do not re-file the same finding)
+
+A manual re-run next week must not duplicate last week's tickets. Mirror the `repair-intake` marker discipline:
+
+1. **Stable fingerprint per finding.**
+   - Anomaly: `sha1("<source>:<stable-signature>:<CURRENT_REPO>")` (12 hex chars). `stable-signature` is the Sentry issue short-id (or culprit), the CloudWatch alarm name, or `errorType@location` — something that survives between runs, **never** the human title or occurrence count.
+   - Gap: the literal `gap:<dimension>:<CURRENT_REPO>` (a dimension is missing-or-not; no hash needed).
+2. **Sentinel in the body.** Embed `<!-- lisa:monitor-finding: <fingerprint> -->` in every filed ticket.
+3. **Search before create** (this IS gate S13). Before filing, search the tracker for the fingerprint string. The search **MUST include closed/resolved tickets** (`gh issue list --search <fp> --state all` for GitHub; JQL with no status filter for JIRA; all states for Linear) — otherwise a just-closed match is invisible and the backoff and decline checks below can't fire. If an **open** ticket carries the fingerprint → skip (optionally link). Otherwise classify a closed match by **how** it closed:
+   - **Closed as _not planned_ — a permanent decline** (`rejection-detection` **Proposal rejection memory**). GitHub `stateReason == "not_planned"`; the config-resolved won't-do/canceled equivalent on JIRA/Linear (never a hardcoded lane string). This is a durable human "no", not a time-boxed guard: **suppress the finding regardless of age**, and re-file only with evidence that **postdates the decline** and establishes a materially changed consequence, requirement, or risk addressing the recorded reason. Seeing the same accepted limitation on a later date is insufficient. The new ticket MUST carry BOTH the machine token (`declined <date>; recurred <date> in <ref>`) and the human acknowledgment sentence (`You declined this on <date>. New evidence (<date>, <ref>) changes the consequence, requirement, or risk: <what changed and why the decline no longer applies>.`). This layers *on top of* the backoff below — a not_planned close outlives any window.
+   - **Closed as _completed_ within the recently-resolved backoff window** (`monitor.backoffHours`, default **24h** — matching the 24h Sentry event window; this is **not** the 2h `intake.repair.staleAfterHours`) → skip, to avoid re-filing a just-fixed regression before its signal has drained. A completed close **older** than the window is not a decline — a genuine recurrence is a regression and may file.
+
+   Only file when no live match or recently-resolved completed match exists, and any prior not_planned decline meets the evidence and acknowledgment requirements above.
+
+## The cap
+
+File **at most `max_candidates` tickets per run** (default **20**; config `monitor.maxCandidates`; per-run `max_candidates=<n>` always wins). Rank candidates before applying the cap — `core` gaps and highest-occurrence anomalies first — so the cap drops the least-important findings, never the most. When the cap truncates, **list every dropped finding** in the report (title + fingerprint, not just a count) — silent truncation reads as "all clear" when it isn't, and a high-signal anomaly that fell just below the cap must still be visible to the human.
+
+## Filing modes and the Verify guard
+
+- **Default (standalone `monitor <env>`): files.** A plain manual run audits, reports, dedupes, and files up to the cap.
+- **`--dry-run`:** does everything except call `tracker-write` — prints exactly which tickets *would* be filed (title, type, fingerprint, dedup verdict) so the human can preview.
+- **`--report-only`:** produces the health/audit summary only — no filing and no would-file analysis. This is the mode Verify uses (below).
+- **Invoked as `lisa-verify`'s post-deploy step: never files — enforced mechanically, not inferred.** `lisa-verify` step 6 invokes monitor as `lisa-monitor <env> --report-only`; monitor must never file when `--report-only` (or `--dry-run`) is set. This is load-bearing **today** — Verify already routes its remote verification through the `monitor` skill, so without the passed flag the new file-by-default behavior would create tickets during every verify run. As a belt-and-suspenders default, if monitor is invoked via the Skill tool from within a Verify flow and no filing flag was passed, treat it as `--report-only` rather than filing.
+
+## Output
+
+A single report: the health/anomaly summary (existing monitor behavior) + an audit table (each in-scope dimension with `OK` / `WARN` / `MISSING` / `PRESENT (unverified)`) + a filing summary (tickets filed with their refs and fingerprints, tickets skipped as duplicates, and the dropped count if the cap truncated). In `--dry-run`, the filing summary lists would-file tickets instead.
+
+## Rules
+
+- File only — never fix. The `intake` / `tracker-build-intake` cron implements what `monitor` files.
+- Always through `tracker-write` with `build_ready: true`; never a vendor write skill directly.
+- Conservative by default — high-signal anomalies and `core` missing dimensions only. `--all-gaps` widens gap tiers; nothing lowers the anomaly bar.
+- Repo-scoped always — type-scoped rubric + `repo:<CURRENT_REPO>` single-repo leaves. Cannot resolve the repo → report, do not file.
+- Idempotent always — fingerprint sentinel + search-before-create; a re-run never duplicates a live or just-resolved finding.
+- Never file without a real, gate-passing description and Validation Journey. A finding that cannot be made into a credible ticket is reported, not filed.
+- Read config with `jq` (local-overrides-global) per `config-resolution`; never hand-parse JSON. Never run an `aws`/`sentry-cli` probe without first confirming credentials.

package/plugins/lisa-devin/rules/reference/operational-hazards.md

@@ -0,0 +1,115 @@
+# Operational Hazards — reference
+
+Full contract behind the `operational-hazards` slug (CodySwannGT/lisa#3681). The eager rule carries
+the two commands; this is the reasoning, the tiers, and the boundary against doctrine.
+
+## The general property
+
+**A detector whose only failure mode is staying quiet cannot be audited.** A fan-out reaches the
+sessions alive at one instant. The sessions that were not alive receive nothing and are told
+nothing, so nobody — the sender included — can name who was missed.
+
+Measured on one machine in one hour: one session started 18 minutes after a warning it needed;
+another started 8 minutes after a different one; four more appeared and vanished entirely inside
+the hour. And the lanes most likely to collide are the ones that just started and are standing up
+fresh environments — so the warning that would have prevented the collision cannot reach the
+session that causes it, because that session does not exist yet.
+
+**The hole is unmeasurable, not merely growing.** Two sessions on the same machine, enumerating
+peers at the same moment, returned different rosters: one session appeared in one listing and had
+never appeared in four consecutive reads by the other. So "I enumerated the roster and checked the
+list" carries an unknown hole, and a fan-out audited against one session's view cannot be audited
+at all.
+
+## What the existing rule injector cannot do
+
+`inject-rules.sh` reads `CLAUDE_PLUGIN_ROOT/rules/eager` — the plugin root, not the project. A
+project cannot register anything there without editing an installed plugin, which the next apply
+overwrites. And it concatenates every `.md` unconditionally: no front matter, no date, no filter.
+Anything written there is injected on every start, permanently, until a human deletes the file.
+
+So the injector is the right *reach* and the wrong *store*. This ledger reuses the reach — the same
+two start events, plus the tool-result event — and supplies a project-owned store whose entries
+carry a condition something evaluates.
+
+## Why the expiry is the mechanism, not a convenience
+
+**The expiry is what separates a transient hazard from doctrine**, and it is the only reason the
+surface can be trusted with transient content: nobody has to remember to remove anything. A hazard
+surface without an expiry becomes the permanent-scripture problem, and a project that has watched
+that happen once will correctly refuse to use the surface again.
+
+The shape is deliberately the threshold-ratchet exemption's (CodySwannGT/lisa#3856) rather than a
+third scheme:
+
+- record the condition in a form something can evaluate — `until`, a `YYYY-MM-DD` day or an
+  ISO-8601 timestamp, live *through* the day named;
+- never let an unevaluable condition lapse into the permissive answer. An entry naming no evaluable
+  expiry — hand-written, or written before `until` existed — **still applies**, and is reported as
+  `unchecked` every time it is read.
+
+An expiry that lapses into "no longer shown" is worse than no expiry: it restores permanent
+scripture in reverse — the hazard vanishes — while every signal still reads healthy. That is why
+the writer refuses `--declare` without `--until`, and refuses an `until` it cannot parse, while the
+reader tolerates one and says so.
+
+## The inverse
+
+A hazard also ends before its expiry. A declaration nothing can void is the defect closed twice
+already — the QA-failure signal (CodySwannGT/lisa#3855) and the human gate (CodySwannGT/lisa#3852)
+— so `--lift` appends a void record naming what resolved it.
+
+Matching is **time-ordered**: a lift voids only a declaration that pre-dates it. A hazard
+re-declared after an earlier lift is therefore not born discharged, which is the unsafe direction
+#3852 records as the one this must not introduce. For the same reason the ledger union keeps the
+**newest** declaration for an id, not the first one read.
+
+## The ledger's two tiers
+
+- **`.lisa/HAZARDS.jsonl`**, committed — reaches every future reader of this project and merges by
+  git's built-in union driver. This is also the tier that answers "does `lisa apply` preserve it":
+  it is host-authored content under `.lisa/`, like the withdrawal tombstones beside it, and no
+  managed-file reconciliation writes it.
+- **`${LISA_STATE_HOME:-~/.lisa}/operational-hazards.jsonl`** — reaches sibling sessions in OTHER
+  worktrees on this machine *now*, which a committed file cannot do until it is merged and pulled.
+  For the fleet case above, this is the tier that matters.
+
+`--declare` and `--lift` write both. Reads are the union. Both files are append-only JSONL, so
+concurrent writers on their own branches reconstruct exactly under `merge=union`.
+
+## How a running session is reached
+
+`--session-start` delivers everything applying and stamps what the session was born knowing.
+`--hook` runs as a PostToolUse hook and announces only what changed since that stamp: a hazard
+declared while this session runs, and a **lift** of a hazard this session was told about. Both
+directions were measured — the provenance of #3681 is a session that was sent a lift for a hold it
+had never received.
+
+A missing stamp is deliberately silent. A session whose starting knowledge is unknown would
+otherwise be told every historical hazard, which degrades the mechanism into distrusting
+everything.
+
+The common path is cheap: when neither tier's `size:mtime` has moved, `--hook` exits after two
+`stat` calls without parsing anything. It fires on every tool call in every session, so anything
+expensive multiplies.
+
+## Surface parity
+
+The hook pair ships into every payload that carries the base hooks, and the injector fires on
+`SubagentStart` as well as `SessionStart` — which makes this better than a broadcast rather than
+merely equivalent, since a fan-out never reaches a subagent at all.
+
+Surfaces with no PostToolUse runtime get the start-event half and `--list`. That is the honest
+split: **the durable half — reaching every session that starts later — is closed everywhere the
+hook installs. The already-running half depends on a tool-result event, so where there is none, a
+running session is reached only when it runs `--list`.**
+
+## What deliberately does not belong here
+
+Anything that should still be true next month. A hazard is a condition of *this machine, this
+branch, this hour*: a port another lane holds, a resource one run has saturated, a command that
+dumps more than you asked for, a gate red for an environmental reason. If the entry would want
+renewing when it expires, it was never a hazard — promote it through the learnings ladder to a rule
+or an executable control, and let the entry lapse.
+
+Not a severity taxonomy, not a notification system, and not a change to how eager rules work.

package/plugins/lisa-devin/rules/reference/prd-definition-of-ready.md

@@ -0,0 +1,118 @@
+# PRD Definition of Ready — Reference
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## PRD Definition of Ready (requirement atoms)
+
+**A requirements document is ready when a planner can decompose it mechanically and a verifier can check the result against it.** Both properties come from the shape of the requirements, not the prose around them. Modeled on ISO/IEC/IEEE 29148's requirement quality characteristics and the EARS sentence patterns; the fit criterion is Volere's.
+
+## The atom
+
+Every requirement is an **identified atom**:
+
+- **Identified** — carries an id (`R1`, `R2`, …). Ids are per-generation; the verbatim text is the durable anchor (same convention as the `*-to-tracker` Requirement Register).
+- **Singular** — one behavior per atom. "The system shall X and Y when Z" is two atoms.
+- **Unambiguous** — no vagueness lexicon: *as appropriate, user-friendly, fast, robust, handle gracefully, etc., and/or, optimize, seamless, intuitive, support* (unbounded). Each is a word no test can check.
+- **Verifiable** — carries a **fit criterion**: the measurable test of satisfaction ("p95 upload completes < 4s for files ≤ 25 MB"). A requirement no test could check is a wish.
+- **Pattern-shaped (SHOULD)** — one of the EARS patterns, which decompose into Gherkin mechanically:
+  - Ubiquitous: *The `<system>` shall `<response>`*
+  - Event-driven: *When `<trigger>`, the `<system>` shall `<response>`*
+  - State-driven: *While `<state>`, the `<system>` shall `<response>`*
+  - Unwanted behavior: *If `<condition>`, then the `<system>` shall `<response>`*
+  - Optional feature: *Where `<feature>` is present, the `<system>` shall `<response>`*
+
+## The document
+
+Beyond the atoms, a ready PRD carries: problem statement · solution outline · user stories grouping their atoms · an explicit **non-functional checklist** (walk the ISO 25010 axes — performance, security, reliability, usability, compatibility, maintainability — and either state the requirement as an atom or state "no requirement"; silence is not a decision) · out of scope · open questions (the honest home for what is NOT ready).
+
+## Enforcement points
+
+- **Write time** — `lisa-research` authors to this shape; `*-write-prd` skills carry it as a body rule.
+- **Intake time (the universal gate)** — `*-to-tracker` Phase 1.45 validates every register atom, because human-authored PRDs never pass through the write path. Failures are product clarifications quoting the atom verbatim with candidate rewrites.
+- **Verify time** — `verify-prd` / spec-conformance consume the atoms; fit criteria become the conformance checks.
+
+Downstream, ticket gate S16 quotes these atoms verbatim and `prd-ticket-coverage` audits atom→ticket coverage — both degrade when "one requirement" is secretly three welded together.
+
+---
+
+The eager head carries the atom definition and enforcement points; this
+reference carries the rationale, the full vagueness lexicon, and worked
+rewrites. The companion rule `work-item-definition-of-ready` governs the next
+stage down (tickets); this rule governs what the Plan factory decomposes from.
+
+## Why requirement shape is the whole game
+
+The pipeline consumes requirements three times, and each consumer needs a
+different property that only shaped atoms provide:
+
+1. **Plan decomposes** — an EARS-shaped atom (*When X, the system shall Y*)
+   maps to a Gherkin scenario (*When X / Then Y*) nearly mechanically. Prose
+   paragraphs force the planner to invent the split, which is where scope
+   quietly drifts between the PRD and the backlog.
+2. **Tickets trace** — gate S16 quotes the requirement verbatim on every leaf.
+   A verbatim quote of a paragraph containing three requirements is an
+   ambiguous trace: which of the three does this ticket satisfy?
+3. **Verification checks conformance** — spec-conformance and `verify-prd`
+   read the PRD back against the shipped result. A fit criterion is a
+   conformance check waiting to run; an adjective is not.
+
+The standards being distilled: **ISO/IEC/IEEE 29148** (successor to IEEE 830)
+supplies the per-requirement quality characteristics — necessary, appropriate,
+unambiguous, complete, singular, feasible, verifiable, correct — and the
+practice of banning untestable phrasing. **EARS** (Mavin et al.) supplies the
+five sentence patterns. **Volere** supplies the fit criterion. **ISO 25010**
+supplies the non-functional axes for the completeness walk. None of these are
+imported wholesale; this rule takes exactly the parts a machine planner and a
+machine verifier consume.
+
+## The vagueness lexicon
+
+Presence of these (and their kin) in a requirement atom FAILs it as
+unverifiable — each is a phrase no test can check:
+
+> as appropriate · as needed · if necessary · user-friendly · intuitive ·
+> seamless · robust · flexible · fast · quickly · efficient · optimize ·
+> minimize / maximize (unbounded) · handle gracefully · support (unbounded) ·
+> etc. · and/or · TBD inside an atom (TBD belongs in Open Questions)
+
+The lexicon is a floor, not a ceiling — validators should flag any phrasing
+they cannot turn into a check.
+
+## Worked rewrites
+
+| Before (fails) | After (passes) |
+|---|---|
+| "Uploads should be fast and handle errors gracefully." | R4: *When a user uploads a file ≤ 25 MB, the system shall complete the upload within 4s at p95.* Fit: perf-trace on staging. R5: *If an upload fails, then the system shall show a retryable error naming the cause.* Fit: screenshot of the error state per failure class. |
+| "The dashboard should be user-friendly and support filtering, sorting, etc." | R7: *The dashboard shall filter by status, owner, and date range.* R8: *The dashboard shall sort by any visible column.* Fit: each verb exercised in an E2E journey. ("etc." is deleted — unnamed features are unbuilt features.) |
+| "Optimize the pipeline." | R2: *The nightly pipeline shall complete within 30 minutes for a 10k-item batch* (baseline: 47m measured 2026-07-01). Fit: pipeline duration metric. — note this is Improvement-shaped: baseline + target, per `work-item-definition-of-ready`. |
+
+## Singularity repair
+
+When an atom contains multiple behaviors, the register splits it (`R4` →
+`R4a`, `R4b`) — **mechanically when the split preserves meaning**, as a
+product clarification when it does not. The split is recorded in the dry-run
+report; it is never silent, because the PRD author's numbering is part of the
+traceability contract.
+
+## The non-functional walk
+
+A PRD is complete only when the ISO 25010 axes were each considered:
+performance, security, reliability, usability, compatibility,
+maintainability/operability. The required artifact is one line per axis —
+either an atom or an explicit "no requirement." The point is not ceremony; it
+is that **silence and "no requirement" are different facts**, and only one of
+them is a decision a verifier can hold the product to.
+
+## Relationship to the lifecycle
+
+- **Write** — `lisa-research` authors atoms; `*-write-prd` carries the body
+  rule. Factory-authored PRDs are born conforming.
+- **Intake** — `*-to-tracker` Phase 1.45 is the universal gate (human-authored
+  PRDs arrive here without passing any write path). Failures quote the atom
+  verbatim, name the defect, and offer 1–3 candidate rewrites — the
+  EARS-shaped rewrite is the default recommendation. Routed like every other
+  intake failure: PRD to `blocked`, product-readable comments.
+- **Verify** — fit criteria become the spec-conformance checks; the
+  requirement register ids appear in the PRD backlink and the coverage audit.

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

@@ -0,0 +1,192 @@
+# PRD Lifecycle Rollup & Generated-Top-Level-Work Contract
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## PRD Lifecycle Rollup & Generated-Top-Level-Work Contract (load-bearing)
+
+The vendor-neutral source of truth for how a PRD owns the work it generated and how its lifecycle rolls up to `shipped`. Companion to `leaf-only-lifecycle` (which governs build-lifecycle of leaves); this rule governs PRD lifecycle and rollup from generated top-level children.
+
+## Generated top-level work (the contract)
+
+A PRD owns the work units it created **at the top of the hierarchy** — the Epic(s) and any top-level Story it created directly. It does NOT own descendants (Sub-tasks, Stories under an Epic, leaves under a top-level unit) — those are owned by their top-level parent and roll up via `leaf-only-lifecycle`.
+
+Leaf Sub-tasks are **never** direct children of a PRD when a top-level Epic/Story hierarchy exists.
+
+## How each vendor records the PRD→child link
+
+**Native hierarchy first**, machine-readable fallback section always written:
+
+- **GitHub Issues** — native sub-issues when source and tracker are the same repo + supports sub-issues.
+- **Linear** — `parentId` or generated Project grouping where the PRD also lives in Linear.
+- **JIRA** — Epic link / parent field, or documented issue-link type.
+- **Confluence / Notion** — no native issue hierarchy; the documented `## Tickets` / `## Generated Work` section IS the source of truth.
+- **Cross-vendor** (e.g. Notion PRD → JIRA tracker) — always documented section in the PRD source.
+
+The documented `## Tickets` section is ALWAYS written (additive to native links) so the generated set is readable without parsing comments.
+
+## Rollup transition
+
+PRD rolls from `ticketed` to `shipped` when every required generated top-level child is terminal. The PRD remains open for `/lisa:verify-prd` after `shipped` — verified PASS performs native closure (archive/close/transition), verified FAIL re-opens to `ticketed` with build-ready fix tickets (never `blocked`).
+
+## Idempotency dedupe key
+
+Re-runs of intake/backlink must dedupe by child-ref identity (e.g. `owner/repo#number` for GitHub, Linear issue UUID, JIRA key) — never by URL string, which varies by formatting.
+
+---
+
+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** or **duplicate** state (both terminal-but-dropped, like not-planned — do not hold the PRD open, excluded from shipped). Linear exposes `duplicate` as its own first-class `state.type`, distinct from `canceled`; an Issue marked as a duplicate (via Linear's native action or a team's Duplicate workflow state) is terminal and must be treated like canceled, never as still-open. |
+| **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 / duplicate / 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** (`lisa-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** (`lisa-prd-ticket-coverage`) — read the generated top-level child set deterministically from the recorded relationship, not from free-form comments.
+- **GitHub PRD shipped rollup** (`lisa-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** (`lisa-linear-prd-intake`, `lisa-confluence-prd-intake`, `lisa-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** (`lisa-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.