Standards & conformance

Members can view everything here (scoped to the repos they can see); only admins can change standards, set enforcement, or waive a doc type.

Two words carry this whole area:

• A standard is what a good document of a given kind should contain — you set it on the Standards page (Standards → Standards).
• Conformance is how each repo measures up to your standards — you read it on Home → Repositories (and each repo’s detail drawer).

Each lives where it matches what you’re doing: the Standards page is authoring-only — where you define what good docs look like and how strictly to enforce them — and Home → Repositories is where you see and act on how every repo measures up.

Two nouns. Standards (this page) govern your documents — which docs a repo must have and how they’re structured. Rules checked against your code live on the separate Policies page. (Governance can be rolled back via GOVERNANCE_V2_ENABLED=false, which restores the older Doc Requirements / Principles / Policies three-tab layout.)

Standard vs Drift. A conformance gap means a doc doesn’t match the standard you defined. Drift is a separate thing — a doc that no longer matches the code’s real state. They’re checked by different systems and shown separately, and this guide never uses “drift” for a conformance gap.

The Standards page — define a standard

A standard describes what a kind of document (a README, a SECURITY policy, a CONTRIBUTING guide, …) should contain, as a list of expected sections. Hekkos ships a catalogue of sensible conventions you can adopt as-is or customize.

Each doc type is one row on the Standards page. The row shows, at a glance, its enforcement level as a pill (see below); expand it to choose a convention, adopt an editable section standard, and edit sections.

Adopt and customize

1. Go to Standards.
2. Expand a document type (e.g. readme).
3. Pick a convention to start from, then Adopt it as an editable standard — or start from scratch.
4. Each section has a heading and guidance. Add, remove, reorder, or reword sections to match how your org actually writes docs.

Once adopted, every scan checks your repos’ docs of that type against the standard, and the result shows per repo on Home → Repositories.

Set the scope — org, initiative, or repo

A standard doesn’t have to apply everywhere. Above the section editor, the authoring-scope selector sets where the standard you’re editing takes effect:

• Organization — the default; the standard applies to every repository.
• Initiative — the standard applies only to the repositories in that initiative (project).
• Repository — the standard applies to that single repo.

A repository is judged against the most specific standard that reaches it (repo over initiative over org), so a repo can carry a tighter doc requirement than the org default without changing anyone else’s. A scoped standard is tagged with its origin wherever it’s shown, so it’s always clear which level a requirement comes from — see What applies to a repo.

Enforcement level — Blocking, Advisory, or Off

Every doc type carries one of three levels, shown as a pill on its row on the Standards page and editable by admins:

• Blocking — a missing required doc or section fails the PR merge check (hekkos/doc-standards). See Drift & enforcement for exactly what blocks and how to wire it into branch protection.
• Advisory — the doc type is checked and scored, and Hekkos opens a suggestion PR to close gaps, but nothing blocks a merge.
• Off — the doc type isn’t tracked at all.

When you set a type to Blocking, the row shows “Enforces on the next PR · Re-check now” — enforcement takes effect the next time each repo opens or updates a PR that touches that doc, and Re-check now refreshes conformance immediately rather than waiting.

Variables & paths

Beneath the doc-type list, the Variables & paths panel holds two inputs your standards depend on — they live here, next to the standards that use them, rather than buried in Settings:

• Standards variables — org-wide values (e.g. a security contact) that substituted sections weave into generated content. Variables are rendered into committed docs and are visible to anyone who can read the repo — never put a secret here.
• Document paths — the file path each doc type maps to (e.g. readme → README.md, security → SECURITY.md), so conformance and the merge gate target the right file when a repo doesn’t use the conventional name.

Conformance — see who measures up (Home → Repositories)

Conformance no longer lives under the Standards page. It’s folded into Home → Repositories — so seeing who measures up sits right next to acting on it.

Each repo is one row showing its drift severity, its conformance Gaps count, its open Violations, and its doc-type Coverage. Search the list, or filter it to All, Needs attention, or Clean; an admin gets a per-row Rescan and a Re-check all that re-runs every repo against every standard. (Before any standard is adopted the Gaps column stays neutral, and the list points you at adopting one — repos still render their drift and coverage.)

Click any row to open its detail drawer — the per-repo conformance breakdown, one card per doc type. The same required-standards information also appears, alongside everything else that governs the repo, in the unified what-applies-to-a-repo panel on the Repositories page, so the two never disagree. The drawer also carries an Open doc PR banner when a suggestion PR is up for that repo, a View drift → link into the repo’s Drift tab, and the Fix this action (below).

What applies to a repo

Opening a repository on the Repositories page (the nav item, formerly Sources) shows one panel that answers “what governs this repo, and from where?” in a single place instead of across three pages:

• Policies in force — the rule union inherited from the org, every initiative the repo is in, and the repo itself, each row tagged with an origin chip (Org / Initiative / This repo) and a Manage at ⟨level⟩ link to where it’s set.
• Documents applied — the platform documents (and enrolled References) that reach this repo, each with its origin.
• Documents required — the effective doc-standards for this repo (the most-specific scope wins), each origin-tagged.
• Findings — the repo’s drift, conformance gaps, and violations in one table.
• Document these first — the highest-impact undocumented surface to tackle.

An identity chip at the top names the repo’s project (or Not in a project). This unified view is the “see” side of the same scopes you set here and on the Policies page.

Per doc type, each card shows a status:

• Conformant / Org default — good.
• Missing / Sections missing — a required doc or section is absent (this is what a Blocking level acts on). A failing Blocking doc type is flagged with a red would block badge, since its gap fails the next PR’s hekkos/doc-standards check.
• Off-standard — the doc exists but has diverged from the standard.
• Stale — a derived section is out of date.
• Unchecked — not checked yet. For a Blocking type this reads “will enforce when checked” — it is not counted as a failure until a scan confirms it, so setting Blocking never retroactively blocks in-flight PRs.
• Paused — Hekkos repeatedly had this doc type’s suggestion closed, so it stopped re-proposing it; it resumes automatically (or an admin clicks Resume).

Fix a gap in one click

Every non-conformant card has a Fix this button (members included). It enqueues the bot-authored suggestion PR that closes the repo’s gaps — the same paced machinery a scan uses, so under a throttled rollout pace it shows Queued and opens when the window elapses. Draft (below) remains the manual authoring path.

Waive a doc type that doesn’t apply

Some repos legitimately don’t need a doc type — a package with no public API needs no API doc. An admin can waive a doc type for a repo (Not applicable, with an optional reason) from its conformance detail — the Home → Repositories drawer or the repo’s panel on the Repositories page. A waived (repo, doc type):

• drops out of the conformance score, and
• is never blocked by a Blocking level.

Waiving is the honest per-repo escape valve — use it instead of turning a doc type Off for the whole org, and instead of dismissing the same PR forever.

Doc Studio — author and preview

Doc Studio is the interactive authoring loop. For a chosen repo + doc type you can See the format, Scaffold a starting draft, and Validate a draft against the standard. These are read/dry-run only — no LLM call is charged here. When you’re ready to ship, Open a suggestion PR (the same action as Fix this) turns your draft into a reviewable PR.

Suggestion PRs

When a scan (or Fix this) finds a doc that’s missing or off-standard, Hekkos opens a PR on that repo with the concrete change — a new file, or edits that add the missing sections, grounded in facts it extracted from the repo.

Where each section came from

Every suggestion PR states its provenance up front. The body leads with a one-line headline naming the dominant source — all sections assembled from your org standard v3, …from the Hekkos catalog, or written by Hekkos for this repo, grounded in its detected facts — and any section whose source differs is annotated individually. Each proposed file is shown collapsed with a one-line note, and a licensing change surfaces a visible “License — decision needed” section rather than burying it in a diff.

Review, merge, dismiss

• Merge it like any PR — the fix is already written.

• Dismiss a suggestion you don’t want by commenting on the PR:

  /hekkos dismiss not relevant — this is an internal tool

  Hekkos records the dismissal and clears its status check. Dismissing the doc-standards merge gate specifically requires repo write access and its own token — see Drift & enforcement.

You can see your org’s suggestions on the Suggestions tab of Home (the Doc Suggestions panel) — open ones (a PR is up) and queued ones (waiting under your rollout pace) — and a repo’s own suggestions surface in its panel on the Repositories page. A queued suggestion carries the same Accept / Dismiss / Ignore buttons right on its card, so you can record your disposition from the dashboard before the PR even opens — the same three verbs, recorded to the same outcome log, as everywhere else in Hekkos.

Polyglot monorepos get the right variant per subtree. When a repo holds more than one stack — say a Go service under services/api and a React app under web/ — Hekkos detects the stack per directory and picks each doc’s convention variant from the stack that actually governs that doc’s location, rather than forcing one repo-wide guess on everything.

Per-repo overrides with .hekkos.yml

A repo can carry a .hekkos.yml at its root:

doc_paths:
  readme: docs/README.md          # this repo keeps its README somewhere else
exclude_from_knowledge: false     # keep this repo out of chat retrieval if true

A repo may tighten enforcement but never relax an org Blocking level — org policy always wins, so a one-line repo edit can’t escape a mandate. To stop enforcing a doc type for a specific repo, waive it (above).

Rollout pace — how fast suggestion PRs open

How quickly suggestion PRs open across your repos is your org’s rollout pace, set in the wizard and changeable in Settings:

• Pilot first (default) — opens PRs for up to 5 repos immediately; the rest open after 48h.
• All at once — opens every suggestion PR immediately.
• Throttled — opens at most N PRs/day until the backlog clears.

Code checks — turn on ready-made policies for your code

Standards keep your docs honest. The Library (the Library sub-view of the Policies page) does the same for your code: ready-made checks that flag risky patterns — weak crypto, a tenant route with no auth guard, plaintext http:// — as violations you can see and act on. You don’t write anything to start: it opens on a catalogue of ready-made checks you turn on.

Members can view the catalogue and violations; only admins turn checks on or off.

Turn one on

1. Go to Policies → Library.
2. Under Recommended for you, each card is a check — its name, a plain-English description, and how serious it is. The recommended ones (weak hashes like MD5/ SHA-1, weak ciphers like DES/RC4) need no setup. A language-specific check also shows a small Recommended for Go, Python hint naming the stacks its extraction fully covers — Hekkos recommends, it never auto-enables, so turning a check on is always your call.
3. Flip a card’s toggle on. That’s it — the check runs on your next scan and any matches show up as violations (on the card’s count and in chat when you ask about your code). Flip it off to stop.

Enable all recommended. An admin can turn on every recommended check that needs no configuration in one click, from the Enable all recommended button by the section heading — the parameterized ones (those that need a detail from you) are left for you to fill in. The rest of the catalogue is grouped by category (security, tenancy, …) so a long list stays scannable.

Some checks need one detail from you — for example “tenant routes must be guarded by your auth middleware” asks for the middleware’s name before it turns on. The card prompts for exactly what it needs.

Where do these come from? The recommended crypto/hash/transport checks work on Go repos out of the box. Covering the same patterns in JavaScript/TypeScript, Python, Ruby, and Java needs the optional cross-language scanner your operator enables — until then those checks simply find nothing on non-Go repos rather than misreporting.

Write your own (advanced)

Below the catalogue, Your custom rules is for anything the presets don’t cover. Write a custom rule (or Customize a preset to start from it) opens an editor where a rule is a short expression over your code’s structure, with a dry-run preview (“this would flag N across M repos”) before you save. This is the power-user path — you never need it to get value from the recommended checks.

Principle vs Standard vs Drift. A principle is a rule about your code; a standard is a rule about a document; drift is a doc that no longer matches the code. Three different checks, shown separately.