Concepts

For anyone in the org.

This page is the canonical vocabulary — the shared reference every other guide, the app, and the bot draw their words from. The handful of terms below are each in plain language, with a link to the guide that covers it in full.

Two nouns, one unit. Governance has exactly two nouns — Standards govern your documents, Policies govern your code — and one unit of each: a section (of a doc) and a rule (of code). Everything else you might read elsewhere (principle, convention, check) is a synonym for rule. Trust is reported as a number, never a “score”.

Plan tier

The plan your org is on — Free or the paid plan. It sets your monthly usage limits and which retrieval mode chat uses. The paid plan is split into repo-count bands (below), and above the top band sits an operator-only Enterprise tier (unlimited repos, arranged with whoever operates your deployment — never self-serve). See Plans, usage & your account.

Plan band

Which repo-count band a paid org is on — Starter, Growth, or Scale (25 / 100 / 500 repositories at the launch defaults). The band modulates your repository cap and your included monthly token budget (the launch defaults scale the budget 5M / 20M / 100M with the band, so bigger bands get proportionally more headroom); only the operation budgets (documents standardized, questions answered) are shared across all paid bands. It’s tracked separately from the plan tier, so a band value never changes whether your org counts as paid — it only sets how many repos you may keep governed. You switch bands, up or down, through the Stripe customer portal. See Plans, usage & your account.

Retrieval mode

How chat finds the material it answers from: keyword (matches the same words as your question — the Free plan) or semantic (matches the meaning and writes a cited AI answer — the Team plan). See Ask Hekkos & MCP.

Model role

The job an LLM call is doing. The classifier role handles the cheap, high-volume yes/no checks; the writer roles produce user-facing prose — doc sections, gap suggestions, and chat answers. See LLM keys & providers.

Authority tier

How much a document is trusted as a statement of current state: canonical (the document of record), reference (counts as coverage, warnings only), historical (kept for lineage, raises no drift), or ignored (never ingested). See Drift & enforcement.

Suggestion PR

The pull request Hekkos opens when a doc is missing or off-standard, with the fix already written. You review and merge it like any PR — or dismiss it. See Standards & attestation.

Real state

What your code actually contains — the routes, env vars, functions, types, and CLI flags Hekkos extracts by scanning your repos. Docs and chat answers are checked against it.

Trust

The org-wide headline number for how well your docs hold up — Trust = Coverage × Accuracy. It leads Overview as the Real-State Trust card — a ring with its Coverage × Accuracy factor meters and a Trust over time trend — and is decomposed again on Insights. Principle and advisory violations are deliberately kept out of it. See Drift & enforcement and Standards & attestation.

Coverage

How much is documented — measured two different ways, so the guides name them distinctly:

• Doc-type coverage — per repo: how many of the doc types your standards expect are actually present. It’s the Coverage column on Overview → Repositories.
• Real-State Coverage — org-wide: how much of your extracted real state (routes, env vars, functions, …) is documented at all. It’s one of the bars on Insights, and a factor in Trust. Documentation can live either in your knowledge base or as an in-code doc comment on the symbol itself (a godoc block, JSDoc, docstring, Javadoc, rustdoc, or Ruby #) — the two are tracked as labeled axes (documented_external and documented_in_code), and the Real-State Trust card shows the split. An in-code comment earns coverage credit only when it makes a bindable, mechanically-checkable claim — a typed signature, a route, an env var — not merely by existing: a content-free comment like “handles the request” is unfalsifiable, so it counts the same as no comment at all (Coverage credits claims, not presence). A docstring generator that stamps the same templated comment on every symbol earns no credit either — even when the template does restate a signature: Hekkos hashes each comment’s shape (with the symbol’s own name stripped out), and a template repeated across many symbols in a repo is treated as boilerplate, not documentation. A comment Hekkos can prove wrong — a stale_comment found by a deterministic check (its typed signature no longer matches, or it references a symbol/env var that no longer exists) — scores below an undocumented symbol: a proven-wrong doc is worse than no doc, so it loses its Coverage credit and counts against Accuracy. Only the separate, low-confidence AI comment-rot guess never moves the headline number.

Drift

When a doc’s claims no longer match the code’s real state. Distinct from a attestation gap (which is about the standard, not the code) — Hekkos never spells drift as an attestation status. See Drift & enforcement.

Standard

What a good document of a given kind should contain — a per-doc-type list of expected sections you define on the Standards page (Standards → Standards). Standards are additive across scopes: the organization sets the standard for a doc type, and a project or repository can add a standard for a doc type no higher scope governs — but can never replace, loosen, or switch off an org or project one. Each standard also carries an enforcement level: Required (a missing required doc or section fails the PR merge check), Advisory (checked and suggested, never blocks), or Off (not tracked); a repo- or project-added standard can only block a merge when the org has set that doc type Required. See Standards & attestation.

Attestation

How closely a repo’s docs match the standards your org defines — the read side of standards, shown per repo on Overview → Repositories (and each repo’s detail drawer). A doc type’s status is attested, missing/sections missing (what a Required level acts on), off-standard (the doc exists but diverged from the standard), stale, or unchecked. See Standards & attestation.

Violations

Findings where your code — not its docs — is at fault, listed on Overview → Violations. Two lenses: principle (the code breaks a rule you declared) and advisory (a known-bad practice even when code and docs agree). Distinct from drift, and kept out of the Trust number. See Drift & enforcement.

Policies

Rules checked against your code — the second of Hekkos’s two governance nouns (Standards govern your documents; Policies govern your code). They live on the Policies page (Standards → Policies) and come through two doors into one rule engine:

• Your policies — rules extracted from your own written standards documents (a security policy, an architecture guide, a wiki page). You attach a document at a scope (Organization, Initiative, or Repository), review the extracted rule candidates, and apply only the ones you choose.
• Library — a catalogue of ready-made code checks (weak crypto, weak TLS versions, an unguarded tenant route, plaintext http://) you turn on without authoring anything. It’s the Library sub-view of the Policies page (the catalogue formerly shown as a separate Principles tab).

Every policy rule starts advisory — it surfaces as a violation but never blocks — until an org admin opts it in; a deterministic rule can then be set Required to gate a merge. See Policies.

Initiative (project)

An admin-assigned set of repositories — a department’s platform, a product line — shown as a “project” in the left organizer of the Repositories page (there is no separate Projects page). A repository can belong to several initiatives, or to none (it then sits in the Not in a project bucket). Standards, policies, and documents attached to an initiative apply to every repository in it. See what applies here.

What applies here

The rule Hekkos uses to decide what governs any given repository: it’s judged against the union of everything attached at the org, at every initiative it belongs to, and at the repo itself (org ∪ initiatives ∪ repo). Every applied rule, document, and required standard is tagged with an origin — Org, an Initiative, or This repo — with a Manage at ⟨level⟩ link that jumps to where the requirement is set. When the same rule is attached at more than one scope the effective view collapses it to one row, and the stricter severity wins — a laxer scope can never soften a stricter one. Open a repository on the Repositories page to see its full “what applies here” panel. See Policies.

Waiver

A per-repo, per-doc-type “not applicable” — a repo that legitimately doesn’t need a doc type (e.g. no public API → no API doc). A waived doc type drops out of attestation coverage and is never blocked by a Required level. Set by an admin from a repo’s attestation detail. See Standards & attestation.