Ground: Evidence-Based Claims for AI Code Analysis

AI agents analyzing codebases make three common claim types:

• DRY violations: "These two files are duplicates"
• Dead code: "This function is never used"
• Orphan modules: "Nothing imports this file"

Without verification, these claims frequently fail:

The cost of false positives is high: incorrect refactoring, broken builds, and eroded trust in AI-assisted analysis.

Ground enforces a simple rule: you cannot claim something until you've checked it.

# This fails - no evidence yet
ground claim duplicate file_a.ts file_b.ts
→ ❌ Blocked: Run 'ground compare file_a.ts file_b.ts' first

# Compute the evidence
ground compare file_a.ts file_b.ts
→ ✓ 94.2% similar (evidence recorded)

# Now the claim succeeds
ground claim duplicate file_a.ts file_b.ts
→ ✓ Claim recorded (grounded in evidence)

The tool implements three verification levels, aligned with the Subtractive Triad:

Ground's key innovation is architectural awareness. Modern serverless applications connect through deployment configuration, not just imports.

Cloudflare Worker Detection

When checking module connectivity, Ground parses wrangler.toml to detect:

• Routes: HTTP endpoints the worker responds to
• Crons: Scheduled trigger patterns
• Bindings: KV, D1, R2, Durable Objects, Queues
• Service bindings: Worker-to-worker connections

# Worker with no code imports, but connected via deployment
ground check connections src/index.ts

→ {
    "architectural": {
      "type": "cloudflare-worker",
      "routes": ["api.example.com/*"],
      "crons": ["0 * * * *"],
      "bindings": 4
    },
    "is_orphan": false  // ✓ Correctly identified as connected
  }

Definition vs Usage Distinction

Ground separates symbol occurrences into definitions and actual_uses:

ground count uses BeadsNotionConfig

→ {
    "total_occurrences": 1,
    "definitions": 1,        // export interface BeadsNotionConfig
    "actual_uses": 0,        // never imported elsewhere
    "is_exported_but_unused": true
  }

# Can now claim as dead code (0 actual uses)
ground claim dead-code BeadsNotionConfig
→ ✓ Claim recorded

CREATE SOMETHING Monorepo

WORKWAY Codebase

An independent agent applied Ground to the WORKWAY codebase with these results:

"The tool provides a 10-20x speedup for codebase hygiene tasks. Without it, I'd be manually grepping and guessing. With it, I have verified claims backed by evidence."
— WORKWAY Agent Feedback

What Ground Does Well

Known Limitations

Ground exposes its capabilities via the Model Context Protocol, enabling AI agents to use it during coding sessions:

// .mcp.json
{
  "mcpServers": {
    "ground": {
      "command": "./packages/ground/target/release/ground-mcp",
      "args": ["--db", ".ground/registry.db"]
    }
  }
}

Available MCP tools (20 total):

Core Analysis

• ground_compare — Compare two files for similarity
• ground_count_uses — Count symbol uses (distinguishes type-only usage)
• ground_check_connections — Check module connectivity
• ground_check_environment — Detect Workers/Node.js API safety
• ground_find_duplicate_functions — Find function-level duplicates
• ground_find_dead_exports — Find unused exports (traces re-exports)
• ground_find_orphans — Batch scan for orphaned modules

Claim System

• ground_claim_duplicate — Claim files are duplicates (blocked until verified)
• ground_claim_dead_code — Claim code is dead (blocked until verified)
• ground_claim_orphan — Claim module is orphaned (blocked until verified)
• ground_suggest_fix — Get refactoring suggestions with beads integration

AI-Native Tools (v2.0)

• ground_analyze — Batch analysis: all checks in one call
• ground_diff — Incremental mode: only new issues since baseline
• ground_verify_fix — Confirm fix without full re-analysis

Probabilistic Sketches

• ground_sketch_create — Create HyperLogLog or Bloom filter
• ground_sketch_add — Add items to sketch
• ground_sketch_query — Query cardinality or membership
• ground_sketch_merge — Merge sketches for distributed analysis
• ground_sketch_list — List active sketches

Version 2.0 transforms Ground from a verification tool into a complete AI-native code quality system. These features enable autonomous agents to find, fix, and verify issues without human intervention.

Batch Analysis

Single call returns all findings with confidence scores and structured fix actions:

ground_analyze({
  "directory": "/path/to/repo",
  "checks": ["duplicates", "dead_exports", "orphans"],
  "cross_package": true
})

→ {
    "summary": {
      "total_issues": 15,
      "auto_fixable": 12,
      "needs_review": 3
    },
    "findings": {
      "duplicates": [
        {
          "type": "duplicate_function",
          "function": "formatCurrency",
          "similarity": 0.94,
          "confidence": 0.97,
          "safe_to_auto_fix": true,
          "fix": {
            "action": "consolidate",
            "target": "packages/shared/utils.ts",
            "imports_to_update": [...]
          }
        }
      ]
    }
  }

Incremental Diff Mode

Only reports new issues since a git baseline—agents don't re-process known issues:

ground_diff({
  "directory": "/path/to/repo",
  "base": "main",
  "checks": ["duplicates", "orphans"]
})

→ {
    "base": "main",
    "changed_files": 19,
    "new_issues": [],
    "message": "No new issues introduced since 'main'. 19 files changed, all clean."
  }

This enables CI integration that only fails PRs introducing new issues:

# .github/workflows/ground.yml
- name: Check for new issues
  run: |
    ground diff --base origin/main
    # Fails only if PR introduces NEW duplicates/orphans
    # Ignores pre-existing issues

Structured Fix Output

Fixes are structured data for agents to execute—not patches for humans to read:

{
  "action": "consolidate",
  "source_files": ["payments/utils.ts", "invoices/utils.ts"],
  "target": "packages/shared/src/stripe-utils.ts",
  "function": "formatCurrency",
  "imports_to_update": [
    {
      "file": "payments/list.ts",
      "old_import": "./utils",
      "new_import": "@company/shared"
    }
  ],
  "confidence": 0.97,
  "safe_to_auto_fix": true,
  "rationale": "Same package, identical implementation"
}

Fix Verification

Close the loop without re-running full analysis:

ground_verify_fix({
  "fix_type": "duplicate_removed",
  "details": {
    "function_name": "formatCurrency",
    "file_a": "payments/utils.ts",
    "file_b": "invoices/utils.ts"
  }
})

→ {
    "verified": true,
    "message": "Verified: 'formatCurrency' no longer duplicated"
  }

Config-Driven Noise Reduction

.ground.yml eliminates noise from structural patterns:

# .ground.yml
ignore:
  functions:
    - getCapabilities    # Interface contract (64 integrations)
    - constructor        # Boilerplate OK
    - initialize         # Framework pattern
  paths:
    - "**/*.test.ts"     # Test isolation expected
    - "**/fixtures/**"
  duplicate_pairs:
    - ["analytics/track/+server.ts", "io/analytics/track/+server.ts"]

The name "Ground" references Heidegger's concept of Grund (ground/foundation). In Heidegger's philosophy, assertions must be grounded—connected to something that supports them. An ungrounded claim floats free, unconnected to reality.

Ground operationalizes this: every claim about code must be grounded in computed evidence. The tool doesn't prevent you from making claims—it ensures those claims rest on something solid.

"You can't claim something until you've checked it."

This aligns with the Subtractive Triad's emphasis on removing what obscures. False claims about code obscure the true state of the system. Ground removes that obscurity by requiring verification.

An independent agent (WORKWAY) conducted systematic testing of Ground across multiple sessions, providing iterative feedback that drove v2.0 development:

"The diff feature closes the loop for autonomous agents: analyze finds all issues (initial scan), diff reports only new issues (CI/PR review), verify_fix confirms the fix worked (close the loop). An agent can now run diff on every PR, only process NEW issues, verify fixes without full re-scan, and have zero noise from config. This is a complete AI-native code quality tool."
— Agent Rating: 10/10

What Doesn't Matter for AI Agents

Notably, the agent feedback explicitly deprioritized features that would matter for humans:

• Visualization — Agents have no eyes
• Pretty reports — Agents parse JSON
• LSP/IDE integration — The agent IS the IDE
• Historical dashboards — Agents have memory

This validates the design principle: AI-native tools need different affordances than human-native tools.

Ground demonstrates that computation-constrained verification significantly improves AI-assisted code analysis. Version 2.0 extends this foundation with AI-native features that enable fully autonomous code quality workflows. The tool now:

• Eliminates false positives through evidence-based claims
• Finds 93+ real DRY violations across production codebases
• Provides 10-20x speedup over manual analysis
• Enables autonomous find → fix → verify workflows
• Supports CI integration via incremental diff mode
• Reduces noise to zero through config-driven filtering

The 10/10 agent rating validates that Ground has reached the threshold for AI-native tooling: agents can autonomously find, fix, and verify code quality issues without human intervention.

The tool is available as part of the CREATE SOMETHING monorepo and can be integrated into any development workflow via the MCP protocol.