Developers New to Kontour? Start with Flow Agents.

v1.11.3npm install -D @kontourai/veritas

Veritas

show whether a change is ready before it reaches review

An agent rewrites an API route and says it's done. The route changed; the test that covers it didn't. Nothing in the diff flags that — the rule about it lives in a doc nobody opened, or in a reviewer's head.

Veritas moves that rule to where the work happens. The agent sees it while it's still editing the file. You see a report that says which of your repo's requirements this change met, which it didn't, and what evidence backs each answer.

View on GitHub →Read the docsnpm package
veritas readiness
$ npx --no @kontourai/veritas readiness --working-tree

veritas: 1 file changed -> app.app
PASS  evidence-check: node -e "process.exit(0)"
      [ 3 PASS lines trimmed ]
WARN  api-routes-require-api-tests: Changed files
      matched app/api/** but no companion changes
      matched tests/api/**.
      -> app/api/projects/route.ts
      [ 2 PASS lines + 1 WARN trimmed ]

0 failures · 2 warnings · run `npx --no @kontourai/veritas
readiness --check evidence` for full generated evidence

Real output, from the Veritas README, against its shipped nextjs-typescript standards template. Trimmed for column width where marked — no line here was written by us.

Who reads it

Two readers, one rule.

The same standard reaches an agent mid-edit and a human at review, but by different commands and with different install requirements. It's worth knowing which half is yours.

While the agent is working

npx --no @kontourai/veritas explain --file src/api/handler.ts returns only the rules that govern that path — short enough to sit in an agent's context window, so the repo's expectations don't fall out of the conversation two hours in.

Install the Claude Code or Codex hook and a change that breaks a rule your repo marks as required is stopped before the write lands, with the rule quoted back (Codex asks you to trust the hook first). Cursor and Copilot get the same findings at the end of the session to repair — feedback, not a block.

When a human picks it up

npx --no @kontourai/veritas readiness --working-tree prints one line per requirement: passed, failed, warned, or accepted by exception with the approver named.

Every run also writes a JSON file under .kontourai/veritas/evidence/. The next person reads the same answer without re-running anything, and without taking the word of whoever ran it first.

Example use case

The catch you'd otherwise miss.

The warning in that first run came from a five-line rule in the repo's standards file: if anything under app/api/** changes, something under tests/api/** has to change with it. Nobody had to remember it, and nobody had to spot it in the diff.

This one is set to Guide, so it warns rather than fails — advice the agent is expected to act on. Set it to Require and the same finding fails the run instead. Either way the next run tells you whether the fix actually landed.

the rule that caught it

nextjs-typescript.repo-standards.json

{
  "id": "api-routes-require-api-tests",
  "kind": "diff-required",
  "enforcementLevel": "Guide",
  "match": {
    "if-changed": "app/api/**",
    "then-require": "tests/api/**"
  }
}
veritas readiness — after the fix
$ npx --no @kontourai/veritas readiness --working-tree

veritas: 2 files changed -> app.app, verification.tests
      [ 4 PASS lines trimmed ]
PASS  api-routes-require-api-tests: Changed files
      matched app/api/** and included required
      companion changes under tests/api/**.
      [ 2 PASS lines trimmed ]

0 failures · 0 warnings · run `npx --no @kontourai/veritas
readiness --check evidence` for full generated evidence

The same command, after the missing API test was added. Trimmed for column width where marked.

When you can't meet the rule

The honest path is a first-class one.

Not every requirement can be satisfied on every change, and pretending otherwise just teaches people to route around the tool. An Exception is an authority-backed decision to accept an unmet or failing requirement for a specific change — recorded with its approver, printed in the readiness report as "accepted by exception," never a silent skip.

Attestations can record how authorization was collected — the human's verbatim authorizing words, or the prompt-and-response exchange, with its source when captured. Six months later you can still see what was actually approved, not just that something was.

On this site

We run this on the repo that builds this page.

kontourai.io is itself a Veritas repo. Its standards file, its repo map, and the attestation that protects them are committed under .veritas/ in the public repository, and a readiness run goes out on every pull request. It's advisory here — we haven't promoted it to a merge gate yet.

Below is the unedited output on the working tree this page was written in, on 25 July 2026 — a broad copy pass across the site — including the parts that aren't green.

veritas readiness — kontourai.io
$ npx --no @kontourai/veritas readiness --working-tree

veritas: 16 files changed -> app.src, tooling.scripts
FAIL  evidence-check: npm run validate && npm run test:rendered
      -> Evidence Check command exited with 1
PASS  policy-changes-require-attestation: Active attestation policy-change-2026-07-20T15-16-09-801Z-ec4b45964e32
      matches current protected standards hashes.
PASS  required-veritas-artifacts: All required repository artifacts are present.
WARN  ai-instruction-files-synced: Some AI instruction files are missing the canonical Veritas governance block.
      -> AGENTS.md
PASS  prefer-veritas-routed-delivery: All required repository artifacts are present.
WARN  surface-status: claim "veritas.policy.kontourai-io.kontourai-io-default.ai-instruction-files-synced"
      is DISPUTED (Evidence explicitly reported a non-passing result.)

1 failure · 2 warnings · run `npx --no @kontourai/veritas readiness --check evidence` for full generated evidence
report: .kontourai/veritas/evidence/veritas-1785017124503.json
  · standards feedback draft: .kontourai/veritas/standards-feedback-drafts/veritas-1785017124503.json
  · run: veritas-1785017124503

That run fetched Veritas from the registry. The prompt shows the command this repo runs now that Veritas is installed here; the output is as printed.

The FAIL is real. At the moment of that run, this repo's own verification command exited non-zero because a page existed that public/sitemap.xml didn't list. The first WARN is real too: AGENTS.md had been hand-edited away from the canonical governance block, so the file agents actually read no longer matched what the repo says it should contain. The second warning is the first one following through — the published claim reads as disputed rather than passing.

None of that is Veritas grading itself. Every line names a rule from a file you can open in the public repo, and the report: path is a JSON artifact — the same answer, readable by the next person without re-running anything. A run that only ever comes back green isn't evidence of much.

What Veritas makes possible

01

Define what good looks like

Repo Standards

Capture the repo expectations reviewers keep in their heads: required tests, protected files, shared contracts, release checks, security scans, boundaries, and authority rules.

requirementsevidence-checksauthoritiesguidance
02

Guide work at the moment of change

Change Guidance

When an agent or developer touches a risky work area, Veritas supplies the relevant standards before context drift turns into a bad merge.

work-areasboundarieshooksrecheck
03

Earn merge readiness

Readiness Reports

Every change gets a clear answer: what passed, what failed, what evidence is stale, what needs recheck, and why this change can or cannot merge with reduced human review.

merge-readinessfreshnessexceptionscoverage

Change boundaries

Shared code, clear coordination.

Fast AI development breaks down when several agents and developers touch the same repo without knowing which work areas are independent, protected, or coupled. Veritas makes those boundaries explicit.

A change that stays inside its work area can move quickly. A change that reaches into a marked area has to carry the extra evidence, owner context, or named approval before Veritas will call it ready.

That's how a shared package, a contract, or a generated artifact stays protected without turning every touch of it into a manual-review bottleneck.

Work Area
Where the change belongs
Change Boundary
Where extra coordination begins
Protected Area
Where stronger authority is required
Boundary Crossing
When readiness needs more evidence

Over time

Standards that get sharper the more you ship.

Veritas records what happened after each run — which rules caught something real, which fired on noise, how long a change sat before it went green — and turns that history into concrete suggestions for tightening, relaxing, or retiring a rule. You accept or reject each one; nothing changes your standards on its own.

Standards feedback

Longitudinal tracking of whether each standard helped, got in the way, or needs adjustment — built from real run evidence.

Recommendations

Data-driven suggestions for tightening, relaxing, or retiring standards, accepted or rejected with authority backing.

Marker benchmarking

Deterministic scoring of whether Veritas guidance actually improves agent outcomes, not just whether checks pass.

Claim authoring

Author and manage Surface claims directly from the repo, so readiness state is portable to people, agents, and other systems.

Current CLI

npx --no @kontourai/veritas init --exploreRead the repo and propose a starting set of standards as a plan file — applies nothing
npx --no @kontourai/veritas initBootstrap Repo Standards, Repo Map, and guidance
npx --no @kontourai/veritas readiness --working-treeReport whether the current change meets the repo standards
npx --no @kontourai/veritas explain --file <path>Show only the rules that govern that path
npx --no @kontourai/veritas attest bootstrap --actor <id> --approval-ref <ref>Record who reviewed the protected standards, and the approval behind it
npx --no @kontourai/veritas claim listAuthor and inspect the readiness claims this repo publishes
npx --no @kontourai/veritas feedback summaryReview whether standards are helping across prior runs
npx --no @kontourai/veritas recommendation listReview data-driven standards recommendations
npx --no @kontourai/veritas integrations claude-code installWire the pre-edit hook that stops a write breaking a required rule
npx --no @kontourai/veritas integrations codex installWire the pre-edit hook plus end-of-session feedback — same command shape for cursor and copilot

Try it on your repo

It won't write anything until you say so.

getting started

$ npm install -D @kontourai/veritas

$ npx --no @kontourai/veritas init --explore

--explore reads your repo and proposes a starting set of standards as a plan file — no model calls, no network, nothing written to your source tree. Read it, edit it, then run npx --no @kontourai/veritas init --apply --plan <path> when it looks right.

View on GitHub →Read the docsnpm package

Veritas is built with Surface. Readiness evidence is written in Surface's open format, so another tool can read it without importing Veritas.