@codyswann/lisa 2.216.0 → 2.217.0

package/plugins/src/base/skills/lisa-github-write-issue/SKILL.md

@@ -41,6 +41,7 @@ Resolve `<ORG>` and `<REPO>` from the ref or from `.lisa.config.json`.
 | Target backend environment | Runtime-behavior changes | Recorded under `## Target Backend Environment`. Skip only for doc / config / type-only. |
 | Sign-in account / credentials | Authenticated-surface tickets | Recorded under `## Sign-in Required`. |
 | Repository | Bug, Task, Sub-task | GitHub Issues live in exactly one repo by definition — record the repo name under `## Repository`, and reject any AC bullet that references a different repo. |
+| Source Requirement | PRD-sourced issues (`prd_source` provided) | `## Source Requirement` with PRD link + verbatim requirement quote(s) — see Phase 3; enforced at every level, sub-issues included. |
 
 Optional but recommended: assignee, milestone, components (label `component:<name>`), story points (label `points:<n>`), labels.
 
@@ -51,6 +52,20 @@ Use `gh api repos/<org>/<repo>/labels --paginate` to discover existing labels be
 The description (issue body) MUST address three audiences. Reject and rewrite if any are missing.
 
 ```markdown
+## Source Requirement
+[Required whenever the issue originates from a PRD (the caller passes
+ `prd_source`). Answers "why was this done?" — cite the PRD and quote the
+ requirement(s) VERBATIM, never paraphrased:
+ - **PRD**: <PRD title + link> §"<section heading>"
+ - **Requirement (R3)**: "<verbatim requirement text from the PRD>"
+ One Requirement line per satisfied requirement. Derived / cross-cutting
+ work that traces to no single requirement uses the supporting form:
+ "Derived work supporting R3, R7 — no single PRD section." Close with:
+ "This issue exists to satisfy the quoted requirement. If implementation
+ scope drifts from the quoted text, the PRD is the authority — raise the
+ conflict rather than silently reinterpreting it." Omit the section only
+ for ad-hoc issues with no PRD lineage.]
+
 ## Context / Business Value
 [Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
  Link to the originating Slack thread, PRD page, incident, or customer report.]
@@ -115,6 +130,7 @@ Scenario: <name>
 ```
 
 Rules:
+- PRD-sourced issues (caller passed `prd_source`) MUST carry the Source Requirement section with verbatim quotes — paraphrases are rejected (validator gate S16). This applies at every level, sub-issues included: a leaf claimed in isolation must explain its own "why".
 - Every acceptance criterion uses Given/When/Then. No vague "should work" language.
 - Every criterion is independently verifiable.
 - If the issue is a Bug, include reproduction steps, expected vs. actual behavior, and environment.

package/plugins/src/base/skills/lisa-jira-validate-ticket/SKILL.md

@@ -62,6 +62,7 @@ links: [{ key: "PROJ-99", type: "is blocked by" }]   # known issue links (may be
 remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
 build_ready: true                 # caller asserts the build-ready role (status:ready) is/would be applied — see S15
 child_refs: ["PROJ-601", "PROJ-602"]   # known child work (sub-tasks / "is blocked by" parentage) — see S15
+prd_source: "https://notion.so/..."    # set when the ticket was generated from a PRD — requires the Source Requirement section, see S16
 ```
 
 If the caller passes only a ticket key, fetch the ticket via `lisa-atlassian-access` `operation: read-ticket key: <KEY>`, derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa-jira-read-ticket`) so S15 can classify the ticket — then run gates.
@@ -89,6 +90,7 @@ Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Ca
 | S13 Relationship Search | `dependency` | true |
 | S14 Evidence manifest binding (leaf work units) | `acceptance-criteria` | true |
 | S15 Leaf-only build-ready | `structural` | false |
+| S16 Source Requirement traceability | `product-clarity` | true |
 | F1 Issue type valid in project | `structural` | false |
 | F2 Epic parent exists and is an Epic | `structural` | false |
 | F3 Linked tickets exist | `structural` | false |
@@ -236,6 +238,35 @@ Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle.
 
 `product_relevant: false` — a build-ready container is a lifecycle/decomposition error for the caller to repair, not a product question.
 
+#### S16 — Source Requirement traceability (PRD-sourced tickets)
+
+Answers "why was this done?": every ticket generated from a PRD must carry
+the requirement it exists to satisfy, quoted verbatim, at every level of
+the hierarchy — sub-tasks included, so a leaf claimed by build-intake in
+isolation is self-explanatory.
+
+**When the gate applies.** Run S16 whenever the spec declares `prd_source`
+(all `*-to-tracker` decomposition paths set it). Without `prd_source`
+(ad-hoc tickets with no PRD lineage) the gate is `N/A` — but if a
+`Source Requirement` section is present anyway, still validate its shape
+so a malformed section never passes silently.
+
+**What must be present.** A `Source Requirement` section (`h2.` / `##` in
+proposed text, or an ADF heading in live JIRA) containing:
+
+1. A link to the source PRD (the `**PRD**:` line), and
+2. At least one `**Requirement` line with **verbatim quoted text**, or the
+   explicit derived-work form (`Derived work supporting R3, R7 — no single
+   PRD section.`).
+
+Missing section, missing PRD link, empty/paraphrased requirement text
+(quotes shorter than a few words, or prose with no quotation), or a bare
+R-id with no quote: FAIL with remediation
+`"Add a Source Requirement section citing the PRD link and quoting the requirement(s) this ticket satisfies verbatim (see the Source Requirement shared format in the *-to-tracker skills). Derived work must name the requirements it supports."`
+
+`product_relevant: true` — a ticket whose requirement cannot be traced is
+a product-clarity problem: nobody can tell why the work exists.
+
 ### Feasibility Gates (require JIRA lookups; skip in dry-run if requested)
 
 #### F1 — Issue type valid in project
@@ -310,6 +341,7 @@ Output is a single fenced text block. Callers parse it; do not add free-form pro
 - [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
 - [PASS|FAIL|N/A] S14 Evidence manifest binding — <one-line reason>
 - [PASS|FAIL|N/A] S15 Leaf-only build-ready — <one-line reason>
+- [PASS|FAIL|N/A] S16 Source Requirement traceability — <one-line reason>
 
 ### Feasibility Gates  (omit this section when --spec-only)
 - [PASS|FAIL|N/A] F1 Issue type valid in project — <one-line reason>

package/plugins/src/base/skills/lisa-jira-write-ticket/SKILL.md

@@ -38,6 +38,7 @@ Required fields (stop and ask if missing — do not invent values):
 | Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only tickets. |
 | Sign-in account / credentials | Tickets that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description (Phase 3). Omit when sign-in is not required. |
 | Single-repo scope | Bug, Task, Sub-task, Improvement | These leaf work units MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
+| Source Requirement | PRD-sourced tickets (`prd_source` provided) | `h2. Source Requirement` with PRD link + verbatim requirement quote(s) — see Phase 3; enforced at every level, sub-tasks included |
 
 Optional but recommended: assignee, components, fix versions, labels, sprint, story points, reporter.
 
@@ -48,6 +49,20 @@ Issue-type validity and required custom fields are enforced by `lisa-jira-valida
 The description MUST address three audiences. Reject and rewrite if any are missing.
 
 ```text
+h2. Source Requirement
+[Required whenever the ticket originates from a PRD (the caller passes
+ `prd_source`). Answers "why was this done?" — cite the PRD and quote the
+ requirement(s) VERBATIM, never paraphrased:
+ - **PRD**: <PRD title + link> §"<section heading>"
+ - **Requirement (R3)**: "<verbatim requirement text from the PRD>"
+ One Requirement line per satisfied requirement. Derived / cross-cutting
+ work that traces to no single requirement uses the supporting form:
+ "Derived work supporting R3, R7 — no single PRD section." Close with:
+ "This ticket exists to satisfy the quoted requirement. If implementation
+ scope drifts from the quoted text, the PRD is the authority — raise the
+ conflict rather than silently reinterpreting it." Omit the section only
+ for ad-hoc tickets with no PRD lineage.]
+
 h2. Context / Business Value
 [Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
  Link to the originating Slack thread, Notion doc, incident, or customer report.]
@@ -93,6 +108,7 @@ h2. Validation Journey
 ```
 
 Rules:
+- PRD-sourced tickets (caller passed `prd_source`) MUST carry the Source Requirement section with verbatim quotes — paraphrases are rejected (validator gate S16). This applies at every level, sub-tasks included: a leaf claimed in isolation must explain its own "why".
 - Every acceptance criterion uses Given/When/Then. No vague "should work" language.
 - Every criterion is independently verifiable (UI, API, data, or performance check).
 - If the ticket is a Bug, include reproduction steps, expected vs. actual behavior, and environment.

package/plugins/src/base/skills/lisa-linear-to-tracker/SKILL.md

@@ -32,21 +32,29 @@ This skill supports two modes, controlled by a `dry_run` flag in `$ARGUMENTS`:
 - **`dry_run: false`** (default — full mode): run all phases, write tickets via `lisa-tracker-write`, run the preservation gate, report.
 - **`dry_run: true`** (planning + validation only — no writes): run Phases 1, 1.5, 1.6, 2, 3, 4 to plan the hierarchy and draft each ticket spec, then call `lisa-tracker-validate` (with `--spec-only`) on every drafted ticket. Aggregate the per-ticket validator reports into a single dry-run report. **Skip Phase 5 (sub-task creation), Phase 5.5 (preservation gate), and Phase 6 (results report)** — none of those make sense without writes. Return the dry-run report so the caller (e.g. `lisa-linear-prd-intake`) can decide whether to proceed.
 
-Dry-run output format is identical to `lisa-notion-to-tracker`'s and `lisa-confluence-to-tracker`'s. Reuse the same fields, including `prd_anchor` and `prd_section`. The only difference: Linear has no inline-comment selection-anchor primitive at the project level — `prd_anchor` is the anchor a downstream caller would use to *post a comment on the related sub-issue* (typically the issue identifier, e.g. `LIN-123`, scoped to a section heading). When the failure does not map to any single sub-issue, set `prd_anchor: null` and the caller falls back to its sentinel feedback channel.
+Dry-run output format is identical to `lisa-notion-to-tracker`'s and `lisa-confluence-to-tracker`'s. Reuse the same fields, including `prd_anchor` and `prd_section`, the `### Requirement register` section, and the per-node `requirements:` lists. The only difference: Linear has no inline-comment selection-anchor primitive at the project level — `prd_anchor` is the anchor a downstream caller would use to *post a comment on the related sub-issue* (typically the issue identifier, e.g. `LIN-123`, scoped to a section heading). When the failure does not map to any single sub-issue, set `prd_anchor: null` and the caller falls back to its sentinel feedback channel.
 
 ```text
 ## linear-to-tracker dry-run: <PRD title>
 
+### Requirement register
+- R1 §"<section heading>": "<verbatim requirement text>"
+- R2 §"<section heading>": "<verbatim requirement text>"
+- ...
+
 ### Planned hierarchy
 - Epic: <summary>
   prd_section: "<heading text from the project description / document that produced this epic>"
   prd_anchor: "<linear issue identifier or null>"
+  requirements: [R1, R2]   # register ids this ticket exists to satisfy; [] only for derived work
   - Story 1.1: <summary>
     prd_section: "<heading or user-story line>"
     prd_anchor: "<linear issue identifier or null>"
+    requirements: [R1]
     - Sub-task [<repo>]: <summary>
       prd_section: "<heading or AC bullet>"
       prd_anchor: "<linear issue identifier or null>"
+      requirements: [R1]
     - ...
   - Story 1.2: ...
 
@@ -82,6 +90,38 @@ The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJir
 
 Bypassing `lisa-tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. Atlassian reads in this skill are limited to the tools listed in `allowed-tools` (currently `getJiraIssueRemoteIssueLinks`) for the Phase 5.5 preservation gate. The Linear read tools listed in `allowed-tools` above are PRD-side only and never write.
 
+## Source Requirement Section (shared format)
+
+Every ticket created by this skill — epic, story, and sub-task alike —
+carries a `## Source Requirement` section in its description so anyone can
+answer "why was this done?" without leaving the ticket:
+
+```markdown
+## Source Requirement
+
+- **PRD**: [<PRD title>](<PRD URL>) §"<section heading>"
+- **Requirement (R3)**: "<verbatim requirement text from the PRD>"
+
+This ticket exists to satisfy the quoted requirement. If implementation
+scope drifts from the quoted text, the PRD is the authority — raise the
+conflict rather than silently reinterpreting it.
+```
+
+Rules:
+
+- **Verbatim quotes, never paraphrases.** The quote is what survives later
+  PRD edits, and it must be readable by a non-technical operator.
+- **Multiple requirements** → one `**Requirement (Rn)**` line each.
+- **Derived / cross-cutting work** (no single requirement) uses the
+  supporting form instead:
+  `- **Requirement**: Derived work supporting R3, R7 — no single PRD section.`
+- **All the way down**: sub-tasks carry full quotes, not just a pointer at
+  the parent Story, so a leaf claimed by build-intake in isolation is
+  self-explanatory.
+- JIRA descriptions render the section as `h2. Source Requirement`;
+  GitHub/Linear use the markdown heading. `lisa-tracker-write` and the
+  validators treat the section as mandatory for PRD-sourced tickets.
+
 ## Input
 
 A Linear project URL, slug, or ID. The PRD is expected to have:
@@ -137,6 +177,37 @@ If env vars are not available, ask the user to provide them explicitly before pr
    - Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
    - Cross-PRD dependencies (references to other Linear projects, documents, or shared infrastructure)
 
+### Phase 1.4: Requirement Register (traceability)
+
+Every ticket this skill creates must be able to answer "why was this done?"
+by pointing at the PRD requirement it satisfies. Build that mapping now,
+while parsing the PRD — it cannot be reliably reconstructed afterwards.
+
+1. **Atomize the PRD into requirements** in document order: goals, user
+   stories, functional and non-functional requirements, acceptance-criteria
+   bullets, and important notes — across the project description, every
+   attached document, and every sub-issue description. Use the same
+   atomization `lisa-prd-ticket-coverage` uses so the two views line up.
+2. **Assign sequential register ids** (`R1`, `R2`, …). Ids are
+   per-generation, not durable — the **verbatim quote is the durable
+   anchor**; if the PRD is edited and re-planned, ids may shift but quotes
+   still identify the requirement.
+3. **Record each entry** as `{ id, verbatim_text, section_heading }`,
+   where `section_heading` is the markdown heading (or the sub-issue
+   identifier) the requirement lives under — the same value used for
+   `prd_anchor`.
+4. **Tag every planned ticket** — epic, story, AND sub-task — with the
+   register ids it exists to satisfy. All the way down: sub-tasks carry
+   their own requirement quotes so a leaf dispatched in isolation is
+   self-explanatory. A ticket that genuinely traces to no single
+   requirement (cross-cutting infrastructure, derived enablement work)
+   gets `requirements: []` and must say which requirements it *supports*
+   in its Source Requirement section instead.
+
+The register feeds three consumers: the `## Source Requirement` section on
+every created ticket (Phases 3–5), the dry-run report (above), and the
+requirement tokens in the PRD back-link (Phase 7).
+
 ### Phase 1.5: Extract Source Artifacts
 
 PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, peer Linear or Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
@@ -183,8 +254,10 @@ For each epic identified in Phase 1, **invoke the `lisa-tracker-write` skill** (
 
 - `project_key`: resolved by `lisa-tracker-write` from `.lisa.config.json`
 - `issue_type`: `Epic`
+- `prd_source`: the originating PRD URL — mandatory for every ticket this skill creates; it arms the validator's S16 traceability gate
 - `summary`: epic title from the PRD
 - `description_body`: a draft of the 3-audience description containing:
+  - A **Source Requirement** section (see the shared format above) citing the Linear project URL, section heading, and the verbatim text of every register requirement (`R-id`) this epic exists to satisfy
   - **Context / Business Value**: epic summary from the PRD, originating Linear project URL, business outcome
   - **Technical Approach**: cross-cutting integration points and constraints surfaced in Phase 2 codebase research
   - List of user stories the epic contains
@@ -213,9 +286,10 @@ For each story, **invoke `lisa-tracker-write`** with:
 
 - `project_key`: resolved by `lisa-tracker-write` from `.lisa.config.json`
 - `issue_type`: `Story`
+- `prd_source`: the originating PRD URL — mandatory for every ticket this skill creates; it arms the validator's S16 traceability gate
 - `epic_parent`: the Epic key captured in Phase 3 (mandatory)
 - `summary`: prefixed per the naming convention above
-- `description_body`: 3-audience description as in `lisa-notion-to-tracker` Phase 4
+- `description_body`: 3-audience description as in `lisa-notion-to-tracker` Phase 4, including as its first element a **Source Requirement** section (shared format above) quoting the register requirement(s) this story satisfies
 - `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below
 
 | Story type | Inherits domains |
@@ -240,6 +314,7 @@ Delegate sub-task creation to **parallel agents** (one per epic or batch of stor
 Each sub-task MUST:
 1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]` and in the description's `## Repository` / `h2. Repository` section
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
+3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
 
 **Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa-tracker-write` applies `status:ready` here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
 
@@ -264,6 +339,7 @@ After all tickets are created, present a summary table to the user:
 - All Epics with keys and URLs
 - All Stories grouped by Epic
 - All Sub-tasks grouped by Story with repo tags
+- **Requirement coverage** — one row per Phase 1.4 register entry (`R-id`, quote excerpt, tickets that declare it); requirements with zero tickets are a gap to resolve before reporting success
 - Repo distribution
 - **Artifact Preservation Matrix**
 - Blockers list with recommendations and alternatives
@@ -279,7 +355,8 @@ Invoke `lisa-prd-backlink` with:
 
 - `source_type: "linear"`
 - `source_ref`: the original Linear project URL
-- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key, requirements }` — `requirements` is the list of Phase 1.4 register ids the ticket satisfies (empty for derived work)
+- `requirement_register`: the Phase 1.4 register (`{ id, verbatim_text, section_heading }` entries), so the back-link section can render the requirement → tickets view
 
 If `lisa-prd-backlink` fails (permission denied, Linear unreachable), surface the error in the Phase 6 report rather than aborting — the tickets are already created. Recommend the user re-run `lisa-prd-backlink` standalone once the source is reachable.
 
@@ -307,10 +384,11 @@ produces broken tickets that downstream skills (triage, journey, evidence) canno
 
 For each sub-task, invoke `lisa-tracker-write` with:
 - issue_type: "Sub-task"
+- prd_source: [the originating PRD URL — mandatory; arms the S16 traceability gate]
 - parent: the parent story key
 - project_key: [PROJECT]
 - summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
-- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo, plus `h2. Source Requirement` quoting the PRD requirement(s) this sub-task satisfies VERBATIM with the PRD link and register id(s) — [paste the exact requirement text and R-ids for each sub-task from the requirement register; do not let the agent paraphrase]
 - gherkin_acceptance_criteria: derived from the story's functional requirements
 - sign_in_account: [test user credentials from config — name + role + how to obtain]
 - target_environment: "dev"

package/plugins/src/base/skills/lisa-linear-validate-issue/SKILL.md

@@ -63,6 +63,7 @@ relations: [{ id: "ENG-99", type: "blocked_by" }]   # known issue relations (may
 remote_links: [{ url: "https://github.com/...", title: "PR #42" }]
 build_ready: true                 # caller asserts the build-ready role (status:ready) is/would be applied — see S15
 child_refs: ["ENG-601", "ENG-602"]   # known child work (sub-issues / project-member issues / blocked_by parentage) — see S15
+prd_source: "https://notion.so/..."    # set when the Issue was generated from a PRD — requires the Source Requirement section, see S16
 ```
 
 If the caller passes only an identifier, fetch the item via `lisa-linear-access operation: get-issue` (Issue) or `lisa-linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item — then run gates.
@@ -90,6 +91,7 @@ Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Ca
 | S13 Relationship Search | `dependency` | true |
 | S14 Evidence manifest binding (leaf work units) | `acceptance-criteria` | true |
 | S15 Leaf-only build-ready | `structural` | false |
+| S16 Source Requirement traceability | `product-clarity` | true |
 | F1 Issue type valid in team | `structural` | false |
 | F2 Project parent exists and is in same team | `structural` | false |
 | F3 Linked items exist | `structural` | false |
@@ -239,6 +241,34 @@ Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle.
 
 `product_relevant: false` — a build-ready container is a lifecycle/decomposition error for the caller to repair, not a product question.
 
+#### S16 — Source Requirement traceability (PRD-sourced Issues)
+
+Answers "why was this done?": every Issue generated from a PRD must carry
+the requirement it exists to satisfy, quoted verbatim, at every level of
+the hierarchy — sub-issues included, so a leaf claimed by build-intake in
+isolation is self-explanatory.
+
+**When the gate applies.** Run S16 whenever the spec declares `prd_source`
+(all `*-to-tracker` decomposition paths set it). Without `prd_source`
+(ad-hoc issues with no PRD lineage) the gate is `N/A` — but if a
+`Source Requirement` section is present anyway, still validate its shape
+so a malformed section never passes silently.
+
+**What must be present.** a `Source Requirement` section (`##` markdown heading) containing:
+
+1. A link to the source PRD (the `**PRD**:` line), and
+2. At least one `**Requirement` line with **verbatim quoted text**, or the
+   explicit derived-work form (`Derived work supporting R3, R7 — no single
+   PRD section.`).
+
+Missing section, missing PRD link, empty/paraphrased requirement text
+(quotes shorter than a few words, or prose with no quotation), or a bare
+R-id with no quote: FAIL with remediation
+`"Add a Source Requirement section citing the PRD link and quoting the requirement(s) this issue satisfies verbatim (see the Source Requirement shared format in the *-to-tracker skills). Derived work must name the requirements it supports."`
+
+`product_relevant: true` — a issue whose requirement cannot be traced is
+a product-clarity problem: nobody can tell why the work exists.
+
 ### Feasibility Gates (require Linear lookups; skip in dry-run if requested)
 
 #### F1 — Issue type valid in team
@@ -317,6 +347,7 @@ Output is a single fenced text block. Callers parse it; do not add free-form pro
 - [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
 - [PASS|FAIL|N/A] S14 Evidence manifest binding — <one-line reason>
 - [PASS|FAIL|N/A] S15 Leaf-only build-ready — <one-line reason>
+- [PASS|FAIL|N/A] S16 Source Requirement traceability — <one-line reason>
 
 ### Feasibility Gates  (omit when --spec-only)
 - [PASS|FAIL|N/A] F1 Issue type valid in team — <one-line reason>

package/plugins/src/base/skills/lisa-linear-write-issue/SKILL.md

@@ -60,6 +60,7 @@ Required fields (stop and ask if missing — never invent values):
 | Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only items. |
 | Sign-in account / credentials | Items that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description. Omit when sign-in is not required. |
 | Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
+| Source Requirement | PRD-sourced Issues (`prd_source` provided) | `## Source Requirement` with PRD link + verbatim requirement quote(s) — see Phase 3; enforced at every level, sub-issues included. |
 
 Optional but recommended: assignee, estimate (story points), labels, project milestone (fix-version equivalent), cycle.
 
@@ -68,6 +69,20 @@ Optional but recommended: assignee, estimate (story points), labels, project mil
 Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, use `##` instead). The description MUST address three audiences. Reject and rewrite if any are missing.
 
 ```markdown
+## Source Requirement
+[Required whenever the Issue originates from a PRD (the caller passes
+ `prd_source`). Answers "why was this done?" — cite the PRD and quote the
+ requirement(s) VERBATIM, never paraphrased:
+ - **PRD**: <PRD title + link> §"<section heading>"
+ - **Requirement (R3)**: "<verbatim requirement text from the PRD>"
+ One Requirement line per satisfied requirement. Derived / cross-cutting
+ work that traces to no single requirement uses the supporting form:
+ "Derived work supporting R3, R7 — no single PRD section." Close with:
+ "This Issue exists to satisfy the quoted requirement. If implementation
+ scope drifts from the quoted text, the PRD is the authority — raise the
+ conflict rather than silently reinterpreting it." Omit the section only
+ for ad-hoc Issues with no PRD lineage.]
+
 ## Context / Business Value
 [Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
  Link to the originating Slack thread, Notion doc, incident, or customer report.]
@@ -108,6 +123,7 @@ Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, us
 ```
 
 Rules:
+- PRD-sourced Issues (caller passed `prd_source`) MUST carry the Source Requirement section with verbatim quotes — paraphrases are rejected (validator gate S16). This applies at every level, sub-issues included: a leaf claimed in isolation must explain its own "why".
 - Every acceptance criterion uses Given/When/Then. No vague "should work" language.
 - Every criterion is independently verifiable (UI, API, data, or performance check).
 - If the item is a Bug, include reproduction steps, expected vs. actual behavior, and environment.

package/plugins/src/base/skills/lisa-notion-to-tracker/SKILL.md

@@ -28,16 +28,24 @@ Dry-run output format:
 ```text
 ## notion-to-tracker dry-run: <PRD title>
 
+### Requirement register
+- R1 §"<section heading>": "<verbatim requirement text>"
+- R2 §"<section heading>": "<verbatim requirement text>"
+- ...
+
 ### Planned hierarchy
 - Epic: <summary>
   prd_section: "<heading text from the PRD that produced this epic>"
   prd_anchor: "<first ~10 chars>...<last ~10 chars>"   # for selection_with_ellipsis; null if no specific section
+  requirements: [R1, R2]   # register ids this ticket exists to satisfy; [] only for derived work
   - Story 1.1: <summary>
     prd_section: "<heading or user-story line>"
     prd_anchor: "<start>...<end>"
+    requirements: [R1]
     - Sub-task [<repo>]: <summary>
       prd_section: "<heading or AC bullet>"
       prd_anchor: "<start>...<end>"
+      requirements: [R1]
     - ...
   - Story 1.2: ...
 
@@ -77,6 +85,38 @@ The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJir
 
 Bypassing `lisa-tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. This is the most common failure mode this skill has had — calling `createJiraIssue` directly is a regression, not an optimization. The Atlassian read tools (`getJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssueRemoteIssueLinks`, `getAccessibleAtlassianResources`, `getJiraProjectIssueTypesMetadata`, `getVisibleJiraProjects`) ARE allowed for context gathering and the Phase 5.5 preservation gate.
 
+## Source Requirement Section (shared format)
+
+Every ticket created by this skill — epic, story, and sub-task alike —
+carries a `## Source Requirement` section in its description so anyone can
+answer "why was this done?" without leaving the ticket:
+
+```markdown
+## Source Requirement
+
+- **PRD**: [<PRD title>](<PRD URL>) §"<section heading>"
+- **Requirement (R3)**: "<verbatim requirement text from the PRD>"
+
+This ticket exists to satisfy the quoted requirement. If implementation
+scope drifts from the quoted text, the PRD is the authority — raise the
+conflict rather than silently reinterpreting it.
+```
+
+Rules:
+
+- **Verbatim quotes, never paraphrases.** The quote is what survives later
+  PRD edits, and it must be readable by a non-technical operator.
+- **Multiple requirements** → one `**Requirement (Rn)**` line each.
+- **Derived / cross-cutting work** (no single requirement) uses the
+  supporting form instead:
+  `- **Requirement**: Derived work supporting R3, R7 — no single PRD section.`
+- **All the way down**: sub-tasks carry full quotes, not just a pointer at
+  the parent Story, so a leaf claimed by build-intake in isolation is
+  self-explanatory.
+- JIRA descriptions render the section as `h2. Source Requirement`;
+  GitHub/Linear use the markdown heading. `lisa-tracker-write` and the
+  validators treat the section as mandatory for PRD-sourced tickets.
+
 ## Input
 
 A Notion PRD URL. The PRD is expected to have:
@@ -122,6 +162,34 @@ If env vars are not available, ask the user to provide them explicitly before pr
    - Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
    - Cross-PRD dependencies (references to other features or shared infrastructure)
 
+### Phase 1.4: Requirement Register (traceability)
+
+Every ticket this skill creates must be able to answer "why was this done?"
+by pointing at the PRD requirement it satisfies. Build that mapping now,
+while parsing the PRD — it cannot be reliably reconstructed afterwards.
+
+1. **Atomize the PRD into requirements** in document order: goals, user
+   stories, functional and non-functional requirements, acceptance-criteria
+   bullets, and important notes. Use the same atomization
+   `lisa-prd-ticket-coverage` uses so the two views line up.
+2. **Assign sequential register ids** (`R1`, `R2`, …). Ids are
+   per-generation, not durable — the **verbatim quote is the durable
+   anchor**; if the PRD is edited and re-planned, ids may shift but quotes
+   still identify the requirement.
+3. **Record each entry** as `{ id, verbatim_text, section_heading }` plus
+   the `prd_anchor` capture described above.
+4. **Tag every planned ticket** — epic, story, AND sub-task — with the
+   register ids it exists to satisfy. All the way down: sub-tasks carry
+   their own requirement quotes so a leaf dispatched in isolation is
+   self-explanatory. A ticket that genuinely traces to no single
+   requirement (cross-cutting infrastructure, derived enablement work)
+   gets `requirements: []` and must say which requirements it *supports*
+   in its Source Requirement section instead.
+
+The register feeds three consumers: the `## Source Requirement` section on
+every created ticket (Phases 3–5), the dry-run report (above), and the
+requirement tokens in the PRD back-link (Phase 7).
+
 ### Phase 1.5: Extract Source Artifacts
 
 PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
@@ -173,9 +241,11 @@ Walkthrough findings are attached to the originating Notion PRD as a comment ("C
 For each PRD epic, **invoke the `lisa-tracker-write` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
 
 - `project_key`: resolved by `lisa-tracker-write` from `.lisa.config.json`
+- `prd_source`: the originating PRD URL — mandatory for every ticket this skill creates; it arms the validator's S16 traceability gate
 - `issue_type`: `Epic`
 - `summary`: epic title from the PRD
 - `description_body`: a draft of the 3-audience description containing:
+  - A **Source Requirement** section (see the shared format below) citing the PRD URL, section heading, and the verbatim text of every register requirement (`R-id`) this epic exists to satisfy
   - **Context / Business Value**: epic summary from the PRD, originating Notion URL, business outcome
   - **Technical Approach**: cross-cutting integration points and constraints surfaced in Phase 2 codebase research
   - List of user stories the epic contains
@@ -206,10 +276,12 @@ For each Epic, plan two kinds of stories:
 For each story, **invoke `lisa-tracker-write`** with:
 
 - `project_key`: resolved by `lisa-tracker-write` from `.lisa.config.json`
+- `prd_source`: the originating PRD URL (arms S16)
 - `issue_type`: `Story`
 - `epic_parent`: the Epic key captured in Phase 3 (mandatory — `lisa-tracker-write` rejects non-bug, non-epic tickets without an epic parent)
 - `summary`: prefixed per the naming convention above
 - `description_body`: a draft of the 3-audience description containing:
+  - A **Source Requirement** section (shared format below) quoting the register requirement(s) this story satisfies
   - **Context / Business Value**: the user story statement from the PRD
   - **Technical Approach**: notes from engineering comments and Phase 2 codebase research
   - **Acceptance Criteria** (Gherkin) derived from the functional requirements — `lisa-tracker-write` will reject prose-only acceptance criteria
@@ -244,6 +316,7 @@ Delegate sub-task creation to **parallel agents** (one per epic or batch of stor
 Each sub-task MUST:
 1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]` and in the description's `## Repository` / `h2. Repository` section. `lisa-tracker-write` enforces single-repo scope on Sub-task; cross-repo or unscoped sub-tasks will be rejected and must be split/restamped before delegation.
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
+3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
 
 **Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa-tracker-write` applies `status:ready` here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
 
@@ -277,6 +350,7 @@ After all tickets are created, present a summary table to the user:
 - All Epics with keys and URLs
 - All Stories grouped by Epic
 - All Sub-tasks grouped by Story with repo tags
+- **Requirement coverage** — one row per Phase 1.4 register entry (`R-id`, quote excerpt, tickets that declare it); requirements with zero tickets are a gap to resolve before reporting success
 - Repo distribution (how many tasks per repo)
 - **Artifact Preservation Matrix** — one row per artifact showing which epic/stories reference it
 - Blockers list with recommendations and alternatives
@@ -292,7 +366,8 @@ Invoke `lisa-prd-backlink` with:
 
 - `source_type: "notion"`
 - `source_ref`: the original PRD URL
-- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key, requirements }` — `requirements` is the list of Phase 1.4 register ids the ticket satisfies (empty for derived work)
+- `requirement_register`: the Phase 1.4 register (`{ id, verbatim_text, section_heading }` entries), so the back-link section can render the requirement → tickets view
 
 If `lisa-prd-backlink` fails (PRD permission denied, Notion unreachable, source mutated mid-run), surface the error in the Phase 6 report rather than aborting — the tickets are already created and their value to the team is not blocked by the back-link write. Recommend the user re-run `lisa-prd-backlink` standalone once the source is reachable again.
 
@@ -329,8 +404,9 @@ For each sub-task, invoke `lisa-tracker-write` with:
 - issue_type: "Sub-task"
 - parent: the parent story key
 - project_key: [PROJECT]
+- prd_source: [the originating PRD URL — mandatory; arms the S16 traceability gate]
 - summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
-- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo, plus `h2. Source Requirement` quoting the PRD requirement(s) this sub-task satisfies VERBATIM with the PRD link and register id(s) — [paste the exact requirement text and R-ids for each sub-task from the requirement register; do not let the agent paraphrase]
 - gherkin_acceptance_criteria: derived from the story's functional requirements
 - sign_in_account: [test user credentials from config — name + role + how to obtain]
 - target_environment: "dev"

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

@@ -19,7 +19,10 @@ Pass `$ARGUMENTS` as a single JSON-style block:
   "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>" }
+    { "key": "<tracker-key>", "title": "<summary>", "type": "Epic|Story|Task|Sub-task|Bug|Spike", "url": "<link>", "parent_key": "<key or null>", "requirements": ["R1", "R3"] }
+  ],
+  "requirement_register": [
+    { "id": "R1", "verbatim_text": "<requirement text quoted from the PRD>", "section_heading": "<PRD heading>" }
   ],
   "section_heading": "## Tickets"   // optional override; default "## Tickets"
 }
@@ -58,6 +61,11 @@ The rendered section must be deterministic — same inputs produce identical out
 
 _Generated by `lisa-prd-backlink`. Regenerated on every Plan run; do not edit by hand._
 
+### Requirement coverage
+
+- **R1** §"<PRD heading>": "<verbatim requirement text>" — [<key>](<url>), [<key>](<url>)
+- **R2** §"<PRD heading>": "<verbatim requirement text>" — _no tickets — gap_
+
 ### <Epic key>: <Epic title>
 
 - [<Epic key>](<url>) — Epic <!-- lisa:gw ref=<ref> url=<url> type=Epic parent= -->
@@ -80,7 +88,7 @@ _Generated by `lisa-prd-backlink`. Regenerated on every Plan run; do not edit by
 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 ref=<ref> url=<url> type=<type> parent=<parent-ref or empty> reqs=<comma-separated requirement ids 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.
@@ -88,8 +96,9 @@ Every list entry ends with a single-line HTML comment — invisible in rendered
 - **`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.
+- **`reqs`** — comma-separated requirement register ids (`R1,R3`) the ticket's `requirements` list declares, or **empty** for derived work or tickets created before traceability. This makes the requirement → tickets mapping parseable from the PRD alone: a reader answers "which tickets carry R3?" by matching `reqs=` tokens, deterministically — no inference.
 
-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.
+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`, `reqs`) 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."