Help

FAQ & troubleshooting

Answers to the questions people ask most when adopting Valinor, and fixes for the errors you're most likely to see. Every error entry below is a real, deliberate behavior of the tool — Valinor fails closed and tells you exactly what's wrong.

Frequently asked questions

What is Valinor, in one sentence?

A CI-native quality-governance product: you declare the quality bar your repository must meet — verifiable claims, branch-protection rules, an LLM-review rubric suite, and a whole-repo audit — and Valinor enforces that bar in CI, deterministically and fail-closed.

Which languages and stacks does it work with?

The doctrine, claims registry, GitHub config-as-code, documentation gates, and rubric reviews are stack-agnostic — they govern any repository. A few gates are JS/TS-specific (for example, the empty-catch lint) and ship off by default unless your stack opts in.

Do I need to send my code anywhere?

No. The deterministic checks (file / grep / token / files-identical claims and the documentation gates) run entirely offline. Only the GitHub configuration checks call the GitHub API, and the optional LLM rubric review runs through Greptile on your pull requests.

Will adopting Valinor break my existing repo's CI on day one?

No, if you use the adoption dials. A baseline grandfathers your current findings so gates block only on new debt, and per-gate severity (error / warn / off) lets you soften a noisy gate while you drain it. Start in advisory or new-code mode and ratchet up.

Is valinor init safe to re-run?

Yes. It re-inlines the current doctrine in place and writes scaffold files only where they're absent, so re-running to pull a doctrine update never clobbers your custom claims.yml, governance.config.yml, or .greptile rules.

How do I update to a new version of Valinor?

Bump the dependency (npm i -D @cmbrcreative/valinor@latest) and re-run npx valinor init . to pull any doctrine update. Because the audit skills are bundled in the package version-locked, upgrading Valinor upgrades your audit skills too — no per-repo drift.

Troubleshooting

A gate prints "dist/ not built"

check-…: dist/ not built — run `npm run build` first

This appears when running Valinor's gate scripts from a source checkout before building. When you use the published package via npx valinor …, the build is already done — this message is only relevant to contributors working inside the Valinor repository.

claims-verify exits non-zero ("N/M drifted")

A claim no longer holds. Each failing claim prints a ✗ <id> — <detail> line naming what was expected. Open claims.yml, find the claim by id, and either fix the repo so the claim is true again (the usual case — a claim is a spec) or, if the claim itself is now wrong, update it. claims-verify fails closed: any drift is a non-zero exit.

repo-settings-check reports ⚠ UNVERIFIABLE

⚠ allow_auto_merge: UNVERIFIABLE — the current token cannot read this field.

Two repo merge-setting booleans (allow_auto_merge, delete_branch_on_merge) are only readable by a classic repo-scoped token; the built-in Actions token returns them as null. The check fails closed rather than reporting a phantom drift. To resolve, either provide a token tier that can read the field (see the CLI reference) or set verify: false on that field in governance.config.yml (with a reason) to stop gating it.

A GitHub command fails to read the ruleset or settings

branch-protection-check, branch-protection-sync, repo-settings-check, and repo-settings-sync call the GitHub API and read GITHUB_TOKEN plus GITHUB_REPOSITORY (owner/repo) from the environment. A read failure exits non-zero with the underlying error. Confirm GITHUB_TOKEN is set with sufficient scope and that GITHUB_REPOSITORY is present (Actions sets it automatically; set it yourself when running locally).

valinor baseline refuses to write

⚠ baseline would grow … refusing to write — fix the new finding(s) first

When a committed baseline already exists, baseline refuses to regenerate if doing so would inflate any finding count — otherwise it would be a one-command bypass of the block-on-new guarantee. Fix the new findings instead. To deliberately re-snapshot from scratch, delete the committed baseline first, then re-run.

check-doc-freshness flags dead internal links, dead config references, and dead valinor / npm run command references; check-docs-coverage flags orphan docs (no governing manifest entry) and stub docs (near-empty placeholders). The error names the offending path — fix the reference, govern the doc, or remove it.

Still stuck?

Previous
Governance overview