Runtime

The runtime engine is for rules no single file can decide. It pairs ast-grep capture rules with a check.ts that receives the matches and returns findings.

This page covers what selects the engine and what using it involves. For the gating model in full, see Runtime rules; for the directory layout and the check.ts contract, Anatomy of a Rule.

What belongs here

Evidence that spans more than one file, or lies outside the files entirely:

• Every environment variable read in code is declared in .env.
• Every i18n key used in source exists in each locale file.
• An exported symbol nothing in the repository imports.
• A rule that has to read git metadata, resolve an alias, or follow a config chain.

Check the boundary before reaching for it. Correlating two things inside one file is still sg, and a rule about the words in a document is Vale. The runtime engine is for evidence that genuinely leaves the file, and it is the only engine that needs an account, so it is worth being sure.

Consistency across documents is the case people most often misfile. “No page may use this word” is Vale. “These twelve pages must agree on a term” needs to see all twelve, which makes it a runtime rule.

How a rule is put together

.taskless/rules/runtime/env-read/
    captures/*.yml     ast-grep rules narrowing which files the check looks at
    check.ts           receives those matches and returns findings
    .tests/            fixtures, in pass/ and fail/ buckets, each case a directory

The captures do the cheap work. If nothing matches, check.ts is never invoked. The check.ts then does the part no single-file engine can: hold two files at once, read git, look outside the repository.

Anatomy of a Rule has the contract in full: the metadata.taskless block, the (root, matches) signature and the Match and Finding shapes, why fixtures are directories, and the fixture, timeout, and verification demands the engine makes.

Why it needs an account

Because it executes code. Not because of what it can express, and not as a paid feature.

An sg or vale rule is inert data. Whatever is in it, the worst a bad one does is report something wrong, so those run with no login, no network, and nothing to verify, because there is nothing to verify.

A check.ts is a program that runs on your machine with your permissions. A rule file arriving in a pull request is code arriving in a pull request. So taskless check signs each check.ts, reconciles that signature with the Taskless service, and runs only what comes back verified. Anything else is reported as skipped, with the reason.

This means sg and vale rules are not a lesser version of anything. They are unexecuted, which is exactly why they need no verification.

What happens without an account

Nothing breaks. taskless check still runs every sg and vale rule. Each runtime rule it finds is listed as skipped, with the reason that it was not verified.

So a runtime rule you write today is inert until someone logs in. Worth saying plainly rather than letting it be discovered from a check that quietly reports nothing.

Security covers the verification model in full, including the CI enforcement backstop and the deliberate escape hatch for running rules unverified.

Authoring one

npx @taskless/cli agent create-runtime-rule

The runtime engine requires a Taskless Cloud account. The other three engines do not.