@codyswann/lisa 2.119.1 → 2.121.1

package/plugins/lisa-copilot/skills/plugin-sync-explain/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: plugin-sync-explain
+description: "Read-only diagnostic for Lisa plugin source/generated drift. Compares plugins/src against generated plugins/lisa* status, reports source-not-built, generated-only, and marketplace registration drift, and preserves the working tree."
+allowed-tools: ["Bash", "Read"]
+---
+
+# Plugin Sync Explain: $ARGUMENTS
+
+`/lisa:plugin-sync-explain` explains why the plugin sync gate would need attention without mutating the working tree.
+
+## Scope
+
+Inspect the current Lisa repository, or an optional path passed as `$ARGUMENTS`, using `scripts/plugin-sync-explain.mjs`.
+
+The diagnostic is **read-only**:
+
+- Do not run `bun run build:plugins`.
+- Do not run `bun run check:plugins`.
+- Do not edit source files, generated plugin artifacts, or `.claude-plugin/marketplace.json`.
+- Do not stash, commit, reset, or clean local changes.
+
+## What to Report
+
+Report a concise terminal-first summary with stable classifications:
+
+- `SOURCE_NOT_BUILT`: files under `plugins/src/**` changed without their generated `plugins/lisa*` counterpart.
+- `GENERATED_ONLY`: files under `plugins/lisa*` changed without their `plugins/src/**` source counterpart.
+- `MARKETPLACE_REGISTRATION_DRIFT`: a built plugin directory is missing from `.claude-plugin/marketplace.json`, or a marketplace source points at a missing built directory.
+- `OUT_OF_SYNC`: source and generated counterparts both changed and need human review.
+- `IN_SYNC`: no plugin source/generated or marketplace registration drift was detected.
+
+For every finding, include the evidence path and the smallest source-first next action. Prefer `bun run build:plugins` only after source edits are in the right place, and preserve `bun run check:plugins` as the final reproducibility gate.
+
+## Process
+
+1. Resolve the repo path from `$ARGUMENTS` or the current directory.
+2. Capture `git status --porcelain` before the diagnostic.
+3. Run:
+   ```bash
+   node plugins/lisa/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+   If running from the source tree before generated artifacts are rebuilt, use:
+   ```bash
+   node plugins/src/base/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+4. Capture `git status --porcelain` after the diagnostic and confirm it is unchanged.
+5. Surface the script output plus the read-only confirmation.
+
+## Rules
+
+- Keep this surface aligned with `scripts/check-plugins-sync.sh`; it explains the gate but does not replace it.
+- Treat `plugins/src/**` as the source of truth and `plugins/lisa*` as generated artifacts.
+- If the diagnostic cannot inspect git status or marketplace JSON, report the error plainly and do not guess.

package/plugins/lisa-copilot/skills/prd-backlink/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: prd-backlink
+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"]
+---
+
+# PRD Back-link
+
+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:
+
+```json
+{
+  "source_type": "notion" | "confluence" | "linear" | "github" | "file",
+  "source_ref": "<URL, page id, project id, issue ref, or absolute file path>",
+  "tickets": [
+    { "key": "<tracker-key>", "title": "<summary>", "type": "Epic|Story|Task|Sub-task|Bug|Spike", "url": "<link>", "parent_key": "<key or null>" }
+  ],
+  "section_heading": "## Tickets"   // optional override; default "## Tickets"
+}
+```
+
+## Behaviour
+
+1. **Fetch the current PRD content** using the source's native read tool:
+   - `notion` → `notion-fetch`
+   - `confluence` → `getConfluencePage`
+   - `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`). 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`
+   - `linear` → Linear MCP update
+   - `github` → `gh issue edit --body`
+   - `file` → `Edit` (preferred) or `Write` (full rewrite if needed)
+5. **Record the PRD→child relationship in the source tool's native hierarchy** where the source supports it and the destination tracker is the same system. Each supported source has its own native-linking section, all governed by the same generated-top-level-work contract, child-ref idempotency, and graceful-degradation discipline from the `prd-lifecycle-rollup` rule:
+   - `github` (same repo as the created tickets) → native GitHub **sub-issue** of the PRD issue — see [Native parent linking (GitHub)](#native-parent-linking-github).
+   - `linear` (PRD also lives in Linear) → native **parent / project** relationship — see [Native parent linking (Linear)](#native-parent-linking-linear).
+   - `jira` (PRD also lives in the same JIRA/Atlassian instance) → native **parent / Epic link** or a documented **issue-link type** — see [Native parent linking (JIRA)](#native-parent-linking-jira).
+
+   The documented `## Tickets` section from step 3 is always written regardless; native linking is **in addition to** it, not a replacement (the documented section is the cross-vendor and older-host fallback per the `prd-lifecycle-rollup` rule). Sources without native issue hierarchy (Notion, Confluence, file) rely on the documented section alone, as does any cross-vendor combination (e.g. a Notion PRD with a JIRA tracker).
+6. **Return** the rendered section (so the caller can include it in its own report) and the source URL of the updated PRD.
+
+## Format
+
+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
+
+_Generated by `lisa:prd-backlink`. Regenerated on every Plan run; do not edit by hand._
+
+### <Epic key>: <Epic 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> <!-- 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> -->
+```
+
+- **`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)`. 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).
+- **Match by stable ref, never by title** (`prd-lifecycle-rollup` idempotency dedupe key). A child is identified by its `ref` token alone — a ticket whose `title` changed but whose `ref` is unchanged is the **same** entry: its displayed title is refreshed in place and it appears exactly once, never duplicated. Title is rendered, never matched on.
+
+## Native parent linking (GitHub)
+
+When `source_type: github` **and** the PRD issue lives in the same repository as the created tickets, make the PRD the structural parent of the work it generated by linking each generated top-level work item as a native GitHub **sub-issue** of the PRD issue. This is the GitHub leg of the PRD→child native-hierarchy requirement in the `prd-lifecycle-rollup` rule (cite it by slug; do not restate its taxonomy here). The documented `## Tickets` section is still written either way — native linking is the first-class relationship; the documented section is the durable fallback for cross-vendor and older hosts.
+
+This section is GitHub-only. The Linear and JIRA native parents have their own sections below ([Linear](#native-parent-linking-linear), [JIRA](#native-parent-linking-jira)); the documented-section-only fallback for Notion / Confluence / file / cross-vendor sources is governed by the `prd-lifecycle-rollup` rule and is out of scope for this GitHub section.
+
+### What gets linked — generated top-level work only
+
+Per the `prd-lifecycle-rollup` "generated top-level work" contract, the PRD owns **only** its generated top-level work as direct children:
+
+- A ticket is **top-level** when its `parent_key` is null/empty — these are the created Epic(s) and any top-level Story created directly under the PRD. Link these as sub-issues of the PRD.
+- A ticket with a non-null `parent_key` is a **descendant** (a Story under an Epic, or a leaf Sub-task) — it is owned by its own top-level parent, **never** linked directly to the PRD. Leaf Sub-tasks are explicitly NOT direct PRD children (PRD #525 non-goal).
+
+So if the PRD generated `Epic E1 → Story S1 → Sub-task T1`, only `E1` becomes a sub-issue of the PRD; `S1` is a sub-issue of `E1` and `T1` of `S1` (those links were already made by the write path), and neither `S1` nor `T1` is a direct child of the PRD.
+
+### Same-repo guard
+
+Native sub-issue linking only applies when the PRD and the work item are in the same repository. Parse `owner/repo` from `source_ref` (the PRD URL or `<org>/<repo>#<n>` token) and from each top-level ticket's `key`/`url`. Skip native linking for any ticket whose repo differs from the PRD's repo (cross-repo or cross-vendor) — record those in the documented section only. The cross-vendor case (e.g. a GitHub PRD with a JIRA/Linear tracker) never reaches this path because the ticket is not a GitHub issue.
+
+### Idempotency — dedupe by child-ref
+
+The dedupe key is **child-ref identity** (`owner/repo#number`), per the `prd-lifecycle-rollup` idempotency rule. Before adding any link, read the PRD's current sub-issues and skip any child already linked, so re-running `prd-backlink` never creates duplicate sub-issue links and is a no-op when everything is already linked.
+
+1. **Read the PRD's existing sub-issues** (same GraphQL `subIssues` query `lisa:github-read-issue` Phase 3 uses), and build the set of already-linked child refs:
+
+   ```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 repository{nameWithOwner}}}}}}' \
+     -F org=<prd_org> -F repo=<prd_repo> -F number=<prd_number> \
+     --jq '.data.repository.issue.subIssues.nodes[] | "\(.repository.nameWithOwner)#\(.number)"'
+   ```
+
+   The resulting `owner/repo#number` strings are the existing child-ref set.
+
+2. **For each generated top-level ticket** in the same repo whose child-ref is **not** already in that set, resolve node IDs and call `addSubIssue` (the same mutation `lisa:github-write-issue` Phase 6 step 3 uses):
+
+   ```bash
+   prd_id=$(gh api graphql -f query='query($org:String!,$repo:String!,$number:Int!){repository(owner:$org,name:$repo){issue(number:$number){id}}}' -F org=<prd_org> -F repo=<prd_repo> -F number=<prd_number> --jq '.data.repository.issue.id')
+   child_id=$(gh api graphql -f query='query($org:String!,$repo:String!,$number:Int!){repository(owner:$org,name:$repo){issue(number:$number){id}}}' -F org=<org> -F repo=<repo> -F number=<child_number> --jq '.data.repository.issue.id')
+   gh api graphql -f query='mutation($parentId:ID!,$childId:ID!){addSubIssue(input:{issueId:$parentId,subIssueId:$childId}){issue{number}subIssue{number}}}' -F parentId="$prd_id" -F childId="$child_id"
+   ```
+
+   A child already in the existing-sub-issue set is a no-op — do not call the mutation for it.
+
+### Graceful degradation
+
+- **Already linked.** Covered by the dedupe read above (no mutation issued). If a concurrent run linked it between the read and the mutation, GitHub rejects the duplicate — treat that rejection as success (the desired end state already holds), not a failure.
+- **Mutation unavailable** (older GHES, sub-issues feature off, or the `addSubIssue`/`subIssues` fields are missing). Fall back to the documented `## Tickets` section only and surface a warning to the caller (`native sub-issue linking unavailable — documented section written`). Never silently drop the relationship and never abort the run — the documented section is the contract that always lands.
+
+## Native parent linking (Linear)
+
+When `source_type: linear` **and** the PRD also lives in Linear (same workspace as the created work items), make the PRD the structural parent of the work it generated using Linear's native **parent / project** relationship. This is the Linear leg of the PRD→child native-hierarchy requirement in the `prd-lifecycle-rollup` rule (cite it by slug; do not restate its taxonomy here). The documented `## Tickets` section is still written either way — native linking is the first-class relationship; the documented section is the durable fallback for cross-vendor and older hosts.
+
+This section is Linear-only. The GitHub and JIRA native parents have their own sections; the documented-section-only fallback for Notion / Confluence / file / cross-vendor sources is out of scope here.
+
+### Which Linear primitive — PRD shape decides
+
+Linear models top-level grouping two ways, and the PRD's own entity type decides which native relationship to use:
+
+- **PRD is a Linear Project** (the common case — a PRD project groups its generated work). Generated top-level **Issues** are attached to the PRD by setting their `projectId` to the PRD Project's id. The Project *is* the native parent of its Issues; no separate parent-issue link is needed.
+- **PRD is a Linear Issue** (a parent issue, not a project). Generated top-level Issues are attached as native **sub-Issues** of the PRD Issue by setting their `parentId` to the PRD Issue's id.
+
+Either way the write surface is `mcp__linear-server__save_issue` with the single relevant field (`projectId` or `parentId`) — the same primitive `lisa:linear-write-issue` uses to set a Story's `projectId` (Epic Project) and a Sub-task's `parentId` (Story Issue). Send **only** that field on update; Linear treats `save_issue` as a full overwrite of the fields named (`lisa:linear-write-issue` Phase 6 UPDATE), so resending other fields would clobber them.
+
+### What gets linked — generated top-level work only
+
+Per the `prd-lifecycle-rollup` "generated top-level work" contract, the PRD owns **only** its generated top-level work as direct children:
+
+- A work item is **top-level** when its `parent_key` is null/empty — these are the created Epic(s) (Linear Projects) and any top-level Story (Linear Issue) created directly under the PRD. Attach these to the PRD via `projectId`/`parentId`.
+- A work item with a non-null `parent_key` is a **descendant** (a Story under an Epic Project, or a leaf Sub-task) — it is owned by its own top-level parent, **never** linked directly to the PRD. Leaf Sub-tasks are explicitly NOT direct PRD children (PRD #525 non-goal); their `parentId` already points at their Story (set by the write path), and overwriting it to point at the PRD would break that hierarchy.
+
+So if the PRD generated `Epic E1 (Project) → Story S1 (Issue) → Sub-task T1 (sub-Issue)`, only the top-level unit is attached to the PRD; `S1` already carries `projectId = E1` and `T1` already carries `parentId = S1` (set by the write path), and neither `S1` nor `T1` is a direct child of the PRD.
+
+### Idempotency — dedupe by child-ref
+
+The dedupe key is **child-ref identity** — the Linear issue/project identifier (e.g. `TEAM-123`) or its UUID — per the `prd-lifecycle-rollup` idempotency rule. Before attaching any child, read the PRD's current children and skip any child already attached, so re-running `prd-backlink` never duplicates a relationship and is a no-op when everything is already attached.
+
+1. **Read the PRD's existing children** (the same reads `lisa:linear-read-issue` uses for Project members and sub-Issues):
+   - PRD-as-Project → `mcp__linear-server__list_issues({project: <prd_project_id>})` and collect each member Issue's identifier/UUID.
+   - PRD-as-Issue → `mcp__linear-server__get_issue({id: <prd_issue_id>})` and collect its sub-Issue identifiers/UUIDs.
+
+   The resulting identifiers/UUIDs are the existing child-ref set.
+
+2. **For each generated top-level item** whose child-ref is **not** already in that set, attach it with a single-field `save_issue`:
+   - PRD-as-Project → `mcp__linear-server__save_issue({id: <child_id>, projectId: <prd_project_id>})`.
+   - PRD-as-Issue → `mcp__linear-server__save_issue({id: <child_id>, parentId: <prd_issue_id>})`.
+
+   A child already in the existing-children set is a no-op — do not issue the `save_issue` call for it. Reading the child's current `projectId`/`parentId` and finding it already equal to the PRD's id is the same no-op (attaching to the value it already holds changes nothing).
+
+### Graceful degradation
+
+- **Already attached.** Covered by the dedupe read above (no write issued). If a concurrent run attached it between the read and the write, re-setting the same `projectId`/`parentId` is harmless (the desired end state already holds) — treat it as success, not a failure.
+- **No native hierarchy / cross-vendor.** If the PRD is not itself a Linear entity (cross-vendor — e.g. a Notion PRD with a Linear tracker, which reaches this skill as `source_type: notion`, not `linear`), or the workspace/team does not expose the relationship, this is a clean **no-op**: fall back to the documented `## Tickets` section only and surface a warning to the caller (`native Linear parent linking unavailable — documented section written`). Never silently drop the relationship and never abort the run — the documented section is the contract that always lands.
+
+## Native parent linking (JIRA)
+
+When `source_type: jira` **and** the PRD also lives in the same JIRA/Atlassian instance as the created tickets, make the PRD the structural parent of the work it generated using JIRA's native **parent / Epic link**, or — where the instance does not allow an Epic/Story to be a child of the PRD's issue type — a documented **issue-link type** (e.g. `relates to`). This is the JIRA leg of the PRD→child native-hierarchy requirement in the `prd-lifecycle-rollup` rule (cite it by slug; do not restate its taxonomy here). The documented `## Tickets` section is still written either way — native linking is the first-class relationship; the documented section is the durable fallback for cross-vendor and older hosts.
+
+This section is JIRA-only. The GitHub and Linear native parents have their own sections; the documented-section-only fallback for Notion / Confluence / file / cross-vendor sources is out of scope here.
+
+### Which JIRA primitive — native parent first, issue-link fallback
+
+JIRA's hierarchy support varies by instance and issue-type scheme, so prefer the strongest relationship the instance allows:
+
+1. **Native parent / Epic link (preferred).** If the PRD's issue type can be a parent of the generated top-level type in the instance's hierarchy (e.g. the PRD is a parent-level issue and the generated work is Epics/Stories beneath it), set the generated top-level issue's **parent** to the PRD — the same parent/Epic-link surface `lisa:jira-write-ticket` uses to set a Story's epic parent (Phase 4a + Phase 6 CREATE). Use `lisa:atlassian-access` `operation: write-ticket payload: {key: <child>, parent: <prd_key>}` (send only the parent field on update so other fields are preserved — `lisa:jira-write-ticket` Phase 6 UPDATE).
+2. **Documented issue-link type (fallback).** If the instance's hierarchy does not allow the PRD to parent the generated type (common when both are Epics, or the PRD is itself an Epic and Epics cannot nest), create a native **issue link** of a documented type instead — `lisa:atlassian-access` `operation: link from: <prd_key> to: <child_key> type: "<link-type>"` — the same link surface `lisa:jira-write-ticket` Phase 6 step 3 uses for `blocks` / `relates to` / etc. Use the project's configured PRD→work link type (default `relates to`); surface an error if an unknown type is passed rather than inventing one.
+
+Choosing between (1) and (2) is per the instance's capability — never invent a parent relationship the issue-type scheme rejects, and never silently downgrade without recording which relationship was used.
+
+### What gets linked — generated top-level work only
+
+Per the `prd-lifecycle-rollup` "generated top-level work" contract, the PRD owns **only** its generated top-level work as direct children:
+
+- A ticket is **top-level** when its `parent_key` is null/empty — these are the created Epic(s) and any top-level Story created directly under the PRD. Attach these to the PRD via the native parent or the documented issue-link type.
+- A ticket with a non-null `parent_key` is a **descendant** (a Story under an Epic, or a leaf Sub-task) — it is owned by its own top-level parent, **never** linked directly to the PRD. Leaf Sub-tasks are explicitly NOT direct PRD children (PRD #525 non-goal); their parent already points at their Story/Epic (set by the write path), and re-parenting them to the PRD would break that hierarchy.
+
+So if the PRD generated `Epic E1 → Story S1 → Sub-task T1`, only `E1` is attached to the PRD; `S1` already carries its epic parent `E1` and `T1` its parent `S1` (set by the write path), and neither `S1` nor `T1` is a direct child of the PRD.
+
+### Idempotency — dedupe by child-ref
+
+The dedupe key is **child-ref identity** — the JIRA issue key (e.g. `PROJ-123`) — per the `prd-lifecycle-rollup` idempotency rule. Before attaching any child, read the PRD's current children/links and skip any child already attached, so re-running `prd-backlink` never duplicates a parent assignment or issue link and is a no-op when everything is already attached.
+
+1. **Read the PRD's existing children and links** (the same reads `lisa:jira-read-ticket` uses):
+   - Native-parent path → enumerate the PRD's children via the epic-link/parent JQL `lisa:jira-read-ticket` Phase 5 uses (`"Epic Link" = <PRD-KEY>` or `parent = <PRD-KEY>`), and collect their keys.
+   - Issue-link path → read the PRD's `issuelinks` (`lisa:jira-read-ticket` Phase 4) and collect the keys already linked with the configured PRD→work link type.
+
+   The resulting issue keys are the existing child-ref set.
+
+2. **For each generated top-level ticket** whose key is **not** already in that set, attach it via the chosen primitive:
+   - Native-parent → `lisa:atlassian-access` `operation: write-ticket payload: {key: <child>, parent: <prd_key>}`.
+   - Issue-link → `lisa:atlassian-access` `operation: link from: <prd_key> to: <child> type: "<link-type>"`.
+
+   A child already in the existing-children/links set is a no-op — do not issue the write/link for it.
+
+### Graceful degradation
+
+- **Already attached.** Covered by the dedupe read above (no write issued). If a concurrent run attached it between the read and the write, JIRA either no-ops the identical parent assignment or rejects the duplicate link — treat that as success (the desired end state already holds), not a failure.
+- **No native hierarchy / cross-vendor.** If the PRD is not itself a JIRA issue (cross-vendor — e.g. a Notion or Confluence PRD with a JIRA tracker, which reaches this skill as `source_type: notion`/`confluence`, not `jira`), or neither a native parent nor a documented issue-link type is available in the instance, this is a clean **no-op**: fall back to the documented `## Tickets` section only and surface a warning to the caller (`native JIRA parent linking unavailable — documented section written`). Never silently drop the relationship and never abort the run — the documented section is the contract that always lands.
+
+## Failures
+
+- **Source unreachable / permission denied.** Stop and report. Do not silently swallow.
+- **Section already present but in a non-standard format** (e.g., user hand-edited it). Replace it anyway — the warning line `_do not edit by hand_` is the contract. Note in the run output that an existing section was overwritten.
+- **Source is a Notion database URL, a Confluence space URL, or any other non-page input.** Stop — back-linking only makes sense against a single PRD page, not a queue. Direct the caller to pass the specific page.
+
+## Output
+
+```text
+PRD back-link updated: <source_url>
+Section: ## Tickets — <n> epics, <n> stories, <n> sub-tasks, <n> unparented (<bugs/spikes>)
+Native parent links: <n> linked, <n> already linked (<vendor> native hierarchy; documented section is the fallback)
+```
+
+The `Native parent links` line reports whichever vendor's native linking ran:
+- **GitHub** (same-repo PRD) → sub-issues via `addSubIssue`.
+- **Linear** (PRD in Linear) → `projectId`/`parentId` attachments via `save_issue`.
+- **JIRA** (PRD in JIRA) → native parent / Epic link, or documented issue-link type.
+
+Omit the `Native parent links` line when no native linking applies (Notion / Confluence / file source, or any cross-vendor combination — documented section only). If native linking was attempted but unavailable for the vendor, replace the counts with the degradation warning from that vendor's Graceful degradation subsection.
+
+## 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 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-copilot/skills/prd-source-write/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: prd-source-write
+description: "Vendor-neutral wrapper for creating (or idempotently updating) a PRD in the configured PRD source. The PRD-side sibling of lisa:tracker-write. Resolves `source` from .lisa.config.local.json first (then .lisa.config.json — local overrides global) and dispatches to lisa:notion-write-prd, lisa:confluence-write-prd, lisa:github-write-prd, or lisa:linear-write-prd. Callers (notably lisa:research) MUST invoke this skill instead of a vendor PRD writer directly — that is what makes the PRD source switchable per project. Accepts an `initial_role` of `draft` (default) or `ready` so a freshly created PRD either waits for human promotion or is immediately picked up by lisa:intake; and a stable dedupe marker so re-runs reference the existing PRD instead of creating a duplicate. The PRD lives in the source — there is no separate document artifact."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# PRD Source Write: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured PRD `source` and delegates to the matching vendor PRD
+writer, which owns the concrete create/update, the lifecycle-role application, and the marker-based
+dedupe. When the supplied PRD body already contains the canonical `## Lisa Usage` ledger, the
+vendor writer must preserve that managed section on update instead of dropping it or reformatting it
+ad hoc. This skill only routes — it never talks to a source API itself.
+
+See the `config-resolution` rule for the full configuration schema and the PRD lifecycle roles.
+
+## Input contract
+
+Callers pass a single structured spec:
+
+```yaml
+operation: create_or_update          # the only operation; create unless the marker already exists
+title: "<PRD title>"
+body: "<full PRD markdown — the entire spec>"
+initial_role: draft | ready          # default: draft. ready = picked up by lisa:intake's PRD scan
+dedupe_key: "<stable-key>"           # e.g. project-ideation's idea key
+marker: "[lisa-project-ideation] idea=<stable-key>"   # embedded in the PRD body for dedupe
+origin: { tool: project-ideation | research | manual }
+source_ref: "<optional existing PRD ref to force an update>"
+ideation_ledger_payload:              # optional; forwarded unchanged to the vendor writer
+  selected_marker: "<same value as marker>"
+  automation_id: "<Codex/Claude automation id or unavailable>"
+  automation_memory_path: "<path or unavailable>"
+  repo: "<org>/<repo or detected repo identity>"
+  prd_ready: true|false
+  persona_names: ["<derived persona name>"]
+  persona_evidence_refs: ["<file/doc/table/release ref>"]
+  selected_idea: "<selected idea title/key>"
+  rejected_overlap_candidates: ["<issue refs/titles considered and rejected>"]
+  expected_empirical_verification_artifact: "<artifact ref or unavailable>"
+```
+
+`initial_role` semantics are uniform across vendors (the role STRINGS resolve per vendor from
+`config-resolution`):
+
+- **`draft`** (default) → the PRD is created in the source's `draft` PRD role. It waits for a human
+  (or a later `ready` promotion) before any intake claims it.
+- **`ready`** → the PRD is created in the source's `ready` PRD role (`prd-ready`), so the PRD-side of
+  `lisa:intake` / the `*-prd-intake` scanner auto-claims it on the next cycle.
+
+There is no "omitted = legacy behavior" mode (unlike the ticket-side `build_ready`): there was no
+prior PRD-source-write behavior to preserve, so omitted means `draft`.
+
+## Workflow
+
+1. **Resolve the source.** Read `.lisa.config.local.json` first (if present), then
+   `.lisa.config.json`. Local overrides global per key. Use `jq` — never hand-parse JSON.
+
+   ```bash
+   local_source=$(jq -r '.source // empty' .lisa.config.local.json 2>/dev/null)
+   global_source=$(jq -r '.source // empty' .lisa.config.json 2>/dev/null)
+   source="${local_source:-${global_source}}"
+   if [ -z "$source" ]; then
+     echo "Error: 'source' is not set in .lisa.config.json. A PRD source (notion / confluence / github / linear) is required to create a PRD. Run /lisa:setup:notion (or :confluence, :github, :linear)." >&2
+     exit 1
+   fi
+   ```
+
+2. **Validate the value and dispatch** (pass the spec verbatim):
+
+   - `notion` → confirm `notion.workspaceId` and `notion.prdDatabaseId` are present, then invoke
+     `lisa:notion-write-prd`.
+   - `confluence` → confirm `atlassian.cloudId` and (`confluence.spaceKey` or
+     `confluence.parents.draft`/`.ready`) are present, then invoke `lisa:confluence-write-prd`.
+   - `github` → confirm `github.org` and `github.repo` are present, then invoke
+     `lisa:github-write-prd`.
+   - `linear` → confirm `linear.workspace` (and team for project placement) is present, then invoke
+     `lisa:linear-write-prd`.
+   - `jira` → **stop and fail loudly**: `"source=jira is not a supported PRD source — config-resolution defines no JIRA PRD lifecycle roles. Use notion / confluence / github / linear, or set source accordingly."` (JIRA is a destination tracker, not a PRD source.)
+   - Any other value (including `file`) → stop and report: `"Unknown PRD source '<value>'. Expected one of: notion, confluence, github, linear."`
+
+3. **Surface the vendor writer's output unchanged.** It returns the created/reused PRD ref + URL,
+   the applied role (`draft`/`ready`), the dedupe marker, and whether it was created or reused.
+   Downstream callers (research, project-ideation) parse this — do not paraphrase.
+
+When `ideation_ledger_payload` is present, this shim still does not render or interpret it. Forward
+the object verbatim to the selected vendor writer so source-specific rendering remains behind the
+configured writer and the dispatch layer never bypasses source selection.
+
+## Rules
+
+- Never bypass dispatch — a vendor-neutral caller calling a `*-write-prd` skill directly defeats the
+  per-project source switch (exactly the `tracker-write` discipline, mirrored).
+- Never drop or duplicate an existing managed `## Lisa Usage` section. Writer-specific preservation
+  and fallback behavior belongs in the vendor writers and follows the `usage-accounting` contract.
+- Never accept a source outside `{notion, confluence, github, linear}`. `jira` and `file` fail loudly.
+- Never mutate the spec between layers. The vendor writers define their own create/dedupe contract.
+- Never drop, rename, or vendor-render `ideation_ledger_payload`; it is a pass-through payload for
+  the configured writer.
+- Never invent a PRD lifecycle role string — resolve every role from `config-resolution` per vendor.
+- Idempotency is the vendor writer's job (marker search before create); this shim only routes.

package/plugins/lisa-copilot/skills/prd-ticket-coverage/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: prd-ticket-coverage
+description: "Verifies that every requirement in a PRD (Notion, Confluence, Linear, or GitHub Issues) is covered by at least one created destination ticket (JIRA, GitHub Issues, or Linear) — no silent drops. Parses the PRD into atomic items (goals, user stories, functional/non-functional requirements, acceptance criteria, important notes), maps each to the created tickets, and produces a coverage matrix and verdict (COMPLETE / COMPLETE_WITH_SCOPE_CREEP / GAPS_FOUND / NO_TICKETS_FOUND). Used by notion-prd-intake / confluence-prd-intake / linear-prd-intake / github-prd-intake post-write to gate the Ticketed transition; can also be invoked standalone for after-the-fact audits."
+allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-get-comments", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluencePageDescendants", "mcp__atlassian__getConfluencePageFooterComments", "mcp__atlassian__getConfluencePageInlineComments", "mcp__atlassian__getConfluenceCommentChildren", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__linear-server__get_project", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_comments"]
+---
+
+# PRD Ticket Coverage Audit: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A PRD URL alone — auto-discover created tickets via the PRD's epic remote link.
+2. A PRD URL plus an explicit list of ticket keys — `<PRD URL> tickets=[KEY-1,KEY-2,...]`. Use this when called from `lisa:notion-prd-intake` or `lisa:confluence-prd-intake` (which know the keys they just created).
+
+The PRD URL can be a **Notion page URL**, a **Confluence page URL**, a **Linear project URL**, or a **GitHub issue URL**. Detect the vendor from the host:
+
+- `notion.so` / `notion.site` → Notion. Fetch with `mcp__claude_ai_Notion__notion-fetch` (`include_discussions: true`) and `mcp__claude_ai_Notion__notion-get-comments`.
+- Atlassian Confluence host (e.g. `*.atlassian.net/wiki/...`) → Confluence. Fetch with `mcp__atlassian__getConfluencePage`, `mcp__atlassian__getConfluencePageDescendants` (for child epic pages), `mcp__atlassian__getConfluencePageFooterComments`, `mcp__atlassian__getConfluencePageInlineComments`, and `mcp__atlassian__getConfluenceCommentChildren` for nested replies.
+- `linear.app` host → Linear. Fetch with `mcp__linear-server__get_project` (capture description, labels, state, attached resources), `mcp__linear-server__list_documents({projectId})` + `mcp__linear-server__get_document` per attached document, `mcp__linear-server__list_issues({project})` for sub-issues that act as child epics / user stories, and `mcp__linear-server__list_comments({issueId})` per sub-issue for decisions and engineering notes. Comments do not exist on the project itself in the MCP surface — sub-issue comments are the substitute.
+- `github.com` host → GitHub Issues. Fetch with the `gh` CLI (no GitHub MCP — Lisa uses the CLI exclusively for GitHub):
+  - `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,milestone,assignees,author,createdAt,comments,url` for the PRD body and comments.
+  - `gh api graphql` with the `subIssues` field for native sub-issue children (these stand in for child epic pages — see `lisa:github-read-issue` Phase 3 for the exact query).
+  - `gh issue view <child-num> --repo <org>/<repo> --json body,comments` per child sub-issue, recursively to depth 3.
+
+All four vendors produce the same downstream artifact-extraction and coverage-matrix logic — only the fetch surface differs. The rest of this skill is vendor-agnostic.
+
+Verify that every atomic item in the PRD is covered by at least one of the listed/discovered destination tickets. The output gates whether the PRD's lifecycle should remain at `Ticketed` (Notion `Status = Ticketed`, Confluence / Linear / GitHub `prd-ticketed` label) or revert to `Blocked`.
+
+The destination tickets are read via `lisa:tracker-read` (which dispatches to `lisa:jira-read-ticket` or `lisa:github-read-issue` per `.lisa.config.json` `tracker`) so this skill itself stays agnostic of which tracker hosts the work.
+
+## Why this exists
+
+Per-ticket gates (`lisa:jira-validate-ticket`) prove each created ticket is well-formed in isolation. They do NOT prove the *set* of created tickets is complete relative to the source PRD. Silent drops happen — an agent generates 8 tickets when the PRD called for 9, and nothing notices. This skill is the catch.
+
+## Phases
+
+### Phase 1 — Resolve inputs
+
+1. Parse `$ARGUMENTS`:
+   - PRD URL → detect vendor from host, extract page ID.
+   - Optional `tickets=[...]` → list of explicit ticket keys.
+2. Fetch the PRD using the vendor-appropriate tool surface:
+   - **Notion**: `notion-fetch` with `include_discussions: true`. Capture: title, body, child Epic pages, all comment threads.
+   - **Confluence**: `getConfluencePage` (capture title, body, labels), `getConfluencePageFooterComments` + `getConfluencePageInlineComments` (capture all comments; walk replies via `getConfluenceCommentChildren` for any thread with children).
+   - **Linear**: `get_project` (capture name, description, labels, state, attached resources). Capture sub-issues via `list_issues({project})` and per-issue comments via `list_comments({issueId})`.
+   - **GitHub**: `gh issue view --json` for the source PRD issue (title, body, labels, comments). Capture sub-issues via the GraphQL `subIssues` traversal.
+3. If the PRD has child Epic sub-pages / sub-issues (a multi-epic PRD), fetch each in parallel:
+   - **Notion**: `notion-fetch` per child page with `include_discussions: true`.
+   - **Confluence**: enumerate descendants via `getConfluencePageDescendants`, then `getConfluencePage` per child plus its comment streams.
+   - **Linear**: enumerate attached documents via `list_documents({projectId})` and fetch each via `get_document`. Treat each document as an extra body source. Sub-issues themselves stand in for "child epic pages" — their descriptions and comments are already captured in step 2.
+   - **GitHub**: enumerate native sub-issues via `gh api graphql` (`subIssues` field), then `gh issue view <child-num> --json body,comments` per child. Recurse to depth 3.
+   The audit walks the full PRD tree.
+4. If `tickets=[...]` not provided, locate the destination Epic by:
+   - Looking for a destination URL in the PRD body, comments, or the PRD's most recent "Ticketed by Claude" comment posted by `lisa:notion-prd-intake` / `lisa:confluence-prd-intake` / `lisa:linear-prd-intake` / `lisa:github-prd-intake` (for Linear, this comment lives on the project's sentinel feedback issue; for the others, it lives on the PRD page / issue itself).
+   - Searching the destination tracker via `lisa:tracker-read` (or directly via `searchJiraIssuesUsingJql` / `gh issue list --search`) for an epic whose summary or description references the PRD title or project ID.
+   - If no epic found, return verdict `NO_TICKETS_FOUND` with a clear remediation — coverage cannot be assessed without the ticket set.
+5. Once the epic is known, fetch all child stories and sub-tasks:
+   - **JIRA destination**: JQL `"Epic Link" = <EPIC-KEY>` and recursively for sub-tasks.
+   - **GitHub destination**: `gh api graphql` `subIssues` traversal of the Epic, recursively for sub-tasks.
+
+### Phase 2 — Extract atomic PRD items
+
+Walk the PRD content and produce a list of **atomic items** — testable, ticketable units of work. Each item gets a stable identifier so the matrix is auditable.
+
+The item types to extract:
+
+| Type | Where it appears in the PRD | Example identifier |
+|------|----------------------------|--------------------|
+| `goal` | `## Goals` section bullets | `goal:1`, `goal:2`, ... |
+| `non-goal` | `## Non-goals` (for scope-creep detection) | `non-goal:1` |
+| `user-story` | Per-Epic page, "User Story" sub-headings | `epic-1.story-1.1` |
+| `functional-req` | "Functional Requirements" sub-section | `epic-1.story-1.1.fr-1` |
+| `non-functional-req` | "Non-functional Requirements" sub-section | `epic-1.story-1.1.nfr-1` |
+| `acceptance-criterion` | Inline AC under a user story | `epic-1.story-1.1.ac-1` |
+| `important-note` | Bold "Important note:" callouts | `note:1` |
+| `mobile-spec` | Mobile-specific behavior callouts | `epic-1.story-1.1.mobile-1` |
+| `state` | Empty / error / loading state notes | `epic-2.story-2.1.state:empty` |
+| `permission` | Role-scoped permission notes | `epic-2.story-2.1.perm:admin` |
+| `decision` | Confirmed decisions in comments (e.g. "Engineering: ...") | `comment:42` |
+
+**Items NOT to extract** (these are not coverage gaps if missing):
+- Open Questions / `[Needs validation]` items — these are PRD-side blockers, not ticket scope.
+- Original concept thesis or annex/historical content — context, not requirements.
+- "Out of scope" items in the PRD — explicitly excluded by product.
+
+For each extracted item, capture: `{ id, type, source (PRD section / line), text (concise summary), keywords (3-5 terms for matching) }`.
+
+### Phase 3 — Map items to tickets
+
+For each created ticket (epic + each story + each sub-task), capture: `{ key, summary, description, acceptance_criteria, scope_signals (keywords from summary + AC) }`.
+
+Build a coverage matrix:
+
+```text
+PRD item id  →  [ticket keys that cover it]
+```
+
+Matching rules (in priority order):
+
+1. **Direct quote / strong keyword overlap**: the ticket's summary or AC explicitly names the PRD item's keywords. High confidence.
+2. **Domain match**: PRD item describes a UI affordance ("Tasks widget") and a ticket scopes that affordance (`[CU-2.1] Tasks widget — empty state`). Medium-high confidence.
+3. **Scope inheritance**: PRD item is a sub-detail of a parent (e.g. an AC under a user story); the ticket covers the parent user story. Medium confidence — flag for review if no more specific ticket exists.
+4. **Cross-ticket coverage**: PRD item spans multiple tickets (e.g. a permission rule that applies to several widgets). Each contributing ticket is recorded.
+
+Items with **zero** matching tickets are coverage gaps.
+
+### Phase 4 — Detect scope creep (informational)
+
+For each created ticket, identify any tickets whose scope_signals do NOT trace back to a PRD item, AND are not justifiable as standard infrastructure tasks (e.g. `X.0 Setup` stories for data model / migrations are typically infrastructure scaffolding, not scope creep).
+
+Scope creep is informational, not blocking — but worth surfacing because it usually indicates the agent invented work.
+
+### Phase 5 — Determine verdict
+
+| Condition | Verdict |
+|-----------|---------|
+| All extracted PRD items have ≥1 matching ticket; no scope creep | `COMPLETE` |
+| All extracted PRD items have ≥1 matching ticket; one or more scope-creep tickets | `COMPLETE_WITH_SCOPE_CREEP` |
+| One or more PRD items have zero matching tickets | `GAPS_FOUND` |
+| The created-tickets list is empty or unfetchable | `NO_TICKETS_FOUND` |
+
+`GAPS_FOUND` is the only verdict that should gate the PRD's `Status`. Scope creep is advisory — surface it, but do not block.
+
+### Phase 6 — Emit report
+
+Output a single fenced text block. Callers parse it; do not add free-form prose around it.
+
+```text
+## prd-ticket-coverage: <PRD title>
+
+PRD page: <URL>
+Tickets audited: <epic-key> + <story-count> stories + <subtask-count> sub-tasks
+Atomic PRD items extracted: <n>
+
+### Coverage matrix
+| PRD item | Tickets |
+|----------|---------|
+| <id> (<type>) — <text> | <ticket-key>, <ticket-key> |
+| <id> (<type>) — <text> | <ticket-key> |
+| <id> (<type>) — <text> | **(none)** |
+| ... | ... |
+
+### Gaps  (PRD items with zero ticket coverage — blocks Ticketed status)
+- item: <item-id> (<type>)
+  text: <text>
+  prd_section: "<heading text from the PRD>"
+  prd_anchor: "<first ~10 chars>...<last ~10 chars>"   # for selection_with_ellipsis; null if no specific section
+  category: <product-clarity|acceptance-criteria|design-ux|scope|dependency|data|technical|structural>
+  what: <plain-language description of the gap, no JIRA jargon — written for the product team>
+  recommendation: <1–3 candidate resolutions: add a ticket scoped to X / extend ticket Y to cover this / mark out-of-scope explicitly. Never "clarify this".>
+
+### Scope creep  (tickets without PRD trace — informational, does not block)
+- <ticket-key> — <summary>
+  - *Why flagged:* <reason — e.g. "no matching item in PRD; not an infra task">
+
+### Verdict: COMPLETE | COMPLETE_WITH_SCOPE_CREEP | GAPS_FOUND | NO_TICKETS_FOUND
+### Gap count: <n>
+### Scope-creep count: <n>
+```
+
+`prd_anchor` and `prd_section` are built the same way as in `lisa:notion-to-tracker` / `lisa:confluence-to-tracker` / `lisa:linear-to-tracker` / `lisa:github-to-tracker`. For Notion, `prd_anchor` is the `selection_with_ellipsis` start/end snippet; for Confluence, it's the inline-comment selection text accepted by `createConfluenceInlineComment`; for Linear, it's a sub-issue identifier (e.g. `LIN-123`) when the gap maps to a specific issue, otherwise `null` (the caller posts unanchored Linear gaps on the project's sentinel feedback issue); for GitHub, it's the section heading from the PRD issue body when the gap traces to a specific section, otherwise `null` (the caller approximates inline anchoring by quoting a body excerpt at the top of the comment). The downstream caller knows which vendor it's writing to and uses the right API; this skill just emits the anchor that vendor expects.
+
+`category` is drawn from the same fixed taxonomy used by `lisa:jira-validate-ticket` so downstream callers can apply one consistent comment-formatting policy. Most coverage gaps map to `scope` (item not represented in any ticket) or `product-clarity` (item too vague to map). Use `acceptance-criteria` for missing pass/fail conditions and `design-ux` for missing visuals.
+
+## Rules
+
+- Read-only — never write to JIRA, never write to Notion (callers do that based on the verdict).
+- Never silently drop a PRD item from extraction. If an item is ambiguous about whether it's scope, include it in extraction with type `ambiguous` and let the matching phase resolve it. The point of the audit is to catch silent drops; the audit can't have its own.
+- Be explicit about confidence in matches — the matrix is for humans to skim; vague matches help no one. If a match is rule-3 ("scope inheritance"), say so.
+- Scope creep is INFORMATIONAL. It is normal for an agent to add infra tickets (`X.0 Setup`) the PRD doesn't explicitly enumerate. Only flag scope creep when the ticket genuinely doesn't trace to PRD content AND isn't standard scaffolding.
+- The `GAPS_FOUND` verdict is the gate. The caller (e.g. `lisa:notion-prd-intake`, `lisa:confluence-prd-intake`, `lisa:linear-prd-intake`, `lisa:github-prd-intake`) uses it to decide whether to revert the lifecycle from `Ticketed` to `Blocked`.