kg-suite-conformance-runner

Fleet-level conformance scanner over a directory of Kinetic Gain Suite JSON docs. Sniffs the protocol of every file, counts by spec, and checks structural conformance — required top-level blocks present, version discriminator detection.

Status: v0.1.0 — Node 20/22 supported, library + CLI.

What it does

For every *.json in a directory tree:

1. Detect the protocol via version field (agent_card_version, tool_card_version, provenance_version, evidence_bundle_version) or shape signals (resourceSpans[] → OTLP, tools[] with names → MCP tools/list).
2. Validate the doc has every required top-level block for its detected protocol (per the spec):
   • agent-cards-spec: agent + capabilities + deployment + safety_posture
   • mcp-tool-card-spec: tool + schema + safety + audit
   • prompt-provenance-spec: prompt + lineage + authorship + approval
   • evidence-bundle-spec: bundle + items
3. Report counts by protocol + findings (missing blocks, malformed JSON, empty files, unknown protocols).

Use it as the "what specs are in my repo and which ones violate basic shape?" routing + validation utility.

CLI

npx kg-suite-conformance-runner <docs-dir>
    [--format json|markdown|summary]
    [--skip path,path]
    [--no-fail-on-unknown]
    [--fail-on-high]
    [--out FILE]

Exit code:

• 0 — clean (or --fail-on-high not set)
• 1 — high finding AND --fail-on-high set
• 2 — usage / I/O error

Library

import { run, detectProtocol, toMarkdown } from "kg-suite-conformance-runner";

const report = run("./suite-docs");
console.log(report.byProtocol);
//   { "agent-cards-spec": 12, "mcp-tool-card-spec": 47, "prompt-provenance-spec": 8, ... }

console.log(report.findings);
//   [{ code, severity, source, message, protocol? }, ...]

console.log(toMarkdown(report));

Composes with

• kg-protocol-detect — the single-doc routing primitive.
• Every Kinetic Gain Suite spec (agent-cards-spec, mcp-tool-card-spec, prompt-provenance-spec, evidence-bundle-spec).
• Every Suite test-vector corpus (use this runner against the canonical fixtures to gut-check your spec compliance).

Develop

npm install
npm run lint && npm run typecheck && npm run coverage && npm run build
npm run demo

License

AGPL-3.0-or-later