@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/rules/reference/derived-branch-plan.md

@@ -0,0 +1,214 @@
+# Derived Branch Plan — reference
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Derived Branch Plan (load-bearing)
+
+**Every applicable leaf work item shows the branch it will be built from and the branch its PR lands in, as a generated `Branch Plan` section — and that section is derived data, not a second authority.** The authority is `## Target Backend Environment` resolved forward through `.lisa.config.json` `deploy.branches`. A work item that displays branches nobody can trace back to that mapping, or a flow that reads the displayed branches instead of recomputing them, is a contract violation.
+
+**One vendor-neutral contract, cited by** `lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`, `lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`, and `lisa-implement` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-vendor prose).
+
+## Why derived, and not two branch fields
+
+The operator need is real: reading a ticket should not require resolving a config file to learn where the work starts and where it lands. But Lisa already owns that fact. Adding independent literal branch fields would create **a second source of truth that can drift** — and the failure mode of that drift is not a cosmetic mismatch, it is code silently shipped to the wrong environment. So the branches are rendered for humans and recomputed for machines. The rendered branches are **never read as input** by any flow, at any phase — a surface that needs the base branch derives it again from the environment.
+
+## The rendered section
+
+Exactly three lines, identical across vendors (`h2. Branch Plan` in JIRA wiki markup, `## Branch Plan` in GitHub/Linear markdown):
+
+```
+Branch from: <branch>
+PR into: <branch>
+Derived from: Target Backend Environment <env> via .lisa.config.json deploy.branches
+```
+
+The third line is the **derivation provenance line**. It is what marks the section machine-authored: a `Branch Plan` without it is treated as hand-authored, and hand-authored branches are never obeyed.
+
+`Branch from` and `PR into` name the **same branch by construction** — implementation checks the feature branch out of `origin/<base>` and targets the PR back into `<base>`. A plan naming two different branches is malformed and fails validation. (A fix that genuinely lands on one branch and must reach another travels as a linked follow-up work item with its own branch plan, never as a divergence inside one plan.)
+
+## Derivation
+
+1. Resolve the environment under the existing `Target Backend Environment` grammar (`config-resolution`, `pre-flight-autofill`) — human-confirmed wins, then validated `Inferred:`, then `Assumption:`.
+2. Map that exact configured key forward through `deploy.branches`. The key must map uniquely and the mapped branch must exist on the remote.
+3. Render both fields to that branch plus the provenance line.
+
+A missing or **ambiguous** mapping, a key that is **not unique**, or a branch absent from the remote **stops** the flow — exactly as `lisa-implement` already stops. **Never default independently to `main`, to the remote default branch, or to any other branch** to keep a write from failing. The remote default is a legitimate input only through the `Assumption:` fallback the environment grammar already defines, and it must be recorded as such.
+
+## Exemption
+
+Work that declares no runtime behavior change — `runtime_behavior_change = false`, i.e. doc-only, config-only, and type-only items — has nothing to derive from and **requires no branch plan**. Its **absence is correct**, not a missing section, and no gate may demand one. Containers (an Epic, or a Story/Spike still holding child work) are exempt for the same reason: they are not built directly.
+
+But the exemption is **declared, never inferred from an absent section**. `Target Backend Environment` is rendered on every leaf, because it is where `runtime_behavior_change` is persisted: an exact configured environment key means `true`, `None — no runtime behavior change: doc-only` (or `config-only` / `type-only`) means `false`, `None — container: state rolls up from children` marks a container, and an **absent section is underivable — never `false`**. On a live item the stored declaration beats any caller assertion, and a contradicting assertion fails S8 rather than being believed. Absence used to be the only signal, which meant the flag every one of S8, S11, S14, and S19 turns on could not be checked against the item at all.
+
+The exemption is one-way. Exempt work that *carries* a branch plan fails validation — branches asserted for work that declared it has no runtime target are hand-authored by definition, which is the second-authority failure this rule exists to prevent.
+
+## Conflict, legacy, and drift
+
+- **Conflict** — a present plan that disagrees with the recomputed plan **fails**; the flow never silently picks a side. The remediation is always to correct the environment, never to edit the branches.
+- **Legacy** — an item written before this rule has no plan. At claim time the implementing agent derives it, **writes the assumption onto the item as a comment**, and proceeds. Never a silent guess.
+- **Drift** — config changed after the plan was rendered. Current config wins; the stale plan is re-rendered and never followed.
+
+---
+
+The full body behind the `derived-branch-plan` eager head. It defines one vendor-neutral contract consumed by the three tracker writers (`lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`), the three validators (`lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`) via gate **S19**, and `lisa-implement` at claim time. Each surface cites this slug rather than growing its own prose, exactly as the vendor arms cite `leaf-only-lifecycle` and `repo-scope-split`. One slug is what keeps a branch plan rejected on JIRA from being accepted on Linear.
+
+## The problem this solves, and the one it must not create
+
+An operator reading a work item cannot see which branch the work starts from or which branch the PR lands in. Both facts are knowable, but only by resolving `.lisa.config.json` — which is exactly the kind of engineering step the factory model says a non-technical operator standing at the gate should not have to take.
+
+The obvious fix — add a "source branch" field and a "PR target" field to the ticket template — is wrong, and it is worth being explicit about why, because it will look like the simple answer every time someone revisits this. Those fields would be **a second source of truth** for a fact Lisa already derives authoritatively from `## Target Backend Environment` + `deploy.branches`. Two authorities do not stay equal. They drift the first time an environment is corrected on a ticket whose branch fields nobody updated, or the first time `deploy.branches` is remapped. And the consequence of that drift is not a stale label: it is an agent branching from, and merging into, the wrong environment's branch — shipping unreviewed code to production, or shipping a production fix into a staging branch where nobody sees it.
+
+So the contract renders the branches **for humans** and recomputes them **for machines**. The rendered section is output. It is never input.
+
+Precedence is therefore not a negotiation: whenever a rendered plan and the resolved environment disagree, **the environment wins** — the authority wins, in every phase, on every vendor, with no exception for a plan a human edited by hand. The only question a disagreement raises is whether to re-render silently (staleness) or stop for a human (a conflict with a confirmed environment or an open PR base). It is never "which branch did they mean?"
+
+## The rendered section
+
+| Vendor | Heading form |
+|---|---|
+| JIRA | `h2. Branch Plan` (ADF heading in live JIRA) |
+| GitHub | `## Branch Plan` |
+| Linear | `## Branch Plan` |
+
+Body, identical on all three:
+
+```
+Branch from: <branch>
+PR into: <branch>
+Derived from: Target Backend Environment <env> via .lisa.config.json deploy.branches
+```
+
+### The derivation provenance line
+
+The third line is load-bearing. It is the discriminator between a section this contract produced and one a human typed, and it is deliberately visible prose rather than an HTML comment — the same reason the `Target Backend Environment` grammar uses visible `Inferred:` / `Assumption:` annotations: JIRA's ADF has no comment node, so a marker that only exists in markdown cannot be a vendor-neutral discriminator.
+
+A `Branch Plan` **without the provenance line is treated as hand-authored**, and hand-authored branches are never obeyed — they are compared against the recomputed plan and, on any disagreement, fail. A provenance line naming an `<env>` that is not an exact configured `deploy.branches` key is itself malformed and fails.
+
+### One branch, two labels
+
+`Branch from` and `PR into` always name the **same branch**. That is not a simplification, it is the invariant `lisa-implement` already implements: the feature branch is cut from `origin/<base>` and the PR targets `<base>`. Both labels exist because operators asked to see both questions answered, and because naming them separately gives the contract somewhere to say they are equal instead of leaving it implicit.
+
+A plan whose two fields name **two different branches** is malformed and fails validation. The case that looks like a counter-example — a bug fixed on a non-integration environment branch that must also reach the integration branch — is handled the way `lisa-implement` already handles it: as a **linked forward cherry-pick follow-up item**, which is its own work item with its own single-branch plan. It is never a divergence inside one plan.
+
+## Derivation algorithm
+
+1. **Resolve the environment.** Use the existing grammar and precedence defined in `config-resolution` and `pre-flight-autofill`: a human-confirmed bare configured key or `Confirmed: <env>` wins; then a validated `Inferred: <env> — evidence: <title|body|reproduction|hostname>`; then `Assumption: <env> — remote default branch <branch>`, or the branch-only `Assumption: remote default branch <branch>` when the reverse-map is not unique. This rule adds no new resolution logic and no new aliases.
+2. **Map forward.** Look the exact configured key up in `deploy.branches`. The key must resolve to exactly one branch.
+3. **Prove the branch.** The mapped branch must exist on the remote.
+4. **Render.** Both fields to that branch, plus the provenance line naming the `<env>` used.
+
+### Stop conditions
+
+| Condition | Behavior |
+|---|---|
+| No environment resolvable and the item is not exempt | Stop — the `Target Backend Environment` gate (S8) already owns this |
+| Environment key absent from `deploy.branches` | Stop |
+| Mapping ambiguous / not unique | Stop |
+| Mapped branch missing on the remote | Stop |
+
+**Never guess.** There is no fallback that quietly substitutes `main`, the remote default branch, or the branch of a sibling environment to keep a write from failing — a silent guess here is the exact failure this contract exists to prevent, and a stopped write is cheap next to a wrong-branch merge. The remote default branch enters only through the `Assumption:` form the environment grammar already defines, and only recorded as an assumption.
+
+## The exemption is declared, never inferred from absence
+
+`runtime_behavior_change` is what S8, S11, S14, and S19 all branch on, and it began life as a **caller-asserted validator input** — the three validators still list it under "Behavioral flags — caller asserts these". Nothing ever persisted it. But the live-item path says: fetch the item, *parse the body sections, derive the spec fields*, then run the gates — and this one field could not be derived from anything the writer had stored. So on re-validation the gate believed whatever the caller claimed about the item it was supposedly checking. `lisa-*-verify` could not produce a truthful verdict, and neither could a human auditor reading the item.
+
+Absence could not stand in for the flag either, because absence is what the two opposite cases look like. An item with no `Target Backend Environment` is either correctly exempt or wrongly missing a required section, and nothing on the item told them apart.
+
+So the flag is persisted, in the section it is already about. **`Target Backend Environment` is rendered on every leaf**, and its content carries the declaration:
+
+| Content | `runtime_behavior_change` | Meaning |
+|---|---|---|
+| An exact configured `deploy.branches` key — bare, `Confirmed:`, `Inferred:`, or `Assumption:` per the environment grammar | `true` | applicable work, targeting that environment |
+| `None — no runtime behavior change: doc-only` (or `config-only`, `type-only`) | `false` | exempt by declaration |
+| `None — container: state rolls up from children` | `false` | an Epic/Project, or an item holding child work |
+| The section is absent | **underivable** | a legacy item written before this contract |
+
+The `None —` prefix is the machine discriminator; the words after it are for the human reading the item. It is deliberately **visible prose rather than an HTML comment**, for exactly the reason the provenance line is: JIRA's ADF has no comment node, so a marker that only exists in markdown cannot be a vendor-neutral discriminator.
+
+**Persisted beats asserted.** On a live item the stored declaration is authoritative. A caller asserting a `runtime_behavior_change` that contradicts it does not override it — the disagreement fails S8, naming both values, because one of the two is wrong and silently preferring either is how an unauditable gate gets built. On a *proposed* spec nothing is persisted yet, so the caller's assertion is the input and the writer's job is to render it.
+
+**Underivable is its own verdict, never `false`.** A legacy item with no section gets `N/A` plus a repair note from every flag-dependent gate, repaired at claim time beside the legacy branch-plan repair — the same asymmetry, for the same reason. What must never happen is reading absence as `false`, which is the silent assumption that made S8, S11, S14, and S19 undecidable on a live item in the first place.
+
+### How strongly this binds
+
+Stated plainly, because the session that produced this contract exists to make exactly this distinction and it would be dishonest to blur it here.
+
+This is **not** an executable control. `ready-role-filing`'s sibling guard is a hook that exits 2 and physically refuses a tool call; nothing here refuses anything. What enforces this contract is a validator agent reading `SKILL.md` and choosing to apply it — the same rung of the ladder that failed to bind 13 filings out of 13.
+
+The regression suite has two halves. **Why they bind differently is `falsifiable-checks`' subject, not this rule's** — read the quantifier guidance there. What belongs here is the measurement, because this contract happens to be where it was taken.
+
+- `runtime-behavior-change-decidability.test.ts` asserts the wording is *present* across all six generated skill roots. It pins the contract against silent deletion or a lossy regeneration, and proves nothing about any particular copy.
+- `runtime-behavior-change-consistency.test.ts` asserts no copy says the *wrong* thing, over every occurrence in the corpus: every declaration marker uses the em-dash discriminator, every absence-derivation site resolves to *underivable* within its own sentence, and no phrasing maps an absent section to `false` or hands authority back to the caller.
+
+This document states its rule **twice** — once in gate S8, once in the execution step — which is what made the gap observable. `lisa-linear-validate-issue` once spelled the discriminator with an ASCII hyphen in its execution step while its own S8 used the em-dash, and 192 assertions stayed green through that mutation twice running. The fix pinned the execution step and left S8's copy bare. Mutating each site separately, whole suite, before and after the second half landed:
+
+| mutated site | before | after |
+|---|---|---|
+| execution step reads an absent section as `false` | 18 | 36 |
+| **gate S8's prose reads an absent section as `false`** | **0** | **18** |
+| writers stop rendering the section | 36 | 54 |
+| a caller's assertion beats the stored declaration | 18 | 36 |
+
+Zero out of 11,270 — same file, same rule, same commit, one site pinned and its twin bare.
+
+(The wrong spelling is deliberately not written out above. This section sits inside the corpus the consistency suite scans, and the first draft of it quoted the defect as an illustration and failed its own check.)
+
+**The executable half of this contract is nothing.** Both suites read markdown. `SKILL.md` *is* the validators' execution substrate — there is no compiled artifact underneath to attach a hook to, so there is no function to call and no return value to assert. What they prove is that the instruction the agent reads is internally consistent; what neither can prove is that the agent then obeys it. Absence-as-`false` was undecidable, is now *decidable* and *non-contradictory*, and both of those are strictly weaker than *enforced*. Treat a gate verdict resting on this contract as evidence, not proof, until a deterministic checker exists to read the declaration off a live item.
+
+This costs nothing in derivation difficulty. A single-environment project — Lisa itself is one, `deploy.branches: { production: main }` — recomputes every applicable item to the same branch. The gate was never hard to satisfy; it was impossible to *audit*, and those are different problems with different fixes. Weakening S19 would have fixed neither.
+
+## Gate S19 — Branch Plan derivation
+
+Registered in all three validators as `| S19 Branch Plan derivation | technical | false |`. The gate **recomputes** the plan from current config and compares; it never reads the rendered branches as input.
+
+| Case | Verdict |
+|---|---|
+| Exempt work (`runtime_behavior_change = false`, or a container) with no plan | `N/A` |
+| Exempt work **carrying** a plan | **FAIL** — hand-authored branches on work that declared no runtime target |
+| `runtime_behavior_change` **underivable** (live legacy item, no Target Backend Environment declaration) | `N/A` with a repair note — absence is never read as `false` |
+| Applicable work, plan present, matches recomputed plan | PASS |
+| Applicable work, plan present, disagrees with recomputed plan | **FAIL** |
+| Applicable work, plan present, missing the provenance line and disagreeing | **FAIL** (hand-authored) |
+| Applicable work, two fields naming different branches | **FAIL** — malformed |
+| Applicable work, derivation hits a stop condition | **FAIL** — same stop as implement |
+| Applicable work, **proposed spec** (pre-write) with no plan | **FAIL** — the writer must render it before the write |
+| Applicable work, **live legacy item** with no plan | `N/A` with a repair note routed to claim time |
+
+The last two rows are the asymmetry that matters. Failing a *proposed* spec is free — the writer just renders the section. Failing every *existing* item would turn a whole legacy queue red overnight for a section no human ever had a way to add, so those are repaired at claim time instead, where the derivation is written onto the item as evidence.
+
+### Failure remediation
+
+Every S19 failure names both plans (rendered and recomputed) and points the fix at **the environment, never the branches**:
+
+> Branch Plan conflicts with the environment mapping. Rendered `Branch from: release/staging`; recomputed from `Target Backend Environment: production` via `deploy.branches` → `main`. Correct the environment, not the branch — the branches are derived. Then re-render.
+
+The gate never silently chooses between the two. Picking one would be a guess wearing a verdict.
+
+## Claim-time behavior (`lisa-implement`)
+
+At claim time the plan is recomputed against **current config and the remote** — never trusted from the item — and one of four arms runs:
+
+- **Match** — proceed. The already-existing base-branch validation, feature-branch sync, and `target_branch=<base>` handoff are unchanged.
+- **Legacy (no plan)** — derive it, **write the assumption onto the item as a comment**, then proceed. The comment carries a visible prose line plus a dedupe marker so a re-claim produces no duplicate:
+
+  ```
+  Branch plan derived for this item: branch from `main`, PR into `main` (Target Backend
+  Environment: production via .lisa.config.json deploy.branches).
+  <!-- [lisa-branch-plan] key=<work-item-ref>::<branch> -->
+  ```
+
+  Marker-dedupe is on `<work-item-ref>::<branch>`, so the comment reappears only if the derived branch actually changes. Where a vendor cannot host an HTML comment, the visible line alone carries it. If the comment cannot be written, that is a stop, not a shrug — proceeding would make it exactly the silent guess this rule forbids.
+- **Conflict with a human-confirmed environment, or with an existing open PR's base** — **stop under the existing confirmation rules**. `lisa-implement` already surfaces a PR-base mismatch and re-targets only with confirmation, on the stated grounds that the ticket's environment is the source of truth; a branch plan never overrides that, and never supplies the confirmation itself.
+- **Stale (config changed since the plan was rendered)** — **current config wins**. Re-render the section onto the item, record the change, and never follow the stale plan. A stale plan is not a conflict to escalate; it is output that fell behind its input.
+
+## Why the gate is `technical` / not product-relevant
+
+S19 is categorized `technical`, `product_relevant: false`, matching S8 — the fact it checks is a deployment-topology fact, and a PRD-intake comment aimed at a product author cannot act on it. The operator-facing value of the section is that it is *visible on the item*, not that its failures are routed to product.
+
+## What this rule deliberately does not do
+
+- It defines **no new environment resolution**, no new aliases, and no new provenance grammar. All of that stays in `config-resolution` / `pre-flight-autofill`, and this rule reads the result.
+- It does **not** let a branch plan influence which environment is chosen, in any direction, at any phase.
+- It does **not** introduce branch fields on PRDs. PRDs are not built directly; their generated leaves carry the plan.

package/plugins/lisa-devin/rules/reference/design-source-of-truth.md

@@ -0,0 +1,260 @@
+# Design Source of Truth
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Design Source of Truth (load-bearing)
+
+**When enabled, Figma is the design source of truth, and every UI surface a change touches declares where its design came from.** A changed UI surface that neither cites a Figma node nor carries the designated marker is a contract violation — and so is a surface whose declaration the gate cannot resolve.
+
+**One vendor-neutral contract, cited by** `lisa-implement`, `lisa-tdd-implementation`, `lisa-review-local`, `lisa-quality-review`, and `lisa-tracker-source-artifacts` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-skill prose).
+
+## Explicit project opt-out
+
+A project with **no design source at all** may set this in `.lisa.config.json`:
+
+```json
+{ "designSource": { "enabled": false } }
+```
+
+Only `designSource.enabled` set to boolean `false` opts out. Absent, true, and
+invalid values retain the default enforcement. The explicit configuration is
+the auditable record; it replaces per-file exception markers for this project.
+The gate exits 0 with `SKIPPED: designSource.enabled=false` before resolving the
+diff. JSON output reports `verdict: "SKIPPED"`, the config key in `reasons`, and
+zero judged surfaces. A skip does not claim that surfaces passed inspection.
+
+When opted out, the five consuming skills omit the design-source step from
+plans, tickets, teammate instructions, and review; they do not ask for markers,
+Figma nodes, or Figma access for this obligation. All declaration, sync-back,
+and fail-closed requirements below apply only when enabled. Host design-system
+rules, `design-value-binding`, and `bdd-e2e-coverage` remain independent and
+unchanged. A project that has Figma must still not use `exclude` to hide its UI
+tree from this contract.
+
+## Membership
+
+Membership is **surface, not repo name or file extension**: a file is in scope the moment a change makes it render something user-observable — a screen, component, layout, style token, visual state, or markup a user reads. Barrels, pure-logic modules, tests, stories, generated output, and vendored code are out. Projects narrow or widen the default detection through `designSource.include` / `designSource.exclude` in `.lisa.config.json`; those filters never turn the obligation off. Only the explicit project opt-out above does.
+
+## The two declarations
+
+Exactly one of these, written as an ordinary comment in whatever syntax the file uses:
+
+| Form | Means |
+|---|---|
+| `DESIGN-SOURCE: <figma-url>` | The surface is backed by a Figma node — it already existed there, or it was synced back. |
+| `DESIGN-SOURCE: none — not in Figma` | The surface is deliberately not captured at the design source. |
+
+The marker's spelling is fixed and load-bearing; a drifted spelling silently disarms the gate. An optional trailing ` — <reason>` records why. Only a `figma.com` URL seals a surface: a link to a screenshot, a Slack thread, or any other mock is **malformed**, not proof.
+
+## Sync-back is the default; the marker is the exception, not the default
+
+When the flow has proven Figma access (the `tool-access-gate` probe), reflecting the surface in Figma and citing the node is the expected outcome. Reach for the marker only when the surface genuinely does not belong in the design source — a debug affordance, a dev-only playground, a throwaway internal tool. The gate reports every marked exception so review can challenge it, and reports a reasonless exception separately when Figma access was available.
+
+## Host design-system rules stay authoritative
+
+Projects that carry their own design-system rules (`figma-design-system`, `design-system`, `use-the-design-library`, or an equivalent) keep them. This contract never restates component hierarchy, token vocabulary, or reuse policy, and never overrides them. It asks one orthogonal question the host rules do not: is the design source declared?
+
+## The gate fails closed
+
+`scripts/design-source-gate.mjs` decides the change deterministically. It fails on an undeclared surface, a malformed annotation, a file that both cites Figma and denies having a source, a changed file it could not read, and a diff it could not compute. **A design-source violation is a blocking review finding, never a warning** — it is not demoted to "optional", "if cheap", or a follow-up. A gate that passes on what it could not read proves nothing, so it never does.
+
+## Bootstrap and degradation
+
+Adoption never demands a retroactive backfill: the gate judges **only the surfaces this change touched**. Pre-existing unannotated UI is burndown, recorded and worked down, not this work item's blocker. A project with no design source may use the explicit project opt-out above; otherwise every changed surface still needs a declaration. Behavior obligations for the same surfaces are unchanged and still governed by `bdd-e2e-coverage`.
+
+---
+
+Design has always leaked in one direction. A ticket arrives with a Figma frame, the frame gets
+built, and then — during implementation, during a bug fix, during a "quick" empty state nobody
+specified — new UI gets invented directly in code. Nothing ever carries it back. A year later the
+Figma file describes a product that no longer exists, and the only way to answer "what is this
+screen supposed to look like?" is to read the code, which is precisely the question the design
+source was supposed to answer.
+
+Lisa had every design obligation conditioned on a design artifact *already existing*. Ticket gate
+S12 fires only `when artifacts_attached = true`. `work-item-definition-of-ready` requires
+design-source precedence "when artifacts exist". `lisa-implement` treats a linked Figma file as a
+required tool and hard-stops when access to it fails. The nearest adjacent behavior —
+`lisa-tracker-source-artifacts` asking UI tickets to flag design-vs-code divergence — files that
+divergence as a *ticket comment*, which closes with the ticket.
+
+Every one of those is about UI that has a source. **None of them govern UI that has none.** That is
+the gap this contract closes, and it closes it on the code side, where the invented UI actually
+lives.
+
+## What the contract asks
+
+One question, per UI surface a change touches: **where did this design come from?**
+
+Not "is it pretty", not "does it use the right token", not "should this component exist" — those are
+the host design system's questions, and it answers them far better than a vendor-neutral contract
+could. This contract asks only whether the answer to the provenance question is written down.
+
+## Membership
+
+A file is a UI surface when a change makes it render something user-observable: a screen,
+component, layout, style token, visual state, or markup a user reads. The gate's default detection
+is two-tier, and the split is deliberate:
+
+- **Extensions that always render** — `.tsx`, `.jsx`, `.vue`, `.svelte` — count wherever they live.
+- **Markup and style extensions** — `.css`, `.scss`, `.sass`, `.less`, `.styl`, `.html`, `.erb`,
+  `.haml`, `.slim`, `.swift`, `.kt`, `.dart`, `.xml` — count only inside a rendering directory
+  (`components`, `screens`, `views`, `pages`, `ui`, `widgets`, `layouts`, `templates`, `atoms`,
+  `molecules`, `organisms`).
+
+The second tier is why a `.ts` barrel under `components/` is out: `src/components/atoms/index.ts`
+re-exports and renders nothing, so demanding a design source from it would be noise, and noise is
+how a gate earns its way into an ignore list. Tests, specs, stories, snapshots, `.d.ts` declarations,
+`node_modules`, and build output are excluded for the same reason.
+
+Projects tune this in `.lisa.config.json`:
+
+```json
+{
+  "designSource": {
+    "include": ["**/*.mjml"],
+    "exclude": ["src/legacy/**"]
+  }
+}
+```
+
+`include` widens the surface; `exclude` narrows it. Neither turns the obligation off — a project that
+excluded its whole UI tree would be declaring it has no UI, which review can see.
+
+## The marker grammar
+
+Exactly one declaration per file, written as an ordinary comment in whatever syntax the file already
+uses. The gate reads the annotation, not the comment characters around it, so all of these are the
+same declaration:
+
+```tsx
+// DESIGN-SOURCE: https://www.figma.com/design/AbC123/Checkout?node-id=412-1187
+```
+
+```css
+/* DESIGN-SOURCE: none — not in Figma */
+```
+
+```svelte
+<!-- DESIGN-SOURCE: none — not in Figma — internal-only debug affordance -->
+```
+
+### `DESIGN-SOURCE: <figma-url>` — sealed
+
+The surface is backed by a design node. Only a `figma.com` URL counts. A screenshot link, a Slack
+permalink, a Jira attachment, or a path to a PNG in the repo is **malformed**, not proof: those are
+copies of a design, and a copy cannot be updated when the design changes. Prefer a URL carrying a
+`node-id` so the citation resolves to the frame rather than the file.
+
+### `DESIGN-SOURCE: none — not in Figma` — the recorded exception
+
+The spelling is fixed, including the em dash, and it is load-bearing: the gate, the rule, the review
+path, and the implement path all cite the same string, so a drifted spelling silently disarms the
+gate rather than failing loudly. An optional trailing ` — <reason>` records why the surface is not
+captured at the source, and the gate surfaces reasonless markers separately (below).
+
+### Everything else
+
+`DESIGN-SOURCE:` followed by anything that is neither form is **malformed** and fails. This is not
+pedantry — it is what stops the annotation from degrading into a comment that says "design source:
+ask Priya" and passes. **Silence is a violation, never a pass.**
+
+A file that carries both a Figma URL and the none-marker is **conflicting** and fails. It is
+asserting two contradictory things about the same surface, and the gate does not pick a winner.
+
+## Sync-back is the default
+
+The order of preference is not decorative:
+
+1. **The surface already exists in Figma.** Cite the node. Nothing else to do.
+2. **Figma access is available and the surface belongs in the design source.** Reflect it in Figma,
+   then cite the node. This is the expected outcome for real product UI, and the whole reason the
+   `tool-access-gate` probe enumerates Figma as a required tool when the work item links one.
+3. **The surface genuinely does not belong in the design source.** Mark it. Debug affordances,
+   dev-only playgrounds, internal tooling, and diagnostics live here.
+
+The marker is the exception, not the default. When Figma access has been proven and a marked
+exception records no reason, the gate reports it under `syncBackPreferred` — non-blocking, because
+turning a preference into a second hard gate would make the honest exception more expensive than a
+copy-pasted Figma link, which is exactly the wrong incentive. It is a review prompt: *you could have
+synced this back — why didn't you?*
+
+## Host design-system rules stay authoritative
+
+Several Lisa host projects already carry a design-system rule of their own —
+`figma-design-system.md`, `design-system.md`, `use-the-design-library.md`. Those files are
+**host-owned**. They define the component hierarchy, the closed token vocabulary, the atom layer,
+the escape hatches, and the lint manifest that enforces all of it, and they are specific to a product
+in ways no shared contract can or should be.
+
+**This contract governs whether the design source is declared, never what to build.** It adds one
+orthogonal obligation on top of whatever the host rule already says. Where a host rule already
+mandates a Figma mapping, this contract is satisfied by that mapping — cite the node and move on.
+
+Two consequences worth stating plainly:
+
+- **Do not duplicate host content into this contract, and do not rewrite host rules to restate this
+  one.** Wire them: the host rule points at this slug for the provenance obligation, this contract
+  points at the host rule for everything else.
+- **Several host design-system rules are generated artifacts** carrying a "generated from
+  `docs/design-system-rfc.md` — do not edit this file directly" provenance header. Respect it:
+  **amend the RFC and regenerate.** A hand-edit to a generated rule is lost on the next
+  regeneration, which is worse than not making the change at all, because it looks like it shipped.
+
+## Gate semantics
+
+`scripts/design-source-gate.mjs` is the executable arm of this contract, and it **fails closed**.
+
+```
+node design-source-gate.mjs --base=origin/main [--head=HEAD] [--figma-access] [--json]
+```
+
+Exit `0` = PASS or explicit SKIPPED, `1` = FAIL, `2` = usage error. When enabled, it classifies every changed file into one status:
+
+| Status | Verdict | Meaning |
+|---|---|---|
+| `figma-source` | pass | Sealed by a Figma node. |
+| `marked-exception` | pass | Explicitly declared as not captured at the source. |
+| `not-applicable` | pass | Not a UI surface, or a deletion — nothing to declare. |
+| `undeclared` | **fail** | A UI surface with no annotation at all. |
+| `malformed` | **fail** | An annotation whose value is neither form. |
+| `conflicting` | **fail** | Cites Figma *and* denies having a source. |
+| `unreadable` | **fail** | The changed file could not be read. |
+
+Plus two change-level failures that exist purely so the gate cannot pass on ignorance:
+`changed-files-unresolved` (the file list never materialized) and `diff-unresolved` (git could not
+compute the range). **A gate that returns PASS when it could not look proves nothing.** This is the
+same discipline `claim-evidence-mapping` applies to verification evidence and `bdd-e2e-coverage`
+applies to a missing runner: the absence of a check is never a passing check.
+
+The gate aggregates — it reports every violating file, not the first one — so a single run tells the
+implementer everything they need to fix.
+
+## Where it is enforced
+
+- **`lisa-implement`** — building or changing a UI surface includes declaring its design source, and
+  the sync-back preference applies while the work is being done, when reflecting the surface in Figma
+  is cheap. The `tool-access-gate` probe already establishes whether Figma access exists.
+- **`lisa-tdd-implementation`** — the declaration lands with the implementation, in the same commit
+  as the surface it describes.
+- **`lisa-review-local` and `lisa-quality-review`** — the gate runs on the branch diff, and a FAIL is
+  a **blocking** finding. It qualifies under `convergent-review` because it names a concrete failure
+  scenario: the design source silently diverges from the shipped product, and nobody can tell which
+  one is authoritative.
+- **`lisa-tracker-source-artifacts`** — its existing design-vs-code divergence note covers the
+  *ticket* side of the same event. It points here for the code side, so the two are one behavior
+  rather than two half-behaviors.
+
+## Bootstrap and degradation
+
+Adoption is never a backfill project. The gate judges only the surfaces the current change touched,
+so a repository with hundreds of unannotated legacy components can adopt the contract on a Tuesday
+and be green on Tuesday. Pre-existing unannotated UI is **burndown**: recorded, worked down
+opportunistically as files are touched, never treated as the current work item's blocker.
+
+A project with no design source may opt out explicitly using `designSource.enabled: false`.
+Without that explicit opt-out, every changed surface still declares its source. In an enabled
+project, deleting or excluding a surface to make the gate green is a violation of the same kind as
+deleting a BDD scenario to improve coverage: mark it, do not drop it.