Preflight

A rule knows how to check something. Its policy decides whether it runs, its settings, severity and blocking behaviour. Two projects can use the same assembly with different file-size budgets, without forking the code. This makes the validation logic independently testable and lets pipeline owners change requirements without rebuilding the tool.

{
    "schemaVersion": 1,
    "pipeline": "projecta",
    "rules": {
        "core.presubmit.large-file": {
            "settings": {
                "maxBytes": 5242880
            }
        }
    },
    "targets": {
        "win64": {
            "rules": {
                "core.presubmit.large-file": {
                    "settings": {
                        "maxBytes": 2621440
                    }
                }
            }
        }
    }
}

Rules declare dependencies and execute in topological levels. Independent checks share a level; later levels wait for their prerequisites. If the toolchain check fails, a dependent compile probe can be skipped rather than producing another predictable failure.

Root-cause attribution follows the dependency chain through intermediate skips. The final message points back to the missing toolchain, giving the developer one problem to solve instead of a list of symptoms. The stage selects the roots of this graph, rather than discarding dependencies from other stages.

I chose a barrier between levels to simplify failure propagation and coordination. A slow rule holds up the next level even when part of it could already start. This is a deliberate cost: execution is easier to audit, and reports are ordered by level and ID regardless of which task finishes first.

A naming convention can block a submit without making compilation meaningless. An optional probe can be a technical prerequisite even when its failure should not reject the submission. A single boolean cannot express both cases. Preflight keeps blocking, which affects the verdict and exit code, separate from gating, which stops dependent rules. Severity remains the communication level, not a substitute for either decision.

Policies can inherit settings, apply explicit platform/configuration targets and seal keys against downstream overrides. Seals accumulate along the inheritance chain, so a project cannot quietly remove an organisation-wide restriction. Local machine overlays are kept out of CI.

The explain command records where effective values came from, including package, file, line and the values they replaced. Target axes must be explicitly supplied to match a target block. That prevents a configuration default from silently choosing a different production policy.

Precedence must be visible because a JSON value alone does not explain the effective configuration. Without provenance, investigating a difference between a local machine and CI would require reconstructing inheritance by hand. preflight explain makes that investigation part of the resolver’s own data.

Rules implement IValidationRule against Preflight.Abstractions. Filesystem, process, changes and policy access arrive through RuleContext services, allowing checks to be tested without the real workspace. The built-in rule assembly has no privileged dependency on Core.

Plugins load into separate collectible assembly contexts while sharing the contract assembly with the host. Dependency versions can coexist; duplicate rule IDs and incompatible contracts produce named refusals instead of an arbitrary winner. This is dependency isolation, not a security sandbox: plugins remain code trusted by the pipeline owner.

A pipeline package contains policy, rule assemblies and a manifest with per-file SHA-256 digests and a supported contract range. Stable entry order and fixed archive timestamps make package bytes reproducible. Installation verifies the archive before committing it to the installed store.

The checkout declares an accepted version range; a machine can pin a version for rollback. Installing a package does not move that pin. Preflight does not fetch updates itself, leaving distribution to the studio’s existing artifact channel and avoiding surprise rule changes across developer machines.

Passed, Warning, Failed, Errored, Skipped and NotApplicable have distinct meanings. A check with nothing applicable to inspect does not claim success; a crashed rule is distinguished from a defect in the workspace. Console, JSON and SARIF render the same report data. Exit codes separate a blocked change from invalid configuration and an internal error.

History is local append-only NDJSON; duration statistics appear only with enough observations. The tool can time a build command, but timing it does not establish that it was validated or that the software works.

Determinism applies to the verdict and finding order when inputs match, including the inspected environment and pipeline version. Duration and runId vary by design; comparing report bytes requires controlling those fields. The same policy on machines with different SDKs can correctly produce different results.

Caching is opt-in and only available for rules that supply an explicit input fingerprint. The key also includes the rule’s effective policy, stage, target, contract generation and assembly identity. Changing a threshold or rebuilding a plugin therefore invalidates the old result. Cached outcomes are visibly marked, so saved work is never presented as a fresh check.

The cost is requiring rule authors to describe relevant inputs. For a probe that cannot safely represent its environment, rerunning is preferable to reusing incomplete evidence. Caching is off by default.