agent-claims (public)

A versioned ledger of small, testable technical claims that an agent (or a human) can reference across code, commentary, and posts. Each claim is one atomic assertion with an evidence state, provenance, and a version scope. This repository holds only non-sensitive, generalizable claims.

The design is modeled on the "claims" that agents.stackoverflow.com extracts from a post: an atomic assertion, a role, a status, and provenance. We keep the same shape and add what a long-lived local ledger needs: a version scope, a re-verify trigger, and supersession history. Git history is the lifecycle log: a status change is a commit, git blame gives per-claim provenance, and supersession is a diff.

Why this exists

• One durable, reviewable source of truth for facts we keep re-deriving.
• Reference a claim by id from a code comment, a PR review, a blog post, or a SOFA reply instead of restating it (restating is how versions drift apart).
• The claim's status drives how confidently we state it: an untested claim is presented as a hypothesis, a verified claim can be stated plainly. Confidence tracks evidence, mechanically.

Layout

claims/<domain>/<slug>.md   one claim per file (YAML frontmatter + rationale)
schema/claim.schema.json    the frontmatter contract
tools/lint_claims.py        stdlib-only validator (also the CI gate)

Claim shape

See schema/claim.schema.json for the full contract. Required frontmatter fields: id, role, status, status_provenance, visibility, domains, context_scope, evidence, created, superseded_by. See CONTRIBUTING.md for the field meanings and the lifecycle.

Validate locally

python tools/lint_claims.py --root claims --public

Public mode enforces visibility: public and scans for internal terms. The denylist of internal terms is not committed here (that would leak the names it guards); supply it with --denylist <file> or the AGENT_CLAIMS_DENYLIST environment variable, sourced from a CI secret.

Scope

Only non-sensitive, generalizable claims belong here. A claim that would expose private infrastructure, internal architecture, or proprietary details must not be published; keep those in a private, access-controlled location and publish only a sanitized, generalized version. The linter's denylist scan is a backstop, not the only control.

Continuous integration

.forgejo/workflows/lint-claims.yml runs the linter in public mode on every push and pull request to main and dev. It requires a Forgejo Actions runner registered for this repository. The internal-term scan is enabled when the AGENT_CLAIMS_DENYLIST repository secret is set (its content is the denylist of sensitive terms); without it, structural validation still runs and the scan is skipped with a warning.