Governance gate commands

These commands reconcile a repo against its declared governance contract — the claims.yml claims, the branch-protection ruleset, and the GitHub repo settings. The -check variants verify (and fail closed on drift); the -sync variants apply.

The GitHub-API commands (branch-protection-*, repo-settings-*) read GITHUB_TOKEN from the environment; which token tier can read which field is documented in the repo's README. For the org-side setup these commands assume in CI (the Valinor App, its credentials, and required-check wiring), see docs/guide/prerequisites.md.


VERIFYclaims-verify [claims.yml]

claims-verify

Verify the repo satisfies every claim declared in claims.yml. Prints one line per claim; exits non-zero if any drifted. Claims are deterministic pins — grep patterns, file presence/absence, or byte-identity between two files — that keep load-bearing facts from eroding. See the claims.yml schema.

  • Name
    path
    Type
    string
    Description

    The claims file. Default: claims.yml.

Verify claims

VERIFY
claims-verify
npx @cmbrcreative/valinor claims-verify claims.yml

CHECKbranch-protection-check [branch-protection.json]

branch-protection-check

Diff the live GitHub branch-protection ruleset against branch-protection.json; exits non-zero on any drift. Reads the required review count from governance.config.yml (autonomy is authoritative — it overrides whatever count the JSON declares).

  • Name
    path
    Type
    string
    Description

    The branch-protection spec. Default: branch-protection.json.

Check branch protection

CHECK
branch-protection-check
npx @cmbrcreative/valinor branch-protection-check branch-protection.json

SYNCbranch-protection-sync [branch-protection.json]

branch-protection-sync

Apply branch-protection.json to the live ruleset — create it if absent, update it if present. The write counterpart of branch-protection-check.

Sync branch protection

SYNC
branch-protection-sync
npx @cmbrcreative/valinor branch-protection-sync branch-protection.json

CHECKrepo-settings-check [governance.config.yml]

repo-settings-check

Verify GitHub repo settings (e.g. merge options) match governance.config.yml. Reports an unreadable admin field as ⚠ UNVERIFIABLE (fail-closed), never a phantom drift — so a field your token can't read fails honest rather than green-or-wrong.

Check repo settings

CHECK
repo-settings-check
npx @cmbrcreative/valinor repo-settings-check governance.config.yml

SYNCrepo-settings-sync [governance.config.yml]

repo-settings-sync

Apply the verify: true repo settings from governance.config.yml to GitHub.

Sync repo settings

SYNC
repo-settings-sync
npx @cmbrcreative/valinor repo-settings-sync governance.config.yml

WRITEbaseline [.valinor/baseline.json]

baseline

Snapshot the repo's current whole-tree gate findings into a per-occurrence baseline — grandfather existing debt so the gates block only on new findings (the new-code adoption mode). Refuses to write if regenerating would grow any count.

  • Name
    path
    Type
    string
    Description

    The baseline file. Default: .valinor/baseline.json (or adoption.baseline from governance.config.yml).

Snapshot a baseline

WRITE
baseline
npx @cmbrcreative/valinor baseline .valinor/baseline.json

Was this page helpful?