Docs

Gets a fresh install ready. Run it once after installing qa. Each step prints what it will do first; every step is safe to run again. 1 Playwright looks where the sweep looks (repo, .playwright, cwd, PLAYWRIGHT_HOME, the per-user home). If missing, installs playwright-core into the per-user home with npm, then runs its CLI to fetch Chromium. Launches Chromium headless once and prints its version and path. Needs node and npm on PATH; if they are absent it prints the exact commands and exits 2. 2 Jev key checks whether TYPESAFE_API_KEY or TYPESAFE_JEV_KEY is set. Presence only; the value is never printed. The CLI never needs it; only the HUNT screens in the qa skill do. Absent is not a failure. 3 skills copies the packaged skills into ~/.claude/skills and ~/.codex/skills for the agents that exist. A directory you made is never touched; a differing copy is reported, not replaced. 4 MCP with --mcp, registers qa with Claude Code and Codex when their CLIs exist (printed first, run only with --yes); otherwise prints the config snippet. Without --mcp, a one-line hint. 5 next prints the first commands to run. --dry-run print every step's plan, change nothing --yes run without asking. Required when there is no terminal. --no-browser skip step 1 --no-skills skip step 3 --json one document on stdout: { ok, dryRun, steps[], next[] } Exit codes: 0 everything requested is ready; 2 invalid usage, no terminal without --yes or --dry-run, or a requested step could not complete. A skipped or failed step is never reported as ready. Never 1.

Scaffolds declarations without overwriting them. --study writes source-derived research; --analysis additionally writes .verify/analysis.json and analysis.md with an evidence ledger, feature/context/risk/story/mutation/proof/fix view. It never invents business requirements or executes mutations.

Runs verify.sh with the flags given, unchanged. verify.sh --help is the authority on those; two that matter to a noisy app: --console-allow REGEX declares a console error expected (matches are counted and the patterns republished under consoleAllowed, never dropped in silence; an unparseable pattern exits 2), and --action-ms MS is one locator action's budget -- a visibility wait, a click, a menu dismissal -- default 2000.

Then opens a private pending run directory and atomically writes immutable report snapshots plus normalized roles and the exact validated CRUD snapshots, with their sha256 digests. The agent receives only those explicit paths and never reads the live role or CRUD files. It always attempts a compatible qa-agent (a verified prebuilt binary, or a cargo build fallback) with those explicit paths, the run ID, lane and mode via --emit-result -- optional evidence by default (unmeasured when no compatible binary exists), never gating unless --autonomous makes it required. Only after the returned digests and schema are verified does the pending directory publish to .verify/runs/<id>/: a reader sees no run or a complete run, never a partial one. run.json carries the embedded result under agent, plus lane and runId; the archive also gets agent-result.json (its canonical bytes). Adapter evidence (qa measure crud, qa measure experiments) is NEVER folded in automatically: name the adapters explicitly with --link-adapters, and their findings travel with their own denominator rather than entering this run's counts. Appends to .verify/trajectory.jsonl and prints the triage. Exit is derived: 2 dominates (the gate itself invalid, OR --autonomous with an absent/invalid agent), else 1 if the gate found gating evidence, else 0. --json output separates gate (verify.sh's own exit) from agent (the embedded result) so a consumer never conflates the two verdicts. --no-archive runs the same snapshot and agent sequence into a private pending directory and still emits gate/agent on stdout (--no-archive --autonomous still enforces require-agent) but publishes nothing: the pending directory is discarded, only after the result is validated, so a failure still leaves a diagnosis on stdout.

--autonomous also produces the canonical three-file graph contract (nodes.jsonl, edges.jsonl, run-manifest.json) via the cargo-built qa-agent into .verify/autonomous/ and validates its manifest. This is reported under the JSON output's autonomous field, distinct from agent. Needs cargo; absent cargo is reported unmeasured. A required kernel or manifest failure is a hard exit 2. The earlier 42-file surface is retired.

Dispatches to one of the three deep-measurement adapters. Each kind keeps its own flags and subwords. crud and coherence --mutate perform real, declared mutation writes under the repo's own opt-in (verify.crud.json); every other kind is read-only. See qa help measure coherence / measure crud / measure experiments for what each one measures and its exit codes.

Reads results. With no kind, prints ranked findings and coverage (triage). report's own sub-verbs stay reachable both nested (qa show report diff|runs|ci <repo>) and directly (qa show diff|runs|ci <repo>). See qa help show triage / show next / show report / show ledger for each one's flags, output, and exit codes. qa show analysis <repo> renders the generated analysis; --format json emits its structured artifact.

The one long-running "do everything" command. With no kind, every phase below is a child qa <cmd> process; this command reads what each one wrote to .verify/ and decides whether the next one runs: 0 --base is used as given. Otherwise this command builds and starts a production server itself (qa run serve --prod; its base becomes --base, stopped at the end unless --keep-serving). If that fails without an explicit --serve, the run is static-only and the report says so; with --serve the failure is INVALID. 1 qa verify --preflight -- exit 2 stops everything and prints its fix lines. When a --base is known, its probe of it decides --prod automatically for every phase below: prod -> add --prod, dev -> continue without it and say timing findings will be P3, unknown -> continue without it. 2 qa init --study; qa init --roles --ignore -- init never overwrites. With more than one principal and no roles file, init scaffolds one role per principal (each owning "/") and the run continues, saying so. 2b Writes turn on when verify.crud.json declares every flow "production": false and the base is loopback: the crud and coherence phases pass --mutate themselves. The sweep gets --mutate only when an app-owned journey declares mutates: true -- generic guessed replay is disabled, so without such a journey the flag could only invalidate the run, and the decision log says it was withheld. An explicit --lane wins; otherwise real-integration is selected when verify.auth-launcher.mjs exists and every persona in verify.roles.json declares "expect". Draft journeys whose every field and submit control resolved from source are promoted to .verify/journeys.mjs under that same mutation opt-in. Each decision and its reason is printed and lands in the exit report. 3 qa verify --ratchet (the baseline) -- exit 2 stops. No --base means a static-only run, said plainly in the report. 3b deep measurement, once, in two groups: Group A (concurrent -- read-only against the app, or writing only to an isolated target) is static coherence. Group B (strictly serial -- these can all write to the SAME dev database) is qa measure crud (under the mutation opt-in), qa measure experiments (qa run generates the Node-owned default queue from the baseline's Rust route priority when none exists, so it needs cargo; pass --queue <path> for a supplied plan; wall time is a quarter of what is left, at most 30 minutes), then runtime coherence (under its own repo-declared opt-in). Whatever could not run is a named line under "what was not measured" with how to enable it. Whichever adapter left measured evidence is folded into the very next qa verify via --link-adapters automatically. 4 qa verify --runs N on the baseline's runtime P0/P1 routes (skipped when there are none) -- ghost findings are written into .verify/loop.json's blocked list so the fix loop never chases them. 5 qa fix plan --lanes N (one worktree + brief per class, disjoint batches), then waits for the host agent to execute the briefs. --once hands off immediately with exit 1. 6 every chunk: qa show ledger, qa show report, one line appended to .verify/trajectory.jsonl. If something was fixed and time remains, qa verify runs again and qa show diff compares it -- new findings send it back to step 4 with whatever time is left. After the depth ladder is exhausted, runtime measurements repeat at --checkpoint-minutes cadence without --resume; source changes wake the coordinator sooner. Static-only runs wait for source changes. --once finishes after the first full pass. 7 exit report: .verify/marathon-report.md (routes total/clean/fixed with commit hashes/open fids/needs-reproduction ghost fids, the ratchet trajectory, every phase's command and exit code verbatim, what stayed unmeasured, which adapters got linked, the depth ladder's rungs with their --resume reused/rejected counts) plus a qa show report HTML. Its first word is PASS, FAIL, or INVALID, matching this command's own exit code. --status reads .verify/marathon.json and prints phase, running/stopped/finished, minutes left, base, lane, writes on/off, depth rung, last command and decision, the last checkpoint counts, wait state, and the report path -- for an agent polling a background run. Exit 0 running or finished, 1 stopped mid-run (resume it), 2 nothing has run here. A bare qa run <repo> on a repo whose .verify/marathon.json is not "done" resumes it -- this covers both a killed process and a --once handoff to open lanes; --fresh discards that state and starts over. A separate marathon.lock refuses a second live coordinator, including --fresh. --resume is still accepted and is a no-op. A recorded server that died is restarted only if --serve was given, otherwise that is INVALID. --dry-run prints the plan above with this run's actual flags and runs nothing. --mutate is added only by the declaration rule in step 2b, never by --hours or any other flag. Default --hours is 10, default --lanes is 4. Exit: 0 the final gate is clean, 1 it has findings (or lanes are ready/open, or time ran out with findings open), 2 a phase could not run.

--fixer, --fixer-protocol, --fixer-timeout, --measure-only, and --commit are retired for qa run: the host agent owns source changes and commits. Use --once for a copy-paste-ready brief. serve is reachable by name (qa run serve ...) -- see qa help run serve for its own flags and exit codes.

Parallel class-level remediation (qa fix plan <repo>, qa fix gate <class> <repo>, ...) and the cross-repo false-positive memory (qa fix fp add|list|rm ...). See qa help fix plan / fix fp for flags, output, and exit codes.

Maintaining the harness itself, not the target repo under test: qa dev atlas --strict, qa dev selftest --fast, qa dev validate <repo>, qa dev capabilities --json, qa dev version --json. See qa help dev atlas / dev capabilities / dev selftest / dev validate / dev version for flags and exit codes.