cue-ai 0.5.0 → 0.7.0

package/src/lib/runtime-materializer.ts

@@ -9,9 +9,22 @@
 
 import { createHash } from "node:crypto";
 import { mkdir, rename, rm, symlink, writeFile, readFile, mkdtemp, readdir, lstat } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve as resolvePath, basename, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { AgentKind, ResolvedProfile } from "../../profiles/_types";
+import { normalizeUvxGitServers } from "./uvx-installer";
+
+const REPO_ROOT = resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const RESOURCES_RULES = join(REPO_ROOT, "resources", "rules");
+const RESOURCES_COMMANDS = join(REPO_ROOT, "resources", "commands");
+const RESOURCES_HOOKS = join(REPO_ROOT, "resources", "hooks");
+const RESOURCES_PLAYBOOKS = join(REPO_ROOT, "resources", "playbooks");
+const RESOURCES_QUALITY_GATES = join(REPO_ROOT, "resources", "quality-gates");
+
+function resolveResourcePath(ref: string, base: string): string {
+  return isAbsolute(ref) ? ref : join(base, ref);
+}
 
 /** MCP server configuration as stored in the registry. */
 export interface McpServerConfig {
@@ -66,23 +79,45 @@ function computeHash(profile: ResolvedProfile, agent: AgentKind): string {
 export async function materializeRuntime(input: MaterializeInput): Promise<MaterializeOutput> {
   const { profile, agent, runtimeRoot } = input;
   const runtimeDir = join(runtimeRoot, profile.name, agentSubdir(agent));
+
+  // Normalize any `uvx --from git+<repo> <bin>` MCP entries: install the
+  // package locally with `uv tool install` and rewrite the entry to call the
+  // installed binary. Sidesteps both the MCP-startup cold-download race and
+  // the auto-mode classifier's "fetch arbitrary code from URL" block.
+  // Idempotent — re-runs detect an existing binary and just rewrite.
+  const { normalized: normalizedRegistry, report: uvxReport } =
+    normalizeUvxGitServers(input.mcpRegistry);
+  const effectiveInput: MaterializeInput = { ...input, mcpRegistry: normalizedRegistry };
+  if (uvxReport.installed.length > 0) {
+    process.stderr.write(
+      `[cue] installed uvx MCPs: ${uvxReport.installed.join(", ")}\n`,
+    );
+  }
+
   const hash = computeHash(profile, agent);
 
+  // Collect profile MCP entries once — used by both cache-hit and rebuild paths
+  // for the .claude.json sync.
+  const mcpServers = collectProfileMcps(profile, agent, effectiveInput.mcpRegistry);
+
   // Short-circuit if hash matches.
   try {
     const existing = (await readFile(join(runtimeDir, ".cue-hash"), "utf8")).trim();
     if (existing === hash) {
       // Refresh state from credentialsSource even on cache hit so account
       // switches and newly-added source entries are reflected.
-      if (input.credentialsSource) {
+      if (effectiveInput.credentialsSource) {
         // Re-merge settings.json from current credentialsSource.
         if (agent === "claude-code") {
-          const merged = await buildClaudeSettings(profile, agent, input);
+          const merged = await buildClaudeSettings(profile, agent, effectiveInput);
           await writeFile(join(runtimeDir, "settings.json"), merged + "\n");
         }
         // Re-overlay any source entries that aren't already present (e.g.
         // user added a new sessions/ entry, plugins/, etc.).
-        await overlaySourceState(runtimeDir, input.credentialsSource);
+        await overlaySourceState(runtimeDir, effectiveInput.credentialsSource);
+      }
+      if (agent === "claude-code") {
+        await syncMcpsIntoClaudeJson(runtimeDir, mcpServers);
       }
       return { runtimeDir, rebuilt: false, hash };
     }
@@ -92,26 +127,123 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
   await mkdir(dirname(runtimeDir), { recursive: true });
   const tmpDir = await mkdtemp(`${runtimeDir}.tmp.`);
 
-  // 1. Skills
+  // 1. Skills — missing refs are warned + skipped, not fatal. A profile that
+  // lists 20 skills and has 1 broken ref shouldn't crash the entire launch.
+  // `cue debug` and `cue validate` surface the broken ref clearly so the user
+  // can fix it. Behavior matches `cue debug`'s tolerance.
   const skillsDir = join(tmpDir, "skills");
   await mkdir(skillsDir, { recursive: true });
+  const skippedSkills: string[] = [];
   for (const skill of profile.skills.local) {
     if (!appliesToAgent(skill, agent)) continue;
-    const src = await input.skillSourceLookup(skill.id);
-    const target = join(skillsDir, skill.id);
-    await mkdir(dirname(target), { recursive: true });
-    await symlink(src, target);
+    try {
+      const src = await input.skillSourceLookup(skill.id);
+      const target = join(skillsDir, skill.id);
+      await mkdir(dirname(target), { recursive: true });
+      await symlink(src, target);
+    } catch (err) {
+      skippedSkills.push(skill.id);
+    }
+  }
+  if (skippedSkills.length > 0) {
+    process.stderr.write(
+      `[cue] skipped ${skippedSkills.length} missing skill(s): ${skippedSkills.slice(0, 5).join(", ")}` +
+      (skippedSkills.length > 5 ? `, +${skippedSkills.length - 5} more` : "") +
+      ` — run \`cue debug ${profile.name}\` for details\n`,
+    );
   }
 
-  // 2. settings.json (Claude) or config.toml (Codex) — Claude-only first cut.
-  const mcpServers: Record<string, McpServerConfig> = {};
-  for (const m of profile.mcps) {
-    if (!appliesToAgent(m, agent)) continue;
-    const reg = input.mcpRegistry[m.id];
-    if (reg !== undefined) mcpServers[m.id] = reg;
+  // Defensive defaults — older fixtures may not declare these arrays.
+  const profileRules = profile.rules ?? [];
+  const profileCommands = profile.commands ?? [];
+  const profileHooks = profile.hooks ?? [];
+
+  // 1b. Commands — symlink each <ref>.md into commands/ (Claude reads .claude/commands/*.md)
+  if (agent === "claude-code" && profileCommands.length > 0) {
+    const commandsDir = join(tmpDir, "commands");
+    await mkdir(commandsDir, { recursive: true });
+    for (const ref of profileCommands) {
+      const src = resolveResourcePath(ref.endsWith(".md") ? ref : `${ref}.md`, RESOURCES_COMMANDS);
+      try {
+        await lstat(src);
+        await symlink(src, join(commandsDir, basename(src)));
+      } catch { /* missing source — skip */ }
+    }
+  }
+
+  // 1c. Rules — symlink into rules/. Contents get appended to CLAUDE.md below.
+  if (profileRules.length > 0) {
+    const rulesDir = join(tmpDir, "rules");
+    await mkdir(rulesDir, { recursive: true });
+    for (const ref of profileRules) {
+      const src = resolveResourcePath(ref.endsWith(".md") ? ref : `${ref}.md`, RESOURCES_RULES);
+      try {
+        await lstat(src);
+        await symlink(src, join(rulesDir, basename(src)));
+      } catch { /* missing source — skip */ }
+    }
+  }
+
+  // 1d. Hooks — symlink scripts into hooks/. settings.json wiring happens in buildClaudeSettings.
+  // A hook ref points at a `.json` config; its referenced script (e.g. `<stem>.sh`)
+  // lives next to it in resources/hooks/ and must be symlinked too, otherwise the
+  // Stop/PreToolUse/etc. hook fires `bash $CLAUDE_CONFIG_DIR/hooks/<stem>.sh` and
+  // dies with "No such file or directory".
+  if (agent === "claude-code" && profileHooks.length > 0) {
+    const hooksDir = join(tmpDir, "hooks");
+    await mkdir(hooksDir, { recursive: true });
+    for (const ref of profileHooks) {
+      const src = resolveResourcePath(ref, RESOURCES_HOOKS);
+      try {
+        await lstat(src);
+        await symlink(src, join(hooksDir, basename(src)));
+      } catch { /* missing source — skip */ }
+      const stem = basename(ref).replace(/\.[^.]+$/, "");
+      for (const ext of [".sh", ".py", ".js", ".mjs", ".ts"]) {
+        const companion = join(RESOURCES_HOOKS, `${stem}${ext}`);
+        try {
+          await lstat(companion);
+          await symlink(companion, join(hooksDir, `${stem}${ext}`));
+        } catch { /* no companion at this ext — skip */ }
+      }
+    }
+  }
+
+  // 1e. Playbooks (Phase 2) — symlink markdown protocols into playbooks/.
+  // Indexed in CLAUDE.md so Claude knows to consult them; bodies lazy-loaded.
+  const profilePlaybooks = (profile as any).playbooks ?? [];
+  if (profilePlaybooks.length > 0) {
+    const pbDir = join(tmpDir, "playbooks");
+    await mkdir(pbDir, { recursive: true });
+    for (const ref of profilePlaybooks) {
+      const src = resolveResourcePath(ref.endsWith(".md") ? ref : `${ref}.md`, RESOURCES_PLAYBOOKS);
+      try {
+        await lstat(src);
+        await symlink(src, join(pbDir, basename(src)));
+      } catch { /* missing source — skip */ }
+    }
   }
+
+  // 1f. Quality gates (Phase 3) — symlink validator scripts into quality-gates/.
+  // The Stop hook (cue-quality-gates.sh, see resources/hooks/) iterates this
+  // directory and fails the session if any gate exits non-zero.
+  const profileGates = (profile as any).qualityGates ?? [];
+  if (agent === "claude-code" && profileGates.length > 0) {
+    const gDir = join(tmpDir, "quality-gates");
+    await mkdir(gDir, { recursive: true });
+    for (const ref of profileGates) {
+      const src = resolveResourcePath(ref, RESOURCES_QUALITY_GATES);
+      try {
+        await lstat(src);
+        await symlink(src, join(gDir, basename(src)));
+      } catch { /* missing source — skip */ }
+    }
+  }
+
+  // 2. settings.json (Claude) or config.toml (Codex) — Claude-only first cut.
+  // mcpServers was already collected above (used by both code paths).
   if (agent === "claude-code") {
-    const merged = await buildClaudeSettings(profile, agent, input);
+    const merged = await buildClaudeSettings(profile, agent, effectiveInput);
     await writeFile(join(tmpDir, "settings.json"), merged + "\n");
   } else {
     // Codex equivalent — write config.toml from registry. Caller pre-renders to TOML.
@@ -130,6 +262,15 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
               `# Active Profile: ${iconStr ? iconStr + " " : ""}${profile.name}\n\n` +
               `> ${profile.description}\n\n`;
 
+  // Phase 1: Persona — multi-line role-priming defining who the agent IS.
+  // Goes above the mechanical "Your Role" block so it primes interpretation
+  // of everything that follows. Profiles without a persona keep the old
+  // generic block (backwards-compatible).
+  const profilePersona = (profile as any).persona ?? "";
+  if (profilePersona.trim()) {
+    stamp += `## Your Expertise\n\n${profilePersona.trim()}\n\n`;
+  }
+
   // Role identity — tell Claude what it is
   stamp += `## Your Role\n\n` +
            `You are operating as **${profile.name}** — ${profile.description.toLowerCase()}.\n` +
@@ -176,16 +317,9 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
     }
   } catch { /* analytics unavailable — skip */ }
 
-  // Profile fit monitoring
-  stamp += `## Profile Fit Monitor\n\n` +
-    `Track how well this profile matches the work being done. If you notice:\n` +
-    `- You're doing work outside this profile's domain (e.g. backend work in a frontend profile)\n` +
-    `- None of the loaded skills are relevant to what the user is asking\n` +
-    `- You keep needing tools/skills that aren't in this profile\n\n` +
-    `Then after completing the user's immediate request, suggest switching:\n\n` +
-    `> 💡 This session has been mostly [backend/infra/docs] work — your current profile is **${profile.name}**.\n` +
-    `> A better fit might be **[suggested]**. Switch with: \`/cue switch [name]\` or \`echo [name] > .cue-profile\`\n\n` +
-    `Only suggest once per session. Don't interrupt urgent work.\n\n`;
+  // Profile fit monitoring — formerly a ~150-token hardcoded block; now a
+  // skill (meta/profile-fit-monitor) loaded on demand. Net per-message cost
+  // drops to just the skill's description line in "## Available Skills".
 
   // #8: Warm-start context — last session summary
   const lastSession = await getLastSessionSummary(profile.name);
@@ -199,6 +333,40 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
     stamp += `## Common Workflows\n\n${chains}\n\n`;
   }
 
+  // Rules — index only. Symlinks live in rules/; Claude reads on demand instead
+  // of paying the full token cost every turn.
+  if (profileRules.length > 0) {
+    stamp += `## Rules (${profileRules.length})\n\n` +
+      `Read on demand from \`rules/\`:\n` +
+      profileRules.map((r) => `- \`rules/${basename(r.endsWith(".md") ? r : `${r}.md`)}\``).join("\n") + "\n\n";
+  }
+
+  // Commands — list as a quick reference
+  if (profileCommands.length > 0) {
+    stamp += `## Available Commands\n\n` +
+      profileCommands.map((c) => `- /${basename(c, ".md")}`).join("\n") + "\n\n";
+  }
+
+  // Playbooks (Phase 2) — proven step-by-step protocols for common tasks.
+  // Indexed only; bodies are read on demand when the matching task triggers.
+  if (profilePlaybooks.length > 0) {
+    stamp += `## Playbooks (${profilePlaybooks.length})\n\n` +
+      `Read on demand from \`playbooks/\` when the user's request matches:\n` +
+      profilePlaybooks.map((p: string) => {
+        const stem = basename(p, ".md");
+        return `- \`playbooks/${stem}.md\` — use when ${stem.replace(/-/g, " ")}`;
+      }).join("\n") + "\n\n" +
+      `**Following a playbook beats freestyling.** If a relevant playbook exists, read it first and step through it.\n\n`;
+  }
+
+  // Quality gates (Phase 3) — mention so Claude knows what'll be checked at Stop.
+  const profileGatesForStamp = (profile as any).qualityGates ?? [];
+  if (profileGatesForStamp.length > 0) {
+    stamp += `## Quality Gates\n\nBefore claiming this session complete, these checks run at Stop:\n` +
+      profileGatesForStamp.map((g: string) => `- \`${basename(g)}\``).join("\n") + "\n\n" +
+      `Don't claim "done" if you haven't met them — they'll fail you publicly.\n\n`;
+  }
+
   stamp += `---\n*generated ${new Date().toISOString()} — do not hand-edit*\n\n`;
 
   await writeFile(join(tmpDir, agent === "claude-code" ? "CLAUDE.md" : "AGENTS.md"), stamp + input.userClaudeMd);
@@ -252,9 +420,56 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
   await rm(runtimeDir, { recursive: true, force: true });
   await rename(tmpDir, runtimeDir);
 
+  if (agent === "claude-code") {
+    await syncMcpsIntoClaudeJson(runtimeDir, mcpServers);
+  }
+
   return { runtimeDir, rebuilt: true, hash };
 }
 
+function collectProfileMcps(
+  profile: ResolvedProfile,
+  agent: AgentKind,
+  registry: Record<string, McpServerConfig>,
+): Record<string, McpServerConfig> {
+  const out: Record<string, McpServerConfig> = {};
+  for (const m of profile.mcps) {
+    if (!appliesToAgent(m, agent)) continue;
+    const reg = registry[m.id];
+    if (reg !== undefined) out[m.id] = reg;
+  }
+  return out;
+}
+
+// Claude Code reads MCP server definitions from .claude.json's top-level
+// `mcpServers` field, not from settings.json. Without this sync, profile MCPs
+// declared in profile.yaml never get started.
+//
+// We dereference any symlink first and write a real file in its place so
+// per-profile MCP additions don't leak back into a shared account-level
+// .claude.json (e.g. multiple cue profiles backed by the same account file).
+async function syncMcpsIntoClaudeJson(
+  runtimeDir: string,
+  mcpServers: Record<string, McpServerConfig>,
+): Promise<void> {
+  const target = join(runtimeDir, ".claude.json");
+  let parsed: Record<string, unknown> = {};
+  try {
+    const raw = await readFile(target, "utf8"); // follows symlink
+    parsed = JSON.parse(raw);
+  } catch {
+    // missing or unreadable — start with an empty doc; claude will fill the
+    // rest on next startup. If the file isn't valid JSON we'd lose state, but
+    // claude itself would also fail to read it, so a clean rewrite is fine.
+  }
+  const existing = (parsed.mcpServers as Record<string, unknown> | undefined) ?? {};
+  parsed.mcpServers = { ...existing, ...mcpServers };
+
+  // Replace whatever's there (symlink or stale file) with a real file copy.
+  await rm(target, { force: true });
+  await writeFile(target, JSON.stringify(parsed, null, 2));
+}
+
 // Build the merged Claude Code settings.json content (string).
 // Reads existing settings from credentialsSource (preserves permissions,
 // trustedDirectories, skipAutoPermissionPrompt) and overlays the profile's
@@ -263,6 +478,9 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
 const CUE_MANAGED_ENTRIES = new Set([
   "settings.json",
   "skills",
+  "commands",
+  "hooks",
+  "rules",
   "CLAUDE.md",
   "AGENTS.md",
   ".cue-hash",
@@ -290,10 +508,31 @@ async function overlaySourceState(targetDir: string, sourceDir: string): Promise
     return; // source unreadable; nothing to overlay
   }
 
+  // Legacy home-root .claude.json fallback: older Claude Code put session
+  // state at ~/.claude.json (sibling to ~/.claude/), not inside it. If the
+  // canonical inside-dir version is missing but the home-root one exists,
+  // surface it so the runtime looks fully onboarded — otherwise claude
+  // boots into the OAuth flow even with a valid .credentials.json present.
+  // Only kicks in when sourceDir is the user's ~/.claude.
+  if (!entries.includes(".claude.json") && sourceDir === join(homedir(), ".claude")) {
+    const legacy = join(homedir(), ".claude.json");
+    try {
+      const { existsSync } = await import("node:fs");
+      if (existsSync(legacy)) entries.push(".claude.json");
+    } catch { /* skip */ }
+  }
+
   for (const name of entries) {
     if (CUE_MANAGED_ENTRIES.has(name)) continue;
     const targetPath = join(targetDir, name);
-    const sourcePath = join(sourceDir, name);
+    // Special-case the legacy ~/.claude.json fallback above: source is at the
+    // home-root path, not inside sourceDir.
+    const isLegacyClaudeJson =
+      name === ".claude.json" &&
+      sourceDir === join(homedir(), ".claude");
+    const sourcePath = isLegacyClaudeJson
+      ? join(homedir(), ".claude.json")
+      : join(sourceDir, name);
 
     let existingType: "symlink" | "other" | "missing" = "missing";
     try {
@@ -301,19 +540,21 @@ async function overlaySourceState(targetDir: string, sourceDir: string): Promise
       existingType = st.isSymbolicLink() ? "symlink" : "other";
     } catch { /* missing */ }
 
-    if (existingType === "other" && name !== ".credentials.json") continue; // cue override — don't touch
+    // .claude.json gets the same copy-not-symlink treatment as .credentials.json:
+    // claude rewrites it atomically and we want per-profile session state, not
+    // a shared one that gets clobbered when 2 profiles run concurrently.
+    const isCopyFile = name === ".credentials.json" || isLegacyClaudeJson;
 
-    if (existingType === "symlink" || (existingType === "other" && name === ".credentials.json")) {
+    if (existingType === "other" && !isCopyFile) continue; // cue override — don't touch
+
+    if (existingType === "symlink" || (existingType === "other" && isCopyFile)) {
       // Replace if it points elsewhere (e.g. previous account on cache hit).
       try {
         await rm(targetPath, { force: true });
       } catch { continue; }
     }
 
-    // .credentials.json must be COPIED (not symlinked) because Claude Code
-    // refreshes tokens via atomic write (write tmp → rename), which replaces
-    // symlinks with regular files, leaving the source stale.
-    if (name === ".credentials.json") {
+    if (isCopyFile) {
       const { copyFile } = await import("node:fs/promises");
       try {
         await copyFile(sourcePath, targetPath);
@@ -336,12 +577,7 @@ async function buildClaudeSettings(
     if (!appliesToAgent(plugin, agent)) continue;
     enabledPlugins[plugin.id] = true;
   }
-  const mcpServers: Record<string, McpServerConfig> = {};
-  for (const m of profile.mcps) {
-    if (!appliesToAgent(m, agent)) continue;
-    const reg = input.mcpRegistry[m.id];
-    if (reg !== undefined) mcpServers[m.id] = reg;
-  }
+  const mcpServers = collectProfileMcps(profile, agent, input.mcpRegistry);
   let baseSettings: Record<string, unknown> = {};
   if (input.credentialsSource) {
     try {
@@ -349,11 +585,43 @@ async function buildClaudeSettings(
       baseSettings = JSON.parse(raw);
     } catch { /* no existing settings — start fresh */ }
   }
-  const settings = {
+
+  // Merge profile hooks. A hook ref points to a JSON file with shape
+  // { hooks: { PreToolUse: [...], ... } } — same shape Claude Code expects.
+  // Multiple hook files concat their event arrays under each lifecycle key.
+  let mergedHooks: Record<string, unknown[]> = {};
+  const baseHooks = (baseSettings.hooks as Record<string, unknown[]> | undefined) ?? {};
+  for (const [k, v] of Object.entries(baseHooks)) {
+    mergedHooks[k] = Array.isArray(v) ? [...v] : [];
+  }
+  for (const ref of (profile.hooks ?? [])) {
+    const src = resolveResourcePath(ref, RESOURCES_HOOKS);
+    try {
+      const raw = await readFile(src, "utf8");
+      const parsed = JSON.parse(raw) as { hooks?: Record<string, unknown[]> };
+      for (const [event, entries] of Object.entries(parsed.hooks ?? {})) {
+        if (!Array.isArray(entries)) continue;
+        mergedHooks[event] = [...(mergedHooks[event] ?? []), ...entries];
+      }
+    } catch { /* missing or malformed — skip */ }
+  }
+
+  const settings: Record<string, unknown> = {
     ...baseSettings,
-    enabledPlugins: { ...(baseSettings.enabledPlugins as Record<string, unknown> ?? {}), ...enabledPlugins },
-    mcpServers: { ...(baseSettings.mcpServers as Record<string, unknown> ?? {}), ...mcpServers },
+    // MCPs are profile-scoped — do NOT merge baseSettings.mcpServers in.
+    // Otherwise every MCP registered in the user's source ~/.claude/settings.json
+    // (or ~/.claude-accounts/<acct>/settings.json) leaks into every profile's
+    // runtime, defeating profile isolation. Profiles like `cybersecurity` that
+    // declare `mcps: []` would otherwise show whatever the user has globally.
+    mcpServers,
+    // Same reasoning for plugins: profile is the source of truth. `enabledPlugins`
+    // controls Claude Code's plugin marketplace toggles per-profile; merging from
+    // baseSettings would re-enable marketing plugins inside a backend profile.
+    enabledPlugins,
   };
+  if (Object.keys(mergedHooks).length > 0) {
+    settings.hooks = mergedHooks;
+  }
   return JSON.stringify(settings, null, 2);
 }
 

package/src/lib/scan-plugins.test.ts

@@ -10,7 +10,7 @@ let pluginsRoot: string;
 let configPath: string;
 
 beforeEach(async () => {
-  root = await mkdtemp(join(tmpdir(), "soul-scan-plugins-"));
+  root = await mkdtemp(join(tmpdir(), "cue-scan-plugins-"));
   pluginsRoot = join(root, "plugins");
   configPath = join(root, "claude.json");
   await mkdir(pluginsRoot, { recursive: true });

package/src/lib/skill-linter.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import { lint, applyFixes, buildPrBody } from "./skill-linter";
+
+const cleanSkill = `---
+name: example-skill
+description: Use when the user asks to do X with Y. Triggers on phrases like "do x".
+tags: [example, demo]
+allowed-tools: Bash(echo:*)
+---
+
+# Example Skill
+
+This is a demo skill body.
+
+## Prerequisites
+
+- \`echo\` — built-in
+`;
+
+describe("skill-linter rules", () => {
+  test("clean skill emits no errors", () => {
+    const { diagnostics } = lint(cleanSkill);
+    expect(diagnostics.filter((d) => d.severity === "error")).toEqual([]);
+  });
+
+  test("R001: missing name is flagged + fixable from H1", () => {
+    const md = `---\ndescription: x\n---\n# My Skill\n`;
+    const diags = lint(md).diagnostics;
+    const r001 = diags.find((d) => d.rule === "R001");
+    expect(r001?.severity).toBe("error");
+    expect(typeof r001?.fix).toBe("function");
+    const fixed = r001!.fix!(md);
+    expect(fixed).toMatch(/name:\s*my-skill/);
+  });
+
+  test("R002: missing description is flagged (not auto-fixable)", () => {
+    const md = `---\nname: x\n---\n# X\n`;
+    const r002 = lint(md).diagnostics.find((d) => d.rule === "R002");
+    expect(r002?.severity).toBe("error");
+    expect(r002?.fix).toBeUndefined();
+  });
+
+  test("R003: description >200 chars is flagged", () => {
+    const long = "A".repeat(250);
+    const md = `---\nname: x\ndescription: ${long}\n---\n`;
+    const r003 = lint(md).diagnostics.find((d) => d.rule === "R003");
+    expect(r003?.severity).toBe("warning");
+  });
+
+  test("R004: description without trigger phrase is flagged", () => {
+    const md = `---\nname: x\ndescription: A library for parsing things.\n---\n`;
+    const r004 = lint(md).diagnostics.find((d) => d.rule === "R004");
+    expect(r004?.severity).toBe("warning");
+  });
+
+  test("R004: description WITH trigger phrase passes", () => {
+    const md = `---\nname: x\ndescription: Use when the user asks for parsing.\n---\n`;
+    expect(lint(md).diagnostics.find((d) => d.rule === "R004")).toBeUndefined();
+  });
+
+  test("R005: bare allowed-tools is flagged + fixed to Bash(name:*) form", () => {
+    const md = `---\nname: x\ndescription: Use when X.\nallowed-tools: nmap, curl\n---\n# X\n`;
+    const r005 = lint(md).diagnostics.find((d) => d.rule === "R005");
+    expect(r005?.severity).toBe("error");
+    const fixed = r005!.fix!(md);
+    expect(fixed).toContain("Bash(nmap:*)");
+    expect(fixed).toContain("Bash(curl:*)");
+  });
+
+  test("R006: skill declares CLIs but no Prerequisites — flagged + fixed", () => {
+    const md = `---\nname: x\ndescription: Use when X.\nallowed-tools: Bash(nmap:*), Bash(sqlmap:*)\n---\n\n# X\n\nThis does things.\n`;
+    const r006 = lint(md).diagnostics.find((d) => d.rule === "R006");
+    expect(r006?.severity).toBe("warning");
+    const fixed = r006!.fix!(md);
+    expect(fixed).toMatch(/^## Prerequisites$/m);
+    expect(fixed).toContain("**nmap**");
+    expect(fixed).toContain("**sqlmap**");
+  });
+
+  test("R006: skill with existing Prerequisites is not flagged", () => {
+    const md = `---\nname: x\ndescription: Use when X.\nallowed-tools: Bash(nmap:*)\n---\n\n# X\n\n## Prerequisites\n\n- nmap\n`;
+    expect(lint(md).diagnostics.find((d) => d.rule === "R006")).toBeUndefined();
+  });
+
+  test("R007: no tags/domain/category is info-level (not error)", () => {
+    const md = `---\nname: x\ndescription: Use when X.\n---\n`;
+    const r007 = lint(md).diagnostics.find((d) => d.rule === "R007");
+    expect(r007?.severity).toBe("info");
+  });
+
+  test("R008: broken anchor link is flagged", () => {
+    const md = `---\nname: x\ndescription: Use when X.\n---\n\n# X\n\nSee [details](#missing-section).\n`;
+    const r008 = lint(md).diagnostics.find((d) => d.rule === "R008");
+    expect(r008?.severity).toBe("warning");
+    expect(r008?.message).toContain("missing-section");
+  });
+});
+
+describe("applyFixes round-trip", () => {
+  test("fixing a broken skill makes errors disappear (round-trip)", () => {
+    const broken = `---\nallowed-tools: nmap, sqlmap\n---\n# Pen Test Helper\n\nDoes stuff.\n`;
+    const { fixed, applied } = applyFixes(broken);
+    expect(applied).toContain("R001"); // name added
+    expect(applied).toContain("R005"); // allowed-tools fixed
+    expect(applied).toContain("R006"); // Prerequisites added
+    // After fix, those three rules should no longer be flagged
+    const remaining = lint(fixed).diagnostics.map((d) => d.rule);
+    expect(remaining).not.toContain("R001");
+    expect(remaining).not.toContain("R005");
+    expect(remaining).not.toContain("R006");
+  });
+
+  test("applyFixes is idempotent — running twice is the same as once", () => {
+    const broken = `---\nallowed-tools: nmap\n---\n# X\n`;
+    const once = applyFixes(broken).fixed;
+    const twice = applyFixes(once).fixed;
+    expect(twice).toBe(once);
+  });
+});
+
+describe("buildPrBody", () => {
+  test("emits a title and body referencing the repo and listing fixes", () => {
+    const before = `---\nallowed-tools: nmap\n---\n# X\n`;
+    const { fixed, applied } = applyFixes(before);
+    const fixedDiags = lint(before).diagnostics.filter((d) => applied.includes(d.rule));
+    const left = lint(fixed).diagnostics;
+    const { title, body } = buildPrBody({
+      repo: "demo/skill",
+      files: [{ path: "SKILL.md", before, after: fixed, fixedRules: [...new Set(applied)] }],
+      diagnosticsFixed: fixedDiags, diagnosticsLeft: left,
+    });
+    expect(title).toContain("cue:");
+    expect(body).toContain("demo/skill");
+    expect(body).toContain("`cue`");
+    expect(body).toContain("opt out");
+    // Title now names the actual fixes (R001 → "add missing name:")
+    expect(title).toMatch(/name|prerequisites|allowed-tools/i);
+    // Body contains an inline diff
+    expect(body).toContain("```diff");
+  });
+});
+
+describe("buildPrTitle", () => {
+  test("0 fixed rules → flagged review title", async () => {
+    const { buildPrTitle } = await import("./skill-linter");
+    expect(buildPrTitle([], ["R002"])).toMatch(/spec issues need review/);
+  });
+  test("1 rule → single-clause title", async () => {
+    const { buildPrTitle } = await import("./skill-linter");
+    expect(buildPrTitle(["R005"], [])).toMatch(/fix `allowed-tools` syntax/);
+  });
+  test("2 rules → joined with +", async () => {
+    const { buildPrTitle } = await import("./skill-linter");
+    expect(buildPrTitle(["R005", "R006"], [])).toMatch(/allowed-tools.*\+.*Prerequisites/);
+  });
+  test("3+ rules → truncates with `+N more`", async () => {
+    const { buildPrTitle } = await import("./skill-linter");
+    expect(buildPrTitle(["R001", "R005", "R006", "R007"], [])).toMatch(/\+\d+ more/);
+  });
+});
+
+describe("R006 with cli-recipes", () => {
+  test("Prerequisites section uses per-platform install commands from cli-recipes.json", () => {
+    const md = `---\nname: x\ndescription: Use when X.\nallowed-tools: Bash(nmap:*)\n---\n\n# X\n\nBody.\n`;
+    const { fixed } = applyFixes(md);
+    expect(fixed).toContain("sudo apt install -y nmap");
+    expect(fixed).toContain("brew install nmap");
+  });
+  test("snap-only recipe (helm) emits snap command", () => {
+    const md = `---\nname: x\ndescription: Use when X.\nallowed-tools: Bash(helm:*)\n---\n\n# X\n\nBody.\n`;
+    const { fixed } = applyFixes(md);
+    expect(fixed).toContain("sudo snap install helm");
+  });
+});