rails-guard
Blocks builder edits to frozen rail paths and greps added diff lines for undeclared suppression markers.
rails-guard
ADLC phase: P4 Build · Gate: frozen rails stay untouched and no added line hides an undeclared suppression marker.
What it defends against
During P4 a builder can quietly edit the very tests, contract types, or CI config
that are supposed to hold it accountable, or slip a .skip(, .only(,
@ts-ignore, or # noqa into the diff to turn a red gate green. rails-guard
enforces two invariants on the diff: declared rail globs must not be touched, and
any newly added suppression marker is blocked unless the active ticket body
carries a matching allow-suppression: declaration. Prose files (.md,
.markdown) are exempt from the marker scan; .mdx is not, because it compiles
to executable JSX.
Usage
adlc rails-guard [--base <ref>] [--ticket <id>] [--tickets <path>] [--rails <glob>...] [--record] [--json]| Flag | Description |
|---|---|
--base <ref> | Freeze baseline to diff against. When omitted, resolves to the merge-base of HEAD with trunk (main/master/origin/main/origin/master) and fails closed if no trunk ref is found. It never defaults to HEAD, which would hide already-committed rail edits. |
--ticket <id> | Load rail globs and allow-suppression declarations from this ticket. |
--tickets <path> | Path to the tickets file (default .adlc/tickets.json). |
--rails <glob> | Frozen-path glob, repeatable. Overrides ticket.rails when supplied. |
--record | On a clean pass, append a rails-check proof (with SHA-256 of every rail-matching file) to .adlc/manifest.jsonl. |
--json | Emit a machine-readable result for orchestrators. |
--help | Print help and exit 0. |
Rails resolve from --rails when given, otherwise from --ticket; with neither, the run is an operational error.
Exit codes
Example
$ adlc rails-guard --rails "test/**" --ticket T42 --base origin/main
rails-guard: 2 violation(s) found
[rail-edit] test/auth.test.ts (matched globs: test/**)
[suppression] src/foo.ts:12 marker: @ts-ignore
exit 2Go deeper
The frozen-rails discipline and why builders must not touch their own tests: Tests Are the Spec.