KG-SSOT¶

Why¶

A company brain is usually built by piling documents into RAG or GraphRAG. That keeps the data, but not the decisions: who decided what, on which source, and whether that source still holds. Teams, of people or of agents, pile up conclusions such as "the retry is idempotent" or "we decided on three attempts", and on the way they lose three things: the source, the date it was last verified and what depends on it. When the person who decided leaves, the reasoning leaves too.

KG-SSOT treats this as a format problem, not a discipline problem. Knowledge lives in a .kg.yaml graph, versioned next to the code, and a formal contract decides in CI what fails:

• a confirmed or production node without provenance fails (a claim with no recoverable source is declared unverifiable instead);
• a source that is only a placeholder (unknown, n/a, tbd) fails;
• an edge that points nowhere fails, and so does a node with no edges;
• a verification stamp with nothing to check against, a decision with no origin and a production claim backed only by testimony raise warnings.

What it does for a company brain¶

Business, technical, compliance and design knowledge can live in the same format, in your repository. It plugs in as a Python package or an MCP server, with a JavaScript validator on npm, and the CI gate is one of its uses, not the point. The pins are checked when kg_query or kg_trace.py runs with --root.

Get started in 60 seconds¶

pip install kg-ssot

# the conformance suite against the reference reader, from the installed package
kg-conformance | tail -2

# one valid graph and one that fails
kg-validate valid.kg.yaml broken.kg.yaml

Or straight from the repository, with hash-checked dependencies:

git clone https://github.com/marciocar/kg-ssot && cd kg-ssot
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r tools/requirements.txt
.venv/bin/python3 -I tools/kg_validate.py \
  spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml \
  spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml

PASS spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml
FAIL spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml
  MUST   form.required.node.label ×1
· 2 files; 1 pass the MUST; 0 with a SHOULD warning (kg-contract-v4.schema.json + kg-contract-v4.should.schema.json)

The tools print in English by default and in Brazilian Portuguese when your locale is pt_BR (or KG_SSOT_LANG=pt-BR). Codes, exit codes and JSON keys never change with the language; only the human text does.

Install¶

A node, inside¶

- id: C_RETRY_SAFE
  node_type: claim
  plane: PROD
  status: confirmed
  impact: 4
  confidence: 0.8
  label: The payment retry is idempotent.
  verified_at: "2026-10-01"
  verified_against: tests/payment_retry_test.py
  provenance:
    source: tests/payment_retry_test.py
    locator: test_retry_is_idempotent
    method: "measurement: integration test in CI"

The label is the claim, short. The provenance says where it came from and how: one of five method classes, measurement, reading, judges, derived or testimony. The stamp says when it was verified and against what. Since contract v4.16 these English names are the canonical form; the Portuguese medição, leitura, juízes, derivado and testemunho are still accepted as aliases, with no warning.

Use it from an AI agent¶

The reference MCP server gives a model the contract and a store: it validates a graph, writes only what passes, reads, lists, queries with every edge resolved to the label on the other end, and shows history. Read-only tools are annotated as such, so a client can skip confirmation for them.

kg-mcp --root ./graphs          # stdio, for Claude Desktop, Claude Code and other MCP clients

kg_schema_help returns the current contract, a minimal passing example and the fixes for the most common codes, so a model can write a passing graph on the first try. llms.txt indexes the documentation for agents, and llms-full.txt has all of it in one file.

The agent skill. skills/kg-ssot/ is an Agent Skills skill that teaches a coding agent to write, fix, validate and query graphs with these tools, in .kg.yaml and .kg.json. In a pre-registered test, an agent with the skill reached the same result with 45% of the output tokens and 54% of the tool calls.

npx skills add marciocar/kg-ssot -s kg-ssot     # Claude Code, Codex and other clients that read Agent Skills

In Claude Code, it also comes as a plugin: /plugin marketplace add marciocar/kg-ssot, then /plugin install kg-ssot@kg-ssot.

How it works¶

flowchart LR
  subgraph product["Product (one tag kg-ssot-vX.Y.Z)"]
    C["Contract<br/>JSON Schema MUST + SHOULD<br/>+ integrity rules"]
    S["Conformance suite<br/>512 cases as plain data"]
    R["Reference reader<br/>kg_validate.py"]
    S -- "every reader passes" --> R
    C --> R
  end
  subgraph adopter["Adopter repository"]
    V["vendor/kg-ssot<br/>+ sha256 stamp"]
    G["kg_gate.py in CI<br/>per-graph ratchet"]
    K["the team's .kg.yaml"]
    V --> G
    K --> G
  end
  product -- "kg_vendor.py update --tag" --> V
  G -- "nothing gets worse:<br/>a new graph passes,<br/>debt only shrinks" --> PR["PR approved"]

1. The contract is JSON Schema 2020-12 at two levels: MUST fails, SHOULD warns. The rules a schema cannot express (unique ids, existing edge ends, orphan nodes) are part of it.
2. The suite is the compatibility proof: each case is a real YAML file with the expected verdict and codes, and a reader passes only if it emits exactly the same codes.
3. The kit brings the contract to a repository by tag, with a stamp that fails local edits, and runs the per-graph ratchet in CI: what already failed becomes named debt, a new graph has to pass, and the debt only shrinks.

Features¶

What KG-SSOT is not¶

Status¶

• Current: contract v4, release kg-ssot-v4.45.0. The reference reader passes 512 of 512 cases in latest/.
• In use: three adopters run the gate in CI, one of them in production.
• Next: v5 will fail a method outside the <class>: <detail> form, which only warns today.
• Open: the semantic layer (freshness, contradiction, domain completeness) lives in optional/, and the reference reader does not implement it: it passes only the 10 valid cases there.

Documentation¶

Contributing¶

A contract change starts with a conformance case: the .kg.yaml that shows the behavior and the expected verdict. Releases are tags kg-ssot-vX.Y.Z of the development repository, where every pull request that touches spec/ or tools/ runs the suite and the kit tests in CI. The release mirror holds only what each tag ships, one commit per tag, and does not take pull requests: a proposal or a bug goes in as an issue, ideally with the case that shows it. A reader in another language is welcome: chapter 7 of the manual explains how to measure it.

License¶

The product (what the release ships, listed in spec/release.json: the contract, the suite, the .kg.yaml cases, the kit in tools/, ADOPTING.md, this README and the manual) is Apache-2.0: LICENSE, with the scope in NOTICE.

_{KG-SSOT was born inside the Onion framework, which now adopts it by tag like any other adopter. The product does not depend on it.}