@codyswann/lisa 3.2.0 → 3.4.0

package/plugins/lisa/scripts/design-source-gate.mjs

@@ -0,0 +1,530 @@
+#!/usr/bin/env node
+/**
+ * Deterministic, fail-closed gate for the `design-source-of-truth` contract.
+ *
+ * Figma is the design source of truth. Every other Lisa design obligation is
+ * conditioned on a design artifact already existing — ticket gate S12 fires only
+ * `when artifacts_attached = true` — so UI invented straight into code was
+ * governed by nothing at all. This gate governs that case, and only that case:
+ * every UI surface a change touches must declare where its design came from,
+ * in exactly one of two forms.
+ *
+ * ```
+ * // DESIGN-SOURCE: https://www.figma.com/design/<file>?node-id=<node>
+ * // DESIGN-SOURCE: none — not in Figma
+ * ```
+ *
+ * The first says the surface is backed by a design node (it already existed, or
+ * it was synced back). The second says the surface is deliberately not captured
+ * at the source; it is the exception, not the default, and the gate reports
+ * every one of them so review can challenge it.
+ *
+ * **The gate fails closed.** Anything it cannot resolve into one of those two
+ * declarations is a violation: no annotation, a malformed one, a file that both
+ * cites Figma and denies having a source, a changed file it could not read, or
+ * a diff it could not compute. A gate that returns PASS when it could not look
+ * proves nothing, so it never does.
+ *
+ * What this module deliberately does NOT decide is *what to build*. Host
+ * design-system rules (`figma-design-system`, `design-system`,
+ * `use-the-design-library`) own component hierarchy, token vocabulary, and
+ * reuse; several are generated from a ratified RFC. This gate stays orthogonal
+ * to all of it — it asks only whether the design source is declared.
+ *
+ * Run it: `node design-source-gate.mjs --base=origin/main [--head=HEAD] [--json]`
+ * Exit 0 = PASS, 1 = FAIL (any violation, or anything unresolvable), 2 = usage.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+/** The one designated marker for UI deliberately not captured in Figma. */
+export const DESIGN_SOURCE_NONE_MARKER = "DESIGN-SOURCE: none — not in Figma";
+
+/** The annotation keyword, in whatever comment syntax the file uses. */
+const ANNOTATION = /DESIGN-SOURCE:[ \t]*(?<value>[^\n]*)/gu;
+
+/**
+ * The none-form, plus an optional trailing reason. The reason is optional so
+ * the marker's documented spelling stays exactly what the rule prints, but a
+ * reasonless marker is reported for sync-back when Figma access is proven.
+ */
+const NONE_FORM =
+  /^none[ \t]*(?:—|--|–)[ \t]*not in Figma(?:[ \t]*(?:—|--|–)[ \t]*(?<reason>.+?))?[ \t]*(?:-->|\*\/|\*|#)?[ \t]*$/u;
+
+/** Only a Figma URL seals a surface. Any other link is malformed, not proof. */
+const FIGMA_URL = /^https:\/\/(?:[\w-]+\.)*figma\.com\/[^\s)]+$/u;
+
+/** Extensions that are a UI surface wherever they live. */
+const UI_EXTENSIONS = [".tsx", ".jsx", ".vue", ".svelte"];
+
+/**
+ * Markup and style extensions that are a UI surface only inside a directory
+ * that renders. A `.ts` barrel or a pure-logic module under `components/`
+ * renders nothing, so extension-plus-directory keeps the gate off code that has
+ * no design to declare.
+ */
+const UI_MARKUP_EXTENSIONS = [
+  ".css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".styl",
+  ".html",
+  ".erb",
+  ".haml",
+  ".slim",
+  ".swift",
+  ".kt",
+  ".dart",
+  ".xml",
+];
+
+/** Directory names that mark a rendering surface. */
+const UI_DIRECTORIES = [
+  "components",
+  "screens",
+  "views",
+  "pages",
+  "ui",
+  "widgets",
+  "layouts",
+  "templates",
+  "atoms",
+  "molecules",
+  "organisms",
+];
+
+/** Never a UI surface: generated output, vendored code, and test scaffolding. */
+const DEFAULT_EXCLUDES = [
+  "**/node_modules/**",
+  "dist/**",
+  "build/**",
+  "coverage/**",
+  ".next/**",
+  "**/*.d.ts",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*.stories.*",
+  "**/__tests__/**",
+  "**/__snapshots__/**",
+];
+
+/** Change types that carry no head content to annotate. */
+const REMOVED_CHANGE_TYPES = new Set(["deleted", "D", "removed"]);
+
+/**
+ * Translate a `**`/`*` glob into an anchored regular expression. Deliberately
+ * tiny: the gate must run from a plugin directory with no dependency install,
+ * so pulling in a glob library is not an option.
+ *
+ * @param {string} pattern Glob pattern, `/`-separated.
+ * @returns {RegExp} Anchored matcher for a repo-relative path.
+ */
+function globToRegExp(pattern) {
+  // Scanned in one pass rather than chained replacements: a second pass would
+  // re-expand the `*` inside a `.*` it had just emitted, which silently turns
+  // `**/node_modules/**` into a pattern that matches nothing.
+  let body = "";
+  let index = 0;
+
+  while (index < pattern.length) {
+    const char = pattern[index];
+    if (char === "*" && pattern[index + 1] === "*") {
+      const slashed = pattern[index + 2] === "/";
+      body += slashed ? "(?:[^/]*/)*" : ".*";
+      index += slashed ? 3 : 2;
+      continue;
+    }
+    if (char === "*") {
+      body += "[^/]*";
+      index += 1;
+      continue;
+    }
+    if (char === "?") {
+      body += "[^/]";
+      index += 1;
+      continue;
+    }
+    body += ".+^${}()|[]\\".includes(char) ? `\\${char}` : char;
+    index += 1;
+  }
+
+  return new RegExp(`^${body}$`, "u");
+}
+
+/**
+ * @param {string} relPath Repo-relative path.
+ * @param {readonly string[]} patterns Glob patterns to test.
+ * @returns {boolean} True when any pattern matches.
+ */
+function matchesAny(relPath, patterns) {
+  return patterns.some(pattern => globToRegExp(pattern).test(relPath));
+}
+
+/**
+ * @param {string} relPath Repo-relative path.
+ * @returns {string} Lowercased extension including the dot, or "".
+ */
+function extensionOf(relPath) {
+  const base = relPath.slice(relPath.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+
+/**
+ * Decide whether a path is a UI surface — something a user can observe.
+ *
+ * Membership is surface, not repo name or file extension alone: an extension
+ * that always renders counts anywhere, while markup and styles count inside a
+ * rendering directory. Projects narrow or widen this through
+ * `designSource.include` / `designSource.exclude` in `.lisa.config.json`.
+ *
+ * @param {string} relPath Repo-relative path of the changed file.
+ * @param {{ include?: readonly string[], exclude?: readonly string[] } | undefined} [config] Project overrides.
+ * @returns {boolean} True when the path is a UI surface.
+ */
+export function isUiSurface(relPath, config) {
+  if (typeof relPath !== "string" || relPath.length === 0) return false;
+
+  const normalized = relPath.replaceAll("\\", "/");
+  const exclude = [...DEFAULT_EXCLUDES, ...(config?.exclude ?? [])];
+  if (matchesAny(normalized, exclude)) return false;
+
+  const include = config?.include ?? [];
+  if (include.length > 0 && matchesAny(normalized, include)) return true;
+
+  const extension = extensionOf(normalized);
+  if (UI_EXTENSIONS.includes(extension)) return true;
+
+  if (!UI_MARKUP_EXTENSIONS.includes(extension)) return false;
+  const segments = normalized.split("/").slice(0, -1);
+  return segments.some(segment =>
+    UI_DIRECTORIES.includes(segment.toLowerCase())
+  );
+}
+
+/**
+ * Strip a trailing comment terminator so a marker written in block or markup
+ * comment syntax yields the same reason as a line comment would.
+ *
+ * @param {string} value Raw annotation value.
+ * @returns {string} Value with any trailing comment close removed.
+ */
+function stripCommentClose(value) {
+  return value.replace(/[ \t]*(?:-->|\*\/|\*\}|\}\)?|#>)[ \t]*$/u, "").trim();
+}
+
+/**
+ * Read every design-source annotation out of a file body.
+ *
+ * @param {string} content File body at the head of the change.
+ * @returns {{ figma: string[], none: { reason: string | null }[], malformed: string[] }} Parsed annotations.
+ */
+function parseAnnotations(content) {
+  const figma = [];
+  const none = [];
+  const malformed = [];
+
+  for (const match of content.matchAll(ANNOTATION)) {
+    const value = stripCommentClose(match.groups?.value ?? "");
+    const noneMatch = NONE_FORM.exec(value);
+    if (noneMatch) {
+      none.push({ reason: noneMatch.groups?.reason?.trim() || null });
+      continue;
+    }
+    if (FIGMA_URL.test(value)) {
+      figma.push(value);
+      continue;
+    }
+    malformed.push(value);
+  }
+
+  return { figma, none, malformed };
+}
+
+/**
+ * Classify one changed file against the contract.
+ *
+ * Statuses: `figma-source` (sealed), `marked-exception` (declared exception),
+ * `not-applicable` (not a UI surface, or a deletion), and the four failing
+ * states `undeclared`, `malformed`, `conflicting`, and `unreadable`.
+ *
+ * @param {{ path: string, changeType?: string, content?: string | null }} file Changed-file record.
+ * @param {{ include?: readonly string[], exclude?: readonly string[] } | undefined} [config] Project overrides.
+ * @returns {{ path: string, uiSurface: boolean, status: string, evidence: string | null, reason: string | null }} Classification.
+ */
+export function classifyDesignSource(file, config) {
+  const relPath = file?.path ?? "";
+  const notApplicable = {
+    path: relPath,
+    uiSurface: false,
+    status: "not-applicable",
+    evidence: null,
+    reason: null,
+  };
+
+  if (REMOVED_CHANGE_TYPES.has(file?.changeType ?? "")) return notApplicable;
+  if (!isUiSurface(relPath, config)) return notApplicable;
+
+  const base = { path: relPath, uiSurface: true, evidence: null, reason: null };
+
+  if (typeof file?.content !== "string") {
+    return { ...base, status: "unreadable" };
+  }
+
+  const { figma, none, malformed } = parseAnnotations(file.content);
+
+  if (figma.length > 0 && none.length > 0) {
+    return { ...base, status: "conflicting", evidence: figma[0] };
+  }
+  if (malformed.length > 0) {
+    return { ...base, status: "malformed", evidence: malformed[0] };
+  }
+  if (figma.length > 0) {
+    return { ...base, status: "figma-source", evidence: figma[0] };
+  }
+  if (none.length > 0) {
+    return {
+      ...base,
+      status: "marked-exception",
+      evidence: DESIGN_SOURCE_NONE_MARKER,
+      reason: none[0]?.reason ?? null,
+    };
+  }
+  return { ...base, status: "undeclared" };
+}
+
+/** Per-file statuses that fail the gate. */
+const VIOLATION_STATUSES = new Set([
+  "undeclared",
+  "malformed",
+  "conflicting",
+  "unreadable",
+]);
+
+/**
+ * Evaluate a whole change.
+ *
+ * Only the files this change touched are judged — a repo full of unannotated
+ * legacy UI is burndown, not this work item's blocker. But the gate refuses to
+ * pass on ignorance: an unresolved file list or a reported diff error is a FAIL
+ * with a named reason, never a quiet PASS.
+ *
+ * @param {{
+ *   files?: readonly { path: string, changeType?: string, content?: string | null }[] | null,
+ *   diffError?: string | null,
+ *   figmaAccess?: boolean,
+ *   config?: { include?: readonly string[], exclude?: readonly string[] }
+ * }} input Change under evaluation.
+ * @returns {{
+ *   verdict: "PASS" | "FAIL",
+ *   reasons: string[],
+ *   violations: object[],
+ *   exceptions: object[],
+ *   syncBackPreferred: object[],
+ *   sealed: object[],
+ *   notApplicable: object[],
+ *   summary: { judged: number, sealed: number, exceptions: number, violations: number }
+ * }} The gate result.
+ */
+export function evaluateDesignSource(input = {}) {
+  const reasons = [];
+  const files = Array.isArray(input.files) ? input.files : null;
+
+  if (files === null) reasons.push("changed-files-unresolved");
+  if (
+    typeof input.diffError === "string" &&
+    input.diffError.trim().length > 0
+  ) {
+    reasons.push("diff-unresolved");
+  }
+
+  const classified = (files ?? []).map(file =>
+    classifyDesignSource(file, input.config)
+  );
+
+  const sealed = classified.filter(entry => entry.status === "figma-source");
+  const exceptions = classified.filter(
+    entry => entry.status === "marked-exception"
+  );
+  const violations = classified.filter(entry =>
+    VIOLATION_STATUSES.has(entry.status)
+  );
+  const notApplicable = classified.filter(
+    entry => entry.status === "not-applicable"
+  );
+
+  // Sync-back is the preference, not a second blocking gate: when Figma access
+  // is proven, an exception that records no reason is surfaced so review can
+  // ask why it was not captured at the source instead.
+  const syncBackPreferred =
+    input.figmaAccess === true
+      ? exceptions.filter(entry => entry.reason === null)
+      : [];
+
+  for (const entry of violations) reasons.push(`${entry.status}:${entry.path}`);
+
+  return {
+    verdict: reasons.length === 0 ? "PASS" : "FAIL",
+    reasons,
+    violations,
+    exceptions,
+    syncBackPreferred,
+    sealed,
+    notApplicable,
+    summary: {
+      judged: sealed.length + exceptions.length + violations.length,
+      sealed: sealed.length,
+      exceptions: exceptions.length,
+      violations: violations.length,
+    },
+  };
+}
+
+/**
+ * Collect the changed files of a git range, reading each one at the head.
+ *
+ * @param {string} base Base revision.
+ * @param {string} head Head revision.
+ * @returns {{ files: object[] | null, diffError: string | null }} Changed files, or the failure.
+ */
+export function collectChangedFiles(base, head) {
+  let output = "";
+  try {
+    output = execFileSync(
+      "git",
+      ["diff", "--name-status", "--no-renames", `${base}...${head}`],
+      { encoding: "utf8" }
+    );
+  } catch (error) {
+    return { files: null, diffError: String(error?.message ?? error) };
+  }
+
+  const files = output
+    .split("\n")
+    .filter(line => line.trim().length > 0)
+    .map(line => {
+      const [rawStatus, relPath] = line.split("\t");
+      const changeType = rawStatus?.startsWith("D") ? "deleted" : "modified";
+      if (changeType === "deleted") {
+        return { path: relPath ?? "", changeType, content: null };
+      }
+      let content = null;
+      try {
+        content = readFileSync(relPath ?? "", "utf8");
+      } catch {
+        content = null;
+      }
+      return { path: relPath ?? "", changeType, content };
+    });
+
+  return { files, diffError: null };
+}
+
+/**
+ * Read the optional `designSource` block from `.lisa.config.json`.
+ *
+ * @returns {{ include?: string[], exclude?: string[] }} Project overrides, or {}.
+ */
+function readProjectConfig() {
+  try {
+    const raw = JSON.parse(readFileSync(".lisa.config.json", "utf8"));
+    return raw?.designSource ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Render the operator-readable report. Written for the non-technical operator
+ * standing at the gate, so it names the file and the exact next action.
+ *
+ * @param {ReturnType<typeof evaluateDesignSource>} result Gate result.
+ * @returns {string} Report text.
+ */
+export function renderReport(result) {
+  const lines = [`design-source gate: ${result.verdict}`];
+
+  if (result.verdict === "PASS") {
+    lines.push(
+      `  ${result.summary.sealed} surface(s) backed by Figma, ${result.summary.exceptions} explicitly marked as not in Figma.`
+    );
+  }
+
+  for (const entry of result.violations) {
+    lines.push(`  ✗ ${entry.path} — ${entry.status}`);
+  }
+  if (result.violations.length > 0) {
+    lines.push(
+      "",
+      "  Each file above changes something a user can see but does not say where its design came from.",
+      "  Fix it one of two ways, sync-back first:",
+      "    1. Reflect the surface in Figma, then annotate it: `DESIGN-SOURCE: <figma-url>`",
+      `    2. If it genuinely is not captured at the source, annotate: \`${DESIGN_SOURCE_NONE_MARKER}\``
+    );
+  }
+  if (result.reasons.includes("changed-files-unresolved")) {
+    lines.push("  ✗ the set of changed files could not be resolved");
+  }
+  if (result.reasons.includes("diff-unresolved")) {
+    lines.push(
+      "  ✗ the diff could not be computed — the gate cannot pass on a change it could not read"
+    );
+  }
+  for (const entry of result.syncBackPreferred) {
+    lines.push(
+      `  ! ${entry.path} — marked as not in Figma with no reason recorded, and Figma access is available. Prefer syncing it back.`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * CLI entrypoint.
+ *
+ * @param {readonly string[]} argv Arguments after the script name.
+ * @returns {number} Process exit code.
+ */
+export function runCli(argv) {
+  const args = new Map(
+    argv
+      .filter(arg => arg.startsWith("--"))
+      .map(arg => {
+        const eq = arg.indexOf("=");
+        return eq === -1
+          ? [arg.slice(2), "true"]
+          : [arg.slice(2, eq), arg.slice(eq + 1)];
+      })
+  );
+
+  const base = args.get("base");
+  if (!base) {
+    process.stderr.write(
+      "usage: design-source-gate.mjs --base=<ref> [--head=<ref>] [--figma-access] [--json]\n"
+    );
+    return 2;
+  }
+
+  const { files, diffError } = collectChangedFiles(
+    base,
+    args.get("head") ?? "HEAD"
+  );
+  const result = evaluateDesignSource({
+    files,
+    diffError,
+    figmaAccess: args.get("figma-access") === "true",
+    config: readProjectConfig(),
+  });
+
+  process.stdout.write(
+    args.get("json") === "true"
+      ? `${JSON.stringify(result, null, 2)}\n`
+      : `${renderReport(result)}\n`
+  );
+  return result.verdict === "PASS" ? 0 : 1;
+}
+
+if (process.argv[1]?.endsWith("design-source-gate.mjs")) {
+  process.exit(runCli(process.argv.slice(2)));
+}

package/plugins/lisa/skills/lisa-implement/SKILL.md

@@ -155,7 +155,9 @@ IF it is a Fix (bug), execute the Reproduce sub-flow FIRST:
 
 For any Fix flow, and for any Build flow that changes user-visible behavior, regression coverage is a required deliverable at the highest practical observation level for the reported surface. If the project has a browser, device, or end-to-end harness for that platform (for example Playwright, Maestro, Detox, Cypress, or an equivalent runtime), the task plan and definition of done MUST include a deterministic regression spec against the reported surface, using mocked or seeded data where needed. This is alongside unit or integration coverage, not a substitute for it. For **frontend work** the deliverable is defined by the `bdd-e2e-coverage` rule and has two halves, both landing in this PR: the Gherkin scenario (stable ID, required platforms) added or updated in the project's behavior contract, and aligned automation in the project's configured runner for **every** platform that scenario requires — no runner substitutes for another, because they guard different platforms of the same behavior. The coverage gate must pass and the matrix and burndown be regenerated before the item is done. Cite the rule; do not restate its scenario, waiver, or bootstrap mechanics here.
 
-For work that adds or changes **persistent state**, the `reset-seed-coverage` rule adds a second non-demotable deliverable landing in this same PR: every entity the item introduces or changes is classified in the project's state contract (`fixture-owned` / `preserve` / `derived-rebuild` / `forbidden`) with a reason and an owner, anything `fixture-owned` declares its ownership predicate and is actually swept, and the state-classification check passes. Writing a flow that creates a record and deletes it only on its happy path does NOT satisfy this — that is the leak, not the coverage. Cite the rule; do not restate its policy, waiver, or bootstrap mechanics here.
+For work that adds or changes a **UI surface**, the `design-source-of-truth` rule adds a second non-demotable deliverable landing in this same PR: every UI surface the change touches declares where its design came from. Figma is the source of truth, so **prefer sync-back** — if the surface is not in Figma yet and the tool-access preflight proved Figma access, reflect it there and cite the node with `DESIGN-SOURCE: <figma-url>`. Only when the surface genuinely does not belong in the design source (debug affordance, dev-only playground, internal tooling) does it carry the exception marker `DESIGN-SOURCE: none — not in Figma`, ideally with a trailing reason. `scripts/design-source-gate.mjs` decides this deterministically and fails closed on anything it cannot resolve; a FAIL blocks the item exactly as a failing coverage gate does. Host design-system rules (`figma-design-system`, `design-system`, `use-the-design-library`, or the project's equivalent) stay authoritative about *what* to build — this obligation is only about declaring the source. Cite the rule; do not restate its marker grammar, host-precedence, or bootstrap mechanics here.
+
+For work that adds or changes **persistent state**, the `reset-seed-coverage` rule adds a third non-demotable deliverable landing in this same PR: every entity the item introduces or changes is classified in the project's state contract (`fixture-owned` / `preserve` / `derived-rebuild` / `forbidden`) with a reason and an owner, anything `fixture-owned` declares its ownership predicate and is actually swept, and the state-classification check passes. Writing a flow that creates a record and deletes it only on its happy path does NOT satisfy this — that is the leak, not the coverage. Cite the rule; do not restate its policy, waiver, or bootstrap mechanics here.
 
 The team lead may not waive, defer, demote, or phrase this regression spec as "optional", "if cheap", "nice to have", or equivalent. The only permitted exits are:
 

package/plugins/lisa/skills/lisa-quality-review/SKILL.md

@@ -16,6 +16,13 @@ For each changed file, evaluate:
 3. **Test coverage** -- Tests present? Testing behavior, not implementation details? Edge cases covered?
 4. **Documentation** -- JSDoc on new functions explaining "why"? Preambles on new files?
 5. **Code clarity** -- Readable variable names? Unnecessary complexity? Could a new team member understand this?
+6. **Design source** -- For UI surfaces, does each changed file say where its design came from? Run the deterministic gate rather than judging by eye:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/design-source-gate.mjs" --base=main --head=HEAD
+   ```
+
+   Exit 1 is a **Critical** finding under the `design-source-of-truth` rule -- the change is blocked until every UI surface either cites a Figma node (`DESIGN-SOURCE: <figma-url>`, the preferred fix -- sync it back) or carries the exception marker `DESIGN-SOURCE: none — not in Figma`. The gate fails closed: an unreadable file or an uncomputable diff is a FAIL, not a pass. Host design-system rules (`figma-design-system`, `design-system`, `use-the-design-library`, or the project's equivalent) stay authoritative about what to build; this checks only that the source is declared. If the gate script is absent, say so in the review rather than skipping silently.
 
 ## Output Format
 

package/plugins/lisa/skills/lisa-review-local/SKILL.md

@@ -14,6 +14,33 @@ maintainability feedback are non-blocking unless a repository rule or work item
 explicitly makes them release criteria. A blocking finding without a concrete
 failure scenario is malformed and must be filtered out.
 
+One deterministic gate runs ahead of the judgement-based review and is exempt
+from the confidence filtering below, because it is decided by a script rather
+than by an agent's opinion.
+
+**Design-source gate (`design-source-of-truth` rule).** Run it against the
+branch diff before step 1:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/design-source-gate.mjs" --base=main --head=HEAD
+```
+
+Exit 0 = PASS, exit 1 = FAIL. A FAIL is a **blocking** review finding and is
+reported verbatim at the top of the review — it is never scored, never filtered
+by confidence, and never demoted to a nitpick. 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. The gate fails closed, so an unresolvable diff or an unreadable
+file is a FAIL too. Each violation is fixed one of two ways, sync-back first:
+reflect the surface in Figma and cite the node with `DESIGN-SOURCE: <figma-url>`,
+or — only when the surface genuinely does not belong in the design source — mark
+it `DESIGN-SOURCE: none — not in Figma`. Host design-system rules
+(`figma-design-system`, `design-system`, `use-the-design-library`, or the
+project's equivalent) remain authoritative about what to build; this gate only
+asks whether the source is declared. If the gate script is not present (the
+project predates the plugin version that ships it), say so explicitly in the
+review — a silent skip is not one of the exits.
+
 To do this, follow these steps precisely:
 
 1. Use a Haiku agent to check the current git state:

package/plugins/lisa/skills/lisa-tdd-implementation/SKILL.md

@@ -71,6 +71,7 @@ TDD Cycle:
 
 - Write the minimum production code to make the test pass
 - Do not optimize, do not add features beyond what the test requires
+- For any UI surface the implementation adds or changes, the `design-source-of-truth` rule requires its design-source declaration to land in the same commit as the surface it describes — `DESIGN-SOURCE: <figma-url>` when the surface is backed by a Figma node (sync it back first if Figma access exists), or the exception marker `DESIGN-SOURCE: none — not in Figma` when it genuinely is not captured at the source. `scripts/design-source-gate.mjs` fails closed on an undeclared surface. Cite the rule; do not restate its marker grammar here.
 - The goal is the simplest code that makes the test green
 
 ### REFACTOR Phase

package/plugins/lisa/skills/lisa-tracker-source-artifacts/SKILL.md

@@ -93,6 +93,8 @@ Mocks define visual *intent*, not implementation shortcut. Every UI-touching tic
 
 If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation. Lovable-generated components are never the reuse target — always use the project's own components.
 
+The divergence note above covers the **ticket** side of this event. The **code** side is governed by the `design-source-of-truth` rule: a UI surface built with no Figma source behind it is either synced back to Figma and annotated `DESIGN-SOURCE: <figma-url>`, or explicitly marked `DESIGN-SOURCE: none — not in Figma`, and review fails closed if neither happened. Cite the rule for the code obligation rather than restating it here — a ticket comment closes with the ticket, the annotation stays with the surface.
+
 ## 8. Preservation gate (run after creating tickets)
 
 Before declaring done, verify every extracted artifact is reachable from the created tickets.

package/plugins/lisa-agy/plugin.json

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