Valinor - Self-enforcing engineering discipline.

The valinor command-line interface exposes Valinor's checks and scaffolding. Invoke it as valinor <command> [path] (via npx valinor …, or directly if you've added it to a script). Each command takes an optional path that defaults to the conventional config file, emits a telemetry event, and fails closed — a non-zero exit on any drift, error, or unreadable input.

Adopting & updating

`init <targetPath>`

Adopt Valinor on a repository. Propagates the versioned canonical doctrine into the target's AGENTS.md ≡ CLAUDE.md and scaffolds the minimum to run the gates: governance.config.yml, a starter claims.yml, a starter README.md, .greptile/config.json (the canonical review-rubric rules), and .github/workflows/valinor-gates.yml.

Flags:

--profile — your repo's profile (shapes the scaffolded config).
--maturity — adoption maturity.
--mode — advisory, new-code, or strict (controls whether gates block).
--stack — your stack (e.g. nextjs); overrides the profile-aware default.
--dry-run — print the plan and write nothing.

Safe to re-run: it re-inlines the current doctrine in place and leaves already-present scaffold files untouched, so pulling a doctrine update never clobbers your custom claims or rules.

Verifying your repo

These are the checks you'll run most — locally and in CI. Each scans your own repo from the working directory and fails closed.

Command	What it checks
`claims-verify [claims.yml]`	Verifies the repo satisfies every claim in `claims.yml`. Prints one line per claim; exits non-zero on any drift.
`doctrine-check [AGENTS.md]`	Verifies your agent doc carries the portable Valinor doctrine block — present, version-current, and un-drifted from the canonical doctrine.
`check-agent-file-principles [AGENTS.md]`	Flags any README-owned section (project / stack / commands / install / usage / license) carried in your agent file outside the doctrine block.
`check-doc-freshness`	Scans your docs for dead internal links, dead config references, dead `valinor` / `npm run` command references, and CLI drift.
`check-docs-coverage`	Checks your `.md` corpus for orphan and stub docs (the exhaustiveness axis).
`check-dependency-health`	OWASP A06: checks your lockfile is present and valid, `npm audit` reports no critical/high vulnerabilities, and no dependency uses an unbounded version specifier. Requires a prior `npm audit --json > audit-report.json` step.
`check-change-narrative`	On a substantial pull request, requires at least one new bullet under your `CHANGELOG.md`'s `## [Unreleased]` section.

Opt-in gates

check-research-ledger, check-plans, and check-no-empty-catch ship off by default. They validate a docs/research/ ledger, a docs/plans/ lifecycle, and empty catch blocks respectively, and no-op until you enable them in governance.config.yml. Turn one on when you adopt its discipline.

GitHub configuration as code

These commands diff (or apply) your repository's GitHub settings against config committed in your repo. They call the GitHub API and read GITHUB_TOKEN from the environment.

Command	What it does
`branch-protection-check [branch-protection.json]`	Diffs the live branch-protection ruleset against your committed `branch-protection.json`; exits non-zero on drift.
`branch-protection-sync [branch-protection.json]`	Applies `branch-protection.json` to the live ruleset (creates or updates it).
`repo-settings-check [governance.config.yml]`	Verifies GitHub repo settings (e.g. merge options) match `governance.config.yml`. Reports an unreadable admin field as `⚠ UNVERIFIABLE` (fail-closed), never a phantom drift.
`repo-settings-sync [governance.config.yml]`	Applies the `verify: true` repo settings from `governance.config.yml`.

The whole-repo audit

Beyond per-change gates, Valinor ships audit skills — graded, standing-repo sweeps of a whole concern (e.g. "has this repo adopted the doctrine?"). They're bundled inside the installed package, version-locked to your Valinor.

npx valinor audit-list                 # discover the available concern ids
npx valinor audit-show doctrine        # print that concern's audit skill, for your agent to run

audit-show is read-only — your coding agent reads the printed skill and runs the graded audit against your repo. Other audit commands (audit-verify, audit-record, audit-trend, and the gate-health and eval commands) support the score-over-time and calibration machinery; run npx valinor with no arguments to see the full list.

Authentication and token tiers

Valinor's GitHub checks read GITHUB_TOKEN from the environment. What each token tier can verify:

Tier	Reads
Built-in Actions `GITHUB_TOKEN`	claims, files, branch-protection rulesets — most checks
GitHub App / fine-grained PAT with Administration: Read	the above + repo administration
Classic PAT with `repo` scope	the above + the admin-write-gated repo merge-setting fields (`allow_auto_merge`, `delete_branch_on_merge`)

The recommended setup is the Valinor GitHub App: install it on your org and have CI mint a short-lived installation token — no personal tokens to provision or rotate. If you gate an admin-only field your token can't read, repo-settings-check reports ⚠ UNVERIFIABLE (fail-closed) with the exact remedy; to deliberately stop gating a field, set verify: false on it in governance.config.yml.

For the exhaustive command list with every flag and default, contributors can consult the in-repo commands reference, which is kept in sync with the CLI source.