npm - @codyswann/lisa - Versions diffs - 2.43.0 → 2.45.0 - Mend

@codyswann/lisa 2.43.0 → 2.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/package.json CHANGED Viewed

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/skills/github-prd-intake/SKILL.md CHANGED Viewed

@@ -39,6 +39,8 @@ In prose below, the role names refer to the resolved labels: e.g. "the `ready` l
 This skill is the GitHub counterpart of `lisa:notion-prd-intake`, `lisa:confluence-prd-intake`, and `lisa:linear-prd-intake`. Phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **issue labels** (mirroring Linear's project labels and Confluence's page labels), (2) the fetch / update tools are the `gh` CLI, and (3) clarifying-question comments land directly on the source PRD issue (because GitHub Issues *do* have native comments — no sentinel issue required, unlike Linear). Keep all four skills behaviorally aligned: when changing intake logic, change them together.
+The **PRD closure rollup phase (3f)** is, for now, GitHub-only: it transitions a `$TICKETED` PRD to `$SHIPPED` (and optionally closes it) once all its generated top-level work is terminal, per the `prd-lifecycle-rollup` rule. The Linear / Confluence / Notion counterparts gain the same rollup in sibling sub-task #584; until then, those three intake skills do not roll up to `shipped`, so this alignment note covers the shared intake/validation phases (1–3e), not yet the rollup phase.
 ## Confirmation policy
 Do NOT ask the caller whether to proceed. Once invoked with a repo, run the cycle to completion — claim, validate, branch to `$BLOCKED` or `$TICKETED`, write the summary. The caller has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
@@ -69,14 +71,15 @@ draft → ready → in_review → blocked | ticketed → shipped
 Exactly one of these labels is expected on a PRD issue at any time.
-This skill ONLY transitions:
+This skill transitions:
 - `$READY` → `$IN_REVIEW` (claim)
 - `$IN_REVIEW` → `$BLOCKED` (gate failures or coverage gaps)
 - `$IN_REVIEW` → `$TICKETED` (success)
 - `$TICKETED` → `$BLOCKED` (post-write coverage gaps from Phase 3e)
+- `$TICKETED` → `$SHIPPED` (PRD closure rollup, Phase 3f — only when **all** generated top-level children are terminal)
-It never adds, removes, or touches the `draft` or `shipped` labels. Those labels are owned by product.
+The `draft` label is owned by product and is never touched here. The `shipped` label is set by this skill's **rollup phase (3f)** when, and only when, the PRD's generated top-level work is all terminal — per the `prd-lifecycle-rollup` rule; product may also set it by hand. Rollup never advances a PRD to `shipped` on partial completion, and never closes a PRD issue unless `github.labels.prd.rollup.closeOnShipped` is configured `true` (default `false` → set `shipped`, leave open).
 A "transition" means: remove the old lifecycle label and add the new one (`gh issue edit <num> --remove-label <old> --add-label <new>`). The skill MUST verify exactly one lifecycle label is present after the update.
@@ -240,6 +243,99 @@ Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* o
 3. The created tickets remain in the destination tracker regardless of the verdict. The audit only tells us whether *more* are needed.
+#### 3f. PRD closure rollup (config-gated)
+A PRD's lifecycle terminal state (`shipped`) is **derived** from whether the work it generated is done — it is never set by hand here on its own authority. This phase implements the GitHub leg of that derivation, per the `prd-lifecycle-rollup` rule (cite it by slug; do not restate its taxonomy or terminal-state semantics here). Linear / Confluence / Notion rollup is a sibling sub-task (#584) and is out of scope for this skill.
+Rollup runs over PRD issues that are already `$TICKETED` (the only state from which a PRD can ship): the freshly-ticketed PRD from Phase 3c, and — because rollup also catches PRDs whose children finished in a *later* cycle — every issue currently carrying `$TICKETED`. Process each independently; one PRD never blocks another's rollup.
+##### 3f.0 Resolve closure config
+Closure is gated on `github.labels.prd.rollup.closeOnShipped` (default `false`). Resolve it with the same local-overrides-global precedence the lifecycle labels use:
+```bash
+# Resolve a boolean rollup flag. Local overrides global per-key; default when unset.
+read_rollup_flag() {
+  local key="$1" default="$2"
+  local local_v global_v
+  local_v=$(jq -r ".github.labels.prd.rollup.${key} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".github.labels.prd.rollup.${key} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+CLOSE_ON_SHIPPED=$(read_rollup_flag closeOnShipped false)
+```
+When `false` (the default), rollup sets `$SHIPPED` but leaves the PRD issue **open** for a human to close. When `true`, rollup also closes the PRD issue after the `$SHIPPED` transition. Closure NEVER happens before all generated top-level work is terminal (`prd-lifecycle-rollup` rule; PRD #525 non-goal).
+##### 3f.1 Idempotency guard (no-op if already shipped)
+Rollup is keyed by the PRD's current state. If the PRD already carries `$SHIPPED` (and is already closed, when `$CLOSE_ON_SHIPPED` is `true`), it is a **no-op** — do not re-transition, do not re-close, do not re-comment. Record it as `already shipped (no-op)` in the cycle summary and move on. This is what makes re-running intake safe.
+##### 3f.2 Read the generated top-level child set
+Read the PRD's **generated top-level work** — its created Epics and any top-level Stories created directly under it, **excluding** leaf Sub-tasks and any Story nested under a generated Epic (`prd-lifecycle-rollup` rule, generated-top-level-work contract). Use two sources, native first:
+1. **Native sub-issues (primary).** Traverse the PRD issue's native sub-issue graph via the GraphQL `subIssues` query (the same query `lisa:github-read-issue` Phase 3 uses). The PRD's direct `subIssues` nodes are its top-level children:
+   ```bash
+   gh api graphql -f query='
+   query($org:String!,$repo:String!,$number:Int!){
+     repository(owner:$org,name:$repo){
+       issue(number:$number){
+         subIssues(first: 100) {
+           nodes {
+             number title state url
+             repository { nameWithOwner }
+             labels(first: 50) { nodes { name } }
+           }
+         }
+       }
+     }
+   }' -F org=<org> -F repo=<repo> -F number=<prd-num>
+   ```
+2. **Documented `## Tickets` section (fallback).** When native sub-issues are unavailable (older GHES, sub-issues feature off, or the source PRD and the destination tracker are different systems so the children were never linked as sub-issues), parse the machine-readable generated-work section `lisa:prd-backlink` writes to the PRD body (`## Tickets`, alias `## Generated Work`; see #582). Top-level children are the `### <Epic key>: <title>` group headers' first line (`- [<ref>](<url>) — Epic`) plus any top-level Story listed directly under `### Unparented items`. Lines nested deeper (`  - ... — Story:` under an Epic, `    - ... — Sub-task:`) are descendants, NOT top-level children — skip them.
+   ```bash
+   # Top-level child refs = Epic lines (top indent) + Unparented top-level Stories.
+   # Sub-tasks and Stories nested under an Epic are descendants — excluded.
+   gh issue view <prd-num> --repo <org>/<repo> --json body --jq '.body' \
+     | awk '/^## (Tickets|Generated Work)/{insec=1;next} /^## /{insec=0}
+            insec && /^- \[.*\] — Epic/{print}
+            insec && /^### Unparented items/{unp=1;next}
+            insec && unp && /^- \[.*\] — Story/{print}'
+   ```
+Dedupe the resulting child set by **child-ref identity** (`owner/repo#number`) so a child that appears both as a native sub-issue and in the documented section is counted once (`prd-lifecycle-rollup` idempotency dedupe key). If neither source yields any child (the PRD generated nothing, or the relationship was never recorded), record `no generated top-level children — rollup skipped` and leave the PRD as `$TICKETED`; do not ship an empty PRD.
+##### 3f.3 Apply the terminal-state predicate
+For each top-level child, fetch its state + labels (already present from the GraphQL nodes, or `gh issue view <child-num> --json state,labels`) and classify per the `prd-lifecycle-rollup` GitHub predicate:
+- **Terminal (shipped).** The child issue is **CLOSED** *and* (where the build-status label is in use) carries the resolved build `done` role label (`status:done` by default). A child Epic is terminal only when it has itself rolled up to its own terminal state per `leaf-only-lifecycle` — read the child's own resolved state; do not re-derive it from its leaves here.
+- **Terminal-but-dropped.** The child is closed **as not planned** (`stateReason == "not_planned"`). It does not hold the PRD open and is excluded from the shipped set — treated like a won't-do leaf.
+- **Incomplete / blocked.** Anything else: still open, or closed without the `done` label. Holds the PRD open.
+The set of **required** children for the all-terminal check is the top-level children minus the terminal-but-dropped ones.
+##### 3f.4 Branch on the rollup verdict
+**All required children terminal** (every required top-level child is terminal; at least one required child exists):
+1. Transition labels: `gh issue edit <prd-num> --repo <org>/<repo> --remove-label "$TICKETED" --add-label "$SHIPPED"`. Verify exactly one lifecycle label remains (the single-label invariant).
+2. **If `$CLOSE_ON_SHIPPED` is `true`**, close the PRD issue: `gh issue close <prd-num> --repo <org>/<repo> --reason completed`. When `false`, leave it open.
+3. Post a short rollup comment naming the terminal child set and (when dropped children exist) the dropped set, so the audit trail records *why* the PRD shipped. Lead with `"Shipped by Claude — all generated top-level work is complete."`
+**Any required child incomplete / blocked**:
+1. Leave the PRD label as `$TICKETED` and leave the issue **open**. Do NOT add `$SHIPPED`. Do NOT close.
+2. Report the incomplete child set — both in the cycle summary and, when at least one cycle has previously ticketed this PRD, as a single advisory comment listing the still-open children (`- <ref> "<title>" — <state>`), so product can see what's blocking the rollup. Keep it idempotent: regenerate the advisory rather than appending a fresh one each cycle.
+##### 3f.5 Rollup is GitHub-only and cites the rule
+This phase only touches GitHub PRD issues. It implements exactly one PRD-lifecycle hop — `$TICKETED → $SHIPPED` — and the optional config-gated close that follows it. All terminal-state semantics, the generated-top-level-work boundary, the env-keyed `done` resolution, and the dedupe-by-child-ref idempotency come from the `prd-lifecycle-rollup` rule; this skill is its GitHub implementation, not a second source of truth.
 ### Phase 4 — Summary report
 ```text
@@ -257,6 +353,14 @@ PRDs processed: <n>
 - Errors (claim failed, etc): <n>
   - <issue-ref> "<title>" — <reason>
+Rollup (Phase 3f):
+- $SHIPPED: <n>
+  - <issue-ref> "<title>" → all <child-count> top-level children terminal (<dropped-count> dropped); closed: <yes|no (closeOnShipped off)>
+- Held open (incomplete children): <n>
+  - <issue-ref> "<title>" → <incomplete-count> of <child-count> top-level children still open
+- Already shipped (no-op): <n>
+- No generated children (rollup skipped): <n>
 Total tickets created: <n>
 Coverage audit summary: <n> COMPLETE / <n> COMPLETE_WITH_SCOPE_CREEP / <n> GAPS_FOUND
 ```
@@ -274,10 +378,11 @@ When the configured destination tracker is GitHub Issues AND the PRD repo is the
 ## Idempotency & safety
 - **Single-cycle scope**: this skill processes the ready set as it exists at the start of Phase 2. New ready issues added mid-cycle are picked up next run.
-- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:github-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes labels among `$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, only ever comments on the source PRD issue. It never edits PRD bodies, never touches `draft` or `shipped` labels, never closes or deletes PRD issues.
+- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:github-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes labels among `$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, `$SHIPPED`, only ever comments on the source PRD issue. It never edits PRD bodies and never touches the `draft` label. It sets the `$SHIPPED` label and may close the PRD issue **only** through the config-gated rollup phase (3f), and never deletes any issue.
 - **Claim-first ordering**: the label flip to `$IN_REVIEW` happens BEFORE validation runs.
 - **Failure isolation**: an exception processing one PRD must not stop the cycle. Catch, record under "Errors" in the summary, continue. The PRD that errored is left labeled `$IN_REVIEW` — humans investigate from there.
 - **Single-label invariant**: after every transition, verify exactly one lifecycle label is present.
+- **Rollup idempotency**: rollup (Phase 3f) is a no-op on a PRD already carrying `$SHIPPED` (and already closed when `closeOnShipped` is `true`) — no duplicate transition, no duplicate close, no duplicate comment. The all-terminal condition is a pure function of the children's current states, so recomputing it is safe to re-run. Closure NEVER precedes the all-terminal condition.
 ## Configuration
@@ -299,7 +404,8 @@ Destination tracker config (jira / github / linear) is consumed by `lisa:tracker
 ## Rules
 - Never write to the destination tracker outside of `lisa:github-to-tracker` → `lisa:tracker-write`.
-- Never add or remove a label this skill doesn't own (`$IN_REVIEW`, `$BLOCKED`, `$TICKETED`). Product owns the `draft`, `ready`, and `shipped` PRD labels.
+- Never add or remove a label this skill doesn't own (`$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, and `$SHIPPED` via the rollup phase only). Product owns the `draft` and `ready` PRD labels; product and the rollup phase (3f) both set `shipped`.
+- Set `$SHIPPED` (and close the PRD when `closeOnShipped` is configured) only from the rollup phase, and only when all generated top-level children are terminal per the `prd-lifecycle-rollup` rule. Never ship or close on partial completion.
 - Never edit a PRD's body. Communication with product happens only via comments.
 - Never post a single dump of all gate failures on one comment. One comment per `prd_anchor` group, plus one rollup for unanchored failures.
 - Never include a gate ID, internal skill name, or engineering shorthand in a comment body.

package/plugins/lisa/skills/prd-backlink/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: prd-backlink
-description: "Update a source PRD with a `## Tickets` section linking back to every work item created from it. Vendor-aware on the source side (Notion / Confluence / Linear / GitHub Issue / file) and tracker-agnostic on the ticket side. Idempotent — regenerates the section on each run rather than appending, so re-planning never accumulates stale links. Invoked by the *-to-tracker skills at the end of their pipeline and standalone if a PRD's Tickets section needs to be refreshed."
+description: "Update a source PRD with an always-written, machine-readable `## Tickets` (alias `## Generated Work`) section linking back to every work item created from it. Each entry carries a parseable ref + URL + type + parent token so the generated child set is readable without scraping prose. Vendor-aware on the source side (Notion / Confluence / Linear / GitHub Issue / file) and tracker-agnostic on the ticket side; the documented section is written for every vendor, additive to native hierarchy linking. Idempotent — regenerates the section on each run rather than appending, so re-planning never accumulates stale links. Invoked by the *-to-tracker skills at the end of their pipeline and standalone if a PRD's Tickets section needs to be refreshed."
 allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
 ---
@@ -8,6 +8,8 @@ allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
 Write or update the `## Tickets` section of a source PRD so it links to every work item created from that PRD. The Debrief flow (and a human reading the PRD months later) uses this section as the canonical work-item set for the initiative.
+This documented section is the **always-written, machine-readable record** of the generated child set. It is written for **every** `source_type` — including the vendors that also get a native hierarchy link (`github` / `linear` / `jira`) — so the generated top-level work is readable later from the PRD body alone, without parsing free-form comments or depending on a native relationship that may be unavailable on older hosts or across vendors. Native hierarchy linking (see the per-vendor sections below) is **additive** to this section, never a substitute for it. This is the documented-section leg of the `prd-lifecycle-rollup` rule (cited by slug; its taxonomy is not restated here).
 ## Input
 Pass `$ARGUMENTS` as a single JSON-style block:
@@ -31,8 +33,8 @@ Pass `$ARGUMENTS` as a single JSON-style block:
    - `linear` → Linear MCP project / issue read
    - `github` → `gh issue view`
    - `file` → `Read` tool on the absolute path
-2. **Locate the existing section.** Search for `section_heading` (default `## Tickets`). If present, you will replace it. If not, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.
-3. **Render the section.** Use the format below. Group by Epic. Within an Epic, group by Story. Sub-tasks nest under their Story. Bugs and Spikes that are not under a Story go in a flat list at the bottom.
+2. **Locate the existing section.** Search for `section_heading` (default `## Tickets`). The canonical heading is `## Tickets`; `## Generated Work` is an accepted alias that the reader recognizes — match either heading when locating an existing section so a PRD authored with either name is found and regenerated in place (never duplicated under the other name). If present under either name, you will replace it (keeping whichever heading was already there, or the explicit `section_heading` override). If not present, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.
+3. **Render the section.** Always render it — for every `source_type`, even when a native hierarchy link was also made (additive, not exclusive). Use the format below. Group by Epic. Within an Epic, group by Story. Sub-tasks nest under their Story. Bugs and Spikes that are not under a Story go in a flat list at the bottom. Each entry carries a machine-readable token (ref + URL + type + parent) so the generated child set is parseable without reading prose — see [Format](#format).
 4. **Write the updated PRD back** using the source's native write tool:
    - `notion` → `notion-update-page`
    - `confluence` → `updateConfluencePage`
@@ -49,7 +51,7 @@ Pass `$ARGUMENTS` as a single JSON-style block:
 ## Format
-The rendered section must be deterministic — same inputs produce identical output bytes. This is what makes idempotency reliable.
+The rendered section must be deterministic — same inputs produce identical output bytes. This is what makes idempotency reliable. Every entry is simultaneously **human-readable** (a nested markdown link) and **machine-readable** (a trailing structured token), so the generated child set can be enumerated by parsing this section alone — the contract LPC-1.3 rollup (`github-prd-intake` / `*-prd-intake`) reads against, with no need to scrape free-form comments.
 ```markdown
 ## Tickets
@@ -58,28 +60,45 @@ _Generated by `lisa:prd-backlink`. Regenerated on every Plan run; do not edit by
 ### <Epic key>: <Epic title>
-- [<Epic key>](<url>) — Epic
-  - [<Story key>](<url>) — Story: <title>
-    - [<Sub-task key>](<url>) — Sub-task: <title>
-    - [<Sub-task key>](<url>) — Sub-task: <title>
-  - [<Story key>](<url>) — Story: <title>
+- [<Epic key>](<url>) — Epic <!-- lisa:gw ref=<ref> url=<url> type=Epic parent= -->
+  - [<Story key>](<url>) — Story: <title> <!-- lisa:gw ref=<ref> url=<url> type=Story parent=<Epic ref> -->
+    - [<Sub-task key>](<url>) — Sub-task: <title> <!-- lisa:gw ref=<ref> url=<url> type=Sub-task parent=<Story ref> -->
+    - [<Sub-task key>](<url>) — Sub-task: <title> <!-- lisa:gw ref=<ref> url=<url> type=Sub-task parent=<Story ref> -->
+  - [<Story key>](<url>) — Story: <title> <!-- lisa:gw ref=<ref> url=<url> type=Story parent=<Epic ref> -->
 ### <Epic key>: <Epic title>
 ...
 ### Unparented items
-- [<Bug key>](<url>) — Bug: <title>
-- [<Spike key>](<url>) — Spike: <title>
+- [<Bug key>](<url>) — Bug: <title> <!-- lisa:gw ref=<ref> url=<url> type=Bug parent= -->
+- [<Spike key>](<url>) — Spike: <title> <!-- lisa:gw ref=<ref> url=<url> type=Spike parent= -->
+```
+### Machine-readable entry token
+Every list entry ends with a single-line HTML comment — invisible in rendered markdown, so the section stays clean for humans, but a stable, greppable record for machines:
+```text
+<!-- lisa:gw ref=<ref> url=<url> type=<type> parent=<parent-ref or empty> -->
 ```
-If the input contains zero items, write the section header with a single line: `_No tickets created — Plan flow may not have completed._` Do not omit the section; presence-of-section is itself a signal to Debrief.
+- **`lisa:gw`** — a fixed sentinel (`gw` = generated work). A reader enumerates the generated child set by matching `<!-- lisa:gw ` lines; it never has to parse the surrounding prose, headings, or indentation.
+- **`ref`** — the child-ref identity from the `prd-lifecycle-rollup` rule: `<org>/<repo>#<n>` for GitHub, the issue/project identifier (e.g. `TEAM-123`) for Linear, the issue key (e.g. `PROJ-123`) for JIRA. This is the same dedupe key native linking uses, so the documented record and the native record agree.
+- **`url`** — the canonical URL of the work item.
+- **`type`** — `Epic | Story | Task | Sub-task | Bug | Spike` (verbatim from the ticket's `type`).
+- **`parent`** — the **`ref`** of this entry's parent (its `parent_key` resolved to the parent's ref), or **empty** when the entry is top-level (`parent_key` null/empty). A reader selects the **generated top-level child set** — exactly what the PRD owns per the rule — as every `lisa:gw` line whose `parent` is empty.
+The visible markdown link and the token always carry the same `ref`/`url`/`type`; the token is the authoritative machine field (the prose may wrap or be reflowed by a host editor, the comment line will not). Field order within the token is fixed (`ref`, `url`, `type`, `parent`) so output is byte-stable.
+If the input contains zero items, write the section header with a single line: `_No tickets created — Plan flow may not have completed._` Do not omit the section; presence-of-section is itself a signal to Debrief, and the always-written guarantee means a reader can always distinguish "ran, produced nothing" from "never ran."
 ## Idempotency
 Rendering rules:
-- Sort epics by key (lexical). Sort stories within an epic by key. Sort sub-tasks within a story by key. Sort the unparented list by `(type, key)`.
+- Sort epics by key (lexical). Sort stories within an epic by key. Sort sub-tasks within a story by key. Sort the unparented list by `(type, key)`. The same sort applies to the `lisa:gw` tokens (each token sits on its entry's line), so the machine-readable order is identical across runs.
 - The line `_Generated by ..._` is fixed text — does not include a timestamp. A timestamp would defeat the diff-equality check Debrief relies on.
+- Regenerate the whole section from the current ticket set on every run — **never append**. Dedupe is by **child-ref** (the token's `ref`, per the `prd-lifecycle-rollup` idempotency dedupe key): the same ticket set produces a byte-identical section with no duplicate entries, and re-running over an existing section is a no-op diff. A ticket present in a prior run but absent now simply does not reappear (stale links never accumulate).
 ## Native parent linking (GitHub)
@@ -242,4 +261,4 @@ Omit the `Native parent links` line when no native linking applies (Notion / Con
 ## Related rules
-- `prd-lifecycle-rollup` — the vendor-neutral source of truth for PRD→generated-top-level-work ownership, the per-vendor terminal predicate, PRD `shipped` rollup, and the child-ref idempotency dedupe key. This skill implements the GitHub, Linear, and JIRA native-linking legs of that rule; it cites the rule by slug rather than restating its taxonomy.
+- `prd-lifecycle-rollup` — the vendor-neutral source of truth for PRD→generated-top-level-work ownership, the per-vendor terminal predicate, PRD `shipped` rollup, and the child-ref idempotency dedupe key. This skill implements both the **documented always-written, machine-readable generated-work section** leg (the universal fallback written for every vendor) and the GitHub, Linear, and JIRA native-linking legs of that rule; it cites the rule by slug rather than restating its taxonomy.

package/plugins/lisa/skills/prd-backlink/agents/openai.yaml CHANGED Viewed

@@ -1,4 +1,4 @@
 display_name: "PRD Backlink"
-short_description: "Update a source PRD with a `## Tickets` section linking back to every work item created from it"
+short_description: "Update a source PRD with an always-written, machine-readable `## Tickets` (alias `## Generated Work`) section linking back to every work…"
 default_prompt:
-  - "Use $prd-backlink: Update a source PRD with a `## Tickets` section linking back to every work item created from it."
+  - "Use $prd-backlink: Update a source PRD with an always-written, machine-readable `## Tickets` (alias `## Generated Work`) section linking back to every work…."

package/plugins/lisa-cdk/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/skills/github-prd-intake/SKILL.md CHANGED Viewed

@@ -39,6 +39,8 @@ In prose below, the role names refer to the resolved labels: e.g. "the `ready` l
 This skill is the GitHub counterpart of `lisa:notion-prd-intake`, `lisa:confluence-prd-intake`, and `lisa:linear-prd-intake`. Phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **issue labels** (mirroring Linear's project labels and Confluence's page labels), (2) the fetch / update tools are the `gh` CLI, and (3) clarifying-question comments land directly on the source PRD issue (because GitHub Issues *do* have native comments — no sentinel issue required, unlike Linear). Keep all four skills behaviorally aligned: when changing intake logic, change them together.
+The **PRD closure rollup phase (3f)** is, for now, GitHub-only: it transitions a `$TICKETED` PRD to `$SHIPPED` (and optionally closes it) once all its generated top-level work is terminal, per the `prd-lifecycle-rollup` rule. The Linear / Confluence / Notion counterparts gain the same rollup in sibling sub-task #584; until then, those three intake skills do not roll up to `shipped`, so this alignment note covers the shared intake/validation phases (1–3e), not yet the rollup phase.
 ## Confirmation policy
 Do NOT ask the caller whether to proceed. Once invoked with a repo, run the cycle to completion — claim, validate, branch to `$BLOCKED` or `$TICKETED`, write the summary. The caller has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
@@ -69,14 +71,15 @@ draft → ready → in_review → blocked | ticketed → shipped
 Exactly one of these labels is expected on a PRD issue at any time.
-This skill ONLY transitions:
+This skill transitions:
 - `$READY` → `$IN_REVIEW` (claim)
 - `$IN_REVIEW` → `$BLOCKED` (gate failures or coverage gaps)
 - `$IN_REVIEW` → `$TICKETED` (success)
 - `$TICKETED` → `$BLOCKED` (post-write coverage gaps from Phase 3e)
+- `$TICKETED` → `$SHIPPED` (PRD closure rollup, Phase 3f — only when **all** generated top-level children are terminal)
-It never adds, removes, or touches the `draft` or `shipped` labels. Those labels are owned by product.
+The `draft` label is owned by product and is never touched here. The `shipped` label is set by this skill's **rollup phase (3f)** when, and only when, the PRD's generated top-level work is all terminal — per the `prd-lifecycle-rollup` rule; product may also set it by hand. Rollup never advances a PRD to `shipped` on partial completion, and never closes a PRD issue unless `github.labels.prd.rollup.closeOnShipped` is configured `true` (default `false` → set `shipped`, leave open).
 A "transition" means: remove the old lifecycle label and add the new one (`gh issue edit <num> --remove-label <old> --add-label <new>`). The skill MUST verify exactly one lifecycle label is present after the update.
@@ -240,6 +243,99 @@ Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* o
 3. The created tickets remain in the destination tracker regardless of the verdict. The audit only tells us whether *more* are needed.
+#### 3f. PRD closure rollup (config-gated)
+A PRD's lifecycle terminal state (`shipped`) is **derived** from whether the work it generated is done — it is never set by hand here on its own authority. This phase implements the GitHub leg of that derivation, per the `prd-lifecycle-rollup` rule (cite it by slug; do not restate its taxonomy or terminal-state semantics here). Linear / Confluence / Notion rollup is a sibling sub-task (#584) and is out of scope for this skill.
+Rollup runs over PRD issues that are already `$TICKETED` (the only state from which a PRD can ship): the freshly-ticketed PRD from Phase 3c, and — because rollup also catches PRDs whose children finished in a *later* cycle — every issue currently carrying `$TICKETED`. Process each independently; one PRD never blocks another's rollup.
+##### 3f.0 Resolve closure config
+Closure is gated on `github.labels.prd.rollup.closeOnShipped` (default `false`). Resolve it with the same local-overrides-global precedence the lifecycle labels use:
+```bash
+# Resolve a boolean rollup flag. Local overrides global per-key; default when unset.
+read_rollup_flag() {
+  local key="$1" default="$2"
+  local local_v global_v
+  local_v=$(jq -r ".github.labels.prd.rollup.${key} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".github.labels.prd.rollup.${key} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+CLOSE_ON_SHIPPED=$(read_rollup_flag closeOnShipped false)
+```
+When `false` (the default), rollup sets `$SHIPPED` but leaves the PRD issue **open** for a human to close. When `true`, rollup also closes the PRD issue after the `$SHIPPED` transition. Closure NEVER happens before all generated top-level work is terminal (`prd-lifecycle-rollup` rule; PRD #525 non-goal).
+##### 3f.1 Idempotency guard (no-op if already shipped)
+Rollup is keyed by the PRD's current state. If the PRD already carries `$SHIPPED` (and is already closed, when `$CLOSE_ON_SHIPPED` is `true`), it is a **no-op** — do not re-transition, do not re-close, do not re-comment. Record it as `already shipped (no-op)` in the cycle summary and move on. This is what makes re-running intake safe.
+##### 3f.2 Read the generated top-level child set
+Read the PRD's **generated top-level work** — its created Epics and any top-level Stories created directly under it, **excluding** leaf Sub-tasks and any Story nested under a generated Epic (`prd-lifecycle-rollup` rule, generated-top-level-work contract). Use two sources, native first:
+1. **Native sub-issues (primary).** Traverse the PRD issue's native sub-issue graph via the GraphQL `subIssues` query (the same query `lisa:github-read-issue` Phase 3 uses). The PRD's direct `subIssues` nodes are its top-level children:
+   ```bash
+   gh api graphql -f query='
+   query($org:String!,$repo:String!,$number:Int!){
+     repository(owner:$org,name:$repo){
+       issue(number:$number){
+         subIssues(first: 100) {
+           nodes {
+             number title state url
+             repository { nameWithOwner }
+             labels(first: 50) { nodes { name } }
+           }
+         }
+       }
+     }
+   }' -F org=<org> -F repo=<repo> -F number=<prd-num>
+   ```
+2. **Documented `## Tickets` section (fallback).** When native sub-issues are unavailable (older GHES, sub-issues feature off, or the source PRD and the destination tracker are different systems so the children were never linked as sub-issues), parse the machine-readable generated-work section `lisa:prd-backlink` writes to the PRD body (`## Tickets`, alias `## Generated Work`; see #582). Top-level children are the `### <Epic key>: <title>` group headers' first line (`- [<ref>](<url>) — Epic`) plus any top-level Story listed directly under `### Unparented items`. Lines nested deeper (`  - ... — Story:` under an Epic, `    - ... — Sub-task:`) are descendants, NOT top-level children — skip them.
+   ```bash
+   # Top-level child refs = Epic lines (top indent) + Unparented top-level Stories.
+   # Sub-tasks and Stories nested under an Epic are descendants — excluded.
+   gh issue view <prd-num> --repo <org>/<repo> --json body --jq '.body' \
+     | awk '/^## (Tickets|Generated Work)/{insec=1;next} /^## /{insec=0}
+            insec && /^- \[.*\] — Epic/{print}
+            insec && /^### Unparented items/{unp=1;next}
+            insec && unp && /^- \[.*\] — Story/{print}'
+   ```
+Dedupe the resulting child set by **child-ref identity** (`owner/repo#number`) so a child that appears both as a native sub-issue and in the documented section is counted once (`prd-lifecycle-rollup` idempotency dedupe key). If neither source yields any child (the PRD generated nothing, or the relationship was never recorded), record `no generated top-level children — rollup skipped` and leave the PRD as `$TICKETED`; do not ship an empty PRD.
+##### 3f.3 Apply the terminal-state predicate
+For each top-level child, fetch its state + labels (already present from the GraphQL nodes, or `gh issue view <child-num> --json state,labels`) and classify per the `prd-lifecycle-rollup` GitHub predicate:
+- **Terminal (shipped).** The child issue is **CLOSED** *and* (where the build-status label is in use) carries the resolved build `done` role label (`status:done` by default). A child Epic is terminal only when it has itself rolled up to its own terminal state per `leaf-only-lifecycle` — read the child's own resolved state; do not re-derive it from its leaves here.
+- **Terminal-but-dropped.** The child is closed **as not planned** (`stateReason == "not_planned"`). It does not hold the PRD open and is excluded from the shipped set — treated like a won't-do leaf.
+- **Incomplete / blocked.** Anything else: still open, or closed without the `done` label. Holds the PRD open.
+The set of **required** children for the all-terminal check is the top-level children minus the terminal-but-dropped ones.
+##### 3f.4 Branch on the rollup verdict
+**All required children terminal** (every required top-level child is terminal; at least one required child exists):
+1. Transition labels: `gh issue edit <prd-num> --repo <org>/<repo> --remove-label "$TICKETED" --add-label "$SHIPPED"`. Verify exactly one lifecycle label remains (the single-label invariant).
+2. **If `$CLOSE_ON_SHIPPED` is `true`**, close the PRD issue: `gh issue close <prd-num> --repo <org>/<repo> --reason completed`. When `false`, leave it open.
+3. Post a short rollup comment naming the terminal child set and (when dropped children exist) the dropped set, so the audit trail records *why* the PRD shipped. Lead with `"Shipped by Claude — all generated top-level work is complete."`
+**Any required child incomplete / blocked**:
+1. Leave the PRD label as `$TICKETED` and leave the issue **open**. Do NOT add `$SHIPPED`. Do NOT close.
+2. Report the incomplete child set — both in the cycle summary and, when at least one cycle has previously ticketed this PRD, as a single advisory comment listing the still-open children (`- <ref> "<title>" — <state>`), so product can see what's blocking the rollup. Keep it idempotent: regenerate the advisory rather than appending a fresh one each cycle.
+##### 3f.5 Rollup is GitHub-only and cites the rule
+This phase only touches GitHub PRD issues. It implements exactly one PRD-lifecycle hop — `$TICKETED → $SHIPPED` — and the optional config-gated close that follows it. All terminal-state semantics, the generated-top-level-work boundary, the env-keyed `done` resolution, and the dedupe-by-child-ref idempotency come from the `prd-lifecycle-rollup` rule; this skill is its GitHub implementation, not a second source of truth.
 ### Phase 4 — Summary report
 ```text
@@ -257,6 +353,14 @@ PRDs processed: <n>
 - Errors (claim failed, etc): <n>
   - <issue-ref> "<title>" — <reason>
+Rollup (Phase 3f):
+- $SHIPPED: <n>
+  - <issue-ref> "<title>" → all <child-count> top-level children terminal (<dropped-count> dropped); closed: <yes|no (closeOnShipped off)>
+- Held open (incomplete children): <n>
+  - <issue-ref> "<title>" → <incomplete-count> of <child-count> top-level children still open
+- Already shipped (no-op): <n>
+- No generated children (rollup skipped): <n>
 Total tickets created: <n>
 Coverage audit summary: <n> COMPLETE / <n> COMPLETE_WITH_SCOPE_CREEP / <n> GAPS_FOUND
 ```
@@ -274,10 +378,11 @@ When the configured destination tracker is GitHub Issues AND the PRD repo is the
 ## Idempotency & safety
 - **Single-cycle scope**: this skill processes the ready set as it exists at the start of Phase 2. New ready issues added mid-cycle are picked up next run.
-- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:github-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes labels among `$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, only ever comments on the source PRD issue. It never edits PRD bodies, never touches `draft` or `shipped` labels, never closes or deletes PRD issues.
+- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:github-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes labels among `$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, `$SHIPPED`, only ever comments on the source PRD issue. It never edits PRD bodies and never touches the `draft` label. It sets the `$SHIPPED` label and may close the PRD issue **only** through the config-gated rollup phase (3f), and never deletes any issue.
 - **Claim-first ordering**: the label flip to `$IN_REVIEW` happens BEFORE validation runs.
 - **Failure isolation**: an exception processing one PRD must not stop the cycle. Catch, record under "Errors" in the summary, continue. The PRD that errored is left labeled `$IN_REVIEW` — humans investigate from there.
 - **Single-label invariant**: after every transition, verify exactly one lifecycle label is present.
+- **Rollup idempotency**: rollup (Phase 3f) is a no-op on a PRD already carrying `$SHIPPED` (and already closed when `closeOnShipped` is `true`) — no duplicate transition, no duplicate close, no duplicate comment. The all-terminal condition is a pure function of the children's current states, so recomputing it is safe to re-run. Closure NEVER precedes the all-terminal condition.
 ## Configuration
@@ -299,7 +404,8 @@ Destination tracker config (jira / github / linear) is consumed by `lisa:tracker
 ## Rules
 - Never write to the destination tracker outside of `lisa:github-to-tracker` → `lisa:tracker-write`.
-- Never add or remove a label this skill doesn't own (`$IN_REVIEW`, `$BLOCKED`, `$TICKETED`). Product owns the `draft`, `ready`, and `shipped` PRD labels.
+- Never add or remove a label this skill doesn't own (`$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, and `$SHIPPED` via the rollup phase only). Product owns the `draft` and `ready` PRD labels; product and the rollup phase (3f) both set `shipped`.
+- Set `$SHIPPED` (and close the PRD when `closeOnShipped` is configured) only from the rollup phase, and only when all generated top-level children are terminal per the `prd-lifecycle-rollup` rule. Never ship or close on partial completion.
 - Never edit a PRD's body. Communication with product happens only via comments.
 - Never post a single dump of all gate failures on one comment. One comment per `prd_anchor` group, plus one rollup for unanchored failures.
 - Never include a gate ID, internal skill name, or engineering shorthand in a comment body.

package/plugins/src/base/skills/prd-backlink/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: prd-backlink
-description: "Update a source PRD with a `## Tickets` section linking back to every work item created from it. Vendor-aware on the source side (Notion / Confluence / Linear / GitHub Issue / file) and tracker-agnostic on the ticket side. Idempotent — regenerates the section on each run rather than appending, so re-planning never accumulates stale links. Invoked by the *-to-tracker skills at the end of their pipeline and standalone if a PRD's Tickets section needs to be refreshed."
+description: "Update a source PRD with an always-written, machine-readable `## Tickets` (alias `## Generated Work`) section linking back to every work item created from it. Each entry carries a parseable ref + URL + type + parent token so the generated child set is readable without scraping prose. Vendor-aware on the source side (Notion / Confluence / Linear / GitHub Issue / file) and tracker-agnostic on the ticket side; the documented section is written for every vendor, additive to native hierarchy linking. Idempotent — regenerates the section on each run rather than appending, so re-planning never accumulates stale links. Invoked by the *-to-tracker skills at the end of their pipeline and standalone if a PRD's Tickets section needs to be refreshed."
 allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
 ---
@@ -8,6 +8,8 @@ allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
 Write or update the `## Tickets` section of a source PRD so it links to every work item created from that PRD. The Debrief flow (and a human reading the PRD months later) uses this section as the canonical work-item set for the initiative.
+This documented section is the **always-written, machine-readable record** of the generated child set. It is written for **every** `source_type` — including the vendors that also get a native hierarchy link (`github` / `linear` / `jira`) — so the generated top-level work is readable later from the PRD body alone, without parsing free-form comments or depending on a native relationship that may be unavailable on older hosts or across vendors. Native hierarchy linking (see the per-vendor sections below) is **additive** to this section, never a substitute for it. This is the documented-section leg of the `prd-lifecycle-rollup` rule (cited by slug; its taxonomy is not restated here).
 ## Input
 Pass `$ARGUMENTS` as a single JSON-style block:
@@ -31,8 +33,8 @@ Pass `$ARGUMENTS` as a single JSON-style block:
    - `linear` → Linear MCP project / issue read
    - `github` → `gh issue view`
    - `file` → `Read` tool on the absolute path
-2. **Locate the existing section.** Search for `section_heading` (default `## Tickets`). If present, you will replace it. If not, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.
-3. **Render the section.** Use the format below. Group by Epic. Within an Epic, group by Story. Sub-tasks nest under their Story. Bugs and Spikes that are not under a Story go in a flat list at the bottom.
+2. **Locate the existing section.** Search for `section_heading` (default `## Tickets`). The canonical heading is `## Tickets`; `## Generated Work` is an accepted alias that the reader recognizes — match either heading when locating an existing section so a PRD authored with either name is found and regenerated in place (never duplicated under the other name). If present under either name, you will replace it (keeping whichever heading was already there, or the explicit `section_heading` override). If not present, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.
+3. **Render the section.** Always render it — for every `source_type`, even when a native hierarchy link was also made (additive, not exclusive). Use the format below. Group by Epic. Within an Epic, group by Story. Sub-tasks nest under their Story. Bugs and Spikes that are not under a Story go in a flat list at the bottom. Each entry carries a machine-readable token (ref + URL + type + parent) so the generated child set is parseable without reading prose — see [Format](#format).
 4. **Write the updated PRD back** using the source's native write tool:
    - `notion` → `notion-update-page`
    - `confluence` → `updateConfluencePage`
@@ -49,7 +51,7 @@ Pass `$ARGUMENTS` as a single JSON-style block:
 ## Format
-The rendered section must be deterministic — same inputs produce identical output bytes. This is what makes idempotency reliable.
+The rendered section must be deterministic — same inputs produce identical output bytes. This is what makes idempotency reliable. Every entry is simultaneously **human-readable** (a nested markdown link) and **machine-readable** (a trailing structured token), so the generated child set can be enumerated by parsing this section alone — the contract LPC-1.3 rollup (`github-prd-intake` / `*-prd-intake`) reads against, with no need to scrape free-form comments.
 ```markdown
 ## Tickets
@@ -58,28 +60,45 @@ _Generated by `lisa:prd-backlink`. Regenerated on every Plan run; do not edit by
 ### <Epic key>: <Epic title>
-- [<Epic key>](<url>) — Epic
-  - [<Story key>](<url>) — Story: <title>
-    - [<Sub-task key>](<url>) — Sub-task: <title>
-    - [<Sub-task key>](<url>) — Sub-task: <title>
-  - [<Story key>](<url>) — Story: <title>
+- [<Epic key>](<url>) — Epic <!-- lisa:gw ref=<ref> url=<url> type=Epic parent= -->
+  - [<Story key>](<url>) — Story: <title> <!-- lisa:gw ref=<ref> url=<url> type=Story parent=<Epic ref> -->
+    - [<Sub-task key>](<url>) — Sub-task: <title> <!-- lisa:gw ref=<ref> url=<url> type=Sub-task parent=<Story ref> -->
+    - [<Sub-task key>](<url>) — Sub-task: <title> <!-- lisa:gw ref=<ref> url=<url> type=Sub-task parent=<Story ref> -->
+  - [<Story key>](<url>) — Story: <title> <!-- lisa:gw ref=<ref> url=<url> type=Story parent=<Epic ref> -->
 ### <Epic key>: <Epic title>
 ...
 ### Unparented items
-- [<Bug key>](<url>) — Bug: <title>
-- [<Spike key>](<url>) — Spike: <title>
+- [<Bug key>](<url>) — Bug: <title> <!-- lisa:gw ref=<ref> url=<url> type=Bug parent= -->
+- [<Spike key>](<url>) — Spike: <title> <!-- lisa:gw ref=<ref> url=<url> type=Spike parent= -->
+```
+### Machine-readable entry token
+Every list entry ends with a single-line HTML comment — invisible in rendered markdown, so the section stays clean for humans, but a stable, greppable record for machines:
+```text
+<!-- lisa:gw ref=<ref> url=<url> type=<type> parent=<parent-ref or empty> -->
 ```
-If the input contains zero items, write the section header with a single line: `_No tickets created — Plan flow may not have completed._` Do not omit the section; presence-of-section is itself a signal to Debrief.
+- **`lisa:gw`** — a fixed sentinel (`gw` = generated work). A reader enumerates the generated child set by matching `<!-- lisa:gw ` lines; it never has to parse the surrounding prose, headings, or indentation.
+- **`ref`** — the child-ref identity from the `prd-lifecycle-rollup` rule: `<org>/<repo>#<n>` for GitHub, the issue/project identifier (e.g. `TEAM-123`) for Linear, the issue key (e.g. `PROJ-123`) for JIRA. This is the same dedupe key native linking uses, so the documented record and the native record agree.
+- **`url`** — the canonical URL of the work item.
+- **`type`** — `Epic | Story | Task | Sub-task | Bug | Spike` (verbatim from the ticket's `type`).
+- **`parent`** — the **`ref`** of this entry's parent (its `parent_key` resolved to the parent's ref), or **empty** when the entry is top-level (`parent_key` null/empty). A reader selects the **generated top-level child set** — exactly what the PRD owns per the rule — as every `lisa:gw` line whose `parent` is empty.
+The visible markdown link and the token always carry the same `ref`/`url`/`type`; the token is the authoritative machine field (the prose may wrap or be reflowed by a host editor, the comment line will not). Field order within the token is fixed (`ref`, `url`, `type`, `parent`) so output is byte-stable.
+If the input contains zero items, write the section header with a single line: `_No tickets created — Plan flow may not have completed._` Do not omit the section; presence-of-section is itself a signal to Debrief, and the always-written guarantee means a reader can always distinguish "ran, produced nothing" from "never ran."
 ## Idempotency
 Rendering rules:
-- Sort epics by key (lexical). Sort stories within an epic by key. Sort sub-tasks within a story by key. Sort the unparented list by `(type, key)`.
+- Sort epics by key (lexical). Sort stories within an epic by key. Sort sub-tasks within a story by key. Sort the unparented list by `(type, key)`. The same sort applies to the `lisa:gw` tokens (each token sits on its entry's line), so the machine-readable order is identical across runs.
 - The line `_Generated by ..._` is fixed text — does not include a timestamp. A timestamp would defeat the diff-equality check Debrief relies on.
+- Regenerate the whole section from the current ticket set on every run — **never append**. Dedupe is by **child-ref** (the token's `ref`, per the `prd-lifecycle-rollup` idempotency dedupe key): the same ticket set produces a byte-identical section with no duplicate entries, and re-running over an existing section is a no-op diff. A ticket present in a prior run but absent now simply does not reappear (stale links never accumulate).
 ## Native parent linking (GitHub)
@@ -242,4 +261,4 @@ Omit the `Native parent links` line when no native linking applies (Notion / Con
 ## Related rules
-- `prd-lifecycle-rollup` — the vendor-neutral source of truth for PRD→generated-top-level-work ownership, the per-vendor terminal predicate, PRD `shipped` rollup, and the child-ref idempotency dedupe key. This skill implements the GitHub, Linear, and JIRA native-linking legs of that rule; it cites the rule by slug rather than restating its taxonomy.
+- `prd-lifecycle-rollup` — the vendor-neutral source of truth for PRD→generated-top-level-work ownership, the per-vendor terminal predicate, PRD `shipped` rollup, and the child-ref idempotency dedupe key. This skill implements both the **documented always-written, machine-readable generated-work section** leg (the universal fallback written for every vendor) and the GitHub, Linear, and JIRA native-linking legs of that rule; it cites the rule by slug rather than restating its taxonomy.