Imported from vaam-apps/vpay-skills (skills/vpay-tooling/SKILL.md). Install upstream with npx skills add vaam-apps/vpay-skills --skill vpay-tooling. Copyright stays with the author.

vpay tooling and gates

Verified against vpay 0799a8d2 (2026-09-18). Version-sensitive claims below carry the date they became true — a feature in vpay's master may be absent from the tree you are editing. On an older or newer vpay, trust the repository over this page. See VERSIONING.md.

just is the entry point for everything. justfile is ~4700 lines and about two-thirds comment (2026-09-16) — the recipes are buried in prose. Do not read it top to bottom; just --list counts them for you.

just --list                 # every recipe, with its last comment line
just --show ci              # one recipe, body and dependencies, authoritative
just --evaluate             # every variable: ports, versions, expected counts

The authority rule — read this first

The recipe body wins. Over its own comment, over AGENTS.md, over CLAUDE.md, over package.json prose. This repository documents itself exhaustively and the prose drifts faster than anything else in it. Always confirm with just --show <recipe> or just --evaluate before you act on a sentence.

A live example, measured 2026-09-16 on master:

Two more sat here until 2026-09-16 and have been fixed — audit-web's comment and AGENTS.md said it was not in just ci and that just ci ran offline, and audit-web's comment and package.json said --audit-level=high. Both had been wrong since 2026-09-11, when issue #103 changed the recipe and nobody re-read the prose around it. They are named here rather than deleted because they are what this rule was worth: reading the recipe found two false statements about what CI runs, five days after the change that falsified them.

What is true now: audit-web is in just ci, it runs at --audit-level=moderate so moderates fail, and just ci therefore needs the network.

A stale comment is not a bug to fix in passing — these are separate branches' comments that never got re-read. Treat them as a warning about the next one you have not found yet.

The inverse habit is also house style here and worth copying: when you correct a claim, say what it said before and date it. A silent correction tells a later reader nothing about which sentences have been checked.

just ci — the exact chain

ci: fmt-check clippy verify test-rust test-doc verify-ignored lint-web test-web audit-web deny

In execution order:

1. cargo fmt --all -- --check
2. pnpm exec prettier --check .
3. cargo clippy --workspace --all-targets -- -D warnings
4. just verify — the fourteen gates plus the verify-docs report
5. cargo nextest run --workspace
6. cargo test --doc --workspace — a second runner; nextest runs no doctests
7. just verify-ignored — the suite census
8. just lint-web — pnpm -r typecheck, then pnpm -r lint
9. pnpm -r test
10. just audit-web — two pnpm audit runs, needs the network
11. cargo deny check

Step 2 is prettier over the working tree, not the index, so an untracked scratch .ts/.md/.json fails just ci in its first seconds. So does a tree where pnpm install has not been run.

AGENTS.md requires just ci to pass locally before review.

just verify — the fourteen gates

Fourteen since 2026-09-18 — thirteen from 2026-09-17 (verify-versions, PR #201), twelve before that. Twelve are cargo xtask subcommands; check-schema and verify-ui are shell in the justfile. The order is chronological by landing date on purpose, so that "check-schema is the seventh gate" — which four other files say — stays true when a gate is added.

verify-docs runs last and is not a gate — it exits 0 whatever it finds. That is deliberate: the cheapest way to pass a doc-ratio gate is to delete the # Errors and # Panics sections.

Full detail, and how contributors trip each one, in references/gates.md.

The day-to-day loop

just fmt                 # cargo fmt --all + prettier --write .
just test-rust           # cargo nextest run --workspace       (needs Docker)
just test-doc            # cargo test --doc --workspace
just test-web            # pnpm -r test
just docs-check          # verify-status + verify-links, offline, seconds
just verify-ui           # the UI greps alone, no build
just ci                  # before you open anything

Subsets: cargo nextest run -p <crate>, cargo nextest run -E 'test(name)', pnpm --filter <pkg> test. Every recipe inventory detail is in references/recipes.md.

What each thing needs

Gates outside just verify and outside just ci: test-storybook, helm-check, docs-check-citations. CI runs all three on every PR, so a green local run does not predict them. audit-web is outside just verify but inside just ci (since 2026-09-11, issue #103) — which is why just ci needs the network.

Lockstep bumps

Change one of these and the other must move in the same commit.

verify-toolchain exists because the drift was measured: with channel moved to 1.98.0 and the Dockerfile left on 1.95.0, the whole of just ci was green. CI reads the channel out of rust-toolchain.toml with an anchored sed in five jobs, so reformatting that line breaks CI.

Flutter, .agents/skills/, and a dead MSISDN convention

Three facts with no home above, kept short here on purpose — depth is in references/recipes.md.

• Six *flutter* recipes (install-flutter, analyze-flutter, test-flutter, test-flutter-web, test-flutter-e2e, test-flutter-emulator) build and test vpay_checkout_flutter (vpay-sdks owns what the package does). All six share one _flutter-preflight and none is in just ci (D-M3) — every count quoted for this package is a human running the recipe by hand. flutter-toolchain.toml pins Flutter 3.47.2 / Dart 3.13.2, unenforced (see the Lockstep table above).
• .prettierignore's .agents/skills/ entry excludes vpay's own vendored agent skills (installed by issue #188 from cratestack/cratestack-skills, hash-pinned in vpay's skills-lock.json) — a different, unrelated skills/ from this repository. Reformatting a vendored copy would change the bytes the lock file hashes; do not "fix" a lint complaint under that path.
• A hex-suffixed MSISDN no longer steers WireMock (2026-09-17, #191): server-side phone validation (#186) rejects it before the mock rail is ever asked. worker_e2e/worker_kill9 and examples/shop's demo table now use real, phonenumber-valid Cameroon numbers matching 2376[579]\d{7}.

Further reading

• references/gates.md — the fourteen gates in depth, including every verify-ui check (its numbering is non-contiguous, so count the recipe's greps rather than trusting its header) and the both-directions gates.
• references/recipes.md — the full recipe inventory, the compose layering and ports, the demo-stack traps, and the .env rules.
• references/ci.md — the three workflows, changes path gating, the readiness-poll lore, the audit-web retry loop, and the testcontainers serialisation in .config/nextest.toml.