Concepts

The Standard

Your Standard is the quality contract every agent answers to — one versioned, shared YAML file compiled from your real codebase, and the place to change what Verity enforces.

The Standard lives at .verity/standard.yaml. It is committed to your repository and uploaded to the service, and every review is measured against it. Because it is shared and versioned, every agent — on every machine, in every session — is held to the same bar, instead of a CLAUDE.md copy drifting on someone's laptop. And unlike instructions to the agent, it is enforced by a reviewer the agent cannot talk out of it.

What is in it

SectionPurpose
knowledge_specProject metadata — name, languages, frameworks, architecture, build system, test framework.
extendsThe review packs the Standard uses, such as verity/core. The packs bring their rules. The file holds no copy of them.
overridesChanges to pack rules: turn one off, or change its severity.
quality_dimensionsThe four quality lenses and their thresholds. With extends, only the ones your team changed.
security_patternsSecurity patterns, each with a severity. With extends, only your team's own. The packs bring the rest.
custom_patternsYour project's own rules — the ones the service writes from the repository profile, and as many as you add.
process_constraintsHow the review behaves: limits, budgets, exclusions, model choices.
tool_configurationThe static-analysis tool. Static analysis is Trivy only, so this names Trivy.

Quality dimensions

Every review checks four quality dimensions. A Standard that names review packs gets these defaults without listing them.

Dimension (id)What it checksDefault signals
Comprehensibility (comprehensibility)Code you can read in one context load.File length (300 lines), cyclomatic complexity (15 per function), function length (50 lines), naming quality.
Modularity (modularity)One concern changes without touching 3 or more files.Single responsibility, shallow abstractions.
Type safety (type_safety)The type system catches errors before runtime.None by default. Add your language's, such as strict mode or explicit return types.
Test adequacy (test_adequacy)Tests define the expected behavior for agents.Coverage (80%, or 90% for AI-written code) and test quality.

Each signal names its threshold, its unit and why it is set there. To change a dimension, add an entry with the same id to quality_dimensions. Your entry replaces the default as a whole, so list every signal you want to keep. To drop a dimension, turn it off in overrides.

.verity/standard.yaml
quality_dimensions:
  - id: comprehensibility        # replaces the default with this id
    description: Code readable in one context load
    signals:
      - metric: file_length
        threshold: 400
        unit: lines
      - metric: cyclomatic_complexity
        threshold: 15
        unit: per_function
overrides:
  type_safety: off               # drops a default dimension

Security patterns

Security rules come from the review packs. verity/core, which every Standard gets, holds these:

Rule (id)SeverityMaps to
Injection into an interpreter (injection-into-interpreter): SQL, shell, eval, templates, deserialization, XMLCriticalCWE-89, 78, 94, 502, 611
No hardcoded secrets (no-hardcoded-secrets)CriticalCWE-798
Object-level authorization (object-level-authz)HighCWE-639, 862
Function-level authorization (function-level-authz)HighCWE-285, 862, 269
Checks fail closed (fail-closed-checks)HighCWE-636, 755
Secrets and personal data in logs (secrets-and-pii-in-logs)HighCWE-532, 359
Dependency verification (dependency-verification)HighCWE-1395
Configuration file integrity (config-file-integrity)HighCWE-15
Signed data integrity (signed-data-integrity)HighCWE-347, 208
Cross-request leak (cross-request-leak)HighCWE-488, 524, 668
Prototype pollution (prototype-pollution)HighCWE-1321
Canonical comparison (canonical-compare)HighCWE-178, 1289, 41

The API, CLI and Web packs add rules for their kind of project: output escaping, path containment, outbound URLs, mass assignment, subprocesses and regular expressions. See every rule, with examples, or run verity standard catalogue core.

Static analysis (Trivy) also checks for secrets and vulnerable dependencies. Put your team's own security rules in security_patterns. An own rule with a catalogue id replaces the catalogue rule.

Standards written before 0.35
An older Standard holds a copy of seven patterns: no hardcoded secrets (CWE-798), input sanitization (CWE-20/80/89/117), parameterized queries (CWE-89), dependency verification (CWE-1395), no unsafe deserialization (CWE-502), access-control checks (CWE-639) and config-file integrity (CWE-15). It keeps that copy until it moves to packs: see Standards written before review packs.

Custom patterns — and their scope

These are the conventions a reviewer would otherwise have to learn by hand — “all API routes go through the auth middleware”, “every Supabase table has an RLS policy”. The service can write them for you (Project rules), and you can add your own. The important part is the scope prose: a pattern's rationale and any note on its enforcement reach the reviewer verbatim and bind it, so a rule that says where it applies is applied only there.

.verity/standard.yaml
custom_patterns:
  - id: validate-at-boundaries
    description: "Validate input at system boundaries"
    severity: high
    enforced_by: []   # AI-only
    rationale: >
      Applies to user input, external APIs (Plaid, Stripe, Auth0) and
      webhook payloads only. Internal service-to-service calls and the
      k6 load-test scripts under perf/ are out of scope.

A rule with no scope is applied everywhere, which is how a load-test script ends up blocking a push. If the same class of finding keeps being disputed or waived, narrow the rule here rather than answering it every time.

Review packs

A Standard names review packs in extends instead of copying rules into the file. A pack is a set of rules for one kind of project. The service expands the packs when it reviews, so your file stays short. When the catalogue changes, every Standard that names the pack gets the change, with no edit to your file.

.verity/standard.yaml
extends:
  - verity/core
  - verity/agent-behavior
  - verity/api
overrides:
  rate-limit-on-costly-routes: off       # drop one pack rule
  check-then-act: { severity: medium }   # change a pack rule's severity
custom_patterns:
  - id: validate-at-boundaries
    # … your own rules, as before
  • verity/core and verity/agent-behavior are for every project. The others — api, data, cli, payments and web — are for the projects that need them.
  • verity init picks the packs from what it sees in the repository: languages, frameworks, dependencies, paths, and whether the repository ships a CLI. It reads these on your machine and sends nothing. It prints the packs it chose. Without sign-in, init writes the older full copy instead.
  • overrides changes a pack rule: off drops it, and { severity: high } changes its severity.
  • Your own rule wins. A rule in security_patterns or custom_patterns with the same id as a pack rule replaces the pack rule.
  • A reference can name a catalogue version, such as verity/core@2026.11. The service has one catalogue today. When the version is not that one, the review uses the current catalogue, and verity standard get --resolved says so.
  • The service refuses a pack name it does not know, so a typo cannot drop a pack without a word.

To see what each pack holds, and how a review reads your Standard:

verity standard catalogue          # every pack, with ✓ on the ones your Standard extends
verity standard catalogue api      # the rules of one pack, with their rule text
verity standard get --resolved     # your Standard as a review reads it, with the packs expanded

The review packs page lists every pack and every rule, with an example of code that breaks it and code that does not.

Standards written before review packs

An older Standard holds a copy of the old template. It keeps working as it is. The next time it is written to the service — by verity standard push, for example — the service stores it as review packs:

  • A rule that is still the template's copy becomes a pack reference.
  • A rule your team edited stays as you wrote it.
  • A rule your team removed stays off, as an overrides entry. Where the pack splits that rule into several new rules, the new rules stay on until a person decides.
  • Your custom_patterns, knowledge_spec and process_constraints do not change.

The CLI prints one line when this happens, and verity standard history marks the version +verity-catalogue:

verity standard push
Standard uploaded (version 7)
The service stored this Standard as review packs (core, agent-behavior, api): 9 patterns now come from the packs, 1 you edited stays as you wrote it, 1 you removed stays off. To undo: set process_constraints.catalogue_conversion: off and push the previous version.
.verity/standard.yaml now holds the stored version (v7). The file you pushed is kept as .verity/standard.2026-10-30T10-12-03-456Z.yaml.

To keep the old format:

  1. Copy the file the CLI kept back over .verity/standard.yaml.
  2. Add catalogue_conversion: off under process_constraints.
  3. Run verity standard push. The service stores the file as written.

To start over instead, run verity init --standard new (CLI 0.35.2 and later). Init sets your file aside — a copy goes to .verity/standard.<time>.yaml — and builds a new Standard with review packs and, if you send the repository profile, project rules. It becomes the team's next version. Your team's own rules are not carried over: copy any you want to keep from the copy into custom_patterns, then run verity standard push.

Process constraints

The knobs that change how the review behaves. All optional; the defaults are what setup writes.

KeyDefaultWhat it does
self_healing_limit2Fix-and-recheck attempts per problem before the gate defers to you.
exclude_pathsbuild output, depsPaths whose findings are demoted to pre-existing rather than blocking. See Findings & verdicts for how it interacts with .verityignore.
specsrelevance-basedalways or never: whether project spec documents ride along as the intent rubric. By default they do when the session actually read them, or in plan mode.
intent_warn_threshold / intent_fail_threshold7 / 4Intent-alignment scores (out of 10) at or below which the gap is flagged. An intent gap on its own never blocks.
git_moment_model / git_moment_reasoning_efforta stronger model, mediumThe reviewer used at commit and push. See Moments.
compound_enabledtrueMaster switch for the knowledge system: the graph, the extractor, and feedback suppressions.
memory_graph_enabledtrueUse the 8-domain graph; false falls back to flat lessons.
memory_graph_budget_tokens2000Tokens of knowledge injected into the reviewer's prompt.
knowledge_injection_budget_tokens2000Tokens of knowledge injected into your agent's context when you submit a prompt.
finding_autosuppress_threshold2False-positive votes on a pattern at a site before it is auto-suppressed for the project.
catalogue_conversionunsetoff stops the service from storing this Standard as review packs when it is written.

How it is created

You do not write the Standard by hand. verity init gets it in one of these ways:

  • Your team's Standard. If the repository already has one on Verity, init offers it, and Enter uses it. Init never pushes a Standard over the team's without that choice: its push holds only if the service still has the version init saw.
  • A new Standard. If there is none, or you choose to create a new one, init builds it from the review packs that fit your repository. It then asks whether to send a repository profile, so the service can add project rules. Without the profile, the Standard has the packs and no project rules.

verity standard synthesize builds a Standard from the codebase on demand, with no model. It writes the full copy of the template, which the service stores as review packs when you push it. The research-backed patterns catalog it draws on ships with the CLI at .claude/skills/verity-setup/patterns-reference.yaml. See the Quickstart.

Project rules

Project rules are the ones only your repository has. The service writes them from a profile of the repository, never from its code:

  1. Init writes the profile to .verity/repo-profile.json, so you can read it first.
  2. Init asks before it sends anything. --yes sends nothing unless you add --profile send.
  3. The service writes rules for this repository into custom_patterns, and stores the result as the next version, with created_by: verity-generate. Init prints each rule: its id, one sentence, where it applies and why.

Security & privacy lists what the profile holds. A repository with very little history and no CLAUDE.md or AGENTS.md gets no question: there is too little to write rules from.

If you skipped the profile, verity standard generate does the same later. It works when the service has no Standard for the project, or when .verity/standard.yaml is your team's latest version. It adds the rules to that version and stores the next one.

Review the rules it writes
The service saw the profile, not the code, so a rule can name the wrong scope or a convention the code does not follow. Read them in .verity/standard.yaml, remove any that do not fit, and push the change. /verity-setup in Claude Code checks each one against the code for you.

Editing and versioning

The Standard is yours to tune, from the file or from the dashboard. Edit .verity/standard.yaml and push it — the service assigns the next version and keeps the full history, append-only, so nothing is ever overwritten:

# edit .verity/standard.yaml, then:
verity standard push

# write the team's latest version into .verity/standard.yaml:
verity standard pull

# what's live, a specific version, or the whole history:
verity standard get
verity standard get --version 3
verity standard get --resolved
verity standard history
  • verity standard push checks the file on your machine first. A file that is not valid YAML, or that the service would refuse, is not sent. The CLI says why. The file must be a regular file inside the repository.
  • verity standard pull writes the service's latest Standard into .verity/standard.yaml. It first keeps a copy of your file as .verity/standard.<time>.yaml.
  • Your own fields stay. A field that Verity does not read is kept as you wrote it, at every level of the Standard.

Two editors change the same Standard without the file: the Standard page on the web (Standards on the web) and verity standard edit in a terminal (The terminal editor). Each save is a new version too. Every run records the version it was judged against, so a verdict is always traceable to the exact bar it was held to — and changing the bar never rewrites history.

A repository's Standard can build on top of its org's Standard, and the org can make rules mandatory. See Org Standards.

Changing the Standard is a change worth reviewing
The file is code. Edit it on a branch, let the gate see the diff, and review it in a pull request like anything else. The gate treats an edit to exclude_paths the way it treats an edit to .verityignore: the new fence does not apply to the session that wrote it.
The service holds it
Every review reads the Standard from the service, so a teammate uses a new version from their next review, with nothing to pull. .verity/standard.yaml is this machine's copy, for reading and editing. See Files & configuration.

The local copy stays current

At a session start, Verity reads the version of the team's Standard. When it moved, and your file is missing or is still the version this machine last saw, Verity pulls the new version: it writes .verity/standard.yaml (and keeps the old file as .verity/standard.<time>.yaml), writes VERITY.md again, and creates .verityignore when the team's Standard has exclusions and the repository has none. It never replaces an existing .verityignore. The agent is told what changed before its first turn.

  • When your file has local edits, Verity leaves it and tells you to run verity standard pull.
  • Each request waits at most 3 seconds, and the pull at most 5. A failure never stops the session.
  • At a commit or a push, Verity only reads the version (at most 3 seconds) and prints one line when your copy is behind. It never writes a file in a git hook.
One local copy per machine
The org Standard has no local file. Reviews read it from the service.