verifika 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/). The CLI flags, exit codes, configuration format (`version: 1`) and JSON output (`schemaVersion: 1`) are the public API.
 
+## [0.0.2] - 2026-10-12
+
+### Changed
+
+- `vfk` is now the advertised command: `--help`, run hints (`Run: vfk logs <check>`), error hints, the README, the docs and the agent skill use it. `verifika` keeps working and is identical.
+
+### Added
+
+- README: a copy-paste prompt that has a coding agent install Verifika, write and validate a config, and install the skill.
+
 ## [0.0.1] - 2026-10-12
 
 First public release.
@@ -27,4 +37,5 @@ First public release.
 - A process that deliberately detaches from the check (on Linux and macOS: leaves the process group, for example via `setsid`; on Windows: breaks away from the job with an exited intermediate parent) is not tracked unless it keeps the check's output open, in which case the check is reported as `error`.
 - On Windows, confirming cleanup queries the process table with PowerShell after each check, which costs roughly 0.5–3 s per check.
 
+[0.0.2]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.2
 [0.0.1]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.1

package/README.md

@@ -4,56 +4,91 @@
 [![Release](https://img.shields.io/github/v/release/alexportelli12/verifika)](https://github.com/alexportelli12/verifika/releases/latest)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Run the checks your changes need, concurrently, with minimal output.
+**Run only the checks your change needs. Get one line back when they pass.**
 
-Verifika is a small CLI for repository verification. You declare your checks (lint, typecheck, tests, build, ...) in `verifika.config.json`. Locally, Verifika runs only the checks affected by your changes; in CI it runs everything. Successful runs print one line, failures print exactly what failed and how to see the full logs. It works the same for developers, CI pipelines and AI coding agents (Claude Code, Codex, OpenCode, and others).
+Every repository has a verification gate: format, lint, typecheck, tests, build. Using it well is harder than it looks:
+
+- **Running everything is slow.** A one-line fix waits minutes for checks it cannot affect, so people (and agents) skip the gate or batch changes until the end.
+- **Picking checks by hand is unreliable.** It is easy to forget the one that breaks, and "it passed" stops meaning much.
+- **Failures are buried in noise.** A test runner can print tens of thousands of lines to report one failed assertion. A coding agent pays for every line in tokens and context, and often never reaches the line that matters.
+
+Verifika fixes this with one config file and one command. You list your checks in `verifika.config.json`, with the files each one covers. Then `vfk` runs only the checks your changes affect, CI runs all of them, and the output says exactly what failed:
 
 ```text
-$ verifika
+$ vfk
 PASS 3/3 (4.1s) selective: 2 files changed since HEAD (a1b2c3d); 2 skipped
 
-$ verifika --all
+$ vfk --all
 FAIL 4/5 (12s) 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
 ```
 
-_Verifika_ is Maltese for "verification".
+## Why Verifika
 
-## Why
+- **Small output, especially for agents.** On a real Angular project, one failing test produced 94,900 bytes of output with the project's previous verify script (~23,700 tokens). Verifika reported the same failure in 369 bytes (~90 tokens): the test name, the assertion and the totals. Full logs stay on disk until you ask for them.
+- **Less waiting.** Locally, only affected checks run: in a 25-check monorepo, a typical edit ran 1–13 of them. Checks that share no build outputs can also run in parallel; on that Angular project, four at a time cut the full gate from 95.5 s to 61.7 s. [Measurements](docs/benchmarks.md).
+- **Deterministic and conservative.** Selection comes from your config, file globs, dependencies and git; no heuristics, no LLM. When the scope of a change is unclear, Verifika runs everything or fails loudly. It never quietly skips a check, and in CI it runs the full suite unless you explicitly ask for a selective run.
+- **Trustworthy results.** Timeouts, fail-fast, correct exit codes and signal handling. A check only passes once its whole process tree has exited. Tested on Linux, macOS and Windows.
+- **Built for humans and coding agents alike.** Live progress on a terminal, one line in agent sessions, JSON for scripts. It ships an [agent skill](skills/verifika/SKILL.md) for Claude Code, Codex, OpenCode and others.
+- **Small.** One JSON file, one runtime dependency, no daemon, no cache to invalidate.
 
-- **Deterministic.** Check selection comes from your config, file globs, dependencies and git. No heuristics, no LLM. When the change scope is unclear, Verifika runs everything or fails loudly; it never quietly skips a check.
-- **Token-efficient.** Agents get one line on success and a bounded failure preview on failure. Full logs stay on disk until asked for.
-- **Fast.** Selective runs skip unaffected checks, and independent checks can run in parallel once you opt in (`defaults.concurrency`). One small runtime dependency.
-- **Reliable.** Timeouts, fail-fast, process cleanup, correct exit codes and signal handling, tested on Linux, macOS and Windows.
+_Verifika_ is Maltese for "verification". The command is `vfk`, short for `verifika`; both are installed and identical.
 
-## Install
+## Get started
 
 Requires Node.js 22.13 or newer.
 
-```sh
-npm install --save-dev verifika
-```
+### With a coding agent
 
-The package installs two commands: `verifika` and its shorthand `vfk`. They are the same program, so use whichever you prefer:
+Paste this prompt into Claude Code, Codex, OpenCode or another coding agent, from your repository root. It installs Verifika, writes and validates a config for your project, and reports what it found.
 
-```sh
-npx verifika plan    # same as: npx vfk plan
-npx vfk --all        # same as: npx verifika --all
+```text
+Set up Verifika (https://github.com/alexportelli12/verifika) in this repository.
+
+1. Check that Node.js is 22.13 or newer, and install the project's dependencies if
+   they are missing. Install Verifika as a dev dependency with this repository's
+   package manager (npm install --save-dev verifika, or the pnpm/yarn equivalent).
+   It provides the `vfk` command.
+2. Run `npx vfk init` to create verifika.config.json, then refine it by reading
+   package.json, the CI workflows and the tool configs:
+   - One check per quality gate the project actually has (such as format, lint,
+     typecheck, unit tests, build). Do not invent checks for tools it does not use,
+     or add a check that another one already fully covers. Every command must be
+     non-interactive and exit on its own: no watch mode, no prompts, no dev servers.
+   - Give each check `paths` globs for the files that can affect it, so local runs
+     select only what a change needs. If unsure, leave `paths` out: the check then
+     runs on every change.
+   - Add `dependsOn` where one check needs another's output (for example e2e after build).
+   - Keep concurrency at 1 unless the checks clearly share no build outputs.
+   - If package.json has no "verify" script, add "verify": "vfk --all".
+   Reference: https://github.com/alexportelli12/verifika/blob/main/docs/configuration.md
+3. Validate the config:
+   - Run `npx vfk --all`. If a check fails, decide whether the config is wrong (fix it)
+     or the project already fails that check (report it; do not fix it).
+   - Run `npx vfk plan`. Until this setup is committed, the changed package.json and
+     lockfile select every check; that is expected. Explain which checks a typical
+     source edit and a documentation-only edit would select once it is committed.
+4. Install the agent skill: copy node_modules/verifika/skills/verifika into this
+   agent's skills directory (see
+   https://github.com/alexportelli12/verifika/blob/main/docs/agents.md).
+
+Do not change source code or existing scripts to make checks pass, and do not commit.
+Finish with: the checks you configured and why, the --all result, the expected
+selection for those two edits, and any existing failures you found.
 ```
 
-The docs use `verifika` throughout. To install it globally instead, run `npm install --global verifika`; to try it without installing, run `npx verifika --help`.
-
-## Quick start
+Review the config it writes before committing it: the commands in it run on every verification.
 
-Generate a starter config from your `package.json` scripts:
+### By hand
 
 ```sh
-npx verifika init
+npm install --save-dev verifika
+npx vfk init     # creates verifika.config.json from your package.json scripts
 ```
 
-Or write `verifika.config.json` yourself:
+`init` only maps conventional script names (`lint`, `test`, `build`, ...) and leaves every check unfiltered, so open the file and give each check `paths`:
 
 ```json
 {
@@ -72,35 +107,35 @@ Or write `verifika.config.json` yourself:
 }
 ```
 
-If your repository checks the formatting of every file (for example `prettier --check .`), format the new `verifika.config.json` too.
-
-Then:
+If your repository checks the formatting of every file (for example `prettier --check .`), format the new `verifika.config.json` too. Then:
 
 ```sh
-npx verifika plan     # which checks would run for your changes, and why
-npx verifika          # run them
-npx verifika --all    # run everything (do this before you push)
+npx vfk plan     # which checks would run for your changes, and why
+npx vfk          # run them
+npx vfk --all    # run everything (do this before you push)
 ```
 
 Add a script so everyone runs the same full gate:
 
 ```json
-{ "scripts": { "verify": "verifika --all" } }
+{ "scripts": { "verify": "vfk --all" } }
 ```
 
+Run logs go to `.verifika/`, which ignores itself in git, so you do not need to edit `.gitignore`. To install globally instead, run `npm install --global verifika`.
+
 ## How checks are selected
 
-| Situation                                      | What runs                                                                                                           |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `verifika` locally                             | Checks whose `paths` match files changed since `changes.base` (default `HEAD`: your uncommitted and untracked work) |
-| `verifika` in CI (`CI` or a known CI variable) | Everything; only `--changed`/`--changed-since` on the command line can narrow it                                    |
-| `verifika --all`                               | Everything                                                                                                          |
-| `verifika --check lint`                        | `lint` and its dependencies                                                                                         |
-| `verifika --changed-since origin/main`         | Checks matching files changed since `merge-base(origin/main, HEAD)`, plus uncommitted and untracked files           |
-| A changed file matches `invalidateAll`         | Everything                                                                                                          |
-| Git unavailable, no commits, unknown base      | Everything, with the reason printed (or an error, when you asked for `--changed`/`--changed-since` explicitly)      |
+| Situation                                 | What runs                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `vfk` locally                             | Checks whose `paths` match files changed since `changes.base` (default `HEAD`: your uncommitted and untracked work) |
+| `vfk` in CI (`CI` or a known CI variable) | Everything; only `--changed`/`--changed-since` on the command line can narrow it                                    |
+| `vfk --all`                               | Everything                                                                                                          |
+| `vfk --check lint`                        | `lint` and its dependencies                                                                                         |
+| `vfk --changed-since origin/main`         | Checks matching files changed since `merge-base(origin/main, HEAD)`, plus uncommitted and untracked files           |
+| A changed file matches `invalidateAll`    | Everything                                                                                                          |
+| Git unavailable, no commits, unknown base | Everything, with the reason printed (or an error, when you asked for `--changed`/`--changed-since` explicitly)      |
 
-A check without `paths` runs whenever any file changed; `"always": true` runs it even when nothing changed. Selecting a check also selects its `dependsOn` checks. `verifika plan` shows every decision.
+A check without `paths` runs whenever any file changed; `"always": true` runs it even when nothing changed. Selecting a check also selects its `dependsOn` checks. `vfk plan` shows every decision.
 
 ## Output modes
 
@@ -120,10 +155,10 @@ Exit codes: `0` passed (or nothing to verify), `1` verification failed, `2` usag
 Every run stores each check's combined stdout/stderr under `.verifika/runs/<run-id>/`. The directory ignores itself in git, and only the last 10 runs are kept (`defaults.keepRuns`).
 
 ```sh
-verifika logs                    # latest run: statuses and log paths
-verifika logs typecheck          # full log of one check
-verifika logs --failed           # logs of every failed check
-verifika logs test --tail 50     # last 50 lines
+vfk logs                  # latest run: statuses and log paths
+vfk logs typecheck        # full log of one check
+vfk logs --failed         # logs of every failed check
+vfk logs test --tail 50   # last 50 lines
 ```
 
 Logs contain whatever your commands print, which can include secrets. They never leave your machine; keep `.verifika/` out of anything you publish.

package/dist/config.js

@@ -30,7 +30,7 @@ export function findConfigFile(cwd, explicit) {
             return candidate;
         const parent = path.dirname(directory);
         if (parent === directory) {
-            throw new VerifikaError(`no ${CONFIG_FILE} found in ${cwd} or any parent directory`, "Create one with: verifika init");
+            throw new VerifikaError(`no ${CONFIG_FILE} found in ${cwd} or any parent directory`, "Create one with: vfk init");
         }
         directory = parent;
     }

package/dist/main.js

@@ -16,15 +16,14 @@ import { OUTPUT_MODES } from "./reporters/reporter.js";
 import { runVerification } from "./runner.js";
 const COMMANDS = ["run", "plan", "logs", "init", "help"];
 const DEFAULT_PREVIEW_LINES = 10;
-export const HELP = `verifika - run the checks your changes need, with minimal output
+export const HELP = `vfk - run the checks your changes need, with minimal output
+(vfk is short for verifika; the two commands are identical)
 
 Usage:
-  verifika [run] [options]        Verify (selective locally, full in CI)
-  verifika plan [options]         Show which checks would run and why
-  verifika logs [check...]        Show logs from the latest run
-  verifika init [--force]         Create verifika.config.json from package.json scripts
-
-vfk is a shorthand for verifika: vfk plan, vfk --all, ...
+  vfk [run] [options]             Verify (selective locally, full in CI)
+  vfk plan [options]              Show which checks would run and why
+  vfk logs [check...]             Show logs from the latest run
+  vfk init [--force]              Create verifika.config.json from package.json scripts
 
 Selection (run, plan):
       --all                       Run every check
@@ -192,7 +191,7 @@ async function runInit(io, values) {
     const root = values.config ? path.dirname(path.resolve(io.cwd, values.config)) : io.cwd;
     const { file, checks } = await initConfig(root, Boolean(values.force));
     io.out(`Created ${path.relative(io.cwd, file) || file} with checks: ${checks.join(", ")}\n`);
-    io.out('Review the commands, add "paths" to checks that only some files affect, format the file if your repository checks formatting, then run: verifika plan\n');
+    io.out('Review the commands, add "paths" to checks that only some files affect, format the file if your repository checks formatting, then run: vfk plan\n');
     return ExitCode.Passed;
 }
 function parse(args, command) {
@@ -208,7 +207,7 @@ function parse(args, command) {
     }
     catch (error) {
         const message = error.message.replace(/\. To specify a positional argument.*$/s, "");
-        throw new VerifikaError(message, `Run "verifika --help" for usage.`);
+        throw new VerifikaError(message, `Run "vfk --help" for usage.`);
     }
 }
 function integerOption(value, flag, min) {

package/dist/reporters/agent.js

@@ -13,7 +13,7 @@ export function renderAgent(result) {
         `${verdict(result)} ${summary.passed}/${summary.selected} (${duration(result.durationMs)}) ${selectionLabel(result.selection, summary.skipped)}`,
     ];
     if (summary.selected === 0)
-        lines.push("Nothing to verify for these changes. Full run: verifika --all");
+        lines.push("Nothing to verify for these changes. Full run: vfk --all");
     let previewed = 0;
     for (const check of problems(result)) {
         lines.push(`${check.name}: ${describeProblem(check)}`);

package/dist/reporters/human.js

@@ -30,7 +30,7 @@ export function humanReporter(output, style, options = {}) {
             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"));
+                output.out(style.dim("Nothing to verify for these changes. Full run: vfk --all\n"));
                 return;
             }
             if (skipped > 0) {

package/dist/reporters/plan.js

@@ -16,7 +16,7 @@ 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));

package/dist/reporters/reporter.js

@@ -28,7 +28,7 @@ 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";
+    const command = withLogs.length === 1 ? `vfk logs ${withLogs[0]?.name}` : "vfk logs --failed";
     return result.latest ? command : `${command} --run ${result.runId}`;
 }
 export function verdict(result) {

package/dist/runs.js

@@ -158,7 +158,7 @@ function isProcessAlive(pid) {
 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.2",
   "description": "Deterministic, agent-friendly repository verification: run the checks your changes need, concurrently, with minimal output.",
   "keywords": [
     "verify",

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 a documented wrapper script such as `npm run verify`. `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:
 
    ```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.
 
@@ -75,18 +75,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` before delivery, every time.
 - `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.