Standards & attestation

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).
• Attestation is how each repo measures up to your standards — you read it on Overview → Repositories (in each repo’s detail view).

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 Overview → 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.

Standard vs Drift. An attestation 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 an attestation 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. For admins 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. Members see the row without the enforcement pill — the level is admin-configured, so a member’s read-only view doesn’t display it rather than guess a default.

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 Overview → Repositories.

License is a special case — an SPDX pick, not a sections editor. A license has no section rules to author, so its card doesn’t offer a section editor or author-from-scratch. Instead you adopt an SPDX convention (MIT, Apache-2.0, …) from the same convention picker; attestation then checks that the repo declares that license. The card shows the adopted convention name (e.g. “MIT · SPDX license”) rather than a section count.

Scope — the org sets it, projects and repos add to it

Standards are additive across scopes. The organization sets the standard for a doc type here on the Standards page, and that standard governs every repository. A project or repo can never replace, loosen, or switch off an org standard — the org’s requirement is the floor, always.

What a lower scope can do is add a standard for a doc type that no higher scope already governs:

• A project (initiative) can add a standard for its repositories from its edit drawer: on the Repositories page, open a project in the left organizer and click its edit (pencil) control. The drawer holds the project’s standards + policies (and a Contents area for assigning repos and enrolling sources); add the standard in its Documents required section. Org-admin only.
• A repository can add a standard for itself from its edit-governance drawer, the same “read at a glance, edit in a drawer” pattern projects use: open the repo on the Repositories page — its detail shows a read-only glance of what governs it (policies in force + documents required) — then click Edit governance and add the standard in the drawer’s Documents required section (→ “Add a standard for this repo”). Repo-admins (verified by a live GitHub repo-admin check) get Edit governance; everyone else gets View governance — the same drawer, read-only — so they can still see what governs the repo without being able to change it.

When you add a scoped standard, the picker offers a “Start from” choice: author the sections from scratch, or seed them from a catalog convention (the same conventions the org tab adopts) and edit from there. Either way the standard is saved at your scope through the normal scoped write — seeding just prefills the section editor so you’re not starting from a blank form.

The Policies config page (Standards → Policies) itself is org-only — it sets org-wide policy that every project and repo inherits. Scoped authoring lives on the Repositories page — in the project edit drawer and the repo Edit-governance drawer — next to what it governs.

You can only add a standard for a doc type no ancestor scope already governs. If the org — or a project the repo belongs to — already sets a standard for that doc type, the add is refused: the add picker leaves those doc types out, and a racing attempt gets a plain “another scope already governs this doc type” conflict that never names the ancestor’s standard. This is the additive-only rule — a lower scope adds coverage the org hasn’t, but never coexists with, replaces, or softens an ancestor’s standard for the same doc type. (Two sibling repos may each independently add a standard for the same doc type; the rule is vertical, not horizontal.) It mirrors how Policies rules already work — add-only and stricter-only.

The same rule applies when you add a repo to a project: if the repo already governs a doc type (through its own standard, or another project it’s in) that the project also governs, the membership change is refused with the same conflict — retire one of the two standards first, then add the repo. This keeps a project’s standard from being silently shadowed by a repo’s own the moment you enroll it.

Inherited standards show read-only. Wherever a repo’s or project’s effective standards are listed, a standard that comes from a higher scope appears with its origin chip and an “Inherited from ⟨origin⟩” label instead of an edit control — so it’s always clear which level a requirement comes from. A scope offers edit/remove controls only on the standards it added itself. A scope’s own standard can be edited in place — Edit opens the section editor hydrated with the standard’s real sections (from the repo-/project-scoped read), so saving updates it without wiping its sections — and Remove deletes it (repo and project scopes both have a delete route).

Where an added standard is enforced. A repo- or project-added standard is checked on every scan — it counts toward that repo’s attestation and drives suggestion PRs, exactly like an org standard. Whether it can block a merge, though, stays an org decision: the hekkos/doc-standards gate blocks only for the doc types the org set to Required in its standards config. So a repo-added standard is Advisory — surfaced but non-blocking — unless the org has set that doc type Required, in which case the repo’s own (stricter) shape is what that repo’s PRs are judged against, on that repo only. A repo-admin can make their own repo stricter, but can never mint a merge gate the org didn’t ask for.

Because of that, every standard row at repo/project scope carries a read-only enforcement pill — Required when the org requires that doc type org-wide, otherwise Advisory — instead of the three-way Required/Advisory/Off control. That control lives only on the org Standards page: enforcement is set once, org-wide.

Enforcement level — Required, Advisory, or Off

Every doc type carries one of three levels, shown to admins as a pill on its row on the Standards page and editable there (members see the row without the pill — enforcement is admin-configured):

• Required — 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 Required, 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 attestation immediately rather than waiting.

Whenever a doc type is missing in one or more repos, the row also shows “Missing in N repo(s)” with an Open fix PRs everywhere action (admins). It confirms the scope, then rechecks every repo — a suggestion PR is (re)built in each of the N repos with a gap, while attested repos are left untouched. It’s the paced roll-out: the standing suggestion PRs are bot-authored and rate-limited, so a large estate fans out over time rather than all at once.

Document path — in each doc-type card

Each doc type maps to a file path (e.g. readme → README.md, security → SECURITY.md) so attestation and the merge gate target the right file when a repo doesn’t use the conventional name. That path override lives inside each doc-type card — expand a doc type and set its path right under the enforcement dial, next to the standard it applies to (it used to sit in a separate panel at the bottom). The org value is the default; a repo’s .hekkos.yml doc_paths still wins at scan time.

Variables

Beneath the doc-type list, the Variables panel holds the org-wide values 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.

Attestation — see who measures up (Overview → Repositories)

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

The repositories list is always shown on Overview, directly above the doc suggestions — no expand/collapse toggle. Each repo is one row showing its drift severity, its attestation Gaps count, its open Violations, and its doc-type Coverage, with a link out to the repo on GitHub beside its name. Search the list, or filter it to All, Needs attention, or Clean; an admin gets a per-row Rescan. (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 attestation 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. Because the day-to-day job is acting on findings, the panel leads with the work and folds the context away:

• An interactive stat strip across the top — up to three cards: open findings, documentation coverage, and the most common finding type. Clicking the open-findings or finding-type card filters the findings table below to match and scrolls it into view (an Active filter · Clear chip appears); the coverage card is informational only. It’s triage, never a composite repo “score”.

• Document these first — the highest-impact undocumented surface to tackle, promoted above the findings table. Each ranked item deep-links to the code on GitHub where the file is known. Entities that already carry an in-code doc comment are badged and ranked lower, since a comment already covers them.

• Findings — the repo’s drift, attestation gaps, and violations in one table. A row’s detail modal links out to the relevant code file, doc file, or PR on GitHub. Opening an attestation-gap row routes its primary action to Doc Studio for that repo + doc type — the surface that actually drafts the missing doc — rather than the read-only standard, so a member has a real way to close the gap.

• Governance context — a collapsed disclosure (with counts) holding the read-only “what governs this repo” glance so the findings can sit higher on the page. Expand it for:

  • 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 required — every doc-standard that governs this repo: the org’s, any project’s, and the repo’s own additions (the additive union), each origin-tagged, with inherited ones shown read-only.
  • For admins, the repo’s Ignored folders list (below).

  The full picture — including the Documents applied (platform documents and enrolled References that reach this repo, each with its origin) — opens from the governance drawer (Edit governance / View governance).

The panel’s identity strip at the top carries the repo’s operational controls alongside its name: a scan-status chip (so an errored, held, or scanning repo isn’t mistaken for a clean one), a per-repo Rescan (admin), the exclude/include-from-knowledge-index toggle (admin), and the live Real-State Trust badge with its admin Public badge opt-in and copy-ready README snippet. When the last scan failed, the strip shows the sanitized failure reason so an admin can diagnose and retry it right here — no org-wide Rescan all required. Rescan asks for confirmation before it re-enqueues a full scan, and on a narrow screen the strip’s buttons collapse to icon-only. A repo’s drift-noise controls split across the panel: the concentration nudge sits directly above the findings it explains, while its Ignored folders list lives inside the Governance context accordion. Admin-only affordances are hidden from read-only members. A chip names the repo’s project when it belongs to one (loose repos are already grouped under Not in a project in the list). 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:

• Attested / Org default — good.
• Missing / Sections missing — a required doc or section is absent (this is what a Required level acts on). A failing Required 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 Required type this reads “will enforce when checked” — it is not counted as a failure until a scan confirms it, so setting Required 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 card that isn’t Attested 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 attestation detail — the Overview → Repositories drawer or the repo’s panel on the Repositories page. A waived (repo, doc type):

• drops out of attestation coverage, and
• is never blocked by a Required 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 (including the verbatim expected text for fixed and substituted sections), Scaffold a starting draft, and Validate a draft against the standard. These are read/dry-run only — no LLM call is charged here. All three resolve the repo-effective standard — the one that actually governs that repo (org, initiative, or a repo-scoped override, most-specific wins) — so the format you preview is exactly the spec Validate measures against, and the doc-type list shows only the standards that apply to the selected repo.

When your draft is ready, Open PR with this draft opens a pull request that commits exactly what’s in the editor — your current edited content — to that doc’s path on a dedicated hekkos/doc-studio/<doc type> branch, and links you straight to the PR. It is honestly attributed as your authored draft, not a bot-generated fix, so a reviewer treats it like any contributor’s documentation change. Edit again after opening and the button re-enables so you can open an updated PR. Copy and Download remain for the offline path — saving the markdown locally or pasting it into an existing PR by hand.

This is different from the Fix this button on the Attestation page, which enqueues the bot’s rollout-paced suggestion PR generated from the repo’s measured facts — that one does not carry your Doc Studio draft. Doc Studio’s Open PR with this draft ships your text; Fix this ships the bot’s measured fix.

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 override 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 in the always-visible Doc Suggestions panel on Overview — 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 / Ignore buttons right on its card, so you can record your disposition from the dashboard before the PR even opens — the same two 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 Required 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.