Policies

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 policy 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 & attestation.
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.)

Most Library checks are a single on/off switch. A few parameterized checks — today the route-guard check — can be added more than once, one instance per configuration, because a real org guards several route families with different middlewares (e.g. /admin/* → RequireAdmin and /orgs/{id}/* → RequireOrgMatch). On such a card, use Add to configure another instance; each instance is edited, previewed, removed, and opted into the merge gate independently, and each shows up as its own rule in the effective-rules view. (Adding the same configuration twice is a no-op; there is a generous per-check instance cap as a fair-use guard.)

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.

Where each scope is configured — org here, project & repo where they live

Governance is additive across three scopes — Organization → Initiative (project) → Repository — and each is configured where it lives, not from a single tree:

Organization — this Standards → Policies page. It configures only org-wide policy: documents and rules here apply to every repository. There is no scope picker on this page — it is org-only.
Initiative (project) — the project’s edit drawer, opened from the Repositories page: pick a project in the left organizer and click its edit (pencil) control. Add project-scoped documents/rules in the drawer. They apply only to the repos in that project.
Repository — open a repo on the Repositories page. Its detail shows a read-only glance of what governs it; click Edit governance (repo-admins) or View governance (everyone else — read-only) to open the drawer. Repo-admins add repo-scoped documents/rules there.

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.

Additive-only — a lower scope can never override a higher one. A project or repo can only add stricter documents and rules on top of what it inherits; it can never remove, weaken, or override an org (or, for a repo, a project) rule. That’s why this page is org-only: org-wide policy is set here, and every project and repo layers on top.

Add a standards document

Each scope’s surface has an Add document ▾ — this page adds org documents; the project edit drawer adds project documents; the repo Edit-governance drawer adds repo documents. The document attaches to that scope; you don’t pick a 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.

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

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 here on the org Policies page — 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 those duplicates to one row so you don’t see it three times — it shows the most-specific copy as the representative, and among the collapsed copies the stricter severity and Required state win. That’s a display collapse of identical rules, not an override: every distinct rule from the org, the initiative, and the repo still applies (the union), and nothing a lower scope does can remove or soften a rule a higher scope set — a laxer scope can never weaken a stricter one.

The effective-rules view

Open a repository on the Repositories page (or a project via its edit drawer, opened from the same page’s organizer) to see exactly the rules that scope is judged against — its own, plus everything inherited from the org (and, for a repo, its project) — each tagged with an origin chip (Org, Initiative: name, or This repo). Inherited rows are read-only there: you manage an org rule here on the org Policies page, and a project rule in the project’s edit drawer. The org Policies page renders its enrolled documents and the org-level rules in force as two stacked sections — Documents and Effective — one below the other (no tabs to flip). That org/initiative Effective view is read-only by design — you opt rules in and out in the Documents section (next to the document each was extracted from), so for an admin the Effective section shows a short “opt each rule in or out on its document, under Documents” pointer rather than being a dead-end.

Where a rule carries a compliance reference — a CWE (Common Weakness Enumeration) or OWASP ASVS identifier — it’s shown as a small read-only badge in the rule’s meta row, so an auditor can trace a check to its standard. Hekkos surfaces these only when the rule already has them; it never invents a mapping.

That same origin-tagged rule union appears — alongside the documents and required standards that govern a repo — in the unified “what applies here” panel on the repo view. See Standards & attestation 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 Required, and never touch org, initiative, or another repo’s rules — Required 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.