Review tiers

How dora review grades artifacts: structure, heuristics, LLM, sessions.

dora review runs every tier that can run. --quick is structure + heuristics. No Judge. --run is opt-in. It is not part of --quick.

Tier 1: Structure

Parseable files, required fields, name/dir consistency, basic schema. Fast. Always available. --quick includes this tier.

Dead file references, duplicate rules, keyword-level violations of memory principles, packaging smells, and scripts/ security smells (outbound network calls, secret prompts). A violated principle weighted 7+ is an error, not a warning. Still no network / LLM. Included in --quick.

Tier 3: LLM

Judgment when a judge is available. Vague descriptions, missing guardrails, scenario coverage against scenarios.yaml.

A judge is either a CLI you already have (claude or grok on PATH, using the subscription you already pay for) or an API key for an LLM provider (dora config / env). CLI is preferred; API is the fallback.

Default: run if available, skip if not
--deep: require this tier; exit 2 if no judge

Tier 4: Sessions

Mines real agent session logs for mechanical evidence a skill was actually invoked. Adapters ship for Claude, Grok, Cursor, Codex, and Copilot. --sessions requires this tier and exits 2 if no recent sessions exist.

Live-run (`--run`)

--run feeds each when in scenarios.yaml to the configured coding agent twice: no skill, then with the skill. An LLM judge scores expect and must_not. A with-skill FAIL is an error. A skill that turns PASS into FAIL is an error. Missing scenarios.yaml is fine.

--run needs an agent (dora config set agent.command) and an API judge. Exit 2 if either is missing. Do not mix --quick and --run.

The run uses an isolated HOME and cwd so host skills do not leak. Each transcript is stored under ~/.doraval/evals/. The Finding names that path.

After a clean with-skill PASS on every case, Dora saves a verdict baseline. The next --run errors if a saved PASS is now FAIL. New cases are FYI.

Checkpoint

When Entire is already enabled, Review prints: “Entire is enabled. Dora will use it while it checks this repo.” JSON and CI stay silent.

When Entire is enabled, Review reads the latest commit that touched the file. When that commit has an Entire-Checkpoint trailer, Review prints the id and the full stored prompt. A list prints them under each row. --quick includes this. JSON puts it on checkpoint. When Entire is off, Review omits checkpoint.

A full Review uses that prompt as invoke evidence. A slash command, or a SKILL.md path, in the prompt counts as an invoke. A missing local log does not mark that Skill Never invoked.

Session health

A full Review also prints Session health. It is not a Finding and not a fifth tier. It reports token pressure from Sessions in the Review window (default last 30 Sessions, 90 days): cache-read share ≥ 80%, call count ≥ 20, user turns ≥ 10. --quick omits it. Scan omits it.

JSON: sessionHealth on each Review result (window, sessionCount, signals). Quiet Sessions have an empty signals list.

Choosing a mode

dora review --all --quick --ci   # CI structural gate
dora review --quick .            # local, no Judge
dora review --deep <path>        # require LLM
dora review --run <path>         # live-run scenarios.yaml