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

package/dist/rules/ai-governance-value-gate-doc-present.js

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import fg from "fast-glob";
+import { createLyseRule } from "./_rule-module.js";
+import { scanForMarkerComponents, makeAllowlistCheck, } from "./ai-governance-ai-marker-component-present.js";
+import { detectReservedAiTokens } from "../parsers/ai-tokens.js";
+const RULE_ID = "ai-governance/value-gate-doc-present";
+const MAX_DOC_BYTES = 500_000;
+const DISABLE_DIRECTIVE = `lyse-disable ${RULE_ID}`;
+const ALLOWLIST_CANDIDATES = [
+    "README.md",
+    "README",
+    "README.mdx",
+    "readme.md",
+    ".lyse.yaml",
+    ".lyse.yml",
+];
+// Ordered candidate paths — checked before the broad glob.
+const STATIC_CANDIDATES = [
+    "AI_GOVERNANCE.md",
+    "docs/ai-value-gate.md",
+    "docs/ai-governance.md",
+    "docs/ai-readiness.md",
+    "docs/ai-checklist.md",
+    ".lyse/ai-value-gate.md",
+];
+// Glob patterns for docs/**/ — name-constrained to avoid catching arbitrary AI docs.
+const DOC_GLOBS = [
+    "docs/**/ai-value-gate.md",
+    "docs/**/ai-governance.md",
+    "docs/**/ai-readiness.md",
+    "docs/**/ai-checklist.md",
+    "**/AI_GOVERNANCE.md",
+];
+const IGNORE = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.git/**",
+    "**/.next/**",
+    "**/out/**",
+    "**/coverage/**",
+];
+// Gate-language patterns modelled on ServiceNow "10-Q" value gate.
+// Each pattern targets a distinct phrasing family; case-insensitive.
+const GATE_PATTERNS = [
+    /\bis\s+ai\s+needed\b/i,
+    /\bvalue[-\s]gate\b/i,
+    /\bgo\s*\/\s*no[-\s]go\b/i,
+    /\bshould\s+this\s+(?:feature\s+)?(?:be|use)\s+ai\b/i,
+    /\bis\s+ai\s+the\s+right\s+tool\b/i,
+    /\bai[-\s]readiness\b/i,
+    /\bwhy\s+ai\s*\?/i,
+    /\bdeterministic\s+rule\b.*instead\s+of\s+ai\b/i,
+];
+export function detectGateLanguage(content) {
+    return GATE_PATTERNS.some((re) => re.test(content));
+}
+function readDocIfSmall(absPath) {
+    try {
+        const stat = statSync(absPath);
+        if (!stat.isFile() || stat.size > MAX_DOC_BYTES || stat.size === 0)
+            return null;
+        return readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function discoverGateDoc(repoRoot) {
+    for (const candidate of STATIC_CANDIDATES) {
+        const abs = join(repoRoot, candidate);
+        if (!existsSync(abs))
+            continue;
+        const content = readDocIfSmall(abs);
+        if (content === null)
+            continue;
+        return { rel: candidate, hasGateLanguage: detectGateLanguage(content) };
+    }
+    let hits = [];
+    try {
+        hits = fg.sync(DOC_GLOBS, {
+            cwd: repoRoot,
+            absolute: false,
+            dot: true,
+            ignore: IGNORE,
+            onlyFiles: true,
+            unique: true,
+        }).sort();
+    }
+    catch {
+        // non-fatal
+    }
+    for (const rel of hits) {
+        const content = readDocIfSmall(join(repoRoot, rel));
+        if (content === null)
+            continue;
+        return { rel, hasGateLanguage: detectGateLanguage(content) };
+    }
+    return null;
+}
+const isAllowlisted = makeAllowlistCheck(DISABLE_DIRECTIVE);
+function hasAiSurface(repoRoot) {
+    const markerComponents = scanForMarkerComponents(repoRoot);
+    if (markerComponents.length > 0)
+        return true;
+    const reservedTokens = detectReservedAiTokens(repoRoot);
+    return reservedTokens.length > 0;
+}
+const evaluate = async (ctx, _files) => {
+    const findings = [];
+    if (!ctx.repoRoot) {
+        return { findings, opportunities: 0 };
+    }
+    if (isAllowlisted(ctx.repoRoot)) {
+        return { findings, opportunities: 0 };
+    }
+    if (!hasAiSurface(ctx.repoRoot)) {
+        return { findings, opportunities: 0 };
+    }
+    const gateDoc = discoverGateDoc(ctx.repoRoot);
+    if (gateDoc === null) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-governance",
+            severity: "warning",
+            location: { file: "AI_GOVERNANCE.md", line: 1, column: 1 },
+            message: "No AI value-gate governance doc found — this DS ships an AI surface but documents no go/no-go decision gate (ServiceNow \"10-Q\" pattern). Create a doc that answers: is AI needed, is it the right tool, what is the fallback?",
+            suggestion: "add AI_GOVERNANCE.md (or docs/ai-governance.md / .lyse/ai-value-gate.md) with a structured checklist requiring AI justification before shipping each AI feature",
+        });
+        return { findings, opportunities: 1 };
+    }
+    if (!gateDoc.hasGateLanguage) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-governance",
+            severity: "warning",
+            location: { file: gateDoc.rel, line: 1, column: 1 },
+            message: `Value-gate doc found at \`${gateDoc.rel}\` but contains no gate language — it does not pose the "is AI needed / go/no-go" decision question`,
+            suggestion: 'add explicit gate questions: "Is AI needed?", "Is AI the right tool?", "What is the deterministic fallback?" — phrasing that forces a go/no-go decision before shipping',
+        });
+        return { findings, opportunities: 1 };
+    }
+    findings.push({
+        ruleId: RULE_ID,
+        axis: "ai-governance",
+        severity: "info",
+        location: { file: gateDoc.rel, line: 1, column: 1 },
+        message: `AI value-gate governance doc detected at \`${gateDoc.rel}\` — DS documents an AI go/no-go decision process`,
+        suggestion: "keep the gate doc up to date as the AI surface evolves; link to it from AGENTS.md or llms.txt so agents can discover it",
+    });
+    return { findings, opportunities: 1 };
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "ai-governance",
+        lyseRuleId: RULE_ID,
+        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
+
+Before 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.
+
+Without 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.
+
+This 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."
+
+The 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
+
+## Is AI needed?
+- [ ] Can a deterministic rule solve this instead?
+- [ ] Does ML outperform a rule on this specific input distribution?
+- [ ] What is the fallback if the model is unavailable?
+
+Go/no-go: answer all three before shipping.`,
+                bad: `# AI Guidelines
+
+Use \`AILabel\` on all AI-generated content surfaces.
+Follow 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/`",
+        ],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+export const _internal = {
+    detectGateLanguage,
+    discoverGateDoc,
+    isAllowlisted,
+    DISABLE_DIRECTIVE,
+    ALLOWLIST_CANDIDATES,
+    STATIC_CANDIDATES,
+    DOC_GLOBS,
+};
+//# sourceMappingURL=ai-governance-value-gate-doc-present.js.map

package/dist/rules/ai-governance-value-gate-doc-present.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-governance-value-gate-doc-present.js","sourceRoot":"","sources":["../../src/rules/ai-governance-value-gate-doc-present.ts"],"names":[],"mappings":"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"}

package/dist/rules/ai-surface-agent-instruction-files.d.ts

@@ -0,0 +1,33 @@
+import type { Rule } from "../types.js";
+type FrontmatterParseResult = {
+    ok: true;
+    data: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+declare function parseFrontmatter(content: string): FrontmatterParseResult;
+declare function isStringOrStringArray(value: unknown): value is string | string[];
+interface CursorValidation {
+    errors: string[];
+    warnings: string[];
+}
+declare function validateCursorRuleFrontmatter(fm: Record<string, unknown>): CursorValidation;
+interface SkillValidation {
+    errors: string[];
+    warnings: string[];
+}
+declare function validateSkillFrontmatter(fm: Record<string, unknown>): SkillValidation;
+export declare const rule: Rule;
+export declare const _internal: {
+    parseFrontmatter: typeof parseFrontmatter;
+    validateCursorRuleFrontmatter: typeof validateCursorRuleFrontmatter;
+    validateSkillFrontmatter: typeof validateSkillFrontmatter;
+    isStringOrStringArray: typeof isStringOrStringArray;
+    CURSOR_RULE_GLOBS: string[];
+    CLAUDE_SKILL_GLOBS: string[];
+    TOKEN_BUDGET_BYTES: number;
+    DESCRIPTION_MAX_CHARS: number;
+    KEBAB_CASE_RE: RegExp;
+};
+export {};

package/dist/rules/ai-surface-agent-instruction-files.js

@@ -0,0 +1,310 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import fg from "fast-glob";
+import { parse as parseYaml } from "yaml";
+import { isPathExcluded } from "./_exclude.js";
+import { createLyseRule } from "./_rule-module.js";
+const RULE_ID = "ai-surface/agent-instruction-files";
+const MAX_FILE_BYTES = 500_000;
+const TOKEN_BUDGET_BYTES = 5_000;
+const DESCRIPTION_MAX_CHARS = 200;
+const CURSOR_RULE_GLOBS = [".cursor/rules/**/*.mdc"];
+const CLAUDE_SKILL_GLOBS = [".claude/skills/*/SKILL.md"];
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/;
+const KEBAB_CASE_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function readFileIfSmall(absPath) {
+    try {
+        const stat = statSync(absPath);
+        if (!stat.isFile())
+            return { content: null, bytes: 0 };
+        const bytes = stat.size;
+        if (bytes > MAX_FILE_BYTES)
+            return { content: null, bytes };
+        return { content: readFileSync(absPath, "utf8"), bytes };
+    }
+    catch {
+        return { content: null, bytes: 0 };
+    }
+}
+function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_RE);
+    if (!match) {
+        return { ok: false, error: "no YAML frontmatter (expected `---` fenced block at top of file)" };
+    }
+    const yamlBody = match[1] ?? "";
+    let parsed;
+    try {
+        parsed = parseYaml(yamlBody);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `frontmatter YAML parse error: ${e instanceof Error ? e.message : "unknown"}`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: "frontmatter must be a YAML mapping" };
+    }
+    return { ok: true, data: parsed };
+}
+function isStringOrStringArray(value) {
+    if (typeof value === "string")
+        return value.length > 0;
+    if (Array.isArray(value)) {
+        return value.length > 0 && value.every((v) => typeof v === "string" && v.length > 0);
+    }
+    return false;
+}
+function validateCursorRuleFrontmatter(fm) {
+    const errors = [];
+    const warnings = [];
+    const description = fm.description;
+    if (typeof description !== "string" || description.trim().length === 0) {
+        errors.push("missing required `description` (string)");
+    }
+    else if (description.trim().length > DESCRIPTION_MAX_CHARS) {
+        warnings.push(`\`description\` is ${description.trim().length} chars (> ${DESCRIPTION_MAX_CHARS}); consider shortening`);
+    }
+    if (!("globs" in fm)) {
+        errors.push("missing required `globs` (string or array of strings)");
+    }
+    else if (!isStringOrStringArray(fm.globs)) {
+        errors.push("`globs` must be a non-empty string or array of strings");
+    }
+    if ("alwaysApply" in fm && typeof fm.alwaysApply !== "boolean") {
+        warnings.push("`alwaysApply` should be a boolean");
+    }
+    return { errors, warnings };
+}
+function validateSkillFrontmatter(fm) {
+    const errors = [];
+    const warnings = [];
+    const name = fm.name;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        errors.push("missing required `name` (kebab-case string)");
+    }
+    else if (!KEBAB_CASE_RE.test(name)) {
+        warnings.push(`\`name\` "${name}" should be kebab-case (lowercase, hyphen-separated)`);
+    }
+    const description = fm.description;
+    if (typeof description !== "string" || description.trim().length === 0) {
+        errors.push("missing required `description` (string)");
+    }
+    else if (description.trim().length > DESCRIPTION_MAX_CHARS) {
+        warnings.push(`\`description\` is ${description.trim().length} chars (> ${DESCRIPTION_MAX_CHARS}); consider shortening`);
+    }
+    return { errors, warnings };
+}
+function discoverFiles(ctx, patterns) {
+    if (!ctx.repoRoot)
+        return [];
+    let entries = [];
+    try {
+        entries = fg.sync(patterns, {
+            cwd: ctx.repoRoot,
+            absolute: false,
+            dot: true,
+            onlyFiles: true,
+            ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**"],
+            followSymbolicLinks: false,
+        });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const rel of entries) {
+        if (isPathExcluded(rel, ctx.excludePaths))
+            continue;
+        out.push(rel);
+    }
+    return out.sort();
+}
+const evaluate = async (ctx, _files) => {
+    const findings = [];
+    if (!ctx.repoRoot) {
+        return { findings, opportunities: 0 };
+    }
+    const cursorFiles = discoverFiles(ctx, CURSOR_RULE_GLOBS);
+    const skillFiles = discoverFiles(ctx, CLAUDE_SKILL_GLOBS);
+    if (cursorFiles.length === 0 && skillFiles.length === 0) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "warning",
+            location: { file: ".cursor/rules/", line: 1, column: 1 },
+            message: "No agent instruction files found (neither `.cursor/rules/*.mdc` nor `.claude/skills/*/SKILL.md`)",
+            suggestion: "add at least one Cursor rule under `.cursor/rules/` or one Claude skill under `.claude/skills/<name>/SKILL.md` so coding agents have project-specific guidance",
+        });
+        // WHY: opportunities: 1 (not 0) signals one actionable fix exists (add any instruction file).
+        // This differs from sibling rules that return opportunities: N (one per candidate path) because
+        // here the surface is entirely absent — there is no per-file opportunity to count.
+        return { findings, opportunities: 1 };
+    }
+    let opportunities = 0;
+    for (const rel of cursorFiles) {
+        opportunities += 1;
+        const abs = join(ctx.repoRoot, rel);
+        const { content, bytes } = readFileIfSmall(abs);
+        const relPath = rel;
+        if (content === null) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Cursor rule file ${relPath} could not be read (file too large: ${bytes} bytes)`,
+                suggestion: `split the rule into smaller files (≤ ${MAX_FILE_BYTES} bytes)`,
+            });
+            continue;
+        }
+        if (bytes > TOKEN_BUDGET_BYTES) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Cursor rule file is ${bytes} bytes (> ${TOKEN_BUDGET_BYTES} byte token-budget) — costs agents context`,
+                suggestion: "split into smaller focused rules or trim prose; agents pay context cost on every load",
+            });
+        }
+        const parsed = parseFrontmatter(content);
+        if (!parsed.ok) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "error",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Cursor rule ${relPath} has invalid frontmatter: ${parsed.error}`,
+                suggestion: "wrap frontmatter in `---` markers and ensure `description` + `globs` keys are present",
+            });
+            continue;
+        }
+        const { errors, warnings } = validateCursorRuleFrontmatter(parsed.data);
+        for (const err of errors) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "error",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Cursor rule ${relPath}: ${err}`,
+                suggestion: "see https://cursor.com/docs/context/rules for the expected frontmatter shape",
+            });
+        }
+        for (const warn of warnings) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Cursor rule ${relPath}: ${warn}`,
+            });
+        }
+    }
+    for (const rel of skillFiles) {
+        opportunities += 1;
+        const abs = join(ctx.repoRoot, rel);
+        const { content, bytes } = readFileIfSmall(abs);
+        const relPath = rel;
+        if (content === null) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Claude skill file ${relPath} could not be read (file too large: ${bytes} bytes)`,
+                suggestion: `keep SKILL.md focused (≤ ${MAX_FILE_BYTES} bytes); use linked files for verbose references`,
+            });
+            continue;
+        }
+        if (bytes > TOKEN_BUDGET_BYTES) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Claude skill file is ${bytes} bytes (> ${TOKEN_BUDGET_BYTES} byte token-budget) — costs agents context`,
+                suggestion: "trim SKILL.md and offload verbose references to linked files",
+            });
+        }
+        const parsed = parseFrontmatter(content);
+        if (!parsed.ok) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "error",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Claude skill ${relPath} has invalid frontmatter: ${parsed.error}`,
+                suggestion: "wrap frontmatter in `---` markers and ensure `name` + `description` keys are present",
+            });
+            continue;
+        }
+        const { errors, warnings } = validateSkillFrontmatter(parsed.data);
+        for (const err of errors) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "error",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Claude skill ${relPath}: ${err}`,
+                suggestion: "see https://docs.claude.com/en/docs/agents-and-tools/skills for the expected frontmatter shape",
+            });
+        }
+        for (const warn of warnings) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Claude skill ${relPath}: ${warn}`,
+            });
+        }
+    }
+    return { findings, opportunities };
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "ai-surface",
+        lyseRuleId: RULE_ID,
+        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
+
+Cursor 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.
+
+Beyond 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.
+
+Token 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",
+        ],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+export const _internal = {
+    parseFrontmatter,
+    validateCursorRuleFrontmatter,
+    validateSkillFrontmatter,
+    isStringOrStringArray,
+    CURSOR_RULE_GLOBS,
+    CLAUDE_SKILL_GLOBS,
+    TOKEN_BUDGET_BYTES,
+    DESCRIPTION_MAX_CHARS,
+    KEBAB_CASE_RE,
+};
+//# sourceMappingURL=ai-surface-agent-instruction-files.js.map

package/dist/rules/ai-surface-agent-instruction-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-surface-agent-instruction-files.js","sourceRoot":"","sources":["../../src/rules/ai-surface-agent-instruction-files.ts"],"names":[],"mappings":"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"}

package/dist/rules/ai-surface-llms-txt-structure.d.ts

@@ -0,0 +1,18 @@
+import type { Rule } from "../types.js";
+interface StructureIssue {
+    line: number;
+    message: string;
+    suggestion: string;
+}
+interface StructureReport {
+    hasH1: boolean;
+    hasBlockquote: boolean;
+    hasSection: boolean;
+    malformedLinks: StructureIssue[];
+}
+declare function analyseStructure(content: string): StructureReport;
+export declare const rule: Rule;
+export declare const _internal: {
+    analyseStructure: typeof analyseStructure;
+};
+export {};