Spanfold
Code

Agentic Auditing

Export the full comparison context for agents.

Visual auditing is for humans. Agentic auditing is for agents: a deterministic JSON artifact with analysis instructions, a compact summary, Markdown orientation, the full result data, and row documents for chunked review.

Write an agent-readable artifact.

Use it at the same workflow boundary as debug HTML: failing tests, CI artifacts, incident handoff, support reports, notebooks, or any place where an agent needs exact temporal evidence instead of a screenshot or prose summary. 

var result = pipeline.History
    .Compare("Provider QA")
    .Target("provider-a", s => s.Source("provider-a"))
    .Against("provider-b", s => s.Source("provider-b"))
    .Within(scope => scope.Window("DeviceOffline"))
    .Using(c => c.Overlap().Residual().Missing())
    .Run();

result.ExportDebugHtml("artifacts/provider-qa.html");
result.ExportLlmContext("artifacts/provider-qa.llm.json");
result = (
    pipeline.history.compare("Provider QA")
    .target("provider-a")
    .against("provider-b")
    .within(window_name="DeviceOffline")
    .using("overlap", "residual", "coverage")
    .run()
)

result.export_llm_context("artifacts/provider-qa.llm.json")

Artifact shape

One file with orientation and exact evidence.

The top-level document is deliberately redundant: agents get concise instructions and summary fields, but can always drill into the full deterministic result JSON and row-level documents.

analysisInstructions Rules for how an agent should cite evidence, preserve row ids, and avoid unsafe inference.
summary Plan name, validity, horizons, selected and normalized window counts, segment count, and row counts.
resultMarkdown A compact deterministic orientation that is useful before inspecting raw row data.
fullResult The complete comparison result export with plan, diagnostics, prepared windows, aligned segments, rows, finality, and summaries.
rowDocuments JSON documents for streaming or chunking: the first entry is the result summary, followed by individual row records.

Example export

An abbreviated .llm.json artifact.

Real exports include the complete fullResult object. This excerpt keeps the shape visible without hiding the parts agents rely on. 

{
  "schema": "spanfold.comparison.llm-context",
  "schemaVersion": 0,
  "artifact": "llm-context",
  "purpose": "Portable comparison context for LLMs, coding agents, CI triage, and support handoff.",
  "analysisInstructions": [
    "Treat fullResult as the source of truth for exact fields, ranges, windows, segments, tags, diagnostics, summaries, and row evidence.",
    "Use resultMarkdown for a concise natural-language orientation before drilling into fullResult.",
    "Use rowDocuments when chunking or streaming row-level analysis; rowDocuments[0] is the result summary and later entries are individual comparison rows."
  ],
  "summary": {
    "planName": "Provider QA",
    "isValid": true,
    "knownAt": null,
    "evaluationHorizon": null,
    "diagnosticCount": 0,
    "selectedWindowCount": 2,
    "excludedWindowCount": 0,
    "normalizedWindowCount": 2,
    "alignedSegmentCount": 3,
    "rowCounts": {
      "overlap": 1,
      "residual": 2,
      "missing": 0,
      "coverage": 0,
      "gap": 0,
      "symmetricDifference": 0,
      "containment": 0,
      "leadLag": 0,
      "asOf": 0
    }
  },
  "resultMarkdown": "# Comparison Explain: Provider QA\n\nisValid: true\n\noverlap rows: 1\nresidual rows: 2",
  "fullResult": {
    "schema": "spanfold.comparison.result",
    "artifact": "result",
    "plan": {
      "name": "Provider QA"
    },
    "prepared": {
      "selectedWindows": [
        {
          "windowName": "DeviceOffline",
          "key": "device-17",
          "source": "provider-a",
          "range": { "start": { "position": 3 }, "end": { "position": 6 } }
        }
      ]
    },
    "aligned": {
      "segments": [
        {
          "windowName": "DeviceOffline",
          "key": "device-17",
          "range": { "start": { "position": 4 }, "end": { "position": 5 } },
          "targetRecordIds": [ "DeviceOffline|device-17|provider-a|3" ],
          "againstRecordIds": [ "DeviceOffline|device-17|provider-b|4" ]
        }
      ]
    },
    "rows": {
      "overlap": [
        {
          "rowId": "overlap[0]",
          "windowName": "DeviceOffline",
          "key": "device-17",
          "range": { "start": { "position": 4 }, "end": { "position": 5 } },
          "targetRecordIds": [ "DeviceOffline|device-17|provider-a|3" ],
          "againstRecordIds": [ "DeviceOffline|device-17|provider-b|4" ]
        }
      ]
    }
  },
  "rowDocuments": [
    {
      "schema": "spanfold.comparison.result-row",
      "artifact": "result-summary",
      "planName": "Provider QA",
      "overlapRowCount": 1,
      "residualRowCount": 2
    },
    {
      "schema": "spanfold.comparison.result-row",
      "artifact": "result-row",
      "rowType": "overlap",
      "rowId": "overlap[0]",
      "windowName": "DeviceOffline",
      "key": "device-17",
      "range": { "start": { "position": 4 }, "end": { "position": 5 } }
    }
  ]
}

Configuration and CLI

Emit context from runs or fixtures.

Use options when runtime configuration decides whether to write an artifact. Use the CLI when a fixture should become an agent-readable report without writing a custom host application. 

var context = ComparisonLlmContextOptions
    .ToFile("artifacts/provider-qa.llm.json");

var result = pipeline.History
    .Compare("Provider QA")
    .Target("provider-a", s => s.Source("provider-a"))
    .Against("provider-b", s => s.Source("provider-b"))
    .Within(scope => scope.Window("DeviceOffline"))
    .Using(c => c.Overlap().Residual())
    .Run(context);
dotnet run --project src/Spanfold.Cli/Spanfold.Cli.csproj -- \
  compare fixture.json --format llm-context