Valinor - Self-enforcing engineering discipline.

claims.yml is how your repo declares the quality claims it must satisfy — a list of human-readable invariants, each backed by a deterministic check Valinor runs in CI. valinor claims-verify reads the file, runs every check, prints one line per claim, and exits non-zero on any drift. This is the mechanism that turns "we keep our docs in sync" from a promise into a gate: you write the claim, attach a check, and CI proves it on every PR.

A claim is most valuable when its check pins the idea against erosion — a grep for a load-bearing phrase, a file presence assertion, a token equality — so a future change that quietly breaks the invariant fails the build with the claim's id in the output.

The claim format

This inventory is a projection of the source of truth — it is generated directly from the Claim and Check schemas in src/claims/schema.ts, so it lists every claim field and every check type with its fields, and can never silently fall behind the code. (The site-freshness gate fails the build if this drifts from the schema.)

Generated — do not hand-edit

The tables below are regenerated by npm run gen:claims-reference. Edit a field or check-type summary in src/siteGen/claimsReference.ts (its single authoritative home), not here.

Claim fields

Every entry in claims.yml is a claim with these fields:

Field	Type	Default	What it does
`id` (required)	string	—	A stable, unique slug for the claim — referenced in CI output and never reused.
`claim` (required)	string	—	The human-readable invariant this entry asserts (what must be true of the repo).
`source_of_truth`	string	—	The authoritative home of the fact, when one file owns it (informational; points a reader at it).
`check` (required)	one of the check types	—	The deterministic check that verifies the claim — one of the check types below (discriminated by `type`).
`owner`	string	—	Who owns keeping the claim true (optional).
`last_verified`	string	—	When the claim was last manually confirmed (optional; for claims a check can only partly cover).

Check types

The check field is one of these types, discriminated by type:

`file`

Assert a path exists (or, with exists: false, is absent).

Field	Type	Default	What it does
`type` (required)	literal `"file"`	—	The discriminator — the literal `"file"`.
`path` (required)	string	—	The repo-relative path that must exist (or be absent).
`exists`	boolean	`true`	Whether the path must exist (`true`) or be absent (`false`).

`grep`

Assert a regex pattern is present (or absent) in a file.

Field	Type	Default	What it does
`type` (required)	literal `"grep"`	—	The discriminator — the literal `"grep"`.
`file` (required)	string	—	The file to scan.
`pattern` (required)	string	—	The regex pattern to match.
`expect`	`present` \| `absent`	`"present"`	Whether the pattern must be `present` or `absent`.

`token`

Assert a structured key in a file equals an expected value (e.g. a YAML/JSON scalar).

Field	Type	Default	What it does
`type` (required)	literal `"token"`	—	The discriminator — the literal `"token"`.
`file` (required)	string	—	The file carrying the structured value.
`key` (required)	string	—	The key/path to the value within the file.
`equals` (required)	string	—	The expected value the key must equal.

`gh-api`

Assert a JSON-pointer into a GitHub API response equals an expected value.

Field	Type	Default	What it does
`type` (required)	literal `"gh-api"`	—	The discriminator — the literal `"gh-api"`.
`endpoint` (required)	string	—	The GitHub API endpoint to call.
`pointer` (required)	string	—	The JSON pointer into the response.
`equals` (required)	union	—	The expected value at the pointer (string, number, or boolean).

`files-identical`

Assert two files are byte-identical (e.g. a propagated copy matches its source).

Field	Type	Default	What it does
`type` (required)	literal `"files-identical"`	—	The discriminator — the literal `"files-identical"`.
`fileA` (required)	string	—	The first file to compare.
`fileB` (required)	string	—	The second file to compare.

An example claim

A claim pinning that a load-bearing doctrine phrase stays in its rubric dossier:

- id: site-freshness-cli-reference-projection
  claim: "The help-center CLI reference's command inventory is a generate-from-source PROJECTION of the src/cli.ts registry, drift-gated by site-freshness"
  source_of_truth: docs/rubrics/site-freshness.md
  check: { type: grep, file: "docs/rubrics/site-freshness.md", pattern: "CLI-reference regenerate-diff", expect: present }

The id is referenced in CI output, the claim states the invariant in prose, the source_of_truth points a reader at the authoritative home, and the check is the deterministic proof — here a grep asserting the phrase is present in the rubric. When you want to verify a structured value instead of a substring, reach for token; for two-file byte-identity (a propagated copy matching its source), files-identical; for a live GitHub setting, gh-api.