verifika 0.0.1 → 0.0.3

package/dist/reporters/human.js

@@ -1,4 +1,5 @@
-import { describeProblem, duration, isFailureStatus, logsHint, MAX_PREVIEWED_FAILURES, problems, selectionLabel, } from "./reporter.js";
+import { formatSeconds } from "../format.js";
+import { describeProblem, duration, isFailureStatus, logsHint, previewDecider, problems, selectionLabel, STOPPING_MESSAGE, } from "./reporter.js";
 const wrap = (open, close) => (text) => `\u001b[${open}m${text}\u001b[${close}m`;
 export const colors = {
     green: wrap(32, 39),
@@ -25,20 +26,13 @@ const HEARTBEAT_MS = 30_000;
 export function humanReporter(output, style, options = {}) {
     const running = new Map();
     let heartbeat;
+    let width = 0;
     return {
-        onStart({ selection, selected }) {
-            const skipped = selection.checks.length - selected.length;
-            output.out(`${style.bold("verifika")} ${selectionLabel(selection, skipped)}\n`);
-            if (selected.length === 0) {
-                output.out(style.dim("Nothing to verify for these changes. Full run: verifika --all\n"));
+        onStart(info) {
+            output.out(renderStart(info, style, options.skipEstimate));
+            width = nameWidth(info.selected);
+            if (info.selected.length === 0)
                 return;
-            }
-            if (skipped > 0) {
-                const names = selection.checks
-                    .filter((check) => !check.selected)
-                    .map((check) => check.name);
-                output.out(style.dim(`skipped: ${names.join(", ")}\n`));
-            }
             if (options.heartbeat) {
                 heartbeat = setInterval(() => {
                     if (running.size === 0)
@@ -58,33 +52,75 @@ export function humanReporter(output, style, options = {}) {
         },
         onCheckEnd(check) {
             running.delete(check.name);
-            const detail = check.status === "passed" ? "" : ` ${describeProblem(check)}`;
-            output.out(`${symbol(check.status, style)} ${check.name} ${style.dim(duration(check.durationMs))}${detail}\n`);
+            output.out(renderCheckEnd(check, style, width));
         },
         onFinish(result) {
             if (heartbeat)
                 clearInterval(heartbeat);
             output.out(renderSummary(result, style));
         },
+        onInterrupt() {
+            output.err(style.yellow(STOPPING_MESSAGE));
+        },
     };
 }
+export function nameWidth(names) {
+    return Math.max(0, ...names.map((name) => name.length));
+}
+/**
+ * The run header (`verifika · <selection> · <n> checks · <j> parallel`), then
+ * the skipped checks with the time skipping them saved.
+ */
+export function renderStart({ selection, selected, concurrency }, style, estimate) {
+    const header = [style.bold("verifika"), selectionLabel(selection, 0)];
+    header.push(`${selected.length} check${selected.length === 1 ? "" : "s"}`);
+    if (selected.length > 0)
+        header.push(`${concurrency} parallel`);
+    let text = `${header.join(" · ")}\n`;
+    const skipped = selection.checks.filter((check) => !check.selected).map((check) => check.name);
+    if (skipped.length > 0) {
+        text += style.dim(`${skipped.length} skipped${savedNote(skipped.length, estimate)}: ${skipped.join(", ")}\n`);
+    }
+    if (selected.length === 0) {
+        text += style.dim("Nothing to verify for these changes. Full run: vfk --all\n");
+    }
+    return text;
+}
+/** ` (~40s saved)`, ` (≥40s saved)` when some durations are unknown, or nothing when none are known. */
+function savedNote(skipped, estimate) {
+    if (!estimate || estimate.unknown >= skipped)
+        return "";
+    return ` (${estimate.unknown > 0 ? "≥" : "~"}${formatSeconds(estimate.knownMs)} saved)`;
+}
+/** The permanent line printed when a check finishes; durations line up in a column. */
+export function renderCheckEnd(check, style, width = 0) {
+    const time = style.dim(duration(check.durationMs).padStart(5));
+    const detail = check.status === "passed" ? "" : `  ${describeProblem(check)}`;
+    return `${symbol(check.status, style)} ${check.name.padEnd(width)} ${time}${detail}\n`;
+}
 export function renderSummary(result, style) {
     const { summary } = result;
     const lines = [];
     const failing = problems(result);
-    let previewed = 0;
+    const decide = previewDecider(result);
+    const width = nameWidth(failing.map((check) => check.name));
     if (failing.length > 0)
         lines.push("");
     for (const check of failing) {
+        const name = check.name.padEnd(width);
+        if (check.status === "blocked") {
+            lines.push(style.dim(`${symbol(check.status, plain)} ${name}  ${blockedReason(check, result)}`));
+            continue;
+        }
         if (!isFailureStatus(check.status)) {
-            lines.push(`${symbol(check.status, style)} ${check.name}: ${describeProblem(check)}`);
+            lines.push(`${symbol(check.status, style)} ${name}  ${describeProblem(check)}`);
             continue;
         }
-        lines.push(`${symbol(check.status, style)} ${style.bold(check.name)}: ${describeProblem(check)}`);
-        if (check.preview.length > 0 && previewed < MAX_PREVIEWED_FAILURES) {
-            previewed++;
+        const preview = decide(check);
+        const rerun = `rerun: vfk -c ${check.name}`;
+        lines.push(`${symbol(check.status, style)} ${style.bold(name)}  ${check.command} → ${describeProblem(check)}${style.dim(` · ${rerun}${preview.note}`)}`);
+        if (preview.show)
             lines.push(...check.preview.map((line) => style.dim(`    ${line}`)));
-        }
     }
     const time = duration(result.durationMs);
     if (result.status === "passed") {
@@ -99,6 +135,18 @@ export function renderSummary(result, style) {
         lines.push(style.dim(`Logs: ${hint}`));
     return `${lines.join("\n")}\n`;
 }
+/** `not run: build failed`, naming what happened to the dependency that blocked the check. */
+function blockedReason(check, result) {
+    const dependency = result.checks.find((other) => other.name === check.blockedBy);
+    if (!dependency)
+        return `not run: ${check.reason}`;
+    const outcome = dependency.status === "timed_out"
+        ? "timed out"
+        : isFailureStatus(dependency.status)
+            ? "failed"
+            : "did not run";
+    return `not run: ${dependency.name} ${outcome}`;
+}
 export function symbol(status, style) {
     switch (status) {
         case "passed":
@@ -109,6 +157,8 @@ export function symbol(status, style) {
             return style.red("✗");
         case "skipped":
             return style.dim("–");
+        case "blocked":
+            return style.dim("○");
         default:
             return style.yellow("!");
     }

package/dist/reporters/live.js

@@ -0,0 +1,209 @@
+import { formatSeconds } from "../format.js";
+import { nameWidth, renderCheckEnd, renderStart, renderSummary, } from "./human.js";
+import { STOPPING_MESSAGE } from "./reporter.js";
+/** Redraw interval: about 10 frames a second, which also throttles output-driven updates. */
+const FRAME_MS = 100;
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CSI = "\u001b[";
+const HIDE_CURSOR = `${CSI}?25l`;
+const SHOW_CURSOR = `${CSI}?25h`;
+// Autowrap stays off while the block is drawn, so an overlong line (wide characters
+// the width estimate missed) is clipped by the terminal instead of wrapping and
+// breaking the cursor-up count of the next redraw.
+const NO_WRAP = `${CSI}?7l`;
+const WRAP = `${CSI}?7h`;
+/**
+ * The redrawn part of the live display: a progress header, one line per running
+ * check (spinner, elapsed time, latest output) and the checks still waiting.
+ * Lines fit the width; the block never exceeds the height minus one row, so the
+ * cursor can always move back to its top.
+ */
+export function renderBlock(state, view, style) {
+    const max = Math.max(1, view.width - 1);
+    const elapsed = formatSeconds(view.now - state.startedAt);
+    const header = `[${state.finished.size}/${state.selected.length}] ${elapsed}${state.stopping ? " · stopping…" : ""}`;
+    const namePad = nameWidth(state.selected);
+    const frame = SPINNER[Math.floor(view.now / FRAME_MS) % SPINNER.length];
+    const running = state.selected
+        .filter((name) => state.running.has(name))
+        .map((name) => {
+        const { since, line } = state.running.get(name);
+        const time = formatSeconds(view.now - since).padStart(5);
+        const prefix = `${frame} ${name.padEnd(namePad)}  ${time}`;
+        if (prefix.length + 2 >= max)
+            return fit(prefix, max);
+        const shown = fit(line, max - prefix.length - 2);
+        return `${frame} ${name.padEnd(namePad)}  ${style.dim(time)}${shown ? `  ${style.dim(shown)}` : ""}`;
+    });
+    const groups = waitingGroups(state);
+    const waiting = groups.map(({ names, why }) => style.dim(fit(`  ${names.join(", ")}  ${why}`, max)));
+    // Keep the header, then as many running checks as fit, then waiting groups;
+    // collapse whatever does not fit into a count.
+    const room = Math.max(1, view.height - 1) - 1;
+    let shownRunning = running.length;
+    let shownWaiting = waiting.length;
+    const total = () => shownRunning +
+        (shownRunning < running.length ? 1 : 0) +
+        shownWaiting +
+        (shownWaiting < waiting.length ? 1 : 0);
+    while (total() > room && (shownWaiting > 0 || shownRunning > 0)) {
+        if (shownWaiting > 0)
+            shownWaiting--;
+        else
+            shownRunning--;
+    }
+    const lines = [style.bold(fit(header, max)), ...running.slice(0, shownRunning)];
+    if (shownRunning < running.length)
+        lines.push(style.dim(fit(`  +${running.length - shownRunning} more running`, max)));
+    lines.push(...waiting.slice(0, shownWaiting));
+    if (shownWaiting < waiting.length) {
+        const hidden = groups
+            .slice(shownWaiting)
+            .reduce((count, group) => count + group.names.length, 0);
+        lines.push(style.dim(fit(`  +${hidden} more waiting`, max)));
+    }
+    return lines.slice(0, Math.max(1, view.height - 1));
+}
+/** Checks not yet started, grouped by what they wait for, e.g. `test, pack  waiting on build`. */
+function waitingGroups(state) {
+    const selected = new Set(state.selected);
+    // A check whose dependency failed (directly or down a chain) will never start.
+    const blocked = new Set();
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const name of state.selected) {
+            if (blocked.has(name) || state.finished.has(name) || state.running.has(name))
+                continue;
+            const deps = state.dependsOn[name] ?? [];
+            if (deps.some((dep) => state.finished.get(dep) === false || blocked.has(dep))) {
+                blocked.add(name);
+                changed = true;
+            }
+        }
+    }
+    const groups = new Map();
+    for (const name of state.selected) {
+        if (state.running.has(name) || state.finished.has(name) || blocked.has(name))
+            continue;
+        const unmet = (state.dependsOn[name] ?? []).filter((dep) => selected.has(dep) && state.finished.get(dep) !== true);
+        const why = state.stopping
+            ? "will not start"
+            : unmet.length > 0
+                ? `waiting on ${unmet.join(", ")}`
+                : "queued";
+        groups.set(why, [...(groups.get(why) ?? []), name]);
+    }
+    return [...groups].map(([why, names]) => ({ names, why }));
+}
+/** Truncates to `width` characters (code points), marking the cut with an ellipsis. */
+export function fit(text, width) {
+    const chars = Array.from(text);
+    if (chars.length <= width)
+        return text;
+    return width <= 0 ? "" : `${chars.slice(0, width - 1).join("")}…`;
+}
+/**
+ * Human output with a live status block. Finished checks print permanently above
+ * the block exactly as the line reporter prints them, so scrollback reads like
+ * line mode; the block below is redrawn in place (cursor up, erase down) and
+ * removed when the run ends. The cursor is hidden while live and restored on
+ * finish, on dispose (errors) and on process exit.
+ */
+export function liveReporter(terminal, style, options = {}) {
+    let state = null;
+    let drawn = 0;
+    let stopTicker;
+    let unregisterExit;
+    let width = 0;
+    const clear = () => (drawn > 0 ? `\r${CSI}${drawn}A${CSI}J` : "");
+    const draw = (above = "") => {
+        if (!state)
+            return;
+        const lines = renderBlock(state, { width: terminal.columns(), height: terminal.rows(), now: terminal.now() }, style);
+        terminal.write(`${clear()}${above}${NO_WRAP}${lines.map((line) => `${line}\n`).join("")}${WRAP}`);
+        drawn = lines.length;
+    };
+    const release = (after = "") => {
+        if (!state) {
+            if (after)
+                terminal.write(after);
+            return;
+        }
+        stopTicker?.();
+        unregisterExit?.();
+        terminal.write(`${clear()}${SHOW_CURSOR}${after}`);
+        state = null;
+        drawn = 0;
+    };
+    return {
+        onStart(info) {
+            terminal.write(renderStart(info, style, options.skipEstimate));
+            width = nameWidth(info.selected);
+            if (info.selected.length === 0)
+                return;
+            state = {
+                selected: info.selected,
+                dependsOn: info.dependsOn,
+                running: new Map(),
+                finished: new Map(),
+                startedAt: terminal.now(),
+                stopping: false,
+            };
+            terminal.write(HIDE_CURSOR);
+            unregisterExit = terminal.onExit(() => terminal.write(`${SHOW_CURSOR}${WRAP}`));
+            stopTicker = terminal.every(FRAME_MS, () => draw());
+            draw();
+        },
+        onCheckStart(name) {
+            state?.running.set(name, { since: terminal.now(), line: "" });
+            draw();
+        },
+        onCheckOutput(name, line) {
+            // Picked up by the next frame; output alone never triggers a redraw.
+            const entry = state?.running.get(name);
+            if (entry)
+                entry.line = line;
+        },
+        onCheckEnd(check) {
+            state?.running.delete(check.name);
+            state?.finished.set(check.name, check.status === "passed");
+            draw(renderCheckEnd(check, style, width));
+        },
+        onFinish(result) {
+            release(renderSummary(result, style));
+        },
+        onInterrupt() {
+            // Clear the block first so the message lands above it, not inside it (or on top of
+            // the ^C the terminal echoed below it); the redrawn block then says it is stopping.
+            if (state) {
+                state.stopping = true;
+                terminal.write(clear());
+                drawn = 0;
+            }
+            terminal.writeError(style.yellow(STOPPING_MESSAGE));
+            draw();
+        },
+        dispose() {
+            release();
+        },
+    };
+}
+/** The real terminal behind stdout. */
+export function systemTerminal(write, writeError, stream) {
+    return {
+        write,
+        writeError,
+        columns: () => stream.columns || 80,
+        rows: () => stream.rows || 24,
+        now: () => performance.now(),
+        every(ms, frame) {
+            const timer = setInterval(frame, ms);
+            timer.unref();
+            return () => clearInterval(timer);
+        },
+        onExit(restore) {
+            process.once("exit", restore);
+            return () => process.off("exit", restore);
+        },
+    };
+}

package/dist/reporters/plan.js

@@ -1,3 +1,4 @@
+import { plain } from "./human.js";
 import { selectionLabel } from "./reporter.js";
 const STATUS_LETTER = {
     added: "A",
@@ -7,7 +8,7 @@ const STATUS_LETTER = {
     changed: "~",
 };
 /** Text rendering of a plan. `maxFiles` bounds the changed-file list. */
-export function renderPlan(selection, maxFiles) {
+export function renderPlan(selection, maxFiles, style = plain) {
     const skipped = selection.checks.filter((check) => !check.selected).length;
     const lines = [`Plan: ${selectionLabel(selection, skipped)}`];
     const files = selection.changes?.files;
@@ -16,12 +17,13 @@ export function renderPlan(selection, maxFiles) {
         for (const file of files.slice(0, maxFiles))
             lines.push(`  ${STATUS_LETTER[file.status]} ${file.path}`);
         if (files.length > maxFiles)
-            lines.push(`  … ${files.length - maxFiles} more (verifika plan --mode json lists all)`);
+            lines.push(`  … ${files.length - maxFiles} more (vfk plan --mode json lists all)`);
     }
     lines.push("Checks:");
     const width = Math.max(...selection.checks.map((check) => check.name.length));
     for (const check of selection.checks) {
-        lines.push(`  ${check.selected ? "run " : "skip"}  ${check.name.padEnd(width)}  ${check.reason}`);
+        const row = `${check.name.padEnd(width)}  ${check.reason}`;
+        lines.push(check.selected ? `  ${style.green("run ")}  ${row}` : style.dim(`  skip  ${row}`));
     }
     return `${lines.join("\n")}\n`;
 }

package/dist/reporters/reporter.js

@@ -1,5 +1,7 @@
 import { formatSeconds } from "../format.js";
 export const OUTPUT_MODES = ["human", "agent", "json", "quiet"];
+/** Printed to stderr in human mode on the first interrupt. */
+export const STOPPING_MESSAGE = "stopping… (Ctrl-C again to force)\n";
 /** Previews are shown for at most this many failed checks, to keep output bounded. */
 export const MAX_PREVIEWED_FAILURES = 3;
 export function isFailureStatus(status) {
@@ -28,9 +30,31 @@ export function logsHint(result) {
     const withLogs = problems(result).filter((check) => isFailureStatus(check.status) && check.log);
     if (withLogs.length === 0)
         return null;
-    const command = withLogs.length === 1 ? `verifika logs ${withLogs[0]?.name}` : "verifika logs --failed";
+    return logsCommand(result, withLogs.length === 1 ? (withLogs[0]?.name ?? "") : "--failed");
+}
+/** `vfk logs <target>`, naming the run when a later run has become the latest. */
+function logsCommand(result, target) {
+    const command = `vfk logs ${target}`;
     return result.latest ? command : `${command} --run ${result.runId}`;
 }
+/**
+ * Decides which failed checks get their preview printed: at most
+ * MAX_PREVIEWED_FAILURES, in config order. The rest get a note pointing at their
+ * log, so a hidden preview never looks like one that found nothing.
+ */
+export function previewDecider(result) {
+    let previewed = 0;
+    return (check) => {
+        if (!isFailureStatus(check.status) || check.preview.length === 0) {
+            return { show: false, note: "" };
+        }
+        if (previewed < MAX_PREVIEWED_FAILURES) {
+            previewed++;
+            return { show: true, note: "" };
+        }
+        return { show: false, note: ` (preview omitted: ${logsCommand(result, check.name)})` };
+    };
+}
 export function verdict(result) {
     return result.status === "passed"
         ? "PASS"

package/dist/runner.js

@@ -1,6 +1,7 @@
 import { constants } from "node:os";
 import path from "node:path";
 import { formatSeconds } from "./format.js";
+import { LastLine } from "./preview.js";
 import { execCheck } from "./process.js";
 import { createRun, logPath, pruneRuns, readLatest, releaseRun, writeRunResult } from "./runs.js";
 import { schedule } from "./scheduler.js";
@@ -47,6 +48,7 @@ export async function runVerification(options) {
         selection,
         selected: selected.map((check) => check.name),
         concurrency: options.concurrency,
+        dependsOn: Object.fromEntries(selected.map((check) => [check.name, check.dependsOn])),
     });
     const env = { ...(options.env ?? process.env), VERIFIKA: "1", VERIFIKA_RUN_ID: runId };
     let firstFailure = null;
@@ -54,6 +56,11 @@ export async function runVerification(options) {
         const check = byName.get(task.name);
         reporter.onCheckStart?.(check.name);
         const log = logPath(runId, check.name);
+        const onCheckOutput = reporter.onCheckOutput?.bind(reporter);
+        const followers = onCheckOutput && {
+            stdout: new LastLine((line) => onCheckOutput(check.name, line)),
+            stderr: new LastLine((line) => onCheckOutput(check.name, line)),
+        };
         const outcome = await execCheck({
             command: check.command,
             cwd: root,
@@ -62,6 +69,7 @@ export async function runVerification(options) {
             logFile: path.join(root, log),
             previewLines: options.previewLines,
             signal,
+            ...(followers ? { onOutput: (stream, text) => followers[stream].write(text) } : {}),
         });
         const checkResult = completedResult(results.get(check.name), check, outcome, log);
         results.set(check.name, checkResult);
@@ -172,7 +180,12 @@ function completedResult(base, check, outcome, log) {
 }
 function notRunResult(base, outcome, interrupted, firstFailure) {
     if (outcome.state === "blocked") {
-        return { ...base, status: "blocked", reason: `dependency ${outcome.dependency} did not pass` };
+        return {
+            ...base,
+            status: "blocked",
+            reason: `dependency ${outcome.dependency} did not pass`,
+            blockedBy: outcome.dependency,
+        };
     }
     if (outcome.state !== "not_started")
         return null;

package/dist/runs.js

@@ -155,10 +155,49 @@ function isProcessAlive(pid) {
         return error.code === "EPERM";
     }
 }
+/**
+ * Estimates the time saved by skipping `names`: each check's duration in the most
+ * recent retained run where it ran to completion (passed or failed).
+ */
+export async function estimateSkipped(root, names) {
+    const found = new Map();
+    let runs = [];
+    try {
+        runs = (await readdir(path.join(root, STATE_DIR, RUNS_DIR)))
+            .filter((name) => RUN_ID_PATTERN.test(name))
+            .sort()
+            .reverse();
+    }
+    catch {
+        // No runs yet: nothing is known.
+    }
+    const wanted = new Set(names);
+    for (const id of runs) {
+        if (found.size === wanted.size)
+            break;
+        let run;
+        try {
+            run = JSON.parse(await readFile(path.join(runDirectory(root, id), RESULT_FILE), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        for (const check of run.checks ?? []) {
+            if (wanted.has(check.name) &&
+                !found.has(check.name) &&
+                (check.status === "passed" || check.status === "failed") &&
+                typeof check.durationMs === "number") {
+                found.set(check.name, check.durationMs);
+            }
+        }
+    }
+    const knownMs = [...found.values()].reduce((total, ms) => total + ms, 0);
+    return { knownMs, unknown: wanted.size - found.size };
+}
 export async function readRun(root, runId) {
     const id = runId ?? (await readLatest(root));
     if (id === null) {
-        throw new VerifikaError("no verification runs recorded yet", "Run `verifika` first.");
+        throw new VerifikaError("no verification runs recorded yet", "Run `vfk` first.");
     }
     if (!RUN_ID_PATTERN.test(id))
         throw new VerifikaError(`invalid run id "${id}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verifika",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Deterministic, agent-friendly repository verification: run the checks your changes need, concurrently, with minimal output.",
   "keywords": [
     "verify",
@@ -51,8 +51,8 @@
     "test": "vitest run",
     "test:pack": "node scripts/pack-smoke.mjs",
     "check:skill": "node scripts/check-skill.mjs",
-    "verifika": "node src/cli.ts",
-    "verify": "node src/cli.ts --all",
+    "verify": "node src/cli.ts",
+    "verify:ci": "node src/cli.ts --all",
     "prepack": "npm run build"
   },
   "dependencies": {

package/skills/verifika/SKILL.md

@@ -10,37 +10,37 @@ Verifika runs a repository's configured checks (lint, typecheck, tests, build, .
 
 ## Is it set up here?
 
-Look for `verifika.config.json` in the repository root (or the package directory in a monorepo). Its `checks` object lists every check name and command. Run the CLI the way the repository does: `npx verifika` when it is a devDependency, `verifika` when installed globally, or a documented wrapper script such as `npm run verify`. The examples below write `verifika`.
+Look for `verifika.config.json` in the repository root (or the package directory in a monorepo). Its `checks` object lists every check name and command. Run the CLI the way the repository does: `npx vfk` when it is a devDependency, `vfk` when installed globally, or the repository's scripts. Projects set up with the init command have `npm run verify` (runs `vfk`: selective) and `npm run verify:ci` (runs `vfk --all`: the full gate). `npm run verify` is not the full gate. `vfk` is short for `verifika`; both commands are identical. The examples below write `vfk`.
 
 ## Workflow
 
 1. **While implementing**, after a meaningful change:
 
    ```sh
-   verifika
+   vfk
    ```
 
-   Runs only the checks matching files changed since the configured `changes.base` (by default `HEAD`: your uncommitted and untracked changes). If the environment sets `CI` (some agent sandboxes do), plain `verifika` runs everything; use `verifika --changed` for a selective run there.
+   Runs only the checks matching files changed since the configured `changes.base` (by default `HEAD`: your uncommitted and untracked changes). If the environment sets `CI` (some agent sandboxes do), plain `vfk` runs everything; use `vfk --changed` for a selective run there.
 
 2. **To see what would run and why**, without running anything:
 
    ```sh
-   verifika plan
+   vfk plan
    ```
 
 3. **To rerun one check** while fixing it (its dependencies run too):
 
    ```sh
-   verifika --check typecheck
+   vfk --check typecheck
    ```
 
-4. **Before claiming the task is complete, committing, or opening a pull request**, always run the full suite:
+4. **Before claiming the task is complete, committing, or opening a pull request**, always run the full suite (`npm run verify:ci` where that script exists):
 
    ```sh
-   verifika --all
+   vfk --all
    ```
 
-5. **To verify a whole branch** rather than just uncommitted work: `verifika --changed-since origin/main` (compares against the merge-base, plus uncommitted and untracked files). Useful for review; it does not replace `verifika --all` before delivery.
+5. **To verify a whole branch** rather than just uncommitted work: `vfk --changed-since origin/main` (compares against the merge-base, plus uncommitted and untracked files). Useful for review; it does not replace `vfk --all` before delivery.
 
 Wait for the command to finish. Long suites can take minutes; allow enough time and never report a result you have not seen.
 
@@ -59,7 +59,22 @@ On failure, one line per problem, a short preview, and the command for full logs
 FAIL 3/4 (3.2s) full run (--all)
 typecheck: exit 2
   src/cart.ts(14,7): error TS2322: Type 'string' is not assignable to type 'number'.
-Run: verifika logs typecheck
+Run: vfk logs typecheck
+```
+
+Previews are shown for at most three failed checks. Any further failed check says where its output is instead:
+
+```text
+FAIL 1/5 (9.8s) full run (--all)
+format: exit 1
+  [warn] src/cart.ts
+lint: exit 1
+  /repo/src/cart.ts
+    12:9  error  'total' is assigned a value but never used  no-unused-vars
+typecheck: exit 2
+  src/cart.ts(14,7): error TS2322: Type 'string' is not assignable to type 'number'.
+test: exit 1 (preview omitted: vfk logs test)
+Run: vfk logs --failed
 ```
 
 | Exit code | Meaning                                                                |
@@ -75,18 +90,18 @@ Check statuses: `passed`, `failed`, `timed_out`, `error` (could not start, or le
 ## When verification fails
 
 1. Read the failing check names and previews first; they usually identify the problem.
-2. If you need more, read only the failing logs: `verifika logs typecheck`, or `verifika logs --failed` for all of them. For long logs use `verifika logs typecheck --tail 80`.
-3. Fix the root cause in the code. Then rerun the failed check (`verifika --check typecheck`), and finish with `verifika --all`.
+2. If you need more, read only the failing logs: `vfk logs typecheck`, or `vfk logs --failed` for all of them. For long logs use `vfk logs typecheck --tail 80`.
+3. Fix the root cause in the code. Then rerun the failed check (`vfk --check typecheck`), and finish with `vfk --all`.
 4. `blocked` checks never ran; fix the dependency they name and rerun.
 5. If a failure is unrelated to your change (for example it also fails on the base branch), report it with evidence instead of working around it.
 
 ## Rules
 
 - Do not claim success unless you saw `PASS` and exit code 0 from a finished run. Say what ran: "selective verification passed (2 checks)" is not "all checks pass".
-- A selective `PASS` only covers the checks it selected. Skipped checks were not verified. Run `verifika --all` before delivery, every time.
+- A selective `PASS` only covers the checks it selected. Skipped checks were not verified. Run `vfk --all` (or `npm run verify:ci`) before delivery, every time; `npm run verify` is selective and does not count.
 - `PASS 0/0` means nothing matched your changes and nothing was verified.
-- Do not read logs of passing checks or use `verifika logs` after a `PASS`; there is nothing to diagnose.
+- Do not read logs of passing checks or use `vfk logs` after a `PASS`; there is nothing to diagnose.
 - Do not edit `verifika.config.json`, remove checks, narrow `paths`, raise timeouts, or pass `--check` to dodge a failing check, unless the user asked for that change.
 - Exit code 2 is not a code failure: read the message (bad flag, unknown check, invalid config, missing git ref) and fix the invocation, or report it.
 - Do not raise concurrency (`-j`) beyond what the config sets: the project chose it, and checks that share build outputs fail spuriously when run together.
-- Prefer the default agent output. Use `verifika --mode json` only when a script needs structured results; avoid `verifika --mode human` in agent sessions.
+- Prefer the default agent output. Use `vfk --mode json` only when a script needs structured results; avoid `vfk --mode human` in agent sessions.