@lyse-labs/lyse 0.1.0-alpha.2 → 0.2.0-alpha.1

package/rules-manifest.json

@@ -64,18 +64,18 @@
       "id": "tokens/dtcg-conformance",
       "axis": "tokens",
       "defaultSeverity": "warning",
-      "shortDescription": "DTCG v2025.10 conformance for token JSON files",
-      "fullDescription": "Validates token JSON files (`*.tokens.json`, files under `tokens/**`) against the W3C Design Tokens Community Group spec (DTCG v2025.10). Flags tokens missing `$type` when it can be inferred from the value, broken aliases (`{group.token}` references that don't resolve), and composite tokens (shadow, typography, border) with the wrong shape.",
+      "shortDescription": "Strict W3C DTCG validation for token JSON files",
+      "fullDescription": "Validates token JSON files (`*.tokens.json`, files under `tokens/**`) against the W3C Design Tokens Community Group draft. Per-leaf checks: every token must declare `$value` and SHOULD declare `$type`; alias references `{group.name}` must resolve; type-specific values are validated (color = CSS color, dimension = number+unit, fontWeight integer 1-1000 or named, duration = number+unit, cubicBezier = 4-number array or named easing, number = finite number, fontFamily = non-empty string|array). Composite tokens (shadow, typography, border, transition, gradient) are shape-checked.",
       "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/tokens-dtcg-conformance.md",
-      "rationale": "Why it matters\n\nDTCG conformance is the contract between design and code. Non-conformant token files don't survive round-trips through Style Dictionary, Tokens Studio, or Figma Tokens plugins — they silently corrupt theming and break dark-mode propagation.\n\nThe most common drift modes are: tokens with `$value` but no `$type` (Style Dictionary can't infer the right transform), aliases that point to renamed paths after a refactor, and composite shadow tokens with legacy string shapes that no longer parse.",
+      "rationale": "Why it matters\n\nDTCG conformance is the contract between design and code. Non-conformant token files don't survive round-trips through Style Dictionary, Tokens Studio, or Figma Tokens plugins — they silently corrupt theming and break dark-mode propagation.\n\nThe most common drift modes are: tokens with `$value` but no `$type` (Style Dictionary can't infer the right transform), aliases that point to renamed paths after a refactor, type-claimed but malformed values (`$type: \"color\"` with `$value: \"blu\"`, `$type: \"dimension\"` with `$value: \"16\"` — no unit), and composite shadow tokens with legacy string shapes that no longer parse.",
       "examples": [
         {
           "good": "{ \"color\": { \"brand\": { \"$value\": \"#2563eb\", \"$type\": \"color\" } } }",
           "bad": "{ \"color\": { \"brand\": { \"$value\": \"#2563eb\" } } }"
         },
         {
-          "good": "{ \"shadow\": { \"sm\": { \"$type\": \"shadow\", \"$value\": { \"offsetX\": \"0\", \"offsetY\": \"1px\", \"blur\": \"2px\", \"color\": \"rgba(0,0,0,0.1)\" } } } }",
-          "bad": "{ \"shadow\": { \"sm\": { \"$type\": \"shadow\", \"$value\": \"0 1px 2px rgba(0,0,0,0.1)\" } } }"
+          "good": "{ \"spacing\": { \"sm\": { \"$value\": \"8px\", \"$type\": \"dimension\" } } }",
+          "bad": "{ \"spacing\": { \"sm\": { \"$value\": \"8\", \"$type\": \"dimension\" } } } (no unit)"
         },
         {
           "good": "{ \"semantic\": { \"primary\": { \"$value\": \"{color.brand}\", \"$type\": \"color\" } } } (when color.brand exists)",
@@ -85,7 +85,8 @@
       "allowlist": [
         "files matching `*.tokens.json` heuristic but containing only $-prefixed metadata (no $value anywhere) — skipped, not flagged",
         "files larger than 1 MB — skipped to avoid pathological cases",
-        "files matching `ctx.excludePaths` config"
+        "files matching `ctx.excludePaths` config",
+        "tokens declaring `$extensions.lyse.disable: [\"tokens/dtcg-conformance\"]` — skipped per the standard DTCG extension mechanism"
       ]
     },
     {
@@ -130,6 +131,31 @@
         "files matching `designSystem.excludePaths` config"
       ]
     },
+    {
+      "id": "components/contracts-strictness",
+      "axis": "components",
+      "defaultSeverity": "warning",
+      "shortDescription": "Component prop contracts must be strictly typed and .d.ts shipped",
+      "fullDescription": "Scans exported PascalCase components in .tsx/.jsx files for lax TypeScript prop contracts that hinder AI-agent code generation: props typed `any` or `unknown` (error), and variant-like props (name matching variant/size/intent/color/tone/appearance/kind) typed plain `string` instead of a string-literal union (warning). Also checks each publishable package.json for a `types` or `typings` field and that the referenced file exists post-build (warning when missing).",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/components-contracts-strictness.md",
+      "rationale": "Why it matters\n\nAI coding agents and IDE tooling rely on TypeScript prop signatures to suggest valid usages. A prop typed `any` or `unknown` is a black hole — the agent has nothing to constrain its output and falls back to guesses. A variant prop typed plain `string` (`variant: string`) is just as bad: the agent has no way to know the component accepts only `\"primary\" | \"secondary\" | \"ghost\"` and will happily suggest `variant=\"huge\"`.\n\nShipping a `.d.ts` (declared via `package.json` `types` / `typings`) is the same problem at the package boundary: without a declaration file, downstream consumers and agents fall back to untyped any-mode and lose every guarantee the source code put in.\n\nThe rule errors on `any` / `unknown` because those are silent footguns. It warns on variant-string and missing `.d.ts` because there are legitimate (if narrow) reasons to leave them, and because the auto-fix path differs from the unsafe types.",
+      "examples": [
+        {
+          "good": "type ButtonVariant = \"primary\" | \"secondary\" | \"ghost\";\ninterface ButtonProps { variant: ButtonVariant; size: \"sm\" | \"md\" | \"lg\"; }\nexport function Button(props: ButtonProps) { return <button />; }",
+          "bad": "interface ButtonProps { variant: string; size: any; data: unknown; }\nexport function Button(props: ButtonProps) { return <button />; }"
+        },
+        {
+          "good": "{ \"name\": \"@acme/ui\", \"main\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" }",
+          "bad": "{ \"name\": \"@acme/ui\", \"main\": \"./dist/index.js\" }"
+        }
+      ],
+      "allowlist": [
+        "framework-allowed props: `children`, `ref`, `key`, `as`, `asChild` (rest-spread `...rest` and ref-forwarded types are skipped)",
+        "private packages (`\"private\": true`) and non-publishable package.json files (no `name`/`main`/`module`/`exports`/`types`/`typings`)",
+        "test files (.test.tsx, .spec.tsx)",
+        "inline `// lyse-disable-next-line components/contracts-strictness` directive (handled by the global suppression engine)"
+      ]
+    },
     {
       "id": "naming/component-pascalcase",
       "axis": "components",
@@ -284,6 +310,405 @@
         "repos with no `componentsModule` configured or auto-detected — rule is N/A",
         "indexes using `export * from ...` — accepted without counting named exports"
       ]
+    },
+    {
+      "id": "ai-surface/mcp-config-present",
+      "axis": "ai-surface",
+      "defaultSeverity": "warning",
+      "shortDescription": "Design system should declare at least one MCP server",
+      "fullDescription": "Looks for an MCP (Model Context Protocol) configuration file at the repo root: `.mcp.json` (Claude Code convention), `.cursor/mcp.json` (Cursor convention), or `claude_desktop_config.json`. When found, validates the file is parseable JSON, has a top-level `mcpServers` object with at least one entry, and each server entry has a non-empty string key and a `command` (string); `args` (array) is optional. Absence emits one warning (DS not yet AI-agent-accessible). Malformed JSON, missing/empty `mcpServers`, or invalid server entries emit errors.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-mcp-config-present.md",
+      "rationale": "Why it matters\n\nThe Model Context Protocol (MCP) is the de-facto standard for letting coding agents (Claude Code, Cursor, Claude Desktop) call tools that surface a design system's components, tokens, and docs at lookup time. A design system without an MCP server declaration leaves agents to scrape README and source files heuristically — the cost-vs-accuracy regression documented in Stream 1 of the AI-Consumable track.\n\nThe signal is binary and cheap to enforce: either the repo declares at least one valid `mcpServers` entry or it doesn't. A warning (not info) reflects the strategic importance of AI-Consumable readiness for Track 2 design systems: shipping a stable MCP surface is now table-stakes.\n\nSeverity escalates to error when a config file is present but malformed — a broken `.mcp.json` silently breaks every agent that tries to connect, which is worse than no config at all.",
+      "examples": [
+        {
+          "good": "{ \"mcpServers\": { \"lyse\": { \"command\": \"npx\", \"args\": [\"@lyse-labs/lyse\", \"mcp\"] } } }",
+          "bad": "{ \"mcpServers\": {} }"
+        },
+        {
+          "good": "{ \"mcpServers\": { \"design-system\": { \"command\": \"node\", \"args\": [\"./mcp-server.js\"] } } }",
+          "bad": "{ \"servers\": [] }"
+        }
+      ],
+      "allowlist": [
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "repos containing `// lyse-disable ai-surface/mcp-config-present` in an adjacent README — rule is N/A"
+      ]
+    },
+    {
+      "id": "ai-surface/llms-txt-structure",
+      "axis": "ai-surface",
+      "defaultSeverity": "warning",
+      "shortDescription": "llms.txt at repo root must follow the llmstxt.org structure",
+      "fullDescription": "Detects whether a design-system repository ships an `llms.txt` file at the repo root and validates the file's structure against the llmstxt.org specification: a single `# <title>` H1, a `> <summary>` blockquote, and at least one `## <section>` heading whose list items follow `- [<title>](<url>): <description>`. Absence emits a warning. A present-but-malformed `llms.txt` emits one error per structural issue. The optional companion file `llms-full.txt` is detected as a bonus signal but is not required.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-llms-txt-structure.md",
+      "rationale": "Why it matters\n\n`llms.txt` (llmstxt.org, Tantum 2024) is the emerging convention for handing AI agents a token-cheap, curated map of a project. For a design system this is the AI-Consumable surface: a single discoverable entry that lists the canonical Quickstart, API reference, component index, and policy docs without forcing the agent to crawl the whole repo.\n\nAbsence is a missed opportunity, not a bug — agents fall back to scanning the README and source tree, which is slower and more expensive. Structural errors (missing H1, missing summary, malformed link rows) are scored as errors because consumers (cursor, claude code, custom agents) parse the file on the assumption it follows the spec, and silent malformations break the contract.\n\nThe companion `llms-full.txt` — a single-file inlining of every linked document — is a strong bonus signal but is not enforced as a hard requirement.",
+      "examples": [
+        {
+          "good": "# Acme DS\n\n> A token-first React design system.\n\n## Docs\n\n- [Quickstart](https://acme.dev/quickstart): Get started in 3 minutes.\n- [API reference](https://acme.dev/api): Full method index.",
+          "bad": "Welcome to Acme DS. We ship Buttons and Cards.\n\n- random link list"
+        }
+      ],
+      "allowlist": [
+        "files larger than 1 MB at `llms.txt` — skipped to avoid pathological cases",
+        "repos whose README at the root contains the directive `lyse-disable ai-surface/llms-txt-structure` — rule is N/A"
+      ]
+    },
+    {
+      "id": "ai-surface/shadcn-registry-valid",
+      "axis": "ai-surface",
+      "defaultSeverity": "warning",
+      "shortDescription": "shadcn-style registry.json must be present and valid",
+      "fullDescription": "Detects whether the design system ships a shadcn-style component registry — `registry.json` at the repo root, `public/registry.json` (Next.js-hosted), or per-component `registry/*.json` files. Validates the minimal shadcn shape: each item must have `name` (string), `type` (e.g. \"registry:ui\") and a non-empty `files` array of `{ path, content?, type? }`. Optional fields (`dependencies`, `registryDependencies`, `tailwind`, `cssVars`) are not validated. When `components.json` exists but no registry is shipped, emits a warning for the missed AI-Consumable surface; malformed JSON or missing required fields are errors.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-shadcn-registry-valid.md",
+      "rationale": "Why it matters\n\nA valid shadcn-style `registry.json` is the single most reliable signal that a design system is AI-Consumable today. The shadcn CLI uses it to install components into downstream apps; coding agents (Cursor, Claude, GPT) increasingly look for it to discover and pull components instead of scraping source files.\n\nDetection is conservative — we look for the canonical locations only (`registry.json`, `public/registry.json`, `registry/*.json`) and validate only the three required fields per the public shadcn schema. Optional fields like `tailwind` and `cssVars` vary across versions and are not part of the validity contract.\n\nA repo declaring `components.json` (the shadcn CLI marker) but no registry is a strong indicator the team is on the shadcn path but hasn't published the consumable surface — that's a warning, not an error. Malformed JSON or items missing `name`/`type`/`files` will silently break the shadcn CLI and any agent consumer, so they are errors.",
+      "examples": [
+        {
+          "good": "{ \"name\": \"button\", \"type\": \"registry:ui\", \"files\": [{ \"path\": \"ui/button.tsx\" }] }",
+          "bad": "{ \"name\": \"button\", \"type\": \"registry:ui\" }"
+        },
+        {
+          "good": "{ \"items\": [{ \"name\": \"button\", \"type\": \"registry:ui\", \"files\": [{ \"path\": \"ui/button.tsx\" }] }] }",
+          "bad": "{ \"items\": [{ \"name\": \"button\" }] }"
+        }
+      ],
+      "allowlist": [
+        "repos with no `components.json` AND no `registry.json` — rule is N/A",
+        "files larger than 4 MB — skipped to avoid pathological cases",
+        "files matching `ctx.excludePaths` config",
+        "disable in `.lyse.yaml`: `rules: { ai-surface/shadcn-registry-valid: off }`"
+      ]
+    },
+    {
+      "id": "ai-surface/agent-instruction-files",
+      "axis": "ai-surface",
+      "defaultSeverity": "warning",
+      "shortDescription": "Repo should ship Cursor rules or Claude skills with valid frontmatter",
+      "fullDescription": "Scans for agent instruction bundles at the repo root: `.cursor/rules/*.mdc` (Cursor rules) and `.claude/skills/*/SKILL.md` (Anthropic Claude skills). When neither is present, emits a single warning — the repo gives coding agents no project-specific guidance signal. When found, each file is parsed for YAML frontmatter and validated: Cursor rules must declare `description` and `globs`; Claude skills must declare `name` (kebab-case) and `description` (≤200 chars). Files larger than 5 KB raise a token-budget warning (they cost agents context on every load). Malformed frontmatter and missing required keys raise errors; oversize, non-kebab `name`, and overlong descriptions raise warnings.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-agent-instruction-files.md",
+      "rationale": "Why it matters\n\nCursor rules and Claude skills are the contract surface for two of the most-used coding agents in 2026. Without at least one of these bundles, the agent has no project-specific guidance beyond `AGENTS.md` or `CLAUDE.md` — and even those don't carry the same auto-attach semantics as Cursor's `globs` field or the same auto-load semantics as Claude's skill manifest.\n\nBeyond presence, the *frontmatter* matters. Cursor uses `globs` to decide which rule fires for which file edit; missing `globs` silently disables the rule. Claude skills are loaded by their `name` + `description` pair (the description is the agent's \"tool selection\" prompt); a missing description means the skill is invisible to the agent's decision loop.\n\nToken budget is the third signal. The Anthropic agent skills documentation (Oct 2026) and the Cursor rules documentation both recommend keeping individual files small — long instruction files crowd out the actual context the agent needs to read, and inflate per-call cost. The 5 KB heuristic is the same threshold the Claude skill examples use.",
+      "examples": [
+        {
+          "good": "---\\ndescription: TypeScript style guide for this monorepo\\nglobs: [\"src/**/*.ts\", \"src/**/*.tsx\"]\\nalwaysApply: false\\n---\\n\\n# TypeScript style\\n\\nUse strict mode. Prefer type aliases over interfaces.",
+          "bad": "---\\n# missing required `description` and `globs`\\n---\\n\\n# TypeScript style\\n\\nUse strict mode."
+        },
+        {
+          "good": "---\\nname: pr-checklist\\ndescription: Generates a PR checklist from the diff (≤200 chars)\\nversion: 1.0.0\\n---\\n\\n# PR checklist skill\\n\\nProcedural instructions for the agent.",
+          "bad": "---\\nname: PR_Checklist\\n# missing `description`; `name` is not kebab-case\\n---\\n\\n# PR checklist"
+        }
+      ],
+      "allowlist": [
+        "files larger than 500 KB — skipped to avoid pathological cases (and counted as an oversize warning)",
+        "files matching `ctx.excludePaths` config",
+        "repos that ship only AGENTS.md/CLAUDE.md but neither Cursor rules nor Claude skills — emit one warning (not error) to nudge adoption"
+      ]
+    },
+    {
+      "id": "ai-governance/ai-tokens-reserved",
+      "axis": "ai-governance",
+      "defaultSeverity": "info",
+      "shortDescription": "Inventory reserved AI-marker design tokens",
+      "fullDescription": "Scans token sources (`tokens.json`, `tokens/**/*.json`, `*.tokens.json`, and `**/*.css` `--*` custom properties) for token names that match reserved AI-marker vocabularies: Carbon (`dragon-fruit`, `*-ai-*` color tokens), Shopify Polaris (`--p-color-*-magic*`, `magic-*`), Workday Canvas (`*-ai-*` segment), and the generic leading/trailing `ai` segment. Matching is segment-anchored (split by `-`, `_`, `.`, `/`) so `rain`, `paint`, `mainColor`, `captain`, `detail` do not trigger. Emits one info finding listing up to 20 matched names when reserved tokens are present; emits nothing when none are. Severity is informational — a DS with no AI surface is not penalized here; the gating rule lives in Track 3.3 (`ai-governance/ai-token-requires-marker`).",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-ai-tokens-reserved.md",
+      "rationale": "Why it matters\n\nAI-marker tokens are how a design system tells consumers — humans and agents — that a UI region was produced by AI. Carbon's `dragon-fruit` AI gradient, Polaris's `magic` namespace, and Workday Canvas's `*-ai-*` color tokens are the three established vocabularies; a fourth generic `ai` segment covers the long tail.\n\nTrack 3 of the Lyse roadmap (Face B — AI-Governance) treats these tokens as the foundation for the composite gating rule `ai-governance/ai-token-requires-marker` (Track 3.3), which enforces that AI-produced surfaces actually wear the AI marker. This rule is the inventory step: detect which reserved tokens the repo declares so 3.3 has a deterministic set to check against. It carries no penalty — a DS with zero AI tokens (no AI surface) emits no finding and is not down-scored. The teeth live in 3.3.\n\nThe shared parser `detectReservedAiTokens(repoRoot)` is exported from `packages/core/src/parsers/ai-tokens.ts` so 3.3 reuses the exact same detection set.",
+      "examples": [
+        {
+          "good": "/* tokens.json */ { \"color\": { \"primary\": \"#0070f3\" } }",
+          "bad": "/* tokens.json */ { \"color\": { \"ai\": { \"primary\": \"#0070f3\" } } }"
+        },
+        {
+          "good": ":root { --color-primary: #0070f3; }",
+          "bad": ":root { --p-color-bg-magic: #f4f0fd; }"
+        },
+        {
+          "good": "/* tokens.json */ { \"gradient\": { \"sunrise\": \"...\" } }",
+          "bad": "/* tokens.json */ { \"gradient\": { \"dragon-fruit\": \"...\" } }"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/ai-tokens-reserved` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "token files larger than 2 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/ai-marker-component-present",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Detect AI-marker component in the DS export surface",
+      "fullDescription": "Scans the design system's export surface (`src/index.ts`, `index.ts`, etc.) and component files (`**/*.{tsx,jsx,vue}`) for a dedicated AI-marker component — a label, badge, avatar, or indicator that visually marks AI-generated output. Recognised vocabularies: Carbon `AILabel`, generic `AIBadge` / `AITag` / `AIIndicator` / `AIAvatar`, `GenAI*` variants, `*AIMarker*`, and Polaris `magic-*` components. Emits `info` when a marker component is found; emits `warning` when reserved AI tokens exist (detected by the shared `detectReservedAiTokens` parser) but no marker component is present; emits nothing when the DS has no AI surface at all.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-ai-marker-component-present.md",
+      "rationale": "Why it matters\n\nAI-marker components are the visual contract between the design system and consumers: they signal \"this content was produced by AI.\" Without a dedicated component, individual teams reinvent ad-hoc markers, breaking consistency and accessibility.\n\nThe most important case to flag is a DS that ships reserved AI tokens (signaling AI-surface intent) but provides no corresponding component — consumers have no standardised way to mark AI provenance visually.\n\nThis rule emits `info` when a marker component is detected (inventory), and `warning` when reserved tokens exist but no marker component is found. A DS with no AI surface emits nothing and is not penalised.\n\nThe exported `AI_MARKER_NAMES` constant is shared with sibling rules (Track 3.3 / 3.5) to ensure a single vocabulary source of truth.",
+      "examples": [
+        {
+          "good": "// src/index.ts\nexport { AILabel } from './ai-label';\nexport { Button } from './button';",
+          "bad": "// src/index.ts — no AI-marker component exported\nexport { Button } from './button';"
+        },
+        {
+          "good": "// AILabel.tsx — component file named with the marker vocabulary",
+          "bad": "// tokens.json has `color.ai.primary` but no AILabel/AIBadge component exists"
+        },
+        {
+          "good": "// Polaris-style: magic-icon.tsx component file detected",
+          "bad": "// Reserved tokens present, no marker component shipped"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/ai-marker-component-present` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "repos with no reserved AI tokens AND no marker component — no AI surface detected, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/explainability-affordance",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Detect an explainability affordance paired with AI-marker components",
+      "fullDescription": "When an AI-marker component is detected in the design system (per the shared `isAiMarkerName` predicate exported by `ai-governance/ai-marker-component-present`), this rule checks whether a companion explainability affordance exists. Detection is name-based: any exported identifier or component file whose name contains `Explain`, `Explainability`, `WhyThis`, `Citation`, `Sources`, `Confidence`, or `Provenance` (case-insensitive) qualifies. A marker component that opens a popover or tooltip carrying explanation content (`aria-describedby` / `role=\"dialog\"` / `role=\"tooltip\"`) also satisfies the rule. Emits `info` when an affordance is found; emits `warning` when an AI-marker exists but no affordance is detected. Emits nothing when no AI-marker is present (no AI surface). Guidelines: HAX G11 (Explain AI decisions) / PAIR Explainability. The behavioral slice — verifying that an indicator appears wherever AI output is rendered — is deferred to Track 4.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-explainability-affordance.md",
+      "rationale": "Why it matters\n\nUsers interacting with AI-generated content have a right to understand why a particular output was produced. HAX G11 (Google PAIR / IBM Human-AI Experience guidelines) requires that AI-powered interfaces expose an explanation pathway — a popover, citation list, confidence meter, or similar affordance — so users can evaluate trustworthiness and take informed action.\n\nWithout this affordance, consumers of the design system have no standard component to reach for when building explainable AI interfaces, leading to ad-hoc implementations with inconsistent UX and missing accessibility attributes.\n\nThis rule checks only the static \"affordance present\" slice (Track 3.5): does the DS export a component whose name signals explainability intent, or does an AI-marker component carry the appropriate ARIA binding to open an explanation panel? The behavioral slice — ensuring such an indicator appears wherever AI output is rendered in a consuming application — requires semantic location detection and is out of scope here; it will be addressed in Track 4.\n\nA DS with no AI-marker component at all has no AI surface and is not penalised.",
+      "examples": [
+        {
+          "good": "// src/index.ts\nexport { AILabel } from './ai-label';\nexport { ExplainPopover } from './explain-popover';",
+          "bad": "// src/index.ts\nexport { AILabel } from './ai-label';\n// no Explain/Citation/Confidence component exported"
+        },
+        {
+          "good": "// AILabel.tsx — marker bound to explanation panel\n<button aria-describedby=\"explain-panel\">AI</button>\n<div id=\"explain-panel\" role=\"dialog\">Why: …</div>",
+          "bad": "// AILabel.tsx — marker with no explanation binding\n<span className=\"ai-badge\">AI</span>"
+        },
+        {
+          "good": "// src/index.ts\nexport { ConfidenceDisplay } from './confidence-display';\nexport { CitationList } from './citation-list';",
+          "bad": "// AI tokens and AIBadge exported, but no explainability affordance component present"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/explainability-affordance` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "repos with no AI-marker component — no AI surface detected, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/ai-token-requires-marker",
+      "axis": "ai-governance",
+      "defaultSeverity": "error",
+      "shortDescription": "AI token usage requires a co-located AI-marker (Carbon mandatory composite)",
+      "fullDescription": "For each component file (`**/*.{tsx,jsx,vue}`): if the file references a reserved AI design token (`var(--ai-*)`, `--p-color-*-magic*`, `color.ai.*`, `dragon-fruit`, etc.) it MUST also render an AI-marker — a JSX element whose name is in the shared `AI_MARKER_NAMES` vocabulary (imported from `ai-governance/ai-marker-component-present`), a `magic-*`-prefixed tag, or an explicit `data-ai` attribute. Token usage without a co-located marker is an `error`. Confidence is HIGH only when token detection is via unambiguous `var(--…)` or bare `--token` references; dot-path heuristic hits are LOW-confidence and suppressed by default. The rule is a no-op when no reserved tokens are declared anywhere in the repo (fast-exit via `detectReservedAiTokens`).",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-ai-token-requires-marker.md",
+      "rationale": "Why it matters\n\nIBM Carbon's AI design system mandates the composite: every AI-generated surface must both (a) consume an AI-marker token for visual styling and (b) render a labelling component (AILabel, AIBadge, etc.) so the provenance is legible to users. Without this pairing, the marker token is applied silently — the UI looks \"AI-styled\" without any transparency cue, which violates IBM's own guidance and emerging regulatory expectations around AI disclosure.\n\nLyse enforces this as an `error` (not `warning`) because the composite is binary: either both halves are present (correct) or one is missing (incorrect — always a bug or oversight, not a style preference). The fast-exit on `detectReservedAiTokens` means the rule is a zero-cost no-op for DS repos with no AI surface.\n\nThe marker vocabulary (`AI_MARKER_NAMES`) is shared with sibling rule `ai-governance/ai-marker-component-present` to keep a single source of truth for what counts as a valid AI marker.",
+      "examples": [
+        {
+          "good": "// AICard.tsx — uses var(--ai-gradient) AND renders <AILabel>\nconst AICard = () => (\n  <div style={{ background: 'var(--ai-gradient)' }}>\n    <AILabel>AI-generated</AILabel>\n    {content}\n  </div>\n);",
+          "bad": "// AICard.tsx — uses var(--ai-gradient) but no AI-marker rendered\nconst AICard = () => (\n  <div style={{ background: 'var(--ai-gradient)' }}>\n    {content}\n  </div>\n);"
+        },
+        {
+          "good": "// AnswerCard.tsx — data-ai attribute used as explicit annotation\n<div data-ai style={{ background: 'var(--p-color-bg-magic)' }}>\n  {aiAnswer}\n</div>",
+          "bad": "// AnswerCard.tsx — magic token applied, no marker whatsoever\n<div style={{ background: 'var(--p-color-bg-magic)' }}>\n  {aiAnswer}\n</div>"
+        },
+        {
+          "good": "// Component.tsx — no AI tokens, no AI-marker needed\nconst Card = () => <div style={{ color: 'var(--color-primary)' }}>{content}</div>;",
+          "bad": "// AIAssistant.vue — uses --ai-surface token, missing data-ai or AIBadge\n<template><div :style=\"{ background: 'var(--ai-surface)' }\">{{ answer }}</div></template>"
+        }
+      ],
+      "allowlist": [
+        "component files larger than 1 MB — skipped",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`",
+        "repos with no reserved AI tokens anywhere — rule is a no-op (zero findings, zero opportunities)",
+        "findings where token reference is ambiguous (dot-path heuristic only) — emitted as LOW confidence and suppressed by default"
+      ]
+    },
+    {
+      "id": "ai-governance/ai-loading-error-states",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Named AI loading state with paired text + AI-specific error state present",
+      "fullDescription": "Scans component files (`**/*.{tsx,jsx,vue}`) for (a) a named AI loading state that carries paired visible or accessible text — not a bare spinner — and (b) an AI-specific error state component. Recognised loading vocabulary: `*Generating*`, `*Thinking*`, `*AILoading*`, `*StreamingIndicator*`, `*AIStatus*`, `*LoadingState*`. A bare generic spinner (`Spinner`, `LoadingSpinner`) without an AI-named wrapper and without a `loadingText` prop or visible status string does NOT satisfy the requirement. Recognised error vocabulary: `*AIError*`, `*GenerationError*`, `*AIFailure*`, `*GenerationFailed*`, `*AITimeout*`, or any name combining an AI keyword (`ai`, `generation`, `genai`, `llm`, `generative`) with an error keyword (`error`, `failure`, `failed`, `timeout`). Emits `warning` for each absent state type when an AI marker surface is detected; emits `info` when both are present; emits nothing when no AI surface is detected. Recovery-flow detection (retry orchestration, post-error behavior) is out of scope — tracked in Track 4 (#16).",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-ai-loading-error-states.md",
+      "rationale": "Why it matters\n\nAI-generating surfaces have two failure modes invisible to generic DS rules: (1) a loading state that gives no context — users see a spinner but don't know if the model is generating, stuck, or done — and (2) a generic error boundary that offers no AI-specific message, leaving users without guidance when a generation fails.\n\nAWS Cloudscape's generative-AI patterns mandate that every AI loading state carry named, visible text (e.g. \"Generating response…\") so users understand what the system is doing and can judge when to wait vs. cancel. A bare, unlabelled spinner violates this requirement.\n\nAn AI-specific error component is equally critical: it must communicate that the AI operation failed (not a generic network error) and ideally suggest next steps — though the recovery-flow logic itself is deferred to Track 4.\n\nThis rule detects the static presence of both states. It cross-conditions: if an AI marker is found but either state is absent, a warning is emitted; if both are present, an info finding confirms the DS is provisioned for AI-state handling.",
+      "examples": [
+        {
+          "good": "// Generating.tsx\nexport const Generating = () => (\n  <div role=\"status\" aria-live=\"polite\">\n    <Spinner /> Generating response…\n  </div>\n);",
+          "bad": "// LoadingSpinner.tsx — bare spinner, no AI name, no paired text\nexport const LoadingSpinner = () => <svg className=\"spin\" />;"
+        },
+        {
+          "good": "// AILoading.tsx — loadingText prop satisfies paired-text requirement\nexport function AILoading({ loadingText }: { loadingText: string }) {\n  return <div><Spinner /><span>{loadingText}</span></div>;\n}",
+          "bad": "// No AI-named loading state at all — only generic Spinner exported"
+        },
+        {
+          "good": "// AIError.tsx\nexport const AIError = ({ message }: { message: string }) => (\n  <div role=\"alert\">\n    <strong>Generation failed</strong>\n    <p>{message}</p>\n  </div>\n);",
+          "bad": "// ErrorBoundary.tsx — generic, gives no AI context\nexport class ErrorBoundary extends React.Component {\n  render() { return this.props.children; }\n}"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/ai-loading-error-states` in an adjacent README, README.md, README.mdx, .lyse.yaml, or .lyse.yml — rule is N/A",
+        "repos with no AI marker surface detected (no AILabel, AIBadge, magic-* etc.) — no AI surface, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`",
+        "recovery-flow detection (retry orchestration, post-error navigation) — explicitly deferred to Track 4 (#16)"
+      ]
+    },
+    {
+      "id": "ai-governance/human-control-affordances",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Detect human-control affordances over AI output",
+      "fullDescription": "Scans component files (`**/*.{tsx,jsx,vue}`) for two groups of human-control affordances. Group 1 — per-output controls: exported component names or button labels matching the correction/dismissal vocabulary (Regenerate, Retry, Stop, Edit, Undo, Confirm, Dismiss, Accept, Reject). Group 2 — global AI toggle: exported names or toggle labels indicating a settings surface that lets users disable AI (AISettings, AiPreferences, DisableAI, or a label 'Disable AI' / 'AI features'). Cross-condition: when an AI-marker component is present (per the shared `isAiMarkerName` predicate) but no per-output control is found, emits `warning`; when controls are detected, emits `info` listing them and noting global toggle presence. Emits nothing when the DS has no AI surface. Guidelines: HAX G8 (efficient correction) / G9 (efficient dismissal).",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-human-control-affordances.md",
+      "rationale": "Why it matters\n\nHAX G8 (efficient correction) and G9 (efficient dismissal) are foundational human-AI interaction guidelines: users must be able to correct, stop, retry, or dismiss AI-generated output without friction. Without corresponding affordances in the design system, consuming teams implement ad-hoc controls that are inconsistent, inaccessible, and miss the correction loop entirely.\n\nThis rule performs static detection: does the DS export components covering the standard correction/dismissal vocabulary? It does not verify usage site coverage (deferred to Track 4).\n\nA DS with no AI-marker component emits nothing and is not penalised.",
+      "examples": [
+        {
+          "good": "// src/index.ts\nexport { AIBadge } from './ai-badge';\nexport { RegenerateButton } from './regenerate-button';\nexport { AISettings } from './ai-settings';",
+          "bad": "// src/index.ts\nexport { AIBadge } from './ai-badge';\n// no correction or dismissal controls exported"
+        },
+        {
+          "good": "// AIControls.tsx\nexport function RegenerateButton() { return <button>Regenerate</button>; }\nexport function DismissResult() { return <button>Dismiss</button>; }",
+          "bad": "// No per-output control components; users have no standardised way to correct AI output"
+        },
+        {
+          "good": "// AISettings.tsx\nexport function AISettings() {\n  return <Toggle label=\"Disable AI\" />;\n}",
+          "bad": "// AI surface present but no global disable/settings toggle shipped"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/human-control-affordances` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "repos with no AI-marker component at all — no AI surface detected, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/ai-marker-anti-patterns",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Lint AI-marker anti-patterns in component source files",
+      "fullDescription": "Scans component files (`**/*.{tsx,jsx,vue}`) for two forbidden AI-marking anti-patterns. Anti-pattern A: a sparkle signal (`✨` literal, `Sparkle`/`Sparkles`/`SparkleIcon` import, or `icon=\"sparkle*\"` prop) used as the sole AI marker with no accompanying text label or AI-marker component — SAP Fiori XAI forbids icon-only marking because it fails accessibility and is ambiguous. Anti-pattern B: the standalone, case-sensitive token `AI` used as the primary action label of a `<button>`, `<Button>`, or `<a>` element — GitLab Pajamas forbids this because `AI` describes the technology, not the user action. Both detectors are pure source heuristics with no runtime or behavioral analysis. Emits `warning` for each occurrence. A sparkle accompanied by a text AI-marker or AI-marker component (`AILabel`, `AIBadge`, magic-* etc.) is not flagged. `AI` appearing only in body or descriptor text (headings, paragraphs) is not flagged.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-ai-marker-anti-patterns.md",
+      "rationale": "Why it matters\n\nIcon-only AI marking (a lone sparkle ✨) silently fails users who rely on assistive technology: a screen reader announces an image description or nothing at all — not \"AI-generated.\" SAP Fiori XAI made this explicit: sparkle MUST be paired with a text label or dedicated AI-marker component. Lyse enforces the same constraint statically.\n\nLabelling a CTA button \"AI\" is a UX anti-pattern: \"AI\" is a noun describing technology, not an action verb. GitLab Pajamas explicitly forbids it, recommending \"Summarize,\" \"Explain,\" or \"Generate\" instead — words that tell the user what will happen, not what engine does it. Lyse catches this in source before it ships.\n\nBoth findings are warnings (not errors) because the fix is mechanical and low-risk.",
+      "examples": [
+        {
+          "good": "<span><AILabel>AI</AILabel> <Sparkles aria-hidden/></span>",
+          "bad": "<span>✨ {generatedText}</span>"
+        },
+        {
+          "good": "<button>Summarize</button>",
+          "bad": "<button>AI</button>"
+        },
+        {
+          "good": "<button>Draft reply</button>",
+          "bad": "<button>Ask AI</button>"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/ai-marker-anti-patterns` in an adjacent README or `.lyse.yaml` — rule is N/A for the entire repo",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`",
+        "sparkle accompanied by a text AI-marker (`AILabel`, `AIBadge`, magic-*, GenAI*, etc.) — not flagged",
+        "`AI` in non-CTA elements (headings, paragraphs, spans) — not flagged"
+      ]
+    },
+    {
+      "id": "ai-governance/ai-content-live-region",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Detect ARIA live region on AI output / streaming components",
+      "fullDescription": "Globs `**/*.{tsx,jsx,vue}` and runs two per-file detectors: one that identifies AI-output/streaming surfaces (AI_MARKER_NAMES, *AIResponse*, *ChatMessage*, isStreaming, isGenerating props), another that detects live-region attributes (aria-live=\"polite|assertive\", role=\"status\", role=\"alert\", PatternFly isLiveRegion). Cross-condition: AI surface present but no live region → `warning`; AI surface inside a live region → `info` naming the mechanism; no AI/streaming surface → no finding.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-ai-content-live-region.md",
+      "rationale": "Why it matters\n\nScreen-reader users rely on ARIA live regions to hear dynamically updated content. When an AI model streams a response token-by-token, the DOM updates silently unless the container carries aria-live=\"polite\", role=\"status\", role=\"alert\", or an equivalent framework mechanism. Without a live region, visually impaired users miss the entire AI response — a failure of both accessibility and AI-governance (the system produces output that some users cannot perceive).\n\nWAI-ARIA specifies that aria-live=\"polite\" announces changes after the user is idle (appropriate for non-urgent AI output); aria-live=\"assertive\" / role=\"alert\" interrupt immediately (use only for errors). PatternFly provides isLiveRegion as a prop on several container components to avoid hand-rolling the attribute.\n\nThis rule checks the static presence of a live-region mechanism in the same file as an AI-output or streaming component — it does not verify runtime behaviour or dynamic DOM updates.",
+      "examples": [
+        {
+          "good": "// aria-live wraps AI output (React)\nexport function AiAnswer({ content }: { content: string }) {\n  return (\n    <div aria-live=\"polite\">\n      <AILabel>AI</AILabel>\n      <p>{content}</p>\n    </div>\n  );\n}",
+          "bad": "// AI output with no live region\nexport function AiAnswer({ content }: { content: string }) {\n  return (\n    <div className=\"response\">\n      <ChatAIResponse content={content} />\n    </div>\n  );\n}"
+        },
+        {
+          "good": "// PatternFly isLiveRegion\n<TextContent isLiveRegion>{streamedContent}</TextContent>",
+          "bad": "// isStreaming prop but no live region wrapper\n<OutputBlock isGenerating={generating} />"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/ai-content-live-region` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "repos with no AI-output or streaming component — no AI surface detected, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/disclaimer-present",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Detect AI disclaimer near AI-generated output",
+      "fullDescription": "Scans component files (`**/*.{tsx,jsx,vue}`) for a co-located AI disclaimer — either disclaimer text (`Generated by AI`, `AI-generated`, `May be inaccurate`, `Check important info`, `Powered by AI`, case-insensitive word-boundary) or a `*Disclaimer*` / `*AIDisclaimer*` component tag. Highest-confidence signal: the GitLab Pajamas canonical disclaimer wording matched verbatim. Cross-condition: if an AI-marker component (per AI_MARKER_NAMES) is present but no disclaimer is found, emits `warning`; if a disclaimer is detected, emits `info` (noting the GitLab canonical match when applicable). Emits nothing when no AI surface is present.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-disclaimer-present.md",
+      "rationale": "Why it matters\n\nAI systems make errors. Capability-framing guidelines (HAX G1/G2) require that AI-generated surfaces carry a visible disclaimer so users understand the system's limits and know to verify critical information.\n\nGitLab Pajamas formalises this with a canonical disclaimer string: \"AI-generated content may be inaccurate. Always check important information.\" When the exact Pajamas wording is used, Lyse flags it as highest-confidence.\n\nThis rule enforces the pairing: an AI-marker component is the visual signal that content is AI-generated; a disclaimer is the capability-framing signal that the content may err. Having the marker without the disclaimer leaves users without the context they need to make safe decisions.\n\nThe rule emits `warning` (action required) when a marker is present but no disclaimer is found, and `info` (inventory) when a disclaimer is detected — flagging whether it matches the GitLab canonical wording.",
+      "examples": [
+        {
+          "good": "// AISummary.tsx — marker + disclaimer present\n<AILabel />\n<p>{summary}</p>\n<p className=\"disclaimer\">Generated by AI. May be inaccurate.</p>",
+          "bad": "// AISummary.tsx — marker present, no disclaimer\n<AILabel />\n<p>{summary}</p>"
+        },
+        {
+          "good": "// GitLab canonical wording — highest-confidence pass\n<AIDisclaimer message=\"AI-generated content may be inaccurate. Always check important information.\" />",
+          "bad": "// AI marker but disclaimer is buried in a tooltip the user may never see\n<AIBadge /><Tooltip>AI content</Tooltip>"
+        },
+        {
+          "good": "// Vue SFC — disclaimer component rendered alongside output\n<template><AIOutput :text /><AiDisclaimer /></template>",
+          "bad": "// Vue SFC — AI token reserved in class, no disclaimer rendered\n<template><div class=\"ai-output\">{{ text }}</div></template>"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/disclaimer-present` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "repos with no AI-marker component AND no disclaimer text — no AI surface detected, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/feedback-control-present",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "Detect a feedback control on AI output",
+      "fullDescription": "When an AI-marker component is detected in the design system, this rule checks whether a companion feedback control exists co-located in the same file. Detection is per-file: a feedback vocabulary match only earns credit when the same file also contains an AI-marker (component name or JSX tag). Detection is two-phase. Phase 1 — name-based scan: checks exported identifiers and file base names against the feedback vocabulary (case-insensitive substring, separator-normalised): `feedback`, `thumbsup`, `thumbsdown`, `rating`, `vote`, `helpful`. Names ending in `Icon`, `Count`, `Result`, `Total`, `Tally`, or `Text` suffixes (display counters / icon primitives) are excluded. Phase 2 — categorized bonus: for each matched feedback component file, checks whether the source exposes a reason vocabulary word (`inaccurate`, `unhelpful`, `offensive`, `tooLong`, `harmful`, `misleading`, `irrelevant`) alongside an enum object, union type, or options array. Three outcomes: AI-marker present + feedback control co-located → `info` (notes if categorized; HAX G15 / PAIR Feedback cited); AI-marker present + no co-located feedback control → `warning`; no AI-marker anywhere → no finding.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-feedback-control-present.md",
+      "rationale": "Why it matters\n\nUsers interacting with AI-generated content need a structured way to signal output quality. HAX G15 (IBM Human-AI Experience guidelines, Granular feedback) and the Google PAIR Feedback & Control guidebook require that AI-powered interfaces expose a feedback control — thumbs up/down, rating, or helpful/unhelpful — so users can communicate when AI output is wrong, harmful, or unhelpful.\n\nVendor mandates: Microsoft Fluent 2 AI design guidelines mandate a feedback affordance on AI output; Amazon Cloudscape AI components documentation encourages it; Red Hat PatternFly AI component guidance recommends it. Without a dedicated component, teams implement ad-hoc controls with inconsistent UX, missing accessibility attributes, and no shared vocabulary for categorized negative feedback.\n\nCategorized feedback (why was it bad?) provides richer model-improvement signal than binary thumbs alone. This rule rewards designs that expose a reason enum (inaccurate, unhelpful, offensive) by noting the categorized bonus in the info message.\n\nThe rule uses per-file co-location: a feedback control only earns credit when it lives in the same file as an AI-marker component or JSX tag. Generic form-validation components (ValidationFeedback), display counters (VoteCount), or product review widgets (ProductRating) in unrelated files do not falsely count. The rule fires only when at least one AI-marker file exists. A DS with no AI surface is not penalized.",
+      "examples": [
+        {
+          "good": "// AiFeedback.tsx — co-located with AI marker\nexport const AILabel = () => null;\nexport const ThumbsUp = () => null;\nexport const ThumbsDown = () => null;",
+          "bad": "// ValidationFeedback.tsx — form errors, no AI marker\nexport const ValidationFeedback = () => null;\n// AILabel.tsx — separate file, no feedback control"
+        },
+        {
+          "good": "// AiFeedback.tsx — exposes categorized reasons alongside AI marker\nexport const AIBadge = () => null;\nexport const AiFeedback = () => null;\nexport const FeedbackReason = { inaccurate: 'inaccurate', unhelpful: 'unhelpful', offensive: 'offensive' } as const;",
+          "bad": "// AiFeedback.tsx — no reason categories\nexport const AiFeedback = () => null;"
+        },
+        {
+          "good": "// StarRating.tsx present alongside AIBadge in the same file",
+          "bad": "// AIBadge.tsx present but no rating, vote, or helpful component shipped in the same file"
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/feedback-control-present` in an adjacent README or `.lyse.yaml` — rule is N/A",
+        "repos with no AI-marker component — no AI surface detected, rule emits nothing",
+        "files larger than 1 MB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
+    },
+    {
+      "id": "ai-governance/value-gate-doc-present",
+      "axis": "ai-governance",
+      "defaultSeverity": "warning",
+      "shortDescription": "AI value-gate governance doc must be present when an AI surface exists",
+      "fullDescription": "When a design system ships an AI surface — detected by an AI-marker component (via the `AI_MARKER_NAMES` vocabulary from Track 3.2) or reserved AI-marker design tokens (Track 3.1, `detectReservedAiTokens`) — this rule checks that a governance value-gate doc exists and contains structured go/no-go decision language. Candidate locations scanned: `AI_GOVERNANCE.md` at repo root, `docs/ai-value-gate.md`, `docs/ai-governance.md`, `docs/ai-readiness.md`, `docs/ai-checklist.md`, `.lyse/ai-value-gate.md`, and `AI_GOVERNANCE.md` anywhere in the repo tree. A doc is considered valid if it contains at least one of: \"is AI needed\", \"value gate\", \"go/no-go\", \"should this be AI\", \"is AI the right tool\", \"ai-readiness\", \"why AI?\", or \"deterministic rule ... instead of AI\". Emits `warning` when AI surface exists but no doc found, or doc found but lacks gate language. Emits `info` when a valid value-gate doc is present. Emits nothing when the DS has no AI surface.",
+      "helpUri": "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-governance-value-gate-doc-present.md",
+      "rationale": "Why it matters\n\nBefore shipping AI-powered UI, design systems need a structured answer to \"is AI actually needed here?\" — a go/no-go gate. ServiceNow's internal \"10-Q\" process documents exactly this: a fixed checklist of questions (is AI the right tool? can a deterministic rule solve this? what is the fallback?) that must be answered before any AI feature lands.\n\nWithout this gate doc, individual teams ship AI features ad-hoc, often when a rule-based solution would have been faster, cheaper, and more auditable. The governance debt accumulates: inconsistent AI use, unclear fallback paths, and no audit trail.\n\nThis rule does NOT enforce the answers — only that the DS ships the document, ensuring the gate process is defined and discoverable. Teams that use Lyse for AI governance get a measurable signal: \"this DS has defined its AI decision process.\"\n\nThe cross-condition logic — checking for an AI surface first via `scanForMarkerComponents` and `detectReservedAiTokens` — ensures DSs without any AI surface are not penalised. The rule is additive: it rewards good governance without creating false positives for projects that have not yet adopted AI features.",
+      "examples": [
+        {
+          "good": "# AI Value Gate\n\n## Is AI needed?\n- [ ] Can a deterministic rule solve this instead?\n- [ ] Does ML outperform a rule on this specific input distribution?\n- [ ] What is the fallback if the model is unavailable?\n\nGo/no-go: answer all three before shipping.",
+          "bad": "# AI Guidelines\n\nUse `AILabel` on all AI-generated content surfaces.\nFollow the design tokens from the `ai` namespace."
+        }
+      ],
+      "allowlist": [
+        "repos containing `lyse-disable ai-governance/value-gate-doc-present` in README, README.md, README.mdx, readme.md, .lyse.yaml, or .lyse.yml — rule is N/A",
+        "DSs with no AI surface (no AI-marker component and no reserved AI tokens) — rule emits nothing",
+        "doc files larger than 500 KB — skipped to avoid pathological cases",
+        "files under `node_modules/`, `dist/`, `build/`, `.git/`, `.next/`, `out/`, `coverage/`"
+      ]
     }
   ]
 }

package/schemas/v1/lyse-rules.json

@@ -16,7 +16,7 @@
         "additionalProperties": false,
         "properties": {
           "id": { "type": "string" },
-          "axis": { "type": "string", "enum": ["tokens", "a11y", "components", "stories", "ai-surface"] },
+          "axis": { "type": "string", "enum": ["tokens", "a11y", "components", "stories", "ai-surface", "ai-governance"] },
           "defaultSeverity": { "type": "string", "enum": ["error", "warning", "info"] },
           "shortDescription": { "type": "string" },
           "fullDescription": { "type": "string" },

package/dist/commands/ci-setup.d.ts

@@ -1,9 +0,0 @@
-export interface CiSetupOptions {
-    cwd: string;
-    threshold?: number;
-    postPrComment?: boolean;
-    uploadSarif?: boolean;
-    publishBench?: boolean;
-    autoApprove?: boolean;
-}
-export declare function runCiSetup(opt: CiSetupOptions): Promise<void>;

package/dist/commands/ci-setup.js

@@ -1,42 +0,0 @@
-import { readFile, writeFile, mkdir, access } from "node:fs/promises";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { detectFromGit } from "../detection/from-git.js";
-import { confirm } from "../menu/prompts.js";
-import { appendCiSetupCompletedEvent } from "../history/ndjson-store.js";
-export async function runCiSetup(opt) {
-    const git = await detectFromGit(opt.cwd);
-    if (!git.github.value) {
-        throw new Error("No GitHub remote detected. `lyse ci setup` requires a GitHub repo.");
-    }
-    const wfPath = join(opt.cwd, ".github/workflows/lyse.yml");
-    try {
-        await access(wfPath);
-        if (!opt.autoApprove) {
-            const overwrite = await confirm(`.github/workflows/lyse.yml exists. Overwrite?`, false);
-            if (!overwrite) {
-                console.log("Aborted (existing file preserved).");
-                return;
-            }
-        }
-    }
-    catch {
-        // File does not exist — proceed to create
-    }
-    // Read template — file is co-located via package.json files[]
-    const templatePath = join(dirname(fileURLToPath(import.meta.url)), "templates/lyse-workflow.yml.template");
-    const template = await readFile(templatePath, "utf8");
-    const rendered = template
-        .replaceAll("{{ default_branch }}", git.git.value?.defaultBranch ?? "main")
-        .replaceAll("{{ threshold }}", String(opt.threshold ?? 70))
-        .replaceAll("{{ post_pr_comment }}", String(opt.postPrComment ?? true))
-        .replaceAll("{{ upload_sarif }}", String(opt.uploadSarif ?? true))
-        .replaceAll("{{ publish_bench }}", String(opt.publishBench ?? false));
-    await mkdir(join(opt.cwd, ".github/workflows"), { recursive: true });
-    await writeFile(wfPath, rendered);
-    console.log(`✓ Created ${wfPath}`);
-    console.log(`  Don't forget: git add .github/workflows/lyse.yml && commit && push`);
-    // Emit telemetry event (opt-in only)
-    await appendCiSetupCompletedEvent(opt.cwd, opt.threshold ?? 70);
-}
-//# sourceMappingURL=ci-setup.js.map

package/dist/commands/ci-setup.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ci-setup.js","sourceRoot":"","sources":["../../src/commands/ci-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAWzE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAmB;IAClD,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,4BAA4B,CAAC,CAAC;IAC3D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,+CAA+C,EAAE,KAAK,CAAC,CAAC;YACxF,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;gBAClD,OAAO;YACT,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;IAED,8DAA8D;IAC9D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,sCAAsC,CAAC,CAAC;IAC3G,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,QAAQ;SACtB,UAAU,CAAC,sBAAsB,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,IAAI,MAAM,CAAC;SAC1E,UAAU,CAAC,iBAAiB,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;SAC1D,UAAU,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC;SACtE,UAAU,CAAC,oBAAoB,EAAE,MAAM,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;SACjE,UAAU,CAAC,qBAAqB,EAAE,MAAM,CAAC,GAAG,CAAC,YAAY,IAAI,KAAK,CAAC,CAAC,CAAC;IAExE,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,mBAAmB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,MAAM,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAElC,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,sEAAsE,CAAC,CAAC;IAEpF,qCAAqC;IACrC,MAAM,2BAA2B,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC"}