@codyswann/lisa 3.3.0 → 3.4.1

package/plugins/lisa-agy/hooks/block-no-verify.agy.sh

@@ -102,16 +102,65 @@ def disables_verification(token):
         and NO_VERIFY.startswith(token)
     )
 
+# The only relocations that keep a repo's own hooks in play. Anything else —
+# including "" and /dev/null, which are simply the two most obvious members of
+# the blocked set rather than special cases — is refused.
+PERMITTED_HOOKS_PATHS = {".husky", ".githooks"}
+
+
+def is_permitted_hooks_path(value):
+    """Whether a core.hooksPath value relocates hooks rather than disabling them.
+
+    Args:
+        value: The raw core.hooksPath value as it appeared on the command line.
+
+    Returns:
+        True if the path is an established in-repo hooks directory.
+    """
+    cleaned = value.strip().strip("'\"")
+    if cleaned.startswith("./"):
+        cleaned = cleaned[2:]
+    return cleaned.rstrip("/") in PERMITTED_HOOKS_PATHS
+
+
 for i, token in enumerate(normalized_tokens):
     if disables_verification(token):
         sys.exit(1)
     if token == "HUSKY=0" or token.startswith("HUSKY_SKIP_HOOKS="):
         sys.exit(1)
-    if token.startswith("core.hooksPath="):
-        value = token.split("=", 1)[1]
-        if value in ("", "/dev/null"):
+    # Allowlist the destinations, do not denylist the disabling ones: hooks are
+    # disabled just as completely by any directory that happens to contain none
+    # (`-c core.hooksPath=/tmp/empty`), so the set that DISABLES hooks is
+    # unbounded while the set that legitimately relocates them is tiny. Matched
+    # case-insensitively because git config names are.
+    lowered = token.lower()
+    if lowered.startswith("core.hookspath="):
+        if not is_permitted_hooks_path(token.split("=", 1)[1]):
+            sys.exit(1)
+    if lowered == "core.hookspath" and i + 1 < len(normalized_tokens):
+        if not is_permitted_hooks_path(normalized_tokens[i + 1]):
+            sys.exit(1)
+    # `--config-env=core.hooksPath=SOMEVAR` reads the path out of the named env
+    # var, so it is not in the command at all and cannot be allowlisted.
+    if lowered.startswith("--config-env="):
+        spec = token.split("=", 1)[1]
+        if spec.split("=", 1)[0].strip().lower() == "core.hookspath":
+            sys.exit(1)
+    # git also accepts `--config-env <name>=<envvar>` as two tokens. Guarding
+    # only the `=` spelling let the trailing `core.hooksPath=.husky` fall
+    # through to the allowlist above, which reads `.husky` as a path — but here
+    # it names an ENVIRONMENT VARIABLE, which can hold /dev/null. Checked at the
+    # `--config-env` token, which the loop reaches first.
+    if lowered == "--config-env" and i + 1 < len(normalized_tokens):
+        spec = normalized_tokens[i + 1]
+        if spec.split("=", 1)[0].strip().strip("'\"").lower() == "core.hookspath":
             sys.exit(1)
-    if token == "core.hooksPath" and i + 1 < len(normalized_tokens) and normalized_tokens[i + 1] in ("", "/dev/null"):
+    # `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.hooksPath
+    # GIT_CONFIG_VALUE_0=/dev/null git ...` sets the same command-scope config
+    # via env-var-style assignments. The index is arbitrary below
+    # GIT_CONFIG_COUNT, so it is matched as `\d+` rather than pinned to 0.
+    key_match = re.match(r"git_config_key_\d+=(.*)$", lowered, re.DOTALL)
+    if key_match and key_match.group(1).strip().strip("'\"") == "core.hookspath":
         sys.exit(1)
 
 sys.exit(0)

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/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-agy/skills/lisa-implement/SKILL.md

@@ -64,7 +64,7 @@ The input-resolver invokes `lisa-track $ARGUMENTS` and owns its complete resolve
 - **Bind before durable work:** only after the verified claim, run:
 
   ```bash
-  node scripts/lisa-work-item.mjs bind <canonical-ref>
+  node scripts/lisa-work-item.mjs link <canonical-ref>
   ```
 
   Require a successful readback of that worktree-local binding. On detached HEAD, `branch: null` is the expected pending binding; after branch creation the mandatory `attach-branch` step below must replace it before any commit. Tracker or binding failure stops the flow; never continue untracked.
@@ -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-agy/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-agy/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: