Policies

Ce contenu n’est pas encore disponible dans votre langue.

For org admins and repo admins. Members can view everything here (scoped to the repos they can see); only admins can attach documents, extract rules, or opt a rule in or out.

Policies turns your org’s written standards — a security policy, an architecture guide, a “how we build things” wiki page — into conformance rules checked against your code. You attach a standards document at a scope, extract advisory rules from it, then opt each rule in or out. It lives under Standards → Policies.

Standards vs Policies — the two nouns

Two surfaces under Standards sound similar and do different jobs — keep them straight:

Standards (Standards → Standards) — which documents each repo must have and how they’re structured (a README with these sections, a SECURITY policy, …). See Standards & conformance.
Policies (Standards → Policies) — rules checked against your code. This page.

Where Standards govern your documents, Policies govern your code. The Policies page has two sub-views, reached from the sub-nav at the top:

Your policies — rules extracted from your own written standards documents: it mines the checks that are specific to your org out of the prose you already wrote. This is the default view and what most of this guide covers.
Library — a catalogue of ready-made code checks you turn on from a list (weak crypto, an unguarded tenant route, plaintext http://). You author nothing to start. (This catalogue used to be a separate Principles tab; it now lives here as a sub-view.)

Both sub-views produce rules that surface as violations and, when an admin opts one in, can gate merges. They’re two doors into the same rule engine.

(Governance can be rolled back via GOVERNANCE_V2_ENABLED=false, which restores the older three-tab layout; the default is the two-noun experience described here.)

The scope tree — Organization, Initiative, Repository

The left rail is a three-level scope tree. Everything you do on the page — attaching a document, extracting rules, opting rules in — happens at whichever node you’ve selected:

Organization — the root. Documents and rules here apply to every repository.
Initiative — a named group of repositories (a department’s platform, a product line). You create initiatives and assign their repositories right here on the tree. Documents and rules attached to an initiative apply only to the repos in it.
Repository — a single repo. Repos that belong to an initiative appear under it; a repo that’s in no initiative hangs directly off Organization.

A repository is always judged against its inherited scopes plus its own:

A repo outside any initiative adheres to the Org documents (plus its own).
A repo inside an initiative adheres to the Org documents, that initiative’s documents, and its own.

Add a standards document

Select a scope node, then use Add document ▾. The document attaches to the selected scope — you don’t pick the scope again. There are three ways in:

Upload a file — a Markdown or text file (.md, .txt), up to 1 MB.
Write inline — give the document a title and paste or write your standard in Markdown.
Browse your knowledge base — enroll something Hekkos has already ingested: a repo’s docs, a connected Confluence space, or your changelog.

Upload and Write create a durable document Hekkos owns: it’s stored, it becomes searchable in Chat alongside your other docs, and it’s auto-enrolled as an extractable standards source — so the Extract action is live immediately, with no separate opt-in step.

Browse your knowledge base opens a tree of everything already in your index, grouped by source (GitHub, Confluence, uploaded & written docs). A GitHub source expands into a folder tree that mirrors the repo, so a large space stays navigable — folders start collapsed, and the filter box at the top narrows the whole tree by name or path (matching folders auto-expand as you type). Tick individual documents to enroll the exact files you want, or tick a folder to enroll everything under it at once. Confluence pages and uploaded/written docs enroll as single leaves. Already-enrolled items are shown as Added and can’t be picked twice. The same document can be enrolled at more than one scope (a repo can adopt an org-wide doc under its own scope).

Editing an uploaded/written document re-indexes it; deleting it removes it from Chat and from the enroll list. Rules already extracted from a document are left in place on delete — removing the source stops future extraction, it doesn’t retract rules you may have already reviewed.

Extract rules — staged review, advisory by default

Each enrolled document/source has an Extract action. Extraction reads the document’s prose and turns each normative statement (“must use…”, “never…”) into a candidate rule — binding a Library preset where one fits, otherwise a generated check — and links each rule back to the document (with a line reference). A statement that maps to no precise check is deferred, not turned into a vague rule. The run reports what it did: N staged for review · N deferred · N sections read.

Nothing goes live automatically — you review first. Extraction stages the candidates rather than applying them. After a run, Review extracted rules shows each candidate in a checklist — its name, the statement it came from, its severity, and its scope — with the deferred statements listed read-only beneath. You then:

Apply selected — promotes only the candidates you tick into live rules (a select-all / none control sits at the top).
Discard — rejects the whole staged batch; nothing is promoted.

A rule is only checked once you’ve applied it — nothing goes live until you apply it.

Every applied rule starts advisory. An advisory rule is checked and shows up as a violation, but it never blocks a merge. You then opt each rule in or out with its On/Off switch, at the scope it was extracted at.

Blocking is a separate, deliberate step — and org-admin only. Only an org admin can flip a rule to Blocking, and only a deterministic rule (one Hekkos can prove with an AST/graph check) is eligible; a fuzzy rule stays advisory forever. A Blocking rule gates merges through the independent hekkos/principles status check — see The policy conformance gate. Extraction itself never sets Blocking.

The LLM-judged lane (off by default)

Some statements can’t reduce to a precise check (“error messages must not leak internals”). Those need the LLM-judged lane, which an org admin turns on at the Organization node — it’s off by default because it sends code context to a model. Its findings are always advisory and can never block. If an extraction defers statements to this lane while it’s off, the page shows a quiet pointer to turn it on.

A concrete inheritance example

Say you attach:

At Organization: a security standard saying “No weak or outdated encryption.”
At the Payments platform initiative: “All money math uses integer minor units.”
At the repository payments-api (which is in Payments platform): “Every ledger write goes through the posting service.”

Then:

payments-api is judged against all three rules (org ∪ initiative ∪ its own).
A repo marketing-site that’s in no initiative is judged against only the org rule.
A sibling repo in Payments platform sees the org rule and the initiative rule, but not payments-api’s own rule.

When the same statement is attached at more than one scope, the effective view collapses it to one row: the more specific scope is the one shown, and among the collapsed copies the stricter severity and Blocking state win — a laxer scope can never soften a stricter one.

The effective-rules view

Select a repository node and switch to the Effective rules tab to see exactly the rules that repo is judged against — its own, plus everything inherited from the org and its initiatives — each tagged with an origin chip (Org, Initiative: name, or This repo). Inherited rows are read-only here: you manage an org rule at the Org node and an initiative rule at the initiative node. The Organization and Initiative nodes have their own effective-rules view too, showing what applies at that level.

This same origin-tagged rule union also appears — alongside the documents and required standards that govern a repo — in the unified “what applies here” panel you get by opening a repository on the Repositories page. See Standards & conformance for that whole-repo view.

Who can do what

Scope	Attach docs · extract · opt rules in/out
Organization	Org admin
Initiative	Org admin
Repository	The repo’s admin on GitHub, or an org admin

Org and initiative management is org admin only (role == admin) — the same tier as the rest of Config.
Repository management is open to a repo admin, determined by a live GitHub repo-admin permission check at the moment you act — not a cached role or a claim in your session. If GitHub says you administer that repo, you can manage its documents and opt its advisory rules in/out. An org admin outranks a repo admin and can manage any repo’s rules.
A repo admin can only opt advisory rules in and out at repo scope. They can never set Blocking, and never touch org, initiative, or another repo’s rules — Blocking and the higher scopes stay with the org admin.
Because the repo check is GitHub-derived, a user with no GitHub identity (an OIDC/SSO login) can’t be a repo admin — though an OIDC org admin still manages repo rules through their org role. If you can’t manage a repo you expected to, confirm you administer it on GitHub and that your org has a GitHub App installation connected.