FAQ

FAQ

Does it modify my code?

No. There is no write API in 0.1. The inspector opens files read-only, and plan returns tasks with effects: [] and readOnly: true. A test asserts those literals still exist in the source, so removing the guarantee fails the build. See the security model.

Does it run my build, or my package manager?

No. Every file is read as text and matched against patterns. Dependencies come from parsing package.json as data. Nothing is imported, spawned, or installed, and there is no network call at any point.

Is it a linter?

No. A linter checks code against style and correctness rules inside files. This checks a repository against an architecture standard, mostly by looking at structure and configuration. They answer different questions and you want both.

Why does check exit 0 when my project is not compliant?

Because whether a finding should stop a pipeline is your policy. Exit 0 means the command ran, and compliant: false in the payload means the repository failed. Exit 2 is reserved for an invalid request: unknown profile, bad option, unreadable root. CI integration shows how to gate on the payload.

My score is 95% but the status says not compliant. Why?

Status depends only on blocking failures, and the score plays no part in it. One blocking failure makes a repository non-compliant at any score. The score measures distance from the standard, and the status measures whether something dangerous is missing. See Scoring and compliance.

A rule fails but my repository does the thing it asks for

Almost always a detection gap rather than a logic error. Run inspect first and confirm the signal is actually false, then read the pattern in the signal reference.

The three most common cases:

database.migrations fails. The path pattern is case-sensitive and expects Migrations/. A lowercase migrations/ is not detected.

A test rule fails. The signals look for UnitTests/, IntegrationTests/, and ArchitectureTests/ by name. Excellent tests in tests/Orders.Tests/ score zero on all three.

api.version-v1 fails. The detector wants a quoted literal containing /api/v1 with the leading slash inside the quotes. [Route("api/v1/orders")] misses, and so do routes assembled by concatenation.

Version 0.2's exception mechanism exists for the cases where you will not change the convention.

Why is inspection so narrow? Why not parse the C#?

Because a report is only useful if you can predict it from reading the source. A pattern you can look at is a pattern you can argue with, and when a result is wrong you can see exactly why in thirty seconds.

Parsing would be more accurate and would also introduce a compiler-shaped dependency, a much larger surface for hostile input, and results that are hard to explain when they disagree with you. Version 0.2 improves the tradeoff by adding per-rule evidence, so a signal reports where it looked, rather than by making detection cleverer and less predictable.

Can I use it for a stack that is not .NET?

Not usefully in 0.1. One profile ships, and it is a .NET one. The signals are also .NET-oriented, so a Java or Go repository would score near zero against everything.

The catalog format is not .NET specific, and adding a profile is a data change. Adding new signals is a code change. See Authoring a profile.

My service has no frontend. It can never be compliant

Correct, and that is the right answer. frontend.react is blocking, so an API-only service fails this profile permanently.

That is not a defect in your repository. It means the profile does not describe your system. The honest fix is a profile that does, not an exception on this one.

What is Kratos, and do I need it?

Kratos is the agent harness this provider is designed to be consumed by. You do not need it. The CLI works standalone, and the 1.0 integration is a future contract rather than a dependency. Mestre Yoda imports nothing from Kratos and knows nothing about its internals.

Why the name?

The project is a Golden Path advisor: it tells you what the standard is and where you have strayed from it, without doing the work for you. The Star Wars reference is not subtle, and the tool is not affiliated with anything Lucasfilm owns.

Why zero runtime dependencies?

It reads repositories other people wrote. A tool in that position should have the smallest possible supply-chain surface of its own. Everything needed is in the Node standard library, and a test asserts that dependencies and devDependencies are both absent from package.json.

Why Node 24 specifically?

The engines field pins >=24 <25. The code uses the built-in test runner and modern syntax, and pinning a single major means one behavior to reason about rather than a compatibility matrix nobody exercises.

Can I keep a private catalog for my company?

Profiles ship inside the package, and there is no external catalog path in 0.1. Fork the repository and maintain the catalog directory, or vendor the catalog and run from a clone. Either way, pin the profile digest in your pipeline so a catalog change cannot silently move a build result.

How do I know the standard has not changed under me?

Compare the profile digest, not the version. Any edit to a manifest, policy, recipe, or gate file changes the digest, including a typo fix that leaves the version alone. CI integration has the pinning step.

Can two runs give different answers for the same repository?

No, given the same catalog. Directory entries are sorted before the walk descends, rules keep manifest order, tasks sort by severity then id, and digests canonicalize JSON before hashing. Nothing reads the clock or generates a random value. A test runs plan twice and asserts deep equality.

inspect reports far fewer files than my repository has

Check three things. Skipped directories: .git, .idea, .next, .vscode, bin, coverage, dist, node_modules, obj. Note that bin is skipped for .NET build output, so source under a directory named bin is invisible. Then check inventory.skippedSymlinks, since a symlinked source tree inspects as nearly empty. Then compare inspectedTextFiles against files, because a large gap means files were skipped for size.

Can I add a rule without touching code?

Yes, if it uses one of the 21 existing signals. Editing the manifest is enough, and validate will tell you if the signal name is wrong. A rule that needs a new signal needs a code change first.

What is the plan id for?

It is a SHA-256 over the profile digest, the observed signals, and the tasks. Store it with a release and you can answer later which standard, against which observed state, produced which advice. Two plans with the same id came from identical inputs.

Can something execute a plan?

Nothing in 0.1, and nothing should try. Task text is prose from the catalog, written for a person, and it changes with a patch release. Version 1.0 introduces typed operations for exactly this reason, and even then the applying is done by the orchestrator rather than by Mestre Yoda.

Where do I report a problem?

Issues for bugs and detection gaps. Private mail to the maintainers for anything security related, without credentials or customer code attached. Detection gaps are the most useful thing to report right now, since that list is what should shape 0.2.