@aiready/agent-grounding 0.9.5 → 0.11.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/agent-grounding@0.9.4 build /Users/pengcao/projects/aiready/packages/agent-grounding
+> @aiready/agent-grounding@0.10.0 build /Users/pengcao/projects/aiready/packages/agent-grounding
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -9,16 +9,16 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/cli.js   16.44 KB
-CJS dist/index.js 10.96 KB
-CJS ⚡️ Build success in 95ms
+ESM dist/index.mjs          1.30 KB
 ESM dist/cli.mjs            5.16 KB
-ESM dist/index.mjs          154.00 B
-ESM dist/chunk-L3MLD6K4.mjs 9.65 KB
-ESM ⚡️ Build success in 95ms
+ESM dist/chunk-T5YTLYD6.mjs 9.69 KB
+ESM ⚡️ Build success in 60ms
+CJS dist/index.js 12.27 KB
+CJS dist/cli.js   16.50 KB
+CJS ⚡️ Build success in 60ms
 DTS Build start
-DTS ⚡️ Build success in 3638ms
+DTS ⚡️ Build success in 2662ms
 DTS dist/cli.d.ts    20.00 B
-DTS dist/index.d.ts  2.36 KB
+DTS dist/index.d.ts  2.49 KB
 DTS dist/cli.d.mts   20.00 B
-DTS dist/index.d.mts 2.36 KB
+DTS dist/index.d.mts 2.49 KB

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
 
 
-> @aiready/agent-grounding@0.1.6 lint /Users/pengcao/projects/aiready/packages/agent-grounding
+> @aiready/agent-grounding@0.9.5 lint /Users/pengcao/projects/aiready/packages/agent-grounding
 > eslint src
 

package/.turbo/turbo-test.log

@@ -1,16 +1,16 @@
 
 
-> @aiready/agent-grounding@0.9.4 test /Users/pengcao/projects/aiready/packages/agent-grounding
+> @aiready/agent-grounding@0.10.0 test /Users/pengcao/projects/aiready/packages/agent-grounding
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/agent-grounding
 
- ✓ src/__tests__/analyzer.test.ts (3 tests) 253ms
+ ✓ src/__tests__/analyzer.test.ts (3 tests) 135ms
 
  Test Files  1 passed (1)
       Tests  3 passed (3)
-   Start at  21:39:02
-   Duration  1.35s (transform 234ms, setup 0ms, import 850ms, tests 253ms, environment 0ms)
+   Start at  09:33:02
+   Duration  1.11s (transform 351ms, setup 0ms, import 812ms, tests 135ms, environment 0ms)
 
 [?25h

package/dist/chunk-T5YTLYD6.mjs

@@ -0,0 +1,297 @@
+// src/analyzer.ts
+import {
+  scanEntries,
+  calculateAgentGrounding,
+  VAGUE_FILE_NAMES,
+  Severity,
+  IssueType
+} from "@aiready/core";
+import { readFileSync, existsSync, statSync } from "fs";
+import { join, extname, basename, relative } from "path";
+import { parse } from "@typescript-eslint/typescript-estree";
+function analyzeFile(filePath) {
+  let code;
+  try {
+    code = readFileSync(filePath, "utf-8");
+  } catch {
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: []
+    };
+  }
+  let ast;
+  try {
+    ast = parse(code, {
+      jsx: filePath.endsWith(".tsx") || filePath.endsWith(".jsx"),
+      range: false,
+      loc: false
+    });
+  } catch {
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: []
+    };
+  }
+  let isBarrel = false;
+  const exportedNames = [];
+  let untypedExports = 0;
+  let totalExports = 0;
+  const domainTerms = [];
+  for (const node of ast.body) {
+    if (node.type === "ExportAllDeclaration") {
+      isBarrel = true;
+      continue;
+    }
+    if (node.type === "ExportNamedDeclaration") {
+      totalExports++;
+      const decl = node.declaration;
+      if (decl) {
+        const name = decl.id?.name ?? decl.declarations?.[0]?.id?.name;
+        if (name) {
+          exportedNames.push(name);
+          domainTerms.push(
+            ...name.replace(/([A-Z])/g, " $1").toLowerCase().split(/\s+/).filter(Boolean)
+          );
+          const hasType = decl.returnType != null || decl.declarations?.[0]?.id?.typeAnnotation != null || decl.typeParameters != null;
+          if (!hasType) untypedExports++;
+        }
+      } else if (node.specifiers && node.specifiers.length > 0) {
+        isBarrel = true;
+      }
+    }
+    if (node.type === "ExportDefaultDeclaration") {
+      totalExports++;
+    }
+  }
+  return { isBarrel, exportedNames, untypedExports, totalExports, domainTerms };
+}
+function detectInconsistentTerms(allTerms) {
+  const termFreq = /* @__PURE__ */ new Map();
+  for (const term of allTerms) {
+    if (term.length >= 3) {
+      termFreq.set(term, (termFreq.get(term) ?? 0) + 1);
+    }
+  }
+  const orphans = [...termFreq.values()].filter((count) => count === 1).length;
+  const common = [...termFreq.values()].filter((count) => count >= 3).length;
+  const vocabularySize = termFreq.size;
+  const inconsistent = Math.max(0, orphans - common * 2);
+  return { inconsistent, vocabularySize };
+}
+async function analyzeAgentGrounding(options) {
+  const rootDir = options.rootDir;
+  const maxRecommendedDepth = options.maxRecommendedDepth ?? 4;
+  const readmeStaleDays = options.readmeStaleDays ?? 90;
+  const { files, dirs: rawDirs } = await scanEntries({
+    ...options,
+    include: options.include || ["**/*.{ts,tsx,js,jsx}"]
+  });
+  const dirs = rawDirs.map((d) => ({
+    path: d,
+    depth: relative(rootDir, d).split(/[/\\]/).filter(Boolean).length
+  }));
+  const deepDirectories = dirs.filter(
+    (d) => d.depth > maxRecommendedDepth
+  ).length;
+  const additionalVague = new Set(
+    (options.additionalVagueNames ?? []).map((n) => n.toLowerCase())
+  );
+  let vagueFileNames = 0;
+  for (const f of files) {
+    const base = basename(f, extname(f)).toLowerCase();
+    if (VAGUE_FILE_NAMES.has(base) || additionalVague.has(base)) {
+      vagueFileNames++;
+    }
+  }
+  const readmePath = join(rootDir, "README.md");
+  const hasRootReadme = existsSync(readmePath);
+  let readmeIsFresh = false;
+  if (hasRootReadme) {
+    try {
+      const stat = statSync(readmePath);
+      const ageDays = (Date.now() - stat.mtimeMs) / (1e3 * 60 * 60 * 24);
+      readmeIsFresh = ageDays < readmeStaleDays;
+    } catch {
+    }
+  }
+  const allDomainTerms = [];
+  let barrelExports = 0;
+  let untypedExports = 0;
+  let totalExports = 0;
+  let processed = 0;
+  for (const f of files) {
+    processed++;
+    options.onProgress?.(
+      processed,
+      files.length,
+      `agent-grounding: analyzing files`
+    );
+    const analysis = analyzeFile(f);
+    if (analysis.isBarrel) barrelExports++;
+    untypedExports += analysis.untypedExports;
+    totalExports += analysis.totalExports;
+    allDomainTerms.push(...analysis.domainTerms);
+  }
+  const {
+    inconsistent: inconsistentDomainTerms,
+    vocabularySize: domainVocabularySize
+  } = detectInconsistentTerms(allDomainTerms);
+  const groundingResult = calculateAgentGrounding({
+    deepDirectories,
+    totalDirectories: dirs.length,
+    vagueFileNames,
+    totalFiles: files.length,
+    hasRootReadme,
+    readmeIsFresh,
+    barrelExports,
+    untypedExports,
+    totalExports: Math.max(1, totalExports),
+    inconsistentDomainTerms,
+    domainVocabularySize: Math.max(1, domainVocabularySize)
+  });
+  const issues = [];
+  if (groundingResult.dimensions.structureClarityScore < 70) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "structure-clarity",
+      severity: Severity.Major,
+      message: `${deepDirectories} directories exceed recommended depth of ${maxRecommendedDepth} \u2014 agents struggle to navigate deep trees.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: `Flatten nested directories to ${maxRecommendedDepth} levels or fewer.`
+    });
+  }
+  if (groundingResult.dimensions.selfDocumentationScore < 70) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "self-documentation",
+      severity: Severity.Major,
+      message: `${vagueFileNames} files use vague names (utils, helpers, misc) \u2014 an agent cannot determine their purpose from the name alone.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: "Rename to domain-specific names: e.g., userAuthUtils \u2192 tokenValidator."
+    });
+  }
+  if (!hasRootReadme) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "entry-point",
+      severity: Severity.Critical,
+      message: "No root README.md found \u2014 agents have no orientation document to start from.",
+      location: { file: join(rootDir, "README.md"), line: 0 },
+      suggestion: "Add a README.md explaining the project structure, entry points, and key conventions."
+    });
+  } else if (!readmeIsFresh) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "entry-point",
+      severity: Severity.Minor,
+      message: `README.md is stale (>${readmeStaleDays} days without updates) \u2014 agents may be misled by outdated context.`,
+      location: { file: readmePath, line: 0 },
+      suggestion: "Update README.md to reflect the current codebase structure."
+    });
+  }
+  if (groundingResult.dimensions.apiClarityScore < 70) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "api-clarity",
+      severity: Severity.Major,
+      message: `${untypedExports} of ${totalExports} public exports lack TypeScript type annotations \u2014 agents cannot infer the API contract.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: "Add explicit return type and parameter annotations to all exported functions."
+    });
+  }
+  if (groundingResult.dimensions.domainConsistencyScore < 70) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "domain-consistency",
+      severity: Severity.Major,
+      message: `${inconsistentDomainTerms} domain terms appear to be used inconsistently \u2014 agents get confused when one concept has multiple names.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: "Establish a domain glossary and enforce one term per concept across the codebase."
+    });
+  }
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      directoriesAnalyzed: dirs.length,
+      score: groundingResult.score,
+      rating: groundingResult.rating,
+      dimensions: groundingResult.dimensions
+    },
+    issues,
+    rawData: {
+      deepDirectories,
+      totalDirectories: dirs.length,
+      vagueFileNames,
+      totalFiles: files.length,
+      hasRootReadme,
+      readmeIsFresh,
+      barrelExports,
+      untypedExports,
+      totalExports,
+      inconsistentDomainTerms,
+      domainVocabularySize
+    },
+    recommendations: groundingResult.recommendations
+  };
+}
+
+// src/scoring.ts
+import { ToolName } from "@aiready/core";
+function calculateGroundingScore(report) {
+  const { summary, rawData, recommendations } = report;
+  const factors = [
+    {
+      name: "Structure Clarity",
+      impact: Math.round(summary.dimensions.structureClarityScore - 50),
+      description: `${rawData.deepDirectories} of ${rawData.totalDirectories} dirs exceed recommended depth`
+    },
+    {
+      name: "Self-Documentation",
+      impact: Math.round(summary.dimensions.selfDocumentationScore - 50),
+      description: `${rawData.vagueFileNames} of ${rawData.totalFiles} files have vague names`
+    },
+    {
+      name: "Entry Points",
+      impact: Math.round(summary.dimensions.entryPointScore - 50),
+      description: rawData.hasRootReadme ? rawData.readmeIsFresh ? "README present and fresh" : "README present but stale" : "No root README"
+    },
+    {
+      name: "API Clarity",
+      impact: Math.round(summary.dimensions.apiClarityScore - 50),
+      description: `${rawData.untypedExports} of ${rawData.totalExports} exports lack type annotations`
+    },
+    {
+      name: "Domain Consistency",
+      impact: Math.round(summary.dimensions.domainConsistencyScore - 50),
+      description: `${rawData.inconsistentDomainTerms} inconsistent domain terms detected`
+    }
+  ];
+  const recs = recommendations.map(
+    (action) => ({
+      action,
+      estimatedImpact: 6,
+      priority: summary.score < 50 ? "high" : "medium"
+    })
+  );
+  return {
+    toolName: ToolName.AgentGrounding,
+    score: summary.score,
+    rawMetrics: {
+      ...rawData,
+      rating: summary.rating
+    },
+    factors,
+    recommendations: recs
+  };
+}
+
+export {
+  analyzeAgentGrounding,
+  calculateGroundingScore
+};

package/dist/cli.js

@@ -264,6 +264,7 @@ async function analyzeAgentGrounding(options) {
 }
 
 // src/scoring.ts
+var import_core2 = require("@aiready/core");
 function calculateGroundingScore(report) {
   const { summary, rawData, recommendations } = report;
   const factors = [
@@ -301,7 +302,7 @@ function calculateGroundingScore(report) {
     })
   );
   return {
-    toolName: "agent-grounding",
+    toolName: import_core2.ToolName.AgentGrounding,
     score: summary.score,
     rawMetrics: {
       ...rawData,
@@ -316,7 +317,7 @@ function calculateGroundingScore(report) {
 var import_chalk = __toESM(require("chalk"));
 var import_fs2 = require("fs");
 var import_path2 = require("path");
-var import_core2 = require("@aiready/core");
+var import_core3 = require("@aiready/core");
 var program = new import_commander.Command();
 program.name("aiready-agent-grounding").description(
   "Measure how well an AI agent can navigate your codebase autonomously"
@@ -346,8 +347,8 @@ EXAMPLES:
 ).option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console|json", "console").option("--output-file <path>", "Output file path (for json)").action(async (directory, options) => {
   console.log(import_chalk.default.blue("\u{1F9ED} Analyzing agent grounding...\n"));
   const startTime = Date.now();
-  const config = await (0, import_core2.loadConfig)(directory);
-  const mergedConfig = (0, import_core2.mergeConfigWithDefaults)(config, {
+  const config = await (0, import_core3.loadConfig)(directory);
+  const mergedConfig = (0, import_core3.mergeConfigWithDefaults)(config, {
     maxRecommendedDepth: 4,
     readmeStaleDays: 90
   });
@@ -363,7 +364,7 @@ EXAMPLES:
   const elapsed = ((Date.now() - startTime) / 1e3).toFixed(2);
   if (options.output === "json") {
     const payload = { report, score: scoring };
-    const outputPath = (0, import_core2.resolveOutputPath)(
+    const outputPath = (0, import_core3.resolveOutputPath)(
       options.outputFile,
       `agent-grounding-report-${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}.json`,
       directory

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   analyzeAgentGrounding,
   calculateGroundingScore
-} from "./chunk-L3MLD6K4.mjs";
+} from "./chunk-T5YTLYD6.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.d.mts

@@ -1,4 +1,9 @@
-import { Issue, IssueType, ScanOptions, ToolScoringOutput } from '@aiready/core';
+import { ToolProvider, Issue, IssueType, ScanOptions, ToolScoringOutput } from '@aiready/core';
+
+/**
+ * Agent Grounding Tool Provider
+ */
+declare const AgentGroundingProvider: ToolProvider;
 
 interface AgentGroundingOptions extends ScanOptions {
     /** Max directory depth before flagging as "too deep" */
@@ -63,4 +68,4 @@ declare function analyzeAgentGrounding(options: AgentGroundingOptions): Promise<
  */
 declare function calculateGroundingScore(report: AgentGroundingReport): ToolScoringOutput;
 
-export { type AgentGroundingIssue, type AgentGroundingOptions, type AgentGroundingReport, analyzeAgentGrounding, calculateGroundingScore };
+export { type AgentGroundingIssue, type AgentGroundingOptions, AgentGroundingProvider, type AgentGroundingReport, analyzeAgentGrounding, calculateGroundingScore };

package/dist/index.d.ts

@@ -1,4 +1,9 @@
-import { Issue, IssueType, ScanOptions, ToolScoringOutput } from '@aiready/core';
+import { ToolProvider, Issue, IssueType, ScanOptions, ToolScoringOutput } from '@aiready/core';
+
+/**
+ * Agent Grounding Tool Provider
+ */
+declare const AgentGroundingProvider: ToolProvider;
 
 interface AgentGroundingOptions extends ScanOptions {
     /** Max directory depth before flagging as "too deep" */
@@ -63,4 +68,4 @@ declare function analyzeAgentGrounding(options: AgentGroundingOptions): Promise<
  */
 declare function calculateGroundingScore(report: AgentGroundingReport): ToolScoringOutput;
 
-export { type AgentGroundingIssue, type AgentGroundingOptions, type AgentGroundingReport, analyzeAgentGrounding, calculateGroundingScore };
+export { type AgentGroundingIssue, type AgentGroundingOptions, AgentGroundingProvider, type AgentGroundingReport, analyzeAgentGrounding, calculateGroundingScore };

package/dist/index.js

@@ -20,10 +20,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AgentGroundingProvider: () => AgentGroundingProvider,
   analyzeAgentGrounding: () => analyzeAgentGrounding,
   calculateGroundingScore: () => calculateGroundingScore
 });
 module.exports = __toCommonJS(index_exports);
+var import_core4 = require("@aiready/core");
+
+// src/provider.ts
+var import_core3 = require("@aiready/core");
 
 // src/analyzer.ts
 var import_core = require("@aiready/core");
@@ -263,6 +268,7 @@ async function analyzeAgentGrounding(options) {
 }
 
 // src/scoring.ts
+var import_core2 = require("@aiready/core");
 function calculateGroundingScore(report) {
   const { summary, rawData, recommendations } = report;
   const factors = [
@@ -300,7 +306,7 @@ function calculateGroundingScore(report) {
     })
   );
   return {
-    toolName: "agent-grounding",
+    toolName: import_core2.ToolName.AgentGrounding,
     score: summary.score,
     rawMetrics: {
       ...rawData,
@@ -310,8 +316,49 @@ function calculateGroundingScore(report) {
     recommendations: recs
   };
 }
+
+// src/provider.ts
+var AgentGroundingProvider = {
+  id: import_core3.ToolName.AgentGrounding,
+  alias: ["agent-grounding", "grounding", "navigation"],
+  async analyze(options) {
+    const report = await analyzeAgentGrounding(
+      options
+    );
+    const results = report.issues.map((i) => ({
+      fileName: i.location.file,
+      issues: [i],
+      metrics: {
+        agentGroundingScore: report.summary.score
+      }
+    }));
+    return import_core3.SpokeOutputSchema.parse({
+      results,
+      summary: report.summary,
+      metadata: {
+        toolName: import_core3.ToolName.AgentGrounding,
+        version: "0.9.5",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        rawData: report.rawData
+      }
+    });
+  },
+  score(output, options) {
+    const report = {
+      summary: output.summary,
+      rawData: output.metadata.rawData,
+      recommendations: output.summary.recommendations || []
+    };
+    return calculateGroundingScore(report);
+  },
+  defaultWeight: 10
+};
+
+// src/index.ts
+import_core4.ToolRegistry.register(AgentGroundingProvider);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgentGroundingProvider,
   analyzeAgentGrounding,
   calculateGroundingScore
 });

package/dist/index.mjs

@@ -1,8 +1,56 @@
 import {
   analyzeAgentGrounding,
   calculateGroundingScore
-} from "./chunk-L3MLD6K4.mjs";
+} from "./chunk-T5YTLYD6.mjs";
+
+// src/index.ts
+import { ToolRegistry } from "@aiready/core";
+
+// src/provider.ts
+import {
+  ToolName,
+  SpokeOutputSchema
+} from "@aiready/core";
+var AgentGroundingProvider = {
+  id: ToolName.AgentGrounding,
+  alias: ["agent-grounding", "grounding", "navigation"],
+  async analyze(options) {
+    const report = await analyzeAgentGrounding(
+      options
+    );
+    const results = report.issues.map((i) => ({
+      fileName: i.location.file,
+      issues: [i],
+      metrics: {
+        agentGroundingScore: report.summary.score
+      }
+    }));
+    return SpokeOutputSchema.parse({
+      results,
+      summary: report.summary,
+      metadata: {
+        toolName: ToolName.AgentGrounding,
+        version: "0.9.5",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        rawData: report.rawData
+      }
+    });
+  },
+  score(output, options) {
+    const report = {
+      summary: output.summary,
+      rawData: output.metadata.rawData,
+      recommendations: output.summary.recommendations || []
+    };
+    return calculateGroundingScore(report);
+  },
+  defaultWeight: 10
+};
+
+// src/index.ts
+ToolRegistry.register(AgentGroundingProvider);
 export {
+  AgentGroundingProvider,
   analyzeAgentGrounding,
   calculateGroundingScore
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/agent-grounding",
-  "version": "0.9.5",
+  "version": "0.11.0",
   "description": "Measures how well an AI agent can navigate a codebase autonomously without human assistance",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -40,7 +40,7 @@
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
     "glob": "^13.0.0",
-    "@aiready/core": "0.19.5"
+    "@aiready/core": "0.21.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/index.ts

@@ -1,5 +1,12 @@
+import { ToolRegistry } from '@aiready/core';
+import { AgentGroundingProvider } from './provider';
+
+// Register with global registry
+ToolRegistry.register(AgentGroundingProvider);
+
 export { analyzeAgentGrounding } from './analyzer';
 export { calculateGroundingScore } from './scoring';
+export { AgentGroundingProvider };
 export type {
   AgentGroundingOptions,
   AgentGroundingReport,

package/src/provider.ts

@@ -0,0 +1,57 @@
+import {
+  ToolProvider,
+  ToolName,
+  SpokeOutput,
+  ScanOptions,
+  ToolScoringOutput,
+  AnalysisResult,
+  SpokeOutputSchema,
+} from '@aiready/core';
+import { analyzeAgentGrounding } from './analyzer';
+import { calculateGroundingScore } from './scoring';
+import { AgentGroundingOptions, AgentGroundingReport } from './types';
+
+/**
+ * Agent Grounding Tool Provider
+ */
+export const AgentGroundingProvider: ToolProvider = {
+  id: ToolName.AgentGrounding,
+  alias: ['agent-grounding', 'grounding', 'navigation'],
+
+  async analyze(options: ScanOptions): Promise<SpokeOutput> {
+    const report = await analyzeAgentGrounding(
+      options as AgentGroundingOptions
+    );
+
+    const results: AnalysisResult[] = report.issues.map((i) => ({
+      fileName: i.location.file,
+      issues: [i] as any[],
+      metrics: {
+        agentGroundingScore: report.summary.score,
+      },
+    }));
+
+    return SpokeOutputSchema.parse({
+      results,
+      summary: report.summary,
+      metadata: {
+        toolName: ToolName.AgentGrounding,
+        version: '0.9.5',
+        timestamp: new Date().toISOString(),
+        rawData: report.rawData,
+      },
+    });
+  },
+
+  score(output: SpokeOutput, options: ScanOptions): ToolScoringOutput {
+    const report = {
+      summary: output.summary,
+      rawData: (output.metadata as any).rawData,
+      recommendations: (output.summary as any).recommendations || [],
+    } as unknown as AgentGroundingReport;
+
+    return calculateGroundingScore(report);
+  },
+
+  defaultWeight: 10,
+};

package/src/scoring.ts

@@ -1,4 +1,4 @@
-import type { ToolScoringOutput } from '@aiready/core';
+import { type ToolScoringOutput, ToolName } from '@aiready/core';
 import type { AgentGroundingReport } from './types';
 
 /**
@@ -51,7 +51,7 @@ export function calculateGroundingScore(
   );
 
   return {
-    toolName: 'agent-grounding',
+    toolName: ToolName.AgentGrounding,
     score: summary.score,
     rawMetrics: {
       ...rawData,