@rely-ai/caliber 1.12.14 → 1.12.15

package/dist/bin.js

@@ -2443,9 +2443,19 @@ function buildGeneratePrompt(fingerprint, targetAgent, prompt, failingChecks, cu
   if (isTargetedFix) {
     parts.push(`TARGETED FIX MODE \u2014 current score: ${currentScore}/100, target: ${targetAgent}`);
     parts.push(`
-The existing config is already high quality. ONLY fix these specific failing checks:`);
+The existing config is already high quality. ONLY fix these specific failing checks:
+`);
     for (const check of failingChecks) {
-      parts.push(`- ${check.name}${check.suggestion ? `: ${check.suggestion}` : ""}`);
+      if (check.fix) {
+        parts.push(`- **${check.name}**`);
+        parts.push(`  Action: ${check.fix.instruction}`);
+        if (check.fix.data && Object.keys(check.fix.data).length > 0) {
+          const dataStr = Object.entries(check.fix.data).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : String(v)}`).join("; ");
+          parts.push(`  Data: ${dataStr}`);
+        }
+      } else {
+        parts.push(`- ${check.name}${check.suggestion ? `: ${check.suggestion}` : ""}`);
+      }
     }
     if (passingChecks && passingChecks.length > 0) {
       parts.push(`
@@ -2460,9 +2470,10 @@ IMPORTANT RULES FOR TARGETED FIX:
 - Do NOT rewrite, restructure, rephrase, or make cosmetic changes.
 - Preserve the existing content as-is except for targeted fixes.
 - If a skill file is not related to a failing check, return it EXACTLY as-is, character for character.
-- For "Documented commands exist": DELETE the specific invalid commands listed in the suggestion. Do NOT replace them with other commands unless you are 100% certain they exist.
-- For "Documented paths exist": DELETE the specific non-existent paths listed in the suggestion. Do NOT replace them with guessed paths.
-- For "Concise context files": Remove the least important lines to get under the line limit. Do NOT add new content.`);
+- For reference accuracy issues: DELETE non-existent paths. Do NOT replace with guessed paths.
+- For concise config issues: Remove the least important lines to get under the token limit. Do NOT add new content.
+- For grounding issues: Add references to the listed project directories in the appropriate sections.
+- Every path or name you reference MUST exist in the project \u2014 use the file tree provided below.`);
   } else if (hasExistingConfigs) {
     parts.push(`Audit and improve the existing coding agent configuration for target: ${targetAgent}`);
   } else {
@@ -3728,12 +3739,12 @@ async function runInteractiveProviderSetup(options) {
 }
 
 // src/scoring/index.ts
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { join as join8 } from "path";
 
 // src/scoring/checks/existence.ts
-import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
 
 // src/scoring/constants.ts
 var POINTS_CLAUDE_MD_EXISTS = 6;
@@ -3744,52 +3755,51 @@ var POINTS_SKILLS_BONUS_CAP = 2;
 var POINTS_CURSOR_MDC_RULES = 3;
 var POINTS_MCP_SERVERS = 3;
 var POINTS_CROSS_PLATFORM_PARITY = 2;
-var POINTS_HAS_COMMANDS = 8;
-var POINTS_NOT_BLOATED = 6;
-var POINTS_NO_VAGUE = 4;
+var POINTS_EXECUTABLE_CONTENT = 8;
+var POINTS_CONCISE_CONFIG = 6;
+var POINTS_CONCRETENESS = 4;
 var POINTS_NO_DIR_TREE = 3;
 var POINTS_NO_DUPLICATES = 2;
-var POINTS_NO_CONTRADICTIONS = 2;
-var POINTS_DEP_COVERAGE = 10;
-var POINTS_SERVICE_COVERAGE = 6;
-var POINTS_MCP_COVERAGE = 4;
-var POINTS_COMMANDS_VALID = 6;
-var POINTS_PATHS_VALID = 4;
-var POINTS_CONFIG_DRIFT = 5;
+var POINTS_HAS_STRUCTURE = 2;
+var POINTS_PROJECT_GROUNDING = 12;
+var POINTS_REFERENCE_DENSITY = 8;
+var POINTS_REFERENCES_VALID = 8;
+var POINTS_CONFIG_DRIFT = 7;
 var POINTS_FRESHNESS = 4;
 var POINTS_NO_SECRETS = 4;
 var POINTS_PERMISSIONS = 2;
 var POINTS_HOOKS = 2;
 var POINTS_AGENTS_MD = 1;
 var POINTS_OPEN_SKILLS_FORMAT = 2;
-var BLOAT_THRESHOLDS = [
-  { maxLines: 150, points: 6 },
-  { maxLines: 200, points: 4 },
-  { maxLines: 300, points: 3 },
-  { maxLines: 500, points: 1 }
+var TOKEN_BUDGET_THRESHOLDS = [
+  { maxTokens: 2e3, points: 6 },
+  { maxTokens: 3500, points: 5 },
+  { maxTokens: 5e3, points: 4 },
+  { maxTokens: 8e3, points: 2 },
+  { maxTokens: 12e3, points: 1 }
+];
+var CODE_BLOCK_THRESHOLDS = [
+  { minBlocks: 3, points: 8 },
+  { minBlocks: 2, points: 6 },
+  { minBlocks: 1, points: 3 }
 ];
-var FRESHNESS_THRESHOLDS = [
-  { maxDaysOld: 7, points: 4 },
-  { maxDaysOld: 14, points: 3 },
-  { maxDaysOld: 30, points: 2 },
-  { maxDaysOld: 60, points: 1 }
+var FRESHNESS_COMMIT_THRESHOLDS = [
+  { maxCommits: 5, points: 4 },
+  { maxCommits: 15, points: 3 },
+  { maxCommits: 30, points: 2 },
+  { maxCommits: 60, points: 1 }
 ];
-var VAGUE_PATTERNS = [
-  /follow\s+best\s+practices/i,
-  /write\s+clean\s+code/i,
-  /ensure\s+quality/i,
-  /be\s+consistent/i,
-  /maintain\s+readability/i,
-  /keep\s+it\s+simple/i,
-  /use\s+appropriate\s+patterns/i,
-  /follow\s+coding\s+standards/i
+var CONCRETENESS_THRESHOLDS = [
+  { minRatio: 0.7, points: 4 },
+  { minRatio: 0.5, points: 3 },
+  { minRatio: 0.3, points: 2 },
+  { minRatio: 0.15, points: 1 }
 ];
-var COMMAND_PATTERNS = [
-  /(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:dev|build|test|lint|start|format)/i,
-  /(?:make|cargo|go)\s+(?:build|test|run|lint|vet|fmt)/i,
-  /(?:vitest|jest|pytest|mocha|ava)\b/i,
-  /(?:eslint|prettier|biome|ruff)\b/i,
-  /npx\s+tsc/i
+var GROUNDING_THRESHOLDS = [
+  { minRatio: 0.5, points: 12 },
+  { minRatio: 0.35, points: 9 },
+  { minRatio: 0.2, points: 6 },
+  { minRatio: 0.1, points: 3 }
 ];
 var SECRET_PATTERNS = [
   /sk-[a-zA-Z0-9]{20,}/,
@@ -3800,12 +3810,14 @@ var SECRET_PATTERNS = [
   /xox[bpors]-[a-zA-Z0-9\-]{10,}/,
   /(?:password|secret|token|api_key)\s*[:=]\s*["'][^"']{8,}["']/i
 ];
-var CONTRADICTION_PAIRS = [
-  { a: /\buse\s+npm\b/i, b: /\buse\s+(?:pnpm|yarn|bun)\b/i },
-  { a: /\buse\s+pnpm\b/i, b: /\buse\s+(?:npm|yarn|bun)\b/i },
-  { a: /\buse\s+yarn\b/i, b: /\buse\s+(?:npm|pnpm|bun)\b/i },
-  { a: /\buse\s+tabs\b/i, b: /\buse\s+spaces\b/i },
-  { a: /\bsemicolons?\b.*\balways\b/i, b: /\bno\s+semicolons?\b/i }
+var SECRET_PLACEHOLDER_PATTERNS = [
+  /your[_-]/i,
+  /xxx/i,
+  /example/i,
+  /placeholder/i,
+  /TODO/i,
+  /CHANGE[_-]?ME/i,
+  /<[^>]+>/
 ];
 var CURSOR_ONLY_CHECKS = /* @__PURE__ */ new Set([
   "cursor_rules_exist",
@@ -3822,6 +3834,9 @@ var BOTH_ONLY_CHECKS = /* @__PURE__ */ new Set([
 var CODEX_ONLY_CHECKS = /* @__PURE__ */ new Set([
   "codex_agents_md_exists"
 ]);
+var NON_CODEX_CHECKS = /* @__PURE__ */ new Set([
+  "agents_md_exists"
+]);
 var GRADE_THRESHOLDS = [
   { minScore: 85, grade: "A" },
   { minScore: 70, grade: "B" },
@@ -3836,187 +3851,10 @@ function computeGrade(score) {
   return "F";
 }
 
-// src/scoring/checks/coverage.ts
-import { readFileSync as readFileSync2, readdirSync } from "fs";
-import { join as join2 } from "path";
-function readFileOrNull2(path27) {
-  try {
-    return readFileSync2(path27, "utf-8");
-  } catch {
-    return null;
-  }
-}
-function collectAllConfigContent(dir) {
-  const parts = [];
-  const claudeMd = readFileOrNull2(join2(dir, "CLAUDE.md"));
-  if (claudeMd) parts.push(claudeMd);
-  const cursorrules = readFileOrNull2(join2(dir, ".cursorrules"));
-  if (cursorrules) parts.push(cursorrules);
-  for (const skillsDir of [join2(dir, ".claude", "skills"), join2(dir, ".cursor", "skills")]) {
-    try {
-      const entries = readdirSync(skillsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          const skill = readFileOrNull2(join2(skillsDir, entry.name, "SKILL.md"));
-          if (skill) parts.push(skill);
-        }
-      }
-    } catch {
-    }
-  }
-  try {
-    const rulesDir = join2(dir, ".cursor", "rules");
-    const mdcFiles = readdirSync(rulesDir).filter((f) => f.endsWith(".mdc"));
-    for (const f of mdcFiles) {
-      const content = readFileOrNull2(join2(rulesDir, f));
-      if (content) parts.push(content);
-    }
-  } catch {
-  }
-  return parts.join("\n").toLowerCase();
-}
-function hasExternalServices(dir) {
-  const allDeps = [
-    ...extractNpmDeps(dir),
-    ...extractPythonDeps(dir),
-    ...extractGoDeps(dir),
-    ...extractRustDeps(dir)
-  ];
-  return detectServices(dir, allDeps).length > 0;
-}
-function detectServices(dir, deps) {
-  const serviceMap = {
-    "postgresql": ["pg", "postgres", "knex", "drizzle-orm", "prisma", "sequelize", "typeorm", "psycopg2", "sqlalchemy", "diesel"],
-    "mongodb": ["mongoose", "mongodb", "mongod", "pymongo", "motor"],
-    "redis": ["redis", "ioredis", "bull", "bullmq", "aioredis"],
-    "supabase": ["@supabase/supabase-js", "supabase", "supabase-py"],
-    "firebase": ["firebase", "firebase-admin", "@firebase/app"],
-    "aws": ["aws-sdk", "@aws-sdk/client-s3", "boto3", "aws-cdk"],
-    "stripe": ["stripe", "@stripe/stripe-js"],
-    "github": ["@octokit/rest", "octokit", "pygithub"],
-    "slack": ["@slack/web-api", "@slack/bolt", "slack-sdk"],
-    "sentry": ["@sentry/node", "@sentry/react", "sentry-sdk"]
-  };
-  const detected = [];
-  const depSet = new Set(deps.map((d) => d.toLowerCase()));
-  for (const [service, markers] of Object.entries(serviceMap)) {
-    if (markers.some((m) => depSet.has(m))) {
-      detected.push(service);
-    }
-  }
-  return detected;
-}
-function getConfiguredMcpServers(dir) {
-  const servers = /* @__PURE__ */ new Set();
-  const mcpFiles = [
-    ".mcp.json",
-    ".cursor/mcp.json",
-    ".claude/settings.local.json",
-    ".claude/settings.json"
-  ];
-  for (const rel of mcpFiles) {
-    try {
-      const content = readFileSync2(join2(dir, rel), "utf-8");
-      const parsed = JSON.parse(content);
-      const mcpServers = parsed.mcpServers;
-      if (mcpServers) {
-        for (const name of Object.keys(mcpServers)) {
-          servers.add(name.toLowerCase());
-        }
-      }
-    } catch {
-    }
-  }
-  return servers;
-}
-function checkCoverage(dir) {
-  const checks = [];
-  const allDeps = [
-    ...extractNpmDeps(dir),
-    ...extractPythonDeps(dir),
-    ...extractGoDeps(dir),
-    ...extractRustDeps(dir)
-  ];
-  const configContent = collectAllConfigContent(dir);
-  const mentionedDeps = [];
-  const unmatchedDeps = [];
-  for (const dep of allDeps) {
-    const normalized = dep.replace(/^@[^/]+\//, "").toLowerCase();
-    const variants = [
-      normalized,
-      normalized.replace(/-/g, "_"),
-      normalized.replace(/_/g, "-"),
-      normalized.replace(/-/g, "")
-    ];
-    if (variants.some((v) => configContent.includes(v))) {
-      mentionedDeps.push(dep);
-    } else {
-      unmatchedDeps.push(dep);
-    }
-  }
-  const depCoverageRatio = allDeps.length > 0 ? mentionedDeps.length / allDeps.length : 1;
-  const effectiveRatio = depCoverageRatio >= 0.85 ? 1 : depCoverageRatio;
-  const depPoints = allDeps.length === 0 ? POINTS_DEP_COVERAGE : Math.round(effectiveRatio * POINTS_DEP_COVERAGE);
-  const topUnmatched = unmatchedDeps.slice(0, 3);
-  checks.push({
-    id: "dep_coverage",
-    name: "Dependency coverage",
-    category: "coverage",
-    maxPoints: POINTS_DEP_COVERAGE,
-    earnedPoints: depPoints,
-    passed: depCoverageRatio >= 0.5,
-    detail: allDeps.length === 0 ? "No dependencies detected" : `${mentionedDeps.length}/${allDeps.length} deps mentioned in configs (${Math.round(depCoverageRatio * 100)}%)`,
-    suggestion: topUnmatched.length > 0 ? `Missing coverage for: ${topUnmatched.join(", ")}${unmatchedDeps.length > 3 ? ` (+${unmatchedDeps.length - 3} more)` : ""}` : void 0
-  });
-  const detectedServices = detectServices(dir, allDeps);
-  const mcpServers = getConfiguredMcpServers(dir);
-  const mcpServerNames = Array.from(mcpServers).join(" ");
-  const coveredServices = [];
-  const uncoveredServices = [];
-  for (const service of detectedServices) {
-    if (mcpServerNames.includes(service) || configContent.includes(`${service} mcp`) || configContent.includes(`mcp.*${service}`)) {
-      coveredServices.push(service);
-    } else {
-      uncoveredServices.push(service);
-    }
-  }
-  const serviceCoverageRatio = detectedServices.length > 0 ? coveredServices.length / detectedServices.length : 1;
-  const servicePoints = detectedServices.length === 0 ? POINTS_SERVICE_COVERAGE : Math.round(serviceCoverageRatio * POINTS_SERVICE_COVERAGE);
-  checks.push({
-    id: "service_coverage",
-    name: "Service/MCP coverage",
-    category: "coverage",
-    maxPoints: POINTS_SERVICE_COVERAGE,
-    earnedPoints: servicePoints,
-    passed: serviceCoverageRatio >= 0.5,
-    detail: detectedServices.length === 0 ? "No external services detected" : `${coveredServices.length}/${detectedServices.length} services have MCP/config coverage`,
-    suggestion: uncoveredServices.length > 0 ? `No MCP server for: ${uncoveredServices.join(", ")} \u2014 consider adding MCP servers for these` : void 0
-  });
-  let mcpPoints;
-  if (detectedServices.length === 0) {
-    mcpPoints = POINTS_MCP_COVERAGE;
-  } else if (mcpServers.size > 0) {
-    mcpPoints = Math.round(serviceCoverageRatio * POINTS_MCP_COVERAGE);
-  } else {
-    mcpPoints = 0;
-  }
-  checks.push({
-    id: "mcp_completeness",
-    name: "MCP completeness",
-    category: "coverage",
-    maxPoints: POINTS_MCP_COVERAGE,
-    earnedPoints: mcpPoints,
-    passed: mcpPoints >= POINTS_MCP_COVERAGE / 2,
-    detail: detectedServices.length === 0 ? "No external services detected (MCP not needed)" : mcpServers.size === 0 ? "No MCP servers configured" : `${mcpServers.size} MCP server${mcpServers.size === 1 ? "" : "s"} configured`,
-    suggestion: mcpServers.size === 0 && detectedServices.length > 0 ? `Project uses ${detectedServices.join(", ")} but has no MCP servers` : void 0
-  });
-  return checks;
-}
-
 // src/scoring/checks/existence.ts
 function countFiles(dir, pattern) {
   try {
-    return readdirSync2(dir, { recursive: true }).map(String).filter((f) => pattern.test(f));
+    return readdirSync(dir, { recursive: true }).map(String).filter((f) => pattern.test(f));
   } catch {
     return [];
   }
@@ -4032,7 +3870,7 @@ function hasMcpServers(dir) {
   ];
   for (const rel of mcpFiles) {
     try {
-      const content = readFileSync3(join3(dir, rel), "utf-8");
+      const content = readFileSync2(join2(dir, rel), "utf-8");
       const parsed = JSON.parse(content);
       const servers = parsed.mcpServers;
       if (servers && Object.keys(servers).length > 0) {
@@ -4046,7 +3884,7 @@ function hasMcpServers(dir) {
 }
 function checkExistence(dir) {
   const checks = [];
-  const claudeMdExists = existsSync3(join3(dir, "CLAUDE.md"));
+  const claudeMdExists = existsSync2(join2(dir, "CLAUDE.md"));
   checks.push({
     id: "claude_md_exists",
     name: "CLAUDE.md exists",
@@ -4055,10 +3893,15 @@ function checkExistence(dir) {
     earnedPoints: claudeMdExists ? POINTS_CLAUDE_MD_EXISTS : 0,
     passed: claudeMdExists,
     detail: claudeMdExists ? "Found at project root" : "Not found",
-    suggestion: claudeMdExists ? void 0 : "Create a CLAUDE.md with project context and commands"
+    suggestion: claudeMdExists ? void 0 : "Create a CLAUDE.md with project context and commands",
+    fix: claudeMdExists ? void 0 : {
+      action: "create_file",
+      data: { file: "CLAUDE.md" },
+      instruction: "Create CLAUDE.md with project context, commands, architecture, and conventions."
+    }
   });
-  const hasCursorrules = existsSync3(join3(dir, ".cursorrules"));
-  const cursorRulesDir = existsSync3(join3(dir, ".cursor", "rules"));
+  const hasCursorrules = existsSync2(join2(dir, ".cursorrules"));
+  const cursorRulesDir = existsSync2(join2(dir, ".cursor", "rules"));
   const cursorRulesExist = hasCursorrules || cursorRulesDir;
   checks.push({
     id: "cursor_rules_exist",
@@ -4068,9 +3911,14 @@ function checkExistence(dir) {
     earnedPoints: cursorRulesExist ? POINTS_CURSOR_RULES_EXIST : 0,
     passed: cursorRulesExist,
     detail: hasCursorrules ? ".cursorrules found" : cursorRulesDir ? ".cursor/rules/ found" : "No Cursor rules",
-    suggestion: cursorRulesExist ? void 0 : "Add .cursor/rules/ for Cursor users on your team"
+    suggestion: cursorRulesExist ? void 0 : "Add .cursor/rules/ for Cursor users on your team",
+    fix: cursorRulesExist ? void 0 : {
+      action: "create_file",
+      data: { file: ".cursor/rules/" },
+      instruction: "Create .cursor/rules/ with project-specific Cursor rules."
+    }
   });
-  const agentsMdExists = existsSync3(join3(dir, "AGENTS.md"));
+  const agentsMdExists = existsSync2(join2(dir, "AGENTS.md"));
   checks.push({
     id: "codex_agents_md_exists",
     name: "AGENTS.md exists",
@@ -4079,10 +3927,15 @@ function checkExistence(dir) {
     earnedPoints: agentsMdExists ? POINTS_CLAUDE_MD_EXISTS : 0,
     passed: agentsMdExists,
     detail: agentsMdExists ? "Found at project root" : "Not found",
-    suggestion: agentsMdExists ? void 0 : "Create AGENTS.md with project context for Codex"
+    suggestion: agentsMdExists ? void 0 : "Create AGENTS.md with project context for Codex",
+    fix: agentsMdExists ? void 0 : {
+      action: "create_file",
+      data: { file: "AGENTS.md" },
+      instruction: "Create AGENTS.md with project context for Codex."
+    }
   });
-  const claudeSkills = countFiles(join3(dir, ".claude", "skills"), /\.(md|SKILL\.md)$/);
-  const codexSkills = countFiles(join3(dir, ".agents", "skills"), /SKILL\.md$/);
+  const claudeSkills = countFiles(join2(dir, ".claude", "skills"), /\.(md|SKILL\.md)$/);
+  const codexSkills = countFiles(join2(dir, ".agents", "skills"), /SKILL\.md$/);
   const skillCount = claudeSkills.length + codexSkills.length;
   const skillBase = skillCount >= 1 ? POINTS_SKILLS_EXIST : 0;
   const skillBonus = Math.min((skillCount - 1) * POINTS_SKILLS_BONUS_PER_EXTRA, POINTS_SKILLS_BONUS_CAP);
@@ -4096,9 +3949,14 @@ function checkExistence(dir) {
     earnedPoints: Math.min(skillPoints, maxSkillPoints),
     passed: skillCount >= 1,
     detail: skillCount === 0 ? "No skills found" : `${skillCount} skill${skillCount === 1 ? "" : "s"} found`,
-    suggestion: skillCount === 0 ? "Add .claude/skills/ with project-specific workflows" : skillCount < 3 ? "Optimal is 2-3 focused skills (SkillsBench research)" : void 0
+    suggestion: skillCount === 0 ? "Add .claude/skills/ with project-specific workflows" : skillCount < 3 ? "Optimal is 2-3 focused skills" : void 0,
+    fix: skillCount === 0 ? {
+      action: "create_skills",
+      data: { currentCount: 0 },
+      instruction: "Create .claude/skills/ with 2-3 project-specific workflow skills."
+    } : void 0
   });
-  const mdcFiles = countFiles(join3(dir, ".cursor", "rules"), /\.mdc$/);
+  const mdcFiles = countFiles(join2(dir, ".cursor", "rules"), /\.mdc$/);
   const mdcCount = mdcFiles.length;
   checks.push({
     id: "cursor_mdc_rules",
@@ -4108,20 +3966,28 @@ function checkExistence(dir) {
     earnedPoints: mdcCount >= 1 ? POINTS_CURSOR_MDC_RULES : 0,
     passed: mdcCount >= 1,
     detail: mdcCount === 0 ? "No .mdc rule files" : `${mdcCount} .mdc rule${mdcCount === 1 ? "" : "s"} found`,
-    suggestion: mdcCount === 0 ? "Add .cursor/rules/*.mdc with frontmatter for Cursor" : void 0
+    suggestion: mdcCount === 0 ? "Add .cursor/rules/*.mdc with frontmatter for Cursor" : void 0,
+    fix: mdcCount === 0 ? {
+      action: "create_mdc_rules",
+      data: {},
+      instruction: "Create .cursor/rules/*.mdc files with YAML frontmatter for Cursor."
+    } : void 0
   });
   const mcp = hasMcpServers(dir);
-  const hasServices = hasExternalServices(dir);
-  const mcpPassed = mcp.count >= 1 || !hasServices;
   checks.push({
     id: "mcp_servers",
     name: "MCP servers configured",
     category: "existence",
     maxPoints: POINTS_MCP_SERVERS,
-    earnedPoints: mcpPassed ? POINTS_MCP_SERVERS : 0,
-    passed: mcpPassed,
-    detail: mcp.count > 0 ? `${mcp.count} server${mcp.count === 1 ? "" : "s"} in ${mcp.sources.join(", ")}` : hasServices ? "No MCP servers (external services detected)" : "No MCP servers needed (no external services detected)",
-    suggestion: !mcpPassed ? "Configure MCP servers in .mcp.json for detected external services" : void 0
+    earnedPoints: mcp.count >= 1 ? POINTS_MCP_SERVERS : 0,
+    passed: mcp.count >= 1,
+    detail: mcp.count > 0 ? `${mcp.count} server${mcp.count === 1 ? "" : "s"} in ${mcp.sources.join(", ")}` : "No MCP servers configured",
+    suggestion: mcp.count === 0 ? "Configure MCP servers in .mcp.json for external service access" : void 0,
+    fix: mcp.count === 0 ? {
+      action: "configure_mcp",
+      data: {},
+      instruction: "Add MCP server configurations in .mcp.json for any external services the project uses."
+    } : void 0
   });
   const hasClaudeConfigs = claudeMdExists || skillCount > 0;
   const hasCursorConfigs = cursorRulesExist || mdcCount > 0;
@@ -4134,89 +4000,298 @@ function checkExistence(dir) {
     earnedPoints: hasParity ? POINTS_CROSS_PLATFORM_PARITY : 0,
     passed: hasParity,
     detail: hasParity ? "Both Claude Code and Cursor configured" : hasClaudeConfigs ? "Only Claude Code \u2014 no Cursor configs" : hasCursorConfigs ? "Only Cursor \u2014 no Claude Code configs" : "Neither platform configured",
-    suggestion: hasParity ? void 0 : "Add configs for both platforms so all teammates get context"
+    suggestion: hasParity ? void 0 : "Add configs for both platforms so all teammates get context",
+    fix: hasParity ? void 0 : {
+      action: "add_platform",
+      data: { hasClaude: hasClaudeConfigs, hasCursor: hasCursorConfigs },
+      instruction: hasClaudeConfigs ? "Add Cursor rules (.cursor/rules/) for cross-platform support." : "Add CLAUDE.md for cross-platform support."
+    }
   });
   return checks;
 }
 
 // src/scoring/checks/quality.ts
-import { readFileSync as readFileSync4 } from "fs";
 import { join as join4 } from "path";
-function readFileOrNull3(path27) {
+
+// src/scoring/utils.ts
+import { readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { join as join3, relative } from "path";
+function readFileOrNull2(filePath) {
   try {
-    return readFileSync4(path27, "utf-8");
+    return readFileSync3(filePath, "utf-8");
   } catch {
     return null;
   }
 }
-function countLines(content) {
-  return content.split("\n").length;
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  "__pycache__",
+  ".venv",
+  "venv",
+  "env",
+  ".env",
+  "target",
+  "vendor",
+  ".cache",
+  ".parcel-cache",
+  "coverage",
+  ".nyc_output",
+  ".turbo",
+  ".caliber",
+  ".claude",
+  ".cursor",
+  ".agents",
+  ".codex"
+]);
+var IGNORED_FILES = /* @__PURE__ */ new Set([
+  ".DS_Store",
+  "Thumbs.db",
+  ".gitignore",
+  ".editorconfig",
+  ".prettierrc",
+  ".prettierignore",
+  ".eslintignore",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "bun.lockb"
+]);
+function collectProjectStructure(dir, maxDepth = 2) {
+  const dirs = [];
+  const files = [];
+  function walk(currentDir, depth) {
+    if (depth > maxDepth) return;
+    try {
+      const entries = readdirSync2(currentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        const name = entry.name;
+        if (name.startsWith(".") && IGNORED_DIRS.has(name)) continue;
+        if (IGNORED_FILES.has(name)) continue;
+        const rel = relative(dir, join3(currentDir, name));
+        if (entry.isDirectory()) {
+          if (IGNORED_DIRS.has(name)) continue;
+          dirs.push(rel);
+          walk(join3(currentDir, name), depth + 1);
+        } else if (entry.isFile()) {
+          files.push(rel);
+        }
+      }
+    } catch {
+    }
+  }
+  walk(dir, 0);
+  return { dirs, files };
 }
+function collectAllConfigContent(dir) {
+  const parts = [];
+  for (const file of ["CLAUDE.md", ".cursorrules", "AGENTS.md"]) {
+    const content = readFileOrNull2(join3(dir, file));
+    if (content) parts.push(content);
+  }
+  for (const skillsDir of [join3(dir, ".claude", "skills"), join3(dir, ".agents", "skills")]) {
+    try {
+      const entries = readdirSync2(skillsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const skill = readFileOrNull2(join3(skillsDir, entry.name, "SKILL.md"));
+          if (skill) parts.push(skill);
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          const content = readFileOrNull2(join3(skillsDir, entry.name));
+          if (content) parts.push(content);
+        }
+      }
+    } catch {
+    }
+  }
+  try {
+    const rulesDir = join3(dir, ".cursor", "rules");
+    const mdcFiles = readdirSync2(rulesDir).filter((f) => f.endsWith(".mdc"));
+    for (const f of mdcFiles) {
+      const content = readFileOrNull2(join3(rulesDir, f));
+      if (content) parts.push(content);
+    }
+  } catch {
+  }
+  return parts.join("\n");
+}
+function estimateTokens2(text) {
+  return Math.ceil(text.length / 4);
+}
+function analyzeMarkdownStructure(content) {
+  const lines = content.split("\n");
+  let headingCount = 0;
+  let h2Count = 0;
+  let h3Count = 0;
+  let codeBlockCount = 0;
+  let codeBlockLines = 0;
+  let listItemCount = 0;
+  let inlineCodeCount = 0;
+  let inCodeBlock = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("```")) {
+      if (!inCodeBlock) codeBlockCount++;
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) {
+      codeBlockLines++;
+      continue;
+    }
+    if (trimmed.startsWith("## ") && !trimmed.startsWith("### ")) h2Count++;
+    if (trimmed.startsWith("### ")) h3Count++;
+    if (trimmed.startsWith("#")) headingCount++;
+    if (/^[-*+]\s/.test(trimmed) || /^\d+\.\s/.test(trimmed)) listItemCount++;
+    const inlineMatches = trimmed.match(/`[^`]+`/g);
+    if (inlineMatches) inlineCodeCount += inlineMatches.length;
+  }
+  return {
+    headingCount,
+    h2Count,
+    h3Count,
+    codeBlockCount,
+    codeBlockLines,
+    listItemCount,
+    inlineCodeCount,
+    totalLines: lines.length,
+    nonEmptyLines: lines.filter((l) => l.trim().length > 0).length
+  };
+}
+function extractReferences(content) {
+  const refs = /* @__PURE__ */ new Set();
+  const backtickPattern = /`([^`]+)`/g;
+  let match;
+  while ((match = backtickPattern.exec(content)) !== null) {
+    const term = match[1].trim();
+    if ((term.includes("/") || /\.\w{1,5}$/.test(term)) && !term.startsWith("-") && term.length < 200) {
+      if (term.startsWith("@") && (term.match(/\//g) || []).length === 1) continue;
+      if (term.includes(" ")) continue;
+      if (/^\d+\.\d+/.test(term)) continue;
+      if (term.includes("/") && !/\.\w{1,5}$/.test(term)) {
+        if (term !== term.toLowerCase() && !/^[a-z]/.test(term)) continue;
+        const segments = term.split("/");
+        if (segments.every((s) => s.length <= 3)) continue;
+      }
+      const cleaned = term.replace(/[,;:!?)]+$/, "");
+      if (cleaned.length > 1) refs.add(cleaned);
+    }
+  }
+  const pathPattern = /(?:^|\s)((?:[a-zA-Z0-9_@.-]+\/)+[a-zA-Z0-9_.*-]+\.[a-zA-Z]{1,5})/gm;
+  while ((match = pathPattern.exec(content)) !== null) {
+    const term = match[1].trim();
+    if (term.length > 2 && term.length < 200) {
+      if (term.startsWith("@") && (term.match(/\//g) || []).length === 1) continue;
+      const cleaned = term.replace(/[,;:!?)]+$/, "");
+      if (cleaned.length > 1) refs.add(cleaned);
+    }
+  }
+  return Array.from(refs);
+}
+function classifyLine(line, inCodeBlock) {
+  if (inCodeBlock) return "concrete";
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return "neutral";
+  if (trimmed.startsWith("#")) return "neutral";
+  if (/`[^`]+`/.test(trimmed)) return "concrete";
+  if (/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+\.[a-zA-Z]{1,5}/.test(trimmed)) return "concrete";
+  if (/[a-zA-Z0-9_]{4,}\/[a-zA-Z0-9_.-]/.test(trimmed)) return "concrete";
+  if (/\b[a-zA-Z0-9_-]+\.[a-zA-Z]{1,5}\b/.test(trimmed) && !/\b(e\.g|i\.e|vs|etc)\b/i.test(trimmed)) return "concrete";
+  return "abstract";
+}
+
+// src/scoring/checks/quality.ts
 function checkQuality(dir) {
   const checks = [];
-  const claudeMd = readFileOrNull3(join4(dir, "CLAUDE.md"));
-  const cursorrules = readFileOrNull3(join4(dir, ".cursorrules"));
-  const agentsMd = readFileOrNull3(join4(dir, "AGENTS.md"));
+  const claudeMd = readFileOrNull2(join4(dir, "CLAUDE.md"));
+  const cursorrules = readFileOrNull2(join4(dir, ".cursorrules"));
+  const agentsMd = readFileOrNull2(join4(dir, "AGENTS.md"));
   const allContent = [claudeMd, cursorrules, agentsMd].filter(Boolean);
   const combinedContent = allContent.join("\n");
-  const primaryInstructions = claudeMd ?? agentsMd;
-  const hasCommands = primaryInstructions ? COMMAND_PATTERNS.some((p) => p.test(primaryInstructions)) : false;
-  const matchedCommands = primaryInstructions ? COMMAND_PATTERNS.filter((p) => p.test(primaryInstructions)).map((p) => {
-    const m = primaryInstructions.match(p);
-    return m ? m[0] : "";
-  }).filter(Boolean) : [];
+  const primaryInstructions = claudeMd ?? agentsMd ?? cursorrules;
+  const structure = primaryInstructions ? analyzeMarkdownStructure(primaryInstructions) : null;
+  const codeBlockCount = structure?.codeBlockCount ?? 0;
+  const codeBlockThreshold = CODE_BLOCK_THRESHOLDS.find((t) => codeBlockCount >= t.minBlocks);
+  const execPoints = codeBlockThreshold?.points ?? 0;
   checks.push({
-    id: "has_commands",
-    name: "Build/test/lint commands",
+    id: "has_executable_content",
+    name: "Executable content (code blocks)",
     category: "quality",
-    maxPoints: POINTS_HAS_COMMANDS,
-    earnedPoints: hasCommands ? POINTS_HAS_COMMANDS : 0,
-    passed: hasCommands,
-    detail: hasCommands ? `Found: ${matchedCommands.slice(0, 3).join(", ")}` : primaryInstructions ? "No build/test/lint commands detected" : "No instructions file to check",
-    suggestion: hasCommands ? void 0 : "Add build, test, and lint commands to your instructions file"
+    maxPoints: POINTS_EXECUTABLE_CONTENT,
+    earnedPoints: execPoints,
+    passed: execPoints >= 6,
+    detail: primaryInstructions ? `${codeBlockCount} code block${codeBlockCount === 1 ? "" : "s"} found` : "No instructions file to check",
+    suggestion: execPoints < 6 ? "Add code blocks with project commands, build steps, and common workflows" : void 0,
+    fix: execPoints < 6 ? {
+      action: "add_code_blocks",
+      data: { currentCount: codeBlockCount, targetCount: 3 },
+      instruction: `Add code blocks with executable commands. Currently ${codeBlockCount}, need at least 3 for full points.`
+    } : void 0
   });
-  const primaryFile = claudeMd ?? agentsMd ?? cursorrules;
-  const primaryName = claudeMd ? "CLAUDE.md" : agentsMd ? "AGENTS.md" : cursorrules ? ".cursorrules" : null;
-  let bloatPoints = 0;
-  let lineCount = 0;
-  if (primaryFile) {
-    lineCount = countLines(primaryFile);
-    const threshold = BLOAT_THRESHOLDS.find((t) => lineCount <= t.maxLines);
-    bloatPoints = threshold ? threshold.points : 0;
-  } else {
-    bloatPoints = POINTS_NOT_BLOATED;
-  }
+  const totalContent = collectAllConfigContent(dir);
+  const totalTokens = estimateTokens2(totalContent);
+  const tokenThreshold = TOKEN_BUDGET_THRESHOLDS.find((t) => totalTokens <= t.maxTokens);
+  const tokenPoints = totalContent.length === 0 ? POINTS_CONCISE_CONFIG : tokenThreshold?.points ?? 0;
   checks.push({
-    id: "not_bloated",
-    name: "Concise context files",
+    id: "concise_config",
+    name: "Concise config (token budget)",
     category: "quality",
-    maxPoints: POINTS_NOT_BLOATED,
-    earnedPoints: bloatPoints,
-    passed: bloatPoints >= 6,
-    detail: primaryName ? `${primaryName}: ${lineCount} lines` : "No context files to measure",
-    suggestion: bloatPoints < POINTS_NOT_BLOATED && primaryName ? `${primaryName} is ${lineCount} lines \u2014 must be \u2264150 lines for full points (currently losing ${POINTS_NOT_BLOATED - bloatPoints} pts)` : void 0
+    maxPoints: POINTS_CONCISE_CONFIG,
+    earnedPoints: tokenPoints,
+    passed: tokenPoints >= 4,
+    detail: totalContent.length === 0 ? "No config files to measure" : `~${totalTokens} tokens total across all config files`,
+    suggestion: tokenPoints < 4 && totalContent.length > 0 ? `Total config is ~${totalTokens} tokens \u2014 reduce to under 5000 for better agent performance` : void 0,
+    fix: tokenPoints < 4 && totalContent.length > 0 ? {
+      action: "reduce_size",
+      data: { currentTokens: totalTokens, targetTokens: 5e3 },
+      instruction: `Reduce total config from ~${totalTokens} tokens to under 5000.`
+    } : void 0
   });
-  const vagueMatches = [];
-  if (combinedContent) {
-    const lines = combinedContent.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      for (const pattern of VAGUE_PATTERNS) {
-        if (pattern.test(lines[i])) {
-          vagueMatches.push({ pattern: lines[i].trim(), line: i + 1 });
-          break;
+  let concreteCount = 0;
+  let abstractCount = 0;
+  const abstractExamples = [];
+  if (primaryInstructions) {
+    let inCodeBlock2 = false;
+    for (const line of primaryInstructions.split("\n")) {
+      if (line.trim().startsWith("```")) {
+        inCodeBlock2 = !inCodeBlock2;
+        continue;
+      }
+      const classification = classifyLine(line, inCodeBlock2);
+      if (classification === "neutral") continue;
+      if (classification === "concrete") {
+        concreteCount++;
+      } else {
+        abstractCount++;
+        if (abstractExamples.length < 3) {
+          abstractExamples.push(line.trim().slice(0, 80));
         }
       }
     }
   }
+  const totalMeaningful = concreteCount + abstractCount;
+  const concreteRatio = totalMeaningful > 0 ? concreteCount / totalMeaningful : 1;
+  const concretenessThreshold = CONCRETENESS_THRESHOLDS.find((t) => concreteRatio >= t.minRatio);
+  const concretenessPoints = totalMeaningful === 0 ? 0 : concretenessThreshold?.points ?? 0;
   checks.push({
-    id: "no_vague_instructions",
-    name: "No vague instructions",
+    id: "concreteness",
+    name: "Concrete instructions",
     category: "quality",
-    maxPoints: POINTS_NO_VAGUE,
-    earnedPoints: vagueMatches.length === 0 ? POINTS_NO_VAGUE : 0,
-    passed: vagueMatches.length === 0,
-    detail: vagueMatches.length === 0 ? "All instructions are specific and actionable" : `${vagueMatches.length} vague instruction${vagueMatches.length === 1 ? "" : "s"} found`,
-    suggestion: vagueMatches.length > 0 ? `Replace "${vagueMatches[0].pattern.slice(0, 50)}" (line ${vagueMatches[0].line}) with specific, measurable guidance` : void 0
+    maxPoints: POINTS_CONCRETENESS,
+    earnedPoints: concretenessPoints,
+    passed: concretenessPoints >= 3,
+    detail: totalMeaningful === 0 ? "No content to analyze" : `${Math.round(concreteRatio * 100)}% of lines reference specific files, paths, or code`,
+    suggestion: concretenessPoints < 3 && totalMeaningful > 0 ? `${abstractCount} lines are generic prose \u2014 replace with specific instructions referencing project files` : void 0,
+    fix: concretenessPoints < 3 && totalMeaningful > 0 ? {
+      action: "replace_vague",
+      data: { abstractLines: abstractExamples, abstractCount, concreteCount, ratio: Math.round(concreteRatio * 100) },
+      instruction: `Replace generic prose with specific references. Examples of vague lines: ${abstractExamples.join("; ")}`
+    } : void 0
   });
   const treeLinePattern = /[├└│─┬]/;
   let treeLineCount = 0;
@@ -4241,7 +4316,12 @@ function checkQuality(dir) {
     earnedPoints: hasLargeTree ? 0 : POINTS_NO_DIR_TREE,
     passed: !hasLargeTree,
     detail: hasLargeTree ? `${treeLineCount}-line directory tree detected in code block` : "No large directory trees found",
-    suggestion: hasLargeTree ? "Remove directory tree listings \u2014 agents discover project structure by reading code" : void 0
+    suggestion: hasLargeTree ? "Remove directory tree listings \u2014 agents discover project structure by reading code" : void 0,
+    fix: hasLargeTree ? {
+      action: "remove_tree",
+      data: { treeLines: treeLineCount },
+      instruction: "Remove directory tree listings from code blocks. Reference key directories inline instead."
+    } : void 0
   });
   let duplicatePercent = 0;
   if (claudeMd && cursorrules) {
@@ -4261,276 +4341,320 @@ function checkQuality(dir) {
     earnedPoints: hasDuplicates ? 0 : POINTS_NO_DUPLICATES,
     passed: !hasDuplicates,
     detail: claudeMd && cursorrules ? hasDuplicates ? `${duplicatePercent}% overlap between CLAUDE.md and .cursorrules` : `${duplicatePercent}% overlap \u2014 acceptable` : "Only one context file (no duplication possible)",
-    suggestion: hasDuplicates ? "CLAUDE.md and .cursorrules share >50% content \u2014 deduplicate to save tokens" : void 0
+    suggestion: hasDuplicates ? "CLAUDE.md and .cursorrules share >50% content \u2014 deduplicate to save tokens" : void 0,
+    fix: hasDuplicates ? {
+      action: "deduplicate",
+      data: { overlapPercent: duplicatePercent },
+      instruction: "Deduplicate content between CLAUDE.md and .cursorrules. Each file should contain platform-specific instructions only."
+    } : void 0
   });
-  const contradictions = [];
-  if (allContent.length >= 2) {
-    for (const pair of CONTRADICTION_PAIRS) {
-      const fileA = allContent.find((c) => pair.a.test(c));
-      const fileB = allContent.find((c) => pair.b.test(c));
-      if (fileA && fileB && fileA !== fileB) {
-        contradictions.push(`"${pair.a.source}" vs "${pair.b.source}"`);
-      }
+  const structureScore = structure ? (structure.h2Count >= 3 ? 1 : 0) + (structure.listItemCount >= 3 ? 1 : 0) : 0;
+  checks.push({
+    id: "has_structure",
+    name: "Structured with headings",
+    category: "quality",
+    maxPoints: POINTS_HAS_STRUCTURE,
+    earnedPoints: primaryInstructions ? structureScore : 0,
+    passed: structureScore >= 2,
+    detail: primaryInstructions ? `${structure.h2Count} sections, ${structure.listItemCount} list items` : "No instructions file to check",
+    suggestion: structureScore < 2 && primaryInstructions ? "Add at least 3 markdown sections (##) and use lists for multi-item instructions" : void 0,
+    fix: structureScore < 2 && primaryInstructions ? {
+      action: "add_structure",
+      data: { currentH2: structure.h2Count, currentLists: structure.listItemCount },
+      instruction: "Organize content into sections with ## headings and use bullet lists for instructions."
+    } : void 0
+  });
+  return checks;
+}
+
+// src/scoring/checks/grounding.ts
+function checkGrounding(dir) {
+  const checks = [];
+  const configContent = collectAllConfigContent(dir);
+  const configLower = configContent.toLowerCase();
+  const projectStructure = collectProjectStructure(dir);
+  const allProjectEntries = [
+    ...projectStructure.dirs,
+    ...projectStructure.files
+  ];
+  const meaningfulEntries = allProjectEntries.filter((e) => e.length > 2);
+  const mentioned = [];
+  const notMentioned = [];
+  for (const entry of meaningfulEntries) {
+    const entryLower = entry.toLowerCase();
+    const variants = [
+      entryLower,
+      entryLower.replace(/\\/g, "/")
+    ];
+    const lastSegment = entry.split("/").pop()?.toLowerCase();
+    if (lastSegment && lastSegment.length > 3) {
+      variants.push(lastSegment);
     }
-  }
-  for (const content of allContent) {
-    for (const pair of CONTRADICTION_PAIRS) {
-      if (pair.a.test(content) && pair.b.test(content)) {
-        contradictions.push(`Same file contains "${pair.a.source}" and "${pair.b.source}"`);
-      }
+    const ismentioned = variants.some((v) => {
+      const escaped = v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      return new RegExp(`(?:^|[\\s\`/"'\\.,(])${escaped}(?:[\\s\`/"'.,;:!?)\\\\]|$)`, "i").test(configLower);
+    });
+    if (ismentioned) {
+      mentioned.push(entry);
+    } else {
+      notMentioned.push(entry);
     }
   }
-  const hasContradictions = contradictions.length > 0;
+  const groundingRatio = meaningfulEntries.length > 0 ? mentioned.length / meaningfulEntries.length : 0;
+  const groundingThreshold = GROUNDING_THRESHOLDS.find((t) => groundingRatio >= t.minRatio);
+  const groundingPoints = meaningfulEntries.length === 0 ? 0 : groundingThreshold?.points ?? 0;
+  const topDirs = projectStructure.dirs.filter((d) => !d.includes("/")).filter((d) => d.length > 2);
+  const matchesConfig = (name) => {
+    const escaped = name.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[\\s\`/"'\\.,(])${escaped}(?:[\\s\`/"'.,;:!?)\\\\]|$)`, "i").test(configLower);
+  };
+  const unmentionedTopDirs = topDirs.filter((d) => !matchesConfig(d));
+  const mentionedTopDirs = topDirs.filter((d) => matchesConfig(d));
   checks.push({
-    id: "no_contradictions",
-    name: "No contradictions",
-    category: "quality",
-    maxPoints: POINTS_NO_CONTRADICTIONS,
-    earnedPoints: hasContradictions ? 0 : POINTS_NO_CONTRADICTIONS,
-    passed: !hasContradictions,
-    detail: hasContradictions ? `${contradictions.length} contradiction${contradictions.length === 1 ? "" : "s"} found` : "No conflicting instructions detected",
-    suggestion: hasContradictions ? `Contradiction: ${contradictions[0]}. Remove or rephrase one of the conflicting statements.` : void 0
+    id: "project_grounding",
+    name: "Project grounding",
+    category: "grounding",
+    maxPoints: POINTS_PROJECT_GROUNDING,
+    earnedPoints: groundingPoints,
+    passed: groundingRatio >= 0.2,
+    detail: meaningfulEntries.length === 0 ? "No project structure detected" : `${mentioned.length}/${meaningfulEntries.length} project entries referenced in config (${Math.round(groundingRatio * 100)}%)`,
+    suggestion: unmentionedTopDirs.length > 0 ? `Config doesn't mention: ${unmentionedTopDirs.slice(0, 5).join(", ")}${unmentionedTopDirs.length > 5 ? ` (+${unmentionedTopDirs.length - 5} more)` : ""}` : void 0,
+    fix: groundingPoints < POINTS_PROJECT_GROUNDING ? {
+      action: "add_references",
+      data: {
+        missing: unmentionedTopDirs.slice(0, 10),
+        mentioned: mentionedTopDirs.slice(0, 10),
+        totalEntries: meaningfulEntries.length,
+        coverage: Math.round(groundingRatio * 100)
+      },
+      instruction: `Reference these project directories in your config: ${unmentionedTopDirs.slice(0, 5).join(", ")}`
+    } : void 0
+  });
+  const refs = extractReferences(configContent);
+  const mdStructure = analyzeMarkdownStructure(configContent);
+  const totalSpecificRefs = refs.length + mdStructure.inlineCodeCount;
+  const density = mdStructure.nonEmptyLines > 0 ? totalSpecificRefs / mdStructure.nonEmptyLines * 100 : 0;
+  let densityPoints = 0;
+  if (configContent.length === 0) {
+    densityPoints = 0;
+  } else if (density >= 40) {
+    densityPoints = POINTS_REFERENCE_DENSITY;
+  } else if (density >= 25) {
+    densityPoints = Math.round(POINTS_REFERENCE_DENSITY * 0.75);
+  } else if (density >= 15) {
+    densityPoints = Math.round(POINTS_REFERENCE_DENSITY * 0.5);
+  } else if (density >= 5) {
+    densityPoints = Math.round(POINTS_REFERENCE_DENSITY * 0.25);
+  }
+  checks.push({
+    id: "reference_density",
+    name: "Reference density",
+    category: "grounding",
+    maxPoints: POINTS_REFERENCE_DENSITY,
+    earnedPoints: densityPoints,
+    passed: densityPoints >= Math.round(POINTS_REFERENCE_DENSITY * 0.5),
+    detail: configContent.length === 0 ? "No config content" : `${totalSpecificRefs} specific references across ${mdStructure.nonEmptyLines} lines (${Math.round(density)}%)`,
+    suggestion: densityPoints < Math.round(POINTS_REFERENCE_DENSITY * 0.5) && configContent.length > 0 ? "Use backticks and paths to reference specific files, commands, and identifiers" : void 0,
+    fix: densityPoints < Math.round(POINTS_REFERENCE_DENSITY * 0.5) && configContent.length > 0 ? {
+      action: "add_inline_refs",
+      data: { currentDensity: Math.round(density), currentRefs: totalSpecificRefs, lines: mdStructure.nonEmptyLines },
+      instruction: "Add more inline code references (backticks) for file paths, commands, and identifiers."
+    } : void 0
   });
   return checks;
 }
 
 // src/scoring/checks/accuracy.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync3, statSync } from "fs";
+import { existsSync as existsSync4 } from "fs";
+import { execSync as execSync8 } from "child_process";
 import { join as join5 } from "path";
-function readFileOrNull4(path27) {
-  try {
-    return readFileSync5(path27, "utf-8");
-  } catch {
-    return null;
-  }
-}
-function readJsonOrNull2(path27) {
-  const content = readFileOrNull4(path27);
-  if (!content) return null;
-  try {
-    return JSON.parse(content);
-  } catch {
-    return null;
-  }
-}
-function getPackageScripts(dir) {
-  const pkg3 = readJsonOrNull2(join5(dir, "package.json"));
-  if (!pkg3?.scripts) return /* @__PURE__ */ new Set();
-  return new Set(Object.keys(pkg3.scripts));
-}
-function validateDocumentedCommands(dir) {
-  const claudeMd = readFileOrNull4(join5(dir, "CLAUDE.md"));
-  if (!claudeMd) return { valid: [], invalid: [], total: 0 };
-  const scripts = getPackageScripts(dir);
+function validateReferences(dir) {
+  const configContent = collectAllConfigContent(dir);
+  if (!configContent) return { valid: [], invalid: [], total: 0 };
+  const refs = extractReferences(configContent);
   const valid = [];
   const invalid = [];
-  const cmdPattern = /(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?([a-zA-Z0-9_:@./-]+)/g;
-  const seen = /* @__PURE__ */ new Set();
-  let match;
-  while ((match = cmdPattern.exec(claudeMd)) !== null) {
-    const scriptName = match[1].replace(/[.,;:!?)]+$/, "");
-    if (seen.has(scriptName)) continue;
-    seen.add(scriptName);
-    const builtins = /* @__PURE__ */ new Set(["install", "ci", "test", "start", "init", "publish", "pack", "link", "uninstall"]);
-    if (builtins.has(scriptName)) {
-      if ((scriptName === "test" || scriptName === "start") && !scripts.has(scriptName)) {
-        invalid.push(`${match[0]} (no "${scriptName}" script in package.json)`);
-      } else {
-        valid.push(match[0]);
-      }
-      continue;
-    }
-    if (scripts.has(scriptName)) {
-      valid.push(match[0]);
+  for (const ref of refs) {
+    if (/^https?:\/\//.test(ref)) continue;
+    if (/^\d+\.\d+/.test(ref)) continue;
+    if (ref.startsWith("#")) continue;
+    if (ref.startsWith("@")) continue;
+    if (ref.includes("*")) continue;
+    if (ref.includes("..")) continue;
+    if (!ref.includes("/") && !ref.includes(".")) continue;
+    const fullPath = join5(dir, ref);
+    if (existsSync4(fullPath)) {
+      valid.push(ref);
     } else {
-      invalid.push(`${match[0]} (no "${scriptName}" script in package.json)`);
-    }
-  }
-  const npxPattern = /npx\s+(\S+)/g;
-  while ((match = npxPattern.exec(claudeMd)) !== null) {
-    const tool = match[1];
-    if (seen.has(`npx-${tool}`)) continue;
-    seen.add(`npx-${tool}`);
-    valid.push(match[0]);
-  }
-  const makePattern = /make\s+(\S+)/g;
-  if (existsSync5(join5(dir, "Makefile"))) {
-    const makefile = readFileOrNull4(join5(dir, "Makefile"));
-    const makeTargets = /* @__PURE__ */ new Set();
-    if (makefile) {
-      for (const line of makefile.split("\n")) {
-        const targetMatch = line.match(/^([a-zA-Z_-]+)\s*:/);
-        if (targetMatch) makeTargets.add(targetMatch[1]);
-      }
-    }
-    while ((match = makePattern.exec(claudeMd)) !== null) {
-      const target = match[1];
-      if (seen.has(`make-${target}`)) continue;
-      seen.add(`make-${target}`);
-      if (makeTargets.has(target)) {
-        valid.push(match[0]);
+      const withoutTrailing = ref.replace(/\/+$/, "");
+      if (withoutTrailing !== ref && existsSync4(join5(dir, withoutTrailing))) {
+        valid.push(ref);
       } else {
-        invalid.push(`${match[0]} (no "${target}" target in Makefile)`);
+        invalid.push(ref);
       }
     }
   }
   return { valid, invalid, total: valid.length + invalid.length };
 }
-function validateDocumentedPaths(dir) {
-  const claudeMd = readFileOrNull4(join5(dir, "CLAUDE.md"));
-  if (!claudeMd) return { valid: [], invalid: [], total: 0 };
-  const valid = [];
-  const invalid = [];
-  const pathPattern = /(?:^|\s|`|"|')((src|lib|app|apps|packages|cmd|internal|test|tests|scripts|config|public|pages|components|routes|services|middleware|utils|helpers)\/[a-zA-Z0-9_./-]+\.[a-zA-Z]{1,5})/gm;
-  const seen = /* @__PURE__ */ new Set();
-  let match;
-  while ((match = pathPattern.exec(claudeMd)) !== null) {
-    const filePath = match[1];
-    if (seen.has(filePath)) continue;
-    seen.add(filePath);
-    if (/\/path\/to\/|\/example[s]?\/|\/your[_-]|\/foo\/|\/bar\//.test(filePath)) continue;
-    if (existsSync5(join5(dir, filePath))) {
-      valid.push(filePath);
-    } else {
-      invalid.push(filePath);
-    }
+function detectGitDrift(dir) {
+  try {
+    execSync8("git rev-parse --git-dir", { cwd: dir, stdio: ["pipe", "pipe", "pipe"] });
+  } catch {
+    return { commitsSinceConfigUpdate: 0, lastConfigCommit: null, isGitRepo: false };
   }
-  return { valid, invalid, total: valid.length + invalid.length };
-}
-function detectConfigDrift(dir) {
-  const srcDirs = ["src", "lib", "app", "cmd", "internal", "pages", "components"];
-  let latestSrcMtime = 0;
-  for (const srcDir of srcDirs) {
-    const fullPath = join5(dir, srcDir);
-    if (!existsSync5(fullPath)) continue;
+  const configFiles = ["CLAUDE.md", "AGENTS.md", ".cursorrules", ".cursor/rules"];
+  let latestConfigCommitHash = null;
+  for (const file of configFiles) {
     try {
-      const files = readdirSync3(fullPath, { recursive: true }).map(String).filter((f) => /\.(ts|js|tsx|jsx|py|go|rs|java|rb)$/.test(f));
-      for (const file of files.slice(0, 100)) {
+      const hash = execSync8(
+        `git log -1 --format=%H -- "${file}"`,
+        { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+      ).trim();
+      if (!hash) continue;
+      if (!latestConfigCommitHash) {
+        latestConfigCommitHash = hash;
+      } else {
         try {
-          const stat = statSync(join5(fullPath, file));
-          if (stat.mtime.getTime() > latestSrcMtime) {
-            latestSrcMtime = stat.mtime.getTime();
-          }
+          execSync8(
+            `git merge-base --is-ancestor ${latestConfigCommitHash} ${hash}`,
+            { cwd: dir, stdio: ["pipe", "pipe", "pipe"] }
+          );
+          latestConfigCommitHash = hash;
         } catch {
         }
       }
     } catch {
     }
   }
-  const configFiles = ["CLAUDE.md", ".cursorrules"];
-  let latestConfigMtime = 0;
-  for (const configFile of configFiles) {
-    try {
-      const stat = statSync(join5(dir, configFile));
-      if (stat.mtime.getTime() > latestConfigMtime) {
-        latestConfigMtime = stat.mtime.getTime();
-      }
-    } catch {
-    }
+  if (!latestConfigCommitHash) {
+    return { commitsSinceConfigUpdate: 0, lastConfigCommit: null, isGitRepo: true };
   }
-  if (latestSrcMtime === 0 || latestConfigMtime === 0) {
-    return { driftDays: 0, srcLastModified: null, configLastModified: null };
+  try {
+    const countStr = execSync8(
+      `git rev-list --count ${latestConfigCommitHash}..HEAD`,
+      { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    ).trim();
+    const commitsSince = parseInt(countStr, 10) || 0;
+    const lastDate = execSync8(
+      `git log -1 --format=%ci ${latestConfigCommitHash}`,
+      { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    ).trim();
+    return {
+      commitsSinceConfigUpdate: commitsSince,
+      lastConfigCommit: lastDate,
+      isGitRepo: true
+    };
+  } catch {
+    return { commitsSinceConfigUpdate: 0, lastConfigCommit: latestConfigCommitHash, isGitRepo: true };
   }
-  const driftMs = latestSrcMtime - latestConfigMtime;
-  const driftDays = Math.max(0, Math.floor(driftMs / (1e3 * 60 * 60 * 24)));
-  return {
-    driftDays,
-    srcLastModified: new Date(latestSrcMtime),
-    configLastModified: new Date(latestConfigMtime)
-  };
 }
 function checkAccuracy(dir) {
   const checks = [];
-  const cmds = validateDocumentedCommands(dir);
-  const cmdRatio = cmds.total > 0 ? cmds.valid.length / cmds.total : 1;
-  const cmdPoints = cmds.total === 0 ? POINTS_COMMANDS_VALID : Math.round(cmdRatio * POINTS_COMMANDS_VALID);
-  checks.push({
-    id: "commands_valid",
-    name: "Documented commands exist",
-    category: "accuracy",
-    maxPoints: POINTS_COMMANDS_VALID,
-    earnedPoints: cmdPoints,
-    passed: cmdRatio >= 0.8,
-    detail: cmds.total === 0 ? "No commands documented" : `${cmds.valid.length}/${cmds.total} commands verified`,
-    suggestion: cmds.invalid.length > 0 ? `Remove these invalid commands from CLAUDE.md: ${cmds.invalid.join("; ")}` : void 0
-  });
-  const paths = validateDocumentedPaths(dir);
-  const pathRatio = paths.total > 0 ? paths.valid.length / paths.total : 1;
-  const pathPoints = paths.total === 0 ? POINTS_PATHS_VALID : Math.round(pathRatio * POINTS_PATHS_VALID);
+  const refs = validateReferences(dir);
+  const refRatio = refs.total > 0 ? refs.valid.length / refs.total : 0;
+  const refPoints = refs.total === 0 ? 0 : Math.round(refRatio * POINTS_REFERENCES_VALID);
   checks.push({
-    id: "paths_valid",
-    name: "Documented paths exist",
+    id: "references_valid",
+    name: "References point to real files",
     category: "accuracy",
-    maxPoints: POINTS_PATHS_VALID,
-    earnedPoints: pathPoints,
-    passed: pathRatio >= 0.8,
-    detail: paths.total === 0 ? "No file paths documented" : `${paths.valid.length}/${paths.total} paths verified`,
-    suggestion: paths.invalid.length > 0 ? `Remove these non-existent paths from CLAUDE.md: ${paths.invalid.join("; ")}` : void 0
+    maxPoints: POINTS_REFERENCES_VALID,
+    earnedPoints: refPoints,
+    passed: refs.total === 0 ? false : refRatio >= 0.8,
+    detail: refs.total === 0 ? "No file references found in config" : `${refs.valid.length}/${refs.total} references verified`,
+    suggestion: refs.invalid.length > 0 ? `These references don't exist: ${refs.invalid.slice(0, 3).join(", ")}${refs.invalid.length > 3 ? ` (+${refs.invalid.length - 3} more)` : ""}` : refs.total === 0 ? "Add file path references to make your config grounded in the project" : void 0,
+    fix: refs.invalid.length > 0 ? {
+      action: "fix_references",
+      data: { invalid: refs.invalid.slice(0, 10), valid: refs.valid.slice(0, 10) },
+      instruction: `Remove or update these non-existent paths: ${refs.invalid.slice(0, 5).join(", ")}`
+    } : refs.total === 0 ? {
+      action: "add_references",
+      data: { currentRefs: 0 },
+      instruction: "Add file path references (e.g., `src/index.ts`) to ground the config in the project."
+    } : void 0
   });
-  const drift = detectConfigDrift(dir);
+  const drift = detectGitDrift(dir);
   let driftPoints = POINTS_CONFIG_DRIFT;
-  if (drift.driftDays > 30) driftPoints = 0;
-  else if (drift.driftDays > 14) driftPoints = Math.round(POINTS_CONFIG_DRIFT * 0.25);
-  else if (drift.driftDays > 7) driftPoints = Math.round(POINTS_CONFIG_DRIFT * 0.5);
-  else if (drift.driftDays > 3) driftPoints = Math.round(POINTS_CONFIG_DRIFT * 0.75);
+  if (!drift.isGitRepo) {
+    driftPoints = POINTS_CONFIG_DRIFT;
+  } else if (!drift.lastConfigCommit) {
+    driftPoints = 0;
+  } else if (drift.commitsSinceConfigUpdate > 50) {
+    driftPoints = 0;
+  } else if (drift.commitsSinceConfigUpdate > 30) {
+    driftPoints = Math.round(POINTS_CONFIG_DRIFT * 0.25);
+  } else if (drift.commitsSinceConfigUpdate > 15) {
+    driftPoints = Math.round(POINTS_CONFIG_DRIFT * 0.5);
+  } else if (drift.commitsSinceConfigUpdate > 5) {
+    driftPoints = Math.round(POINTS_CONFIG_DRIFT * 0.75);
+  }
   checks.push({
     id: "config_drift",
     name: "Config freshness vs code",
     category: "accuracy",
     maxPoints: POINTS_CONFIG_DRIFT,
     earnedPoints: driftPoints,
-    passed: drift.driftDays <= 7,
-    detail: drift.srcLastModified && drift.configLastModified ? drift.driftDays === 0 ? "Config is up to date with code changes" : `Code changed ${drift.driftDays} day${drift.driftDays === 1 ? "" : "s"} after last config update` : "Could not determine drift",
-    suggestion: drift.driftDays > 7 ? `Code has changed since last config update \u2014 run \`caliber refresh\` to sync` : void 0
+    passed: drift.commitsSinceConfigUpdate <= 15 || !drift.isGitRepo,
+    detail: !drift.isGitRepo ? "Not a git repository \u2014 skipping drift check" : !drift.lastConfigCommit ? "Config files not tracked in git" : drift.commitsSinceConfigUpdate === 0 ? "Config is up to date with latest commits" : `${drift.commitsSinceConfigUpdate} commit${drift.commitsSinceConfigUpdate === 1 ? "" : "s"} since last config update`,
+    suggestion: drift.commitsSinceConfigUpdate > 15 ? `Code has had ${drift.commitsSinceConfigUpdate} commits since last config update \u2014 run \`caliber refresh\` to sync` : void 0,
+    fix: drift.commitsSinceConfigUpdate > 15 ? {
+      action: "refresh_config",
+      data: { commitsSince: drift.commitsSinceConfigUpdate, lastConfigCommit: drift.lastConfigCommit },
+      instruction: `Config is ${drift.commitsSinceConfigUpdate} commits behind. Review recent changes and update config accordingly.`
+    } : void 0
   });
   return checks;
 }
 
 // src/scoring/checks/freshness.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
+import { execSync as execSync9 } from "child_process";
 import { join as join6 } from "path";
-function readFileOrNull5(path27) {
-  try {
-    return readFileSync6(path27, "utf-8");
-  } catch {
-    return null;
-  }
-}
-function daysSinceModified(filePath) {
-  try {
-    const stat = statSync2(filePath);
-    const now = Date.now();
-    const mtime = stat.mtime.getTime();
-    return Math.floor((now - mtime) / (1e3 * 60 * 60 * 24));
-  } catch {
-    return null;
+function getCommitsSinceConfigUpdate(dir) {
+  const configFiles = ["CLAUDE.md", "AGENTS.md", ".cursorrules"];
+  for (const file of configFiles) {
+    try {
+      const hash = execSync9(
+        `git log -1 --format=%H -- "${file}"`,
+        { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+      ).trim();
+      if (hash) {
+        const countStr = execSync9(
+          `git rev-list --count ${hash}..HEAD`,
+          { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+        ).trim();
+        return parseInt(countStr, 10) || 0;
+      }
+    } catch {
+    }
   }
+  return null;
 }
 function checkFreshness(dir) {
   const checks = [];
-  const claudeMdPath = join6(dir, "CLAUDE.md");
-  const agentsMdPath = join6(dir, "AGENTS.md");
-  const primaryPath = existsSync6(claudeMdPath) ? claudeMdPath : agentsMdPath;
-  const primaryName = existsSync6(claudeMdPath) ? "CLAUDE.md" : "AGENTS.md";
-  const daysOld = daysSinceModified(primaryPath);
+  const commitsSince = getCommitsSinceConfigUpdate(dir);
   let freshnessPoints = 0;
   let freshnessDetail = "";
-  if (daysOld === null) {
-    freshnessDetail = "No instructions file to check";
+  if (commitsSince === null) {
+    freshnessDetail = "Config files not tracked in git";
+    freshnessPoints = 0;
   } else {
-    const threshold = FRESHNESS_THRESHOLDS.find((t) => daysOld <= t.maxDaysOld);
+    const threshold = FRESHNESS_COMMIT_THRESHOLDS.find((t) => commitsSince <= t.maxCommits);
     freshnessPoints = threshold ? threshold.points : 0;
-    freshnessDetail = daysOld === 0 ? "Modified today" : daysOld === 1 ? "Modified yesterday" : `Modified ${daysOld} days ago`;
+    freshnessDetail = commitsSince === 0 ? "Config updated in the latest commit" : `${commitsSince} commit${commitsSince === 1 ? "" : "s"} since last config update`;
   }
   checks.push({
     id: "claude_md_freshness",
-    name: `${primaryName} freshness`,
+    name: "Config freshness",
     category: "freshness",
     maxPoints: POINTS_FRESHNESS,
     earnedPoints: freshnessPoints,
-    passed: freshnessPoints >= 4,
+    passed: freshnessPoints >= 3,
     detail: freshnessDetail,
-    suggestion: daysOld !== null && freshnessPoints < 4 ? `${primaryName} is ${daysOld} days old \u2014 run \`caliber refresh\` to update it` : void 0
+    suggestion: commitsSince !== null && freshnessPoints < 3 ? `Config is ${commitsSince} commits behind \u2014 run \`caliber refresh\` to update it` : void 0,
+    fix: commitsSince !== null && freshnessPoints < 3 ? {
+      action: "refresh_config",
+      data: { commitsSince },
+      instruction: `Config is ${commitsSince} commits behind. Update it to reflect recent changes.`
+    } : void 0
   });
   const filesToScan = [
     "CLAUDE.md",
@@ -4543,17 +4667,16 @@ function checkFreshness(dir) {
   ];
   const secretFindings = [];
   for (const rel of filesToScan) {
-    const content = readFileOrNull5(join6(dir, rel));
+    const content = readFileOrNull2(join6(dir, rel));
     if (!content) continue;
     const lines = content.split("\n");
     for (let i = 0; i < lines.length; i++) {
       for (const pattern of SECRET_PATTERNS) {
         if (pattern.test(lines[i])) {
-          secretFindings.push({
-            file: rel,
-            line: i + 1,
-            pattern: pattern.source.slice(0, 20) + "..."
-          });
+          const isPlaceholder = SECRET_PLACEHOLDER_PATTERNS.some((p) => p.test(lines[i]));
+          if (!isPlaceholder) {
+            secretFindings.push({ file: rel, line: i + 1 });
+          }
           break;
         }
       }
@@ -4564,17 +4687,21 @@ function checkFreshness(dir) {
     id: "no_secrets",
     name: "No secrets in config files",
     category: "freshness",
-    maxPoints: POINTS_NO_SECRETS,
-    // This is a penalty: -8 if secrets found, +8 if clean
     earnedPoints: hasSecrets ? -POINTS_NO_SECRETS : POINTS_NO_SECRETS,
+    maxPoints: POINTS_NO_SECRETS,
     passed: !hasSecrets,
     detail: hasSecrets ? `${secretFindings.length} potential secret${secretFindings.length === 1 ? "" : "s"} found in ${secretFindings[0].file}:${secretFindings[0].line}` : "No secrets detected",
-    suggestion: hasSecrets ? `Remove secrets from ${secretFindings[0].file}:${secretFindings[0].line} \u2014 use environment variables instead` : void 0
+    suggestion: hasSecrets ? `Remove secrets from ${secretFindings[0].file}:${secretFindings[0].line} \u2014 use environment variables instead` : void 0,
+    fix: hasSecrets ? {
+      action: "remove_secrets",
+      data: { findings: secretFindings.slice(0, 5) },
+      instruction: `Remove credentials from ${secretFindings[0].file}:${secretFindings[0].line}. Use environment variable references instead.`
+    } : void 0
   });
   const settingsPath = join6(dir, ".claude", "settings.json");
   let hasPermissions = false;
   let permissionDetail = "";
-  const settingsContent = readFileOrNull5(settingsPath);
+  const settingsContent = readFileOrNull2(settingsPath);
   if (settingsContent) {
     try {
       const settings = JSON.parse(settingsContent);
@@ -4596,27 +4723,25 @@ function checkFreshness(dir) {
     earnedPoints: hasPermissions ? POINTS_PERMISSIONS : 0,
     passed: hasPermissions,
     detail: permissionDetail,
-    suggestion: hasPermissions ? void 0 : "Add permissions.allow to .claude/settings.json for safer agent execution"
+    suggestion: hasPermissions ? void 0 : "Add permissions.allow to .claude/settings.json for safer agent execution",
+    fix: hasPermissions ? void 0 : {
+      action: "add_permissions",
+      data: {},
+      instruction: "Add a permissions.allow list to .claude/settings.json with commonly used commands."
+    }
   });
   return checks;
 }
 
 // src/scoring/checks/bonus.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7, readdirSync as readdirSync4 } from "fs";
-import { execSync as execSync8 } from "child_process";
+import { existsSync as existsSync5, readdirSync as readdirSync3 } from "fs";
+import { execSync as execSync10 } from "child_process";
 import { join as join7 } from "path";
-function readFileOrNull6(path27) {
-  try {
-    return readFileSync7(path27, "utf-8");
-  } catch {
-    return null;
-  }
-}
 function hasPreCommitHook(dir) {
   try {
-    const gitDir = execSync8("git rev-parse --git-dir", { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const gitDir = execSync10("git rev-parse --git-dir", { cwd: dir, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     const hookPath = join7(gitDir, "hooks", "pre-commit");
-    const content = readFileOrNull6(hookPath);
+    const content = readFileOrNull2(hookPath);
     return content ? content.includes("caliber") : false;
   } catch {
     return false;
@@ -4627,7 +4752,7 @@ function checkBonus(dir) {
   let hasClaudeHooks = false;
   let hasPrecommit = false;
   const hookSources = [];
-  const settingsContent = readFileOrNull6(join7(dir, ".claude", "settings.json"));
+  const settingsContent = readFileOrNull2(join7(dir, ".claude", "settings.json"));
   if (settingsContent) {
     try {
       const settings = JSON.parse(settingsContent);
@@ -4644,7 +4769,6 @@ function checkBonus(dir) {
     hookSources.push("git pre-commit");
   }
   const hasHooks = hasClaudeHooks || hasPrecommit;
-  const hookDetail = hasHooks ? hookSources.join(", ") : settingsContent ? "No hooks in settings.json" : "No hooks configured";
   checks.push({
     id: "hooks_configured",
     name: "Hooks configured",
@@ -4652,10 +4776,15 @@ function checkBonus(dir) {
     maxPoints: POINTS_HOOKS,
     earnedPoints: hasHooks ? POINTS_HOOKS : 0,
     passed: hasHooks,
-    detail: hookDetail,
-    suggestion: hasHooks ? void 0 : "Run `caliber hooks --install` for auto-refresh"
+    detail: hasHooks ? hookSources.join(", ") : "No hooks configured",
+    suggestion: hasHooks ? void 0 : "Run `caliber hooks --install` for auto-refresh",
+    fix: hasHooks ? void 0 : {
+      action: "install_hooks",
+      data: {},
+      instruction: "Install caliber hooks for automatic config refresh on commits."
+    }
   });
-  const agentsMdExists = existsSync7(join7(dir, "AGENTS.md"));
+  const agentsMdExists = existsSync5(join7(dir, "AGENTS.md"));
   checks.push({
     id: "agents_md_exists",
     name: "AGENTS.md exists",
@@ -4664,16 +4793,21 @@ function checkBonus(dir) {
     earnedPoints: agentsMdExists ? POINTS_AGENTS_MD : 0,
     passed: agentsMdExists,
     detail: agentsMdExists ? "Found at project root" : "Not found",
-    suggestion: agentsMdExists ? void 0 : "Add AGENTS.md \u2014 the emerging cross-agent standard (60k+ repos)"
+    suggestion: agentsMdExists ? void 0 : "Add AGENTS.md \u2014 the emerging cross-agent standard",
+    fix: agentsMdExists ? void 0 : {
+      action: "create_file",
+      data: { file: "AGENTS.md" },
+      instruction: "Create AGENTS.md with project context for cross-agent compatibility."
+    }
   });
   const skillsDir = join7(dir, ".claude", "skills");
   let openSkillsCount = 0;
   let totalSkillFiles = 0;
   try {
-    const entries = readdirSync4(skillsDir, { withFileTypes: true });
+    const entries = readdirSync3(skillsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        const skillMd = readFileOrNull6(join7(skillsDir, entry.name, "SKILL.md"));
+        const skillMd = readFileOrNull2(join7(skillsDir, entry.name, "SKILL.md"));
         if (skillMd) {
           totalSkillFiles++;
           if (skillMd.trimStart().startsWith("---")) {
@@ -4695,7 +4829,12 @@ function checkBonus(dir) {
     earnedPoints: allOpenSkills ? POINTS_OPEN_SKILLS_FORMAT : 0,
     passed: allOpenSkills,
     detail: totalSkillFiles === 0 ? "No skills to check" : allOpenSkills ? `All ${totalSkillFiles} skill${totalSkillFiles === 1 ? "" : "s"} use SKILL.md with frontmatter` : `${openSkillsCount}/${totalSkillFiles} use OpenSkills format`,
-    suggestion: totalSkillFiles > 0 && !allOpenSkills ? "Migrate skills to .claude/skills/{name}/SKILL.md with YAML frontmatter (SkillsBench: +16.2pp improvement)" : void 0
+    suggestion: totalSkillFiles > 0 && !allOpenSkills ? "Migrate skills to .claude/skills/{name}/SKILL.md with YAML frontmatter" : void 0,
+    fix: totalSkillFiles > 0 && !allOpenSkills ? {
+      action: "migrate_skills",
+      data: { openSkills: openSkillsCount, total: totalSkillFiles },
+      instruction: "Migrate flat skill files to .claude/skills/{name}/SKILL.md with YAML frontmatter."
+    } : void 0
   });
   return checks;
 }
@@ -4737,14 +4876,15 @@ function filterChecksForTarget(checks, target) {
     if (CURSOR_ONLY_CHECKS.has(c.id)) return target.includes("cursor");
     if (CODEX_ONLY_CHECKS.has(c.id)) return target.includes("codex");
     if (BOTH_ONLY_CHECKS.has(c.id)) return target.includes("claude") && target.includes("cursor");
+    if (NON_CODEX_CHECKS.has(c.id)) return !target.includes("codex");
     return true;
   });
 }
 function detectTargetAgent(dir) {
   const agents = [];
-  if (existsSync8(join8(dir, "CLAUDE.md")) || existsSync8(join8(dir, ".claude", "skills"))) agents.push("claude");
-  if (existsSync8(join8(dir, ".cursorrules")) || existsSync8(join8(dir, ".cursor", "rules"))) agents.push("cursor");
-  if (existsSync8(join8(dir, ".codex")) || existsSync8(join8(dir, ".agents", "skills"))) agents.push("codex");
+  if (existsSync6(join8(dir, "CLAUDE.md")) || existsSync6(join8(dir, ".claude", "skills"))) agents.push("claude");
+  if (existsSync6(join8(dir, ".cursorrules")) || existsSync6(join8(dir, ".cursor", "rules"))) agents.push("cursor");
+  if (existsSync6(join8(dir, ".codex")) || existsSync6(join8(dir, ".agents", "skills"))) agents.push("codex");
   return agents.length > 0 ? agents : ["claude"];
 }
 function computeLocalScore(dir, targetAgent) {
@@ -4752,7 +4892,7 @@ function computeLocalScore(dir, targetAgent) {
   const allChecks = [
     ...checkExistence(dir),
     ...checkQuality(dir),
-    ...checkCoverage(dir),
+    ...checkGrounding(dir),
     ...checkAccuracy(dir),
     ...checkFreshness(dir),
     ...checkBonus(dir)
@@ -4770,7 +4910,7 @@ function computeLocalScore(dir, targetAgent) {
     categories: {
       existence: sumCategory(checks, "existence"),
       quality: sumCategory(checks, "quality"),
-      coverage: sumCategory(checks, "coverage"),
+      grounding: sumCategory(checks, "grounding"),
       accuracy: sumCategory(checks, "accuracy"),
       freshness: sumCategory(checks, "freshness"),
       bonus: sumCategory(checks, "bonus")
@@ -4790,12 +4930,12 @@ var AGENT_DISPLAY_NAMES = {
 var CATEGORY_LABELS = {
   existence: "FILES & SETUP",
   quality: "QUALITY",
-  coverage: "COVERAGE",
+  grounding: "GROUNDING",
   accuracy: "ACCURACY",
   freshness: "FRESHNESS & SAFETY",
   bonus: "BONUS"
 };
-var CATEGORY_ORDER = ["existence", "quality", "coverage", "accuracy", "freshness", "bonus"];
+var CATEGORY_ORDER = ["existence", "quality", "grounding", "accuracy", "freshness", "bonus"];
 function gradeColor(grade) {
   switch (grade) {
     case "A":
@@ -4908,7 +5048,7 @@ function displayScoreDelta(before, after) {
 import chalk7 from "chalk";
 import ora from "ora";
 import select4 from "@inquirer/select";
-import { mkdirSync, readFileSync as readFileSync8, readdirSync as readdirSync5, existsSync as existsSync9, writeFileSync } from "fs";
+import { mkdirSync, readFileSync as readFileSync4, readdirSync as readdirSync4, existsSync as existsSync7, writeFileSync } from "fs";
 import { join as join9, dirname as dirname2 } from "path";
 
 // src/scanner/index.ts
@@ -5067,7 +5207,7 @@ import fs22 from "fs";
 import path17 from "path";
 import os3 from "os";
 import crypto3 from "crypto";
-import { execSync as execSync9 } from "child_process";
+import { execSync as execSync11 } from "child_process";
 var CONFIG_DIR2 = path17.join(os3.homedir(), ".caliber");
 var CONFIG_FILE2 = path17.join(CONFIG_DIR2, "config.json");
 var runtimeDisabled = false;
@@ -5094,7 +5234,7 @@ function getMachineId() {
 }
 function getGitEmailHash() {
   try {
-    const email = execSync9("git config user.email", { encoding: "utf-8" }).trim();
+    const email = execSync11("git config user.email", { encoding: "utf-8" }).trim();
     if (!email) return void 0;
     return crypto3.createHash("sha256").update(email).digest("hex");
   } catch {
@@ -5244,7 +5384,7 @@ function getInstalledSkills() {
   ];
   for (const dir of dirs) {
     try {
-      const entries = readdirSync5(dir, { withFileTypes: true });
+      const entries = readdirSync4(dir, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isDirectory()) {
           installed.add(entry.name.toLowerCase());
@@ -5409,9 +5549,9 @@ Already installed skills: ${Array.from(installed).join(", ")}`);
 }
 function extractTopDeps() {
   const pkgPath = join9(process.cwd(), "package.json");
-  if (!existsSync9(pkgPath)) return [];
+  if (!existsSync7(pkgPath)) return [];
   try {
-    const pkg3 = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+    const pkg3 = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     const deps = Object.keys(pkg3.dependencies ?? {});
     const trivial = /* @__PURE__ */ new Set([
       "typescript",
@@ -6004,7 +6144,7 @@ async function initCommand(options) {
   let passingChecks;
   let currentScore;
   if (hasExistingConfig && baselineScore.score >= 95 && !options.force) {
-    failingChecks = llmFixableChecks.map((c) => ({ name: c.name, suggestion: c.suggestion }));
+    failingChecks = llmFixableChecks.map((c) => ({ name: c.name, suggestion: c.suggestion, fix: c.fix }));
     passingChecks = baselineScore.checks.filter((c) => c.passed).map((c) => ({ name: c.name }));
     currentScore = baselineScore.score;
     if (failingChecks.length > 0) {
@@ -6102,7 +6242,7 @@ async function initCommand(options) {
             }, onComplete: () => {
             }, onError: () => {
             } },
-            inlineFailingChecks.map((c) => ({ name: c.name, suggestion: c.suggestion })),
+            inlineFailingChecks.map((c) => ({ name: c.name, suggestion: c.suggestion, fix: c.fix })),
             inlineScore.score,
             inlineScore.checks.filter((c) => c.passed).map((c) => ({ name: c.name })),
             { skipSkills: true, forceTargetedFix: true }
@@ -6196,7 +6336,9 @@ async function initCommand(options) {
       if (agentsStub) {
         const setup = generatedSetup;
         setup.codex = { agentsMd: agentsStub.content };
-        if (!setup.targetAgent || !setup.targetAgent.includes("codex")) {
+        if (!setup.targetAgent) {
+          setup.targetAgent = ["codex"];
+        } else if (Array.isArray(setup.targetAgent) && !setup.targetAgent.includes("codex")) {
           setup.targetAgent.push("codex");
         }
       }
@@ -6923,7 +7065,7 @@ import chalk13 from "chalk";
 import ora5 from "ora";
 
 // src/lib/git-diff.ts
-import { execSync as execSync10 } from "child_process";
+import { execSync as execSync12 } from "child_process";
 var MAX_DIFF_BYTES = 1e5;
 var DOC_PATTERNS = [
   "CLAUDE.md",
@@ -6937,7 +7079,7 @@ function excludeArgs() {
 }
 function safeExec(cmd) {
   try {
-    return execSync10(cmd, {
+    return execSync12(cmd, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       maxBuffer: 10 * 1024 * 1024
@@ -7864,7 +8006,7 @@ learn.command("status").description("Show learning system status").action(tracke
 import fs32 from "fs";
 import path26 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { execSync as execSync11 } from "child_process";
+import { execSync as execSync13 } from "child_process";
 import chalk17 from "chalk";
 import ora6 from "ora";
 import confirm from "@inquirer/confirm";
@@ -7874,7 +8016,7 @@ var pkg2 = JSON.parse(
 );
 function getInstalledVersion() {
   try {
-    const globalRoot = execSync11("npm root -g", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const globalRoot = execSync13("npm root -g", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     const pkgPath = path26.join(globalRoot, "@rely-ai", "caliber", "package.json");
     return JSON.parse(fs32.readFileSync(pkgPath, "utf-8")).version;
   } catch {
@@ -7919,7 +8061,7 @@ Update available: ${current} -> ${latest}`)
     }
     const spinner = ora6("Updating caliber...").start();
     try {
-      execSync11(`npm install -g @rely-ai/caliber@${latest}`, {
+      execSync13(`npm install -g @rely-ai/caliber@${latest}`, {
         stdio: "pipe",
         timeout: 12e4,
         env: { ...process.env, npm_config_fund: "false", npm_config_audit: "false" }
@@ -7936,7 +8078,7 @@ Update available: ${current} -> ${latest}`)
       console.log(chalk17.dim(`
 Restarting: caliber ${args.join(" ")}
 `));
-      execSync11(`caliber ${args.map((a) => JSON.stringify(a)).join(" ")}`, {
+      execSync13(`caliber ${args.map((a) => JSON.stringify(a)).join(" ")}`, {
         stdio: "inherit",
         env: { ...process.env, CALIBER_SKIP_UPDATE_CHECK: "1" }
       });