What a clean check means

Summary#

osy validate runs offline: no server, no database, no account. That is what makes it quick enough to run on every save — and it means a few checks genuinely cannot run there, because they need state that only exists when the app is compiled. A clean run lists them rather than implying it checked everything.

Signature#

osy validate [path] [--json]

Description#

A successful run ends with the checks that did not happen:

✓ Validated successfully (4 entities, 7 functions)
  ⓘ 10 checks run only on a server compile:
    • app.Config settings resolved against .env.development / .env.production
    • the app.Config plaintext-secret warning
    • app.Audit surfaces resolved against the audit baseline entities
    • agent `Skills` / runbook `Uses` against the committed skill catalog
    …and 6 more — osy validate --json lists them all.

Each line names a kind of check, not a count, because a count is not something you can act on. The point is to tell you when a local green is not the whole answer: if you have just edited app.Config, added a control, or wired an agent to a skill, that is the moment to run a real compile.

Everything else osy validate reports is held to exact agreement with the server — the same rule, from the same code, in the same words. The list above is the residue, and it is deliberately small.

Why these need a compile#

They all read something that does not exist until the app is built:

• .env values — a setting with no Default takes its value from .env.development / .env.production, and an .env key naming no declared setting is an error. Neither file is in scope for a source check. See per-environment config (app.Config).
• Committed rows — an agent's Skills, a runbook's Uses, and app.Audit surfaces resolve against rows the compile writes. A skill catalogue holds skills your source does not declare, so checking locally would report an unknown skill for one that exists.
• osyrin.lock — whether a control has a package pinned, and whether each chunks { } entry has a file. An unpinned control fails in the browser and nowhere else.
• Metadata the platform owns — [Id(...)] directives, [Test(...)] fixture links, counter scopes shared across entities.

Examples#

osy validate                 # the whole project, with the footer
osy validate --json          # every skipped check, with a stable id and a reason

For tooling, the JSON carries a notCheckedHere array — on failing runs too, because a run that is about to go green means no more than the one that just did:

osy validate --json | jq '.notCheckedHere[] | .id'

See also#

The inner loop — where osy validate sits in the edit → check → run loop.

Compiling your app — the compile that performs the checks listed above.

Checking your app — osy lint, the maturity signal, beside these correctness ones.

per-environment config (app.Config) — app.Config and how a setting takes its value from .env.