@codyswann/lisa 3.2.0 → 3.4.0

package/plugins/lisa-copilot/rules/reference/session-status-updates.md

@@ -0,0 +1,60 @@
+# Session Status Updates — Plain Language, and Always Say If It's Safe to Close
+
+## Why this is a rule and not a style preference
+
+Lisa's premise is that a non-technical person can direct software work by describing outcomes. That premise already binds everything crossing a gate outward — intake rejections, clarifying questions, ticket descriptions, verification reports — because a non-technical operator is standing at the gate.
+
+In-session conversation was never held to the same bar, and the result was a split personality: careful, plain-language ticket prose and simultaneously a stream of chat messages full of file paths, rule slugs, and reasoning narrative. The human reading both is the same human. This rule closes the split.
+
+## The three-part shape
+
+Every update answers, in this order:
+
+1. **What changed** — what is different in the world now that was not before. Shipped, fixed, filed, deployed.
+2. **What's blocked** — using the strict meaning from `not-blocked-just-waiting`. If nothing is blocked, say so; "waiting on the CI run" belongs here labelled as waiting.
+3. **What needs a decision** — see below.
+
+What is deliberately excluded: how you found it. The files you read, the searches you ran, the hypotheses you discarded, the dead ends. That is your working memory, not their update. If they want it they will ask, and the offer to elaborate costs one clause.
+
+## Voice
+
+Write the way you would speak to a competent colleague who does not work on this system.
+
+- Prefer the user-visible name of a thing over its implementation name. "The login page broke" beats "the auth guard regressed at the controller boundary."
+- Do not use Lisa vocabulary (rung, gate, leaf, intake, ratchet) with someone who has not asked for it.
+- Do not use a file path where a description works. Paths are for when the human will open the file.
+- Short sentences. No preamble about what you are about to say.
+
+Two lines the user themselves offered as the target: *"just tell me what's going on and what my options are"* and *"give me the summary, I'll ask for detail if I want it."*
+
+## Decisions
+
+A decision presented as a paragraph of context is a decision the human has to excavate. State it as a decision:
+
+- **The decision** — one sentence naming the choice to be made.
+- **Your recommendation** — you have more context than they do; do not withhold it. Recommending is not deciding.
+- **The ramifications of each option** — one line apiece, in terms of consequences they care about (time, cost, risk, what breaks, what it forecloses), not in terms of implementation.
+
+An option you consider unacceptable is still listed, with the reason it is unacceptable. Presenting one option as if it were the only one is a decision you made on their behalf without saying so.
+
+## The close line
+
+Every update ends with exactly:
+
+```
+Safe to close: yes/no — <reason>
+```
+
+`yes` means killing the session right now loses nothing: work is committed and pushed, tickets are in the state they should be in, nothing is running that will not finish on its own.
+
+`no` names the specific in-flight thing that would be lost. Real examples: a local dev server or test run still going; a ticket filed but not yet flipped to ready, so nothing will pick it up; a commit that exists only in the working tree; a PR whose checks nobody is watching; a deploy mid-flight.
+
+The line exists because the human's most common question — asked or unasked — is "can I close this?" Making them ask it costs a round trip; making them guess costs them work.
+
+## Relationship to the other communication rules
+
+- `report-actionability` governs **completeness**: the denominator, every item accounted for, who acts on each. It is about what a report must contain.
+- `automation-runbook-contract` governs the **outcome line** a terminating flow opens with.
+- This rule governs the **voice** of a session update, its three-part shape, and the close line.
+
+None of the three is relaxed by the others. An update can satisfy all three at once and usually should: outcome line first, denominator stated, plain language throughout, close line last.

package/plugins/lisa-copilot/rules/reference/wiki-knowledge-source.md

@@ -9,13 +9,29 @@ A project has a wiki in one of two shapes:
 
 Either way, freshness is not your concern. The query and ingest skills run `scripts/ensure-wiki.mjs` as their own first step, which resolves the wiki root and — for a remote wiki — clones the mirror if missing and fast-forwards it when stale (subject to a short TTL, and tolerant of being offline: it proceeds with the existing mirror and warns rather than blocking). The freshness guarantee lives in the tool, not in the caller's discipline. Do **not** add a separate "make sure the wiki is current" step to your own workflow — calling the skill already does it.
 
-Before researching project background, conventions, ownership, architecture, glossary terms, or "how/why does X work here":
+## Load posture: on demand, not at session start
 
-1. Consult the wiki first via the wiki query skill (`/lisa-wiki-query`, or the runtime's wiki query skill), which resolves the wiki root for you. For a local wiki you may also start from `wiki/index.md` and follow links.
-2. Use what the wiki says as the authoritative answer when it covers the question. Do not re-derive it from raw sources when the wiki already documents it.
-3. Fall back to primary sources (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe in the code.
+The wiki is **not** read during session bootstrap, and no flow may add a "load the wiki" step to its startup. This is a deliberate reversal of the rule's earlier "consult the wiki first" posture, recorded in `wiki/decisions/2026-08-12-agent-neutral-host-rules-path.md` section 6 (decision D3). The reasoning is context budget: the wiki is deep declarative knowledge, which is the WIKI rung of the learnings ladder precisely *because* it should be paid for only when routed to. Loading it unconditionally converts an on-demand rung into an eager one and charges every session — including the large majority that never ask a knowledge question — for knowledge they do not use.
+
+What survives the softening is discoverability. An agent must **know the wiki exists and know how to query it**, so that a question needing depth goes to the curated answer instead of a fresh scrape of the codebase. What is dropped is the obligation to consult it before every piece of research, and the framing of the wiki as the authority that outranks primary sources.
+
+When you do need project depth:
+
+1. Call the wiki query skill (`/lisa-wiki-query`, or the runtime's equivalent), which resolves the wiki root for you. For a local wiki you may also start from `wiki/index.md` and follow links.
+2. Prefer what the wiki says over re-deriving the same answer from raw sources — that is what it is curated for.
+3. Fall back to primary sources (code, tickets, commit history, external docs) when the wiki is silent, ambiguous, or contradicted by what you observe in the code.
 4. If you find the wiki is wrong, stale, or missing knowledge that belongs there, surface the gap — and where the project's workflow supports it, capture the correction back into the wiki via its ingestion path (`/lisa-wiki-ingest` or equivalent) rather than leaving the knowledge only in this session.
 
 The wiki documents knowledge; it does not override executable behavior. When the wiki and the running code disagree about what the system actually does, trust the code and treat the wiki as out of date. See the `documentation-source-paths` rule for how source-material directories relate to the wiki.
 
-If the project has neither a local `wiki/` nor a `wiki.source` pointer in `.lisa.config.json`, this rule does not apply.
+## Applicability is the plugin gate, not just the wiki content
+
+This rule ships in the **base** plugin, but the skill it directs you to (`lisa-wiki-query`) ships in the **wiki** plugin. Those are gated differently, and for a period a base-only project received this rule pointing at a skill it did not have — a rule with a dangling instruction, which teaches an agent to distrust its rules.
+
+The applicability condition is therefore stated as the *installation* gate rather than as "does a `wiki/` folder exist". The `lisa-wiki` plugin is selected when `wiki/lisa-wiki.config.json` exists **or** `.lisa.config.json` declares a top-level `wiki` key (`src/core/lisa-plugin-selection.ts`); on Claude Code it is additionally gated by `enabledPlugins["lisa-wiki@lisa"]` in `.claude/settings.json`. When that gate is not satisfied:
+
+- This rule does not apply. There is no wiki to query and no query skill to call.
+- The recovery path is `/lisa-wiki-install`, the bootstrap skill that **base** ships precisely so a project that never enabled the wiki plugin can still discover it. Naming a base-shipped skill is what keeps the instruction reachable in every install.
+- **Never block on the absent skill.** Degrade to primary sources and continue, per the same degrade-never-block posture `readiness-rubric` and `rejection-detection` use for surfaces that may not be installed.
+
+A remote-only wiki declared through `wiki.source` is covered by the `wiki` config key, so the pointer form satisfies the same gate.

package/plugins/lisa-copilot/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-copilot/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-copilot/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