# Static-analysis Judgment

Not every valuable Astrale practice is a static rule. The linter must be honest about what it cannot
prove.

## False-positive budget

The burden of proof belongs to automation, not to the code author. If a rule cannot distinguish valid
code from a violation without inferring intent, its default disposition is `guidance` or `research`,
not `warning`.

Before implementing a rule, ask:

- Is the violation represented by syntax, resolved symbols, types, compiled schema, or an explicit
  project contract?
- Can every common valid alternative be represented without a suppression?
- Does the diagnostic prevent a concrete failure often enough to justify its maintenance and review
  cost?
- Would a narrower rule capture the mechanically decidable part without claiming the broader design
  judgment?

The existence of a possible AST heuristic is not evidence that a rule should exist. Severity does not
solve ambiguity, and a local disable comment does not make systematic false positives acceptable.

## Keep in knowledge and review

The following require domain or product judgment:

- Whether bounded-context names and ownership reflect the business correctly.
- Which context semantically owns a cross-context edge.
- Whether a generic relation should instead be assignment, tagging, blocking, duplication, hierarchy,
  or mention behavior.
- Whether an authorization check targets the correct resource and permission.
- Whether an intentionally open callable is appropriate.
- Whether deletion should cascade, reject, preserve, archive, or detach related data.
- Whether import conflict, identity, partial-failure, and idempotency semantics are adequate.
- Whether a set of writes forms one business invariant.
- Whether a query projects every fact required by the use case.
- Whether a fresh read is actually required after receiving hydrated data.
- Whether a helper legitimately owns its own durable step.
- Whether UI vocabulary, hierarchy, and interaction design are domain-first and high quality.
- Whether a feature should exist at all.

These topics may have simulations, review checklists, or evidence collectors. They must not become
static diagnostics based on filenames or keywords.

The registry keeps these ideas with an explicit `guidance` disposition and rationale. This is a design
record, not an implementation backlog. A narrower replacement may be proposed later under its own
detection contract.

## Heuristic promotion

A heuristic may begin as an opt-in warning when it provides useful evidence, but its message must say
what was observed rather than claim intent.

For example:

```text
Observed 101 get() calls after one children() page in scenario delete-large-issue.
```

is valid evidence. The following overclaims:

```text
Your query architecture is wrong.
```

Promotion from warning to error requires repeated evidence across golden domains, a deterministic
contract, and documented valid exceptions.

Before a heuristic becomes even an opt-in warning, it must first move from `research` to `implement`.
Report-only prototypes may collect evidence, but they must not appear as ordinary project diagnostics.

## Knowledge relationship

Every accepted rule links to knowledge that explains why it exists. Knowledge entries may reference
the semantic identifier, but the registry is authoritative for automation disposition and lifecycle.
Executable owner, severity, and detection behavior apply only after an `implement` entry is accepted.

Agent skills should instruct agents to run the native project commands and interpret diagnostics. They
should not duplicate the entire rule catalog in prose.