docs(docs): release v0.2.20

Add FEATURES.md and USAGE.md entries to the [0.2.20] changelog section.
No code changes — documentation reorganisation only.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project uses [Semantic Versioning](https://semver.org).
 
+## [0.2.20] - 2026-06-14
+
+### Added
+
+- **`glint explain <RULE>`** — new subcommand that prints the description, rationale, a bad-YAML example, and the corrected fix for any rule ID (GL001–GL043). `glint explain` with no argument lists all rules with ID, severity, and title. Rule IDs are case-insensitive (`gl007` and `GL007` are equivalent).
+
+- **`rules:if:` evaluated reachability (GL042)** — warns when every `rules:if:` condition in a job evaluates to false using the values of variables declared in the pipeline YAML, meaning the job can never be included in a pipeline run. The check is conservative: it only fires when all variables referenced in the `if:` expressions are explicitly declared in the YAML; predefined `CI_*` / `GITLAB_*` variables and undeclared variables are treated as unknown (may have any runtime value) to avoid false positives.
+
+- **`inherit:` completeness (GL043)** — warns when a job declares `inherit: default:` (boolean or list form) but the pipeline has no `default:` block, making the declaration a no-op. Also warns when the list form names fields (e.g. `[image, before_script]`) that are not actually set in the `default:` block — those list entries have no effect.
+
+- **`FEATURES.md`** — full feature reference extracted from the README: all 43 lint rules in categorised tables, include resolution capabilities, context simulation details, output format schemas, configuration reference, graph visualisation modes, and developer tools. The README `## Features` section replaced with a compact 6-line `## What it does` summary with a link to `FEATURES.md`.
+
+- **`USAGE.md`** — complete command-by-command usage reference extracted from the README: `glint check` with all output formats and examples, context simulation flags and predefined variable table, remote includes and token resolution, cache and offline mode, component reference format, `glint graph` modes, `glint explain` usage, project config (`.glint.yml`), and inline suppression. The README `## Usage` section replaced with the commands block and a single link to `USAGE.md`.
+
 ## [0.2.19] - 2026-06-14
 
 ### Added

FEATURES.md

@@ -0,0 +1,259 @@
+# glint — feature reference
+
+This document describes every capability in the current release.
+For planned work see [ROADMAP.md](ROADMAP.md).
+
+---
+
+## Lint rules
+
+Every finding carries a stable rule ID (`GL001` – `GL043`) that can be used to
+suppress, filter, or look up the check. Run `glint explain <ID>` for a
+description, bad-YAML example, and fix.
+
+### Pipeline-level
+
+| ID | Sev | Rule |
+|----|-----|------|
+| GL001 | WARN | No `stages:` block — GitLab falls back to its built-in default stages |
+| GL002 | ERR | `workflow.rules[*].when` must be `always` or `never` |
+| GL036 | ERR | `default.timeout` is not a valid GitLab CI duration string |
+| GL040 | WARN | A stage name appears more than once in `stages:` |
+
+### Job structure
+
+| ID | Sev | Rule |
+|----|-----|------|
+| GL003 | ERR | Job missing required `script:` (or `run:`) |
+| GL004 | ERR | Job `stage:` references a stage not declared in `stages:` |
+| GL005 | ERR | `only:` and `rules:` used together |
+| GL006 | ERR | `except:` and `rules:` used together |
+| GL007 | WARN | `only:` / `except:` used (deprecated; prefer `rules:`) |
+
+### Keyword constraints
+
+| ID | Sev | Rule |
+|----|-----|------|
+| GL008 | ERR | `when:` has an invalid value |
+| GL009 | ERR | `when: delayed` without `start_in:` |
+| GL010 | ERR | `start_in:` set but `when:` is not `delayed` |
+| GL011 | ERR | `parallel:` integer not in range 2–200, or map form missing `matrix:` |
+| GL012 | ERR | `retry:` integer not in range 0–2, or `retry.max` out of range |
+| GL013 | ERR | `retry.when:` contains an unrecognised failure type |
+| GL014 | ERR | `allow_failure:` is not a boolean or a map with `exit_codes:` |
+| GL015 | ERR | `interruptible:` is not a boolean |
+| GL016 | ERR | Trigger job also defines `script:` |
+| GL017 | ERR | `trigger:` map missing `project:` or `include:` |
+| GL018 | ERR | `coverage:` is not a regex wrapped in `/…/` |
+| GL019 | ERR | `release:` missing required `tag_name:`, or is not a map |
+| GL020 | ERR | `environment.url` set without `environment.name`, or invalid `action:` |
+| GL021 | ERR | `artifacts.when` invalid, or `expose_as` set without `paths` |
+| GL022 | WARN | `pages` job `artifacts.paths` does not include `public/` |
+| GL023 | ERR | `cache.when` or `cache.policy` has an invalid value |
+| GL024 | ERR | `rules[*].when` has an invalid value |
+| GL025 | ERR | `image:` map form missing `name:` |
+| GL026 | ERR | `inherit.default` / `inherit.variables` is not a boolean or list |
+| GL034 | ERR | `services:` map form missing `name:`, or `alias:` is not a valid DNS label |
+| GL036 | ERR | `timeout:` is not a valid GitLab CI duration string |
+| GL037 | ERR | `id_tokens:` entry missing required `aud:` |
+| GL038 | ERR | `secrets:` entry missing a provider key (`vault`, `gcp_secret_manager`, `azure_key_vault`) |
+| GL039 | WARN | Job uses `pages:` keyword but `artifacts.paths` doesn't include the publish directory |
+| GL041 | WARN | `cache.key.files` entry looks like a glob; must be an exact file path |
+
+### Cross-job graph
+
+| ID | Sev | Rule |
+|----|-----|------|
+| GL027 | ERR/WARN | `needs:` references a job that doesn't exist (WARN when `optional: true`) |
+| GL028 | ERR | `needs:` references a job in a later stage |
+| GL029 | ERR | Circular dependency in `needs:` graph |
+| GL030 | ERR | `dependencies:` references a job that doesn't exist |
+| GL031 | ERR | `dependencies:` references a job in the same or a later stage |
+
+### Expression & reachability
+
+| ID | Sev | Rule |
+|----|-----|------|
+| GL032 | WARN | `rules:if:` references `$VAR` not declared in any `variables:` block (may be false-positive for project-setting variables) |
+| GL033 | WARN | Every rule in `rules:` has `when: never` — job permanently excluded (provable without evaluating `if:` expressions) |
+| GL035 | WARN | `rules:changes` / `rules:exists` path is absolute — absolute paths never match in GitLab CI |
+| GL042 | WARN | Every `rules:if:` condition evaluates to false given the declared variable values — job statically unreachable (only fires when all referenced variables are declared in YAML) |
+
+### Inheritance
+
+| ID | Sev | Rule |
+|----|-----|------|
+| GL043 | WARN | `inherit: default:` declared but the pipeline has no `default:` block (dead declaration), or the list form names fields not set in `default:` |
+
+### Hidden jobs
+
+Jobs whose name starts with `.` are reusable templates; most rules are skipped for them. This matches GitLab CI's own behaviour.
+
+---
+
+## Include resolution
+
+| Capability | Notes |
+|------------|-------|
+| `include: local:` | Read from disk, recursively merged before linting |
+| `include: remote:` | HTTPS URL fetched unauthenticated; unreachable URLs produce a warning, linting continues |
+| `include: project:` | Fetched from the GitLab REST API using the configured token; skipped with a warning when no token is available |
+| `include: component:` | Fetched from the GitLab CI/CD Catalog; public components work without a token |
+| `include: inputs:` | `$[[ inputs.KEY ]]` and `$[[ inputs.KEY \| default(…) ]]` placeholders substituted from the `with:` block before parsing |
+| Depth limit | Include chains capped at 100 levels (matches GitLab); circular cross-file references detected via visited-set tracking |
+| Offline mode | `--offline` serves all remote includes from the cache; missing entries produce a warning |
+| Include cache | `--cache-dir DIR` (or `~/.cache/glint` by default with `--offline`) persists fetched templates; keyed by SHA-256 of the request coordinates |
+
+**Token resolution order** (first non-empty wins):
+
+| Source | Header |
+|--------|--------|
+| `--token` flag / `GITLAB_TOKEN` env | `PRIVATE-TOKEN` |
+| `CI_JOB_TOKEN` env | `JOB-TOKEN` |
+| `GITLAB_PRIVATE_TOKEN` env | `PRIVATE-TOKEN` |
+
+**URL resolution order:** `--gitlab-url` flag → `CI_SERVER_URL` env → `GITLAB_URL` env → `https://gitlab.com`
+
+---
+
+## Context simulation
+
+Pass `--branch`, `--tag`, `--source`, or `--var` to evaluate `rules:if:` and
+`only`/`except` filters against a specific pipeline event. When no context flag
+is given glint defaults to `--branch main --source push` so that `rules:if:`
+expressions are always evaluated.
+
+**Evaluated at lint time:**
+
+- `rules:if:` — full expression language: `==`, `!=`, `=~`, `!~`, `&&`, `||`, `!`, `(…)`, `$VAR`/`${VAR}`, string literals, `null`, regex flags (`/pat/i`)
+- `only:` / `except:` — ref keywords, branch-name globs, and `/regex/` patterns
+- `workflow:rules:` — evaluated to determine whether the pipeline would run; matching rule's `variables:` are injected before job evaluation
+- Variable expansion — `$VAR` / `${VAR}` references in variable values expanded after all sources merge; transitive chains resolved (up to 10 passes)
+
+**Not evaluated** (no git tree at lint time): `rules:changes:`, `rules:exists:`.
+
+**Predefined variables** set by shortcut flags:
+
+| Flag | Variables populated |
+|------|---------------------|
+| `--branch NAME` | `CI_COMMIT_BRANCH`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE=push` |
+| `--tag NAME` | `CI_COMMIT_TAG`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE=push`; clears `CI_COMMIT_BRANCH` |
+| `--source EVENT` | `CI_PIPELINE_SOURCE` |
+| `--var KEY=VALUE` | any variable; overrides shortcuts; repeatable |
+
+Use `--list-vars` to print the resolved variable table to stderr.
+
+---
+
+## Output formats
+
+Pass `--format` to `glint check`. In structured formats the summary line is
+written to stderr so stdout contains only the machine-readable payload.
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| Text (default) | `--format text` | Ruff-style `file:line: RULE [sev] message` |
+| JSON | `--format json` | Stable schema (version 1); `findings` array + `summary` block |
+| SARIF 2.1.0 | `--format sarif` | Consumed by GitHub Code Scanning and GitLab SAST |
+| JUnit XML | `--format junit` | CI test-report artifact (`artifacts:reports:junit`) |
+| GitHub annotations | `--format github` | `::error file=…,line=…,title=RULE::message` inline PR comments |
+
+**JSON schema (`schema_version: 1`):**
+```json
+{
+  "schema_version": 1,
+  "glint_version": "v0.2.20",
+  "pipeline": ".gitlab-ci.yml",
+  "findings": [
+    {"rule":"GL004","severity":"error","file":".gitlab-ci.yml","line":14,
+     "job":"deploy","message":"stage \"production\" is not defined in 'stages'"}
+  ],
+  "summary": {"total": 1, "errors": 1, "warnings": 0}
+}
+```
+
+---
+
+## Configuration
+
+### `.glint.yml` project config file
+
+Searched from the pipeline file's directory upward to the first `.git` boundary.
+
+```yaml
+# Suppress rules globally for this project.
+ignore:
+  - GL007   # migrating from only:/except:
+  - GL032   # dynamic variables injected by CI
+
+# Override rule severity (error | warning | ignore).
+# 'ignore' is equivalent to listing the rule in ignore:.
+severity:
+  GL004: warning   # demote during a stage migration
+  GL035: error     # promote to hard error for this project
+
+# Extra stage names valid beyond those in the pipeline's own stages: block.
+stages:
+  - quality
+  - security
+
+# Default GitLab token (lower priority than --token and GITLAB_TOKEN).
+token: glpat-xxxx
+
+# Default GitLab instance URL.
+url: https://gitlab.example.com
+
+# Default cache directory.
+cache_dir: ~/.cache/glint
+```
+
+**Priority chain:** `--token`/`--gitlab-url` flags > `.glint.yml` > environment variables.
+
+### Inline suppression (`# glint: ignore`)
+
+Suppress a finding for a specific job by placing a comment immediately before it:
+
+```yaml
+# glint: ignore GL007
+legacy-job:
+  only: [main]
+  script: echo ok
+
+# Multiple rules (comma- or space-separated):
+# glint: ignore GL007, GL032
+other-job:
+  script: echo ok
+
+# Suppress every rule for this job:
+# glint: ignore all
+noisy-job:
+  script: echo ok
+```
+
+Suppressions are scoped to the single job they precede and do not affect other
+jobs or pipeline-level findings.
+
+---
+
+## Graph visualization (`glint graph`)
+
+| Mode | Output |
+|------|--------|
+| `tree` (default) | Terminal job tree: stages as branches, jobs as leaves; annotated with `[manual]`, `[delayed]`, `[trigger]` where applicable |
+| `includes` | Mermaid flowchart to stdout; colour-coded nodes by include type (local, remote, project, component, template) |
+| `pipeline` | GitLab CI-style SVG/PNG written to `--out` directory (default: `glint-out/`); converted to PNG when `rsvg-convert`, `inkscape`, or `magick` is available |
+| `all` | `includes` to stdout + `pipeline` file path to stderr |
+
+In DAG pipelines (any job has `needs:`) the pipeline graph uses job-to-job
+Bézier connectors instead of stage-to-stage lines.
+
+---
+
+## Developer tools
+
+| Tool | Description |
+|------|-------------|
+| `glint explain <RULE>` | Print description, rationale, bad-YAML example, and fix for a rule. Case-insensitive (`gl007` = `GL007`). |
+| `glint explain` | List all rules with ID, severity, and title. |
+| `--list-vars` | Print all resolved pipeline variables (pipeline + workflow rules + context) to stderr before linting. |
+| `--version` / `-v` | Print the compiled version string. |

README.md

@@ -6,50 +6,23 @@
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/release-v0.2.19-blue.svg" alt="Release"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/release-v0.2.20-blue.svg" alt="Release"></a>
 </p>
 
 > **Disclaimer:** This tool was built through iterative AI-assisted development with [Claude](https://claude.ai). It is experimental, incomplete, and not intended for production use. Coverage of GitLab CI keywords is best-effort and may lag behind GitLab's evolving spec. Use it at your own discretion — no correctness guarantees are made. Contributions and bug reports are welcome.
 
 A local tool to validate and lint `.gitlab-ci.yml` pipelines without needing a GitLab server.
 
-## Features
+## What it does
 
-- **YAML validation** — detects malformed pipeline files early
+- **Lints** — 43 rules covering pipeline structure, keyword constraints, `needs:`/`dependencies:` graphs, expression reachability, and deprecations (GL001–GL043); run `glint explain <ID>` for any rule
-- **Stage validation** — every job's `stage` must be declared in `stages`
+- **Resolves includes** — local files, HTTPS URLs, GitLab project templates, and CI/CD Catalog components, with offline cache support
-- **`extends:` resolution** — resolves single and multi-level template inheritance before linting, so derived jobs are evaluated against their fully merged definition
+- **Simulates context** — `--branch`, `--tag`, `--source` flags evaluate `rules:if:` and `only`/`except` to show which jobs would be active, manual, or skipped
-- **`needs:` DAG validation** — checks that `needs:` references exist, respect stage ordering, and contain no circular dependencies
+- **Multiple output formats** — `--format text` (default, ruff-style), `json`, `sarif` (GitHub Code Scanning / GitLab SAST), `junit`, `github` (PR annotations)
-- **`dependencies:` validation** — checks that artifact dependency references exist and are in earlier stages
+- **Project config** — `.glint.yml` for rule suppression, severity overrides, token/URL defaults; `# glint: ignore RULE` for per-job inline suppression
-- **Keyword validation** — validates constraints on `when`, `parallel`, `retry`, `allow_failure`, `trigger`, `artifacts`, `cache`, `release`, `environment`, `coverage`, `rules`, and more
+- **Graph visualization** — `glint graph` prints a terminal job tree; `glint graph pipeline` renders a GitLab CI-style SVG/PNG
-- **Remote project includes** — fetches `include: project:` templates from the GitLab API so extends/needs can be validated against the full merged pipeline
-- **CI/CD catalog components** — resolves `include: component:` references from the GitLab CI/CD Catalog; public components work without a token
-- **Deprecation warnings** — flags `only`/`except` usage in favour of `rules`
-- **Local include resolution** — `include: local:` entries are read from disk and recursively merged before linting, so multi-file pipelines are fully validated
-- **Extended variable declarations** — `variables:` entries may use the `{value, description, options}` map form (GitLab CI 13.7+); `default.image` accepts both string and map form; `rules.changes`/`rules.exists` accept both list and `{paths, compare_to}` map form
-- **Graph output** — `glint graph` prints a job tree (stages → jobs) to the terminal; `glint graph includes` emits a Mermaid include dependency diagram; `glint graph pipeline` renders a GitLab CI-style PNG/SVG
-- **Context simulation** — pass `--branch`, `--tag`, or `--source` to `glint check` or `glint graph` to see which jobs would be active, manual, or skipped for a specific pipeline event; evaluates `rules:if:` expressions and `only`/`except` filters
-- **Variable expansion** — `$VAR` and `${VAR}` references inside variable values are expanded after all sources are merged (pipeline defaults → workflow-rule overrides → CLI flags); transitive chains resolve automatically; visible via `--list-vars`
-- **Non-string variable scalars** — `BUILD: true`, `RETRIES: 3` and other bare boolean/integer variable values are handled correctly throughout: they render in `--list-vars` output and are injected into the evaluation context as their string equivalents, matching GitLab CI's behaviour
-- **Static reachability (GL033)** — warns when a job's `rules:` block can never activate: if every rule has `when: never` the job is permanently excluded from any pipeline run, provable without evaluating any `if:` expressions
-- **`services:` validation (GL034)** — map form requires a `name` key; `alias` must be a valid DNS label (letters, digits, hyphens, dots; no leading/trailing hyphens)
-- **`rules:changes` / `rules:exists` glob safety (GL035)** — warns when paths are absolute (start with `/`), which can never match since GitLab CI paths are always relative to the repository root
-- **`timeout:` format (GL036)** — validates that job and `default:` timeout values are valid GitLab CI duration strings (`1h 30m`, `90 minutes`, `2 hours`, etc.)
-- **`id_tokens:` validation (GL037)** — each OIDC token entry must have an `aud` key (missing `aud` is a GitLab API error at runtime)
-- **`secrets:` validation (GL038)** — each secret entry must declare exactly one provider (`vault`, `gcp_secret_manager`, or `azure_key_vault`)
-- **`pages:` keyword + `artifacts.paths` (GL039)** — warns when a job uses the `pages:` keyword but `artifacts.paths` does not include the publish directory (default: `public`)
-- **Duplicate stage names (GL040)** — warns when a stage name appears more than once in `stages:`; GitLab silently merges duplicates, which can cause confusing ordering
-- **`cache.key.files` glob detection (GL041)** — warns when `cache.key.files` entries contain glob metacharacters; this field requires exact file paths, not patterns
-- **Recursive include depth limit** — include chains are capped at 100 nesting levels (matching GitLab's own limit); project and component includes are now tracked in the visited-file set to prevent cross-include cycles
-- **`include: inputs:` substitution** — when a `component:` entry has a `with:` block, all `$[[ inputs.KEY ]]` and `$[[ inputs.KEY | default(…) ]]` placeholders in the fetched template are substituted before parsing, so component-scoped jobs get their correct `stage:` and keyword values instead of `$[[…]]` placeholders
-- **Offline mode + include cache** — pass `--cache-dir DIR` to cache fetched remote templates (project: and component: includes) to disk; `--offline` serves entirely from the cache without making network calls
-- **Structured output formats** — `--format json` emits a stable JSON report; `--format sarif` emits SARIF 2.1.0 (consumed by GitHub Code Scanning and GitLab SAST); `--format junit` emits JUnit XML (consumable as a CI test-report artifact); `--format github` emits GitHub Actions annotation lines (`::error file=…::`) so findings appear as inline PR comments
-- **`.glint.yml` project config** — rule suppression (`ignore: [GL007]`), severity overrides (`severity: {GL004: warning}`), extra stages allowlist (`stages: [quality]`), and default token/URL/cache-dir so flags are not needed on every invocation
-- **Inline suppression comments** — `# glint: ignore GL007` (or `# glint: ignore all`) immediately before a job definition suppresses the specified rule(s) for that job without touching other jobs
-- **Sorted findings output** — findings are sorted by source file then line number, so all issues from the same file appear together in order; pipeline-level findings (no file) sort first
-- **Consistent ruff-style warnings** — all warnings (unresolvable includes, skipped extends chains, workflow non-start) use the same `path: [warning] message` format as lint findings
-- **`--version` / `-v` flag** — prints the compiled version string (e.g. `glint v0.2.14`); the version is also shown at the top of every `--help` output
 
-See [ROADMAP.md](ROADMAP.md) for planned improvements.
+See [FEATURES.md](FEATURES.md) for the complete feature reference and lint rules table, and [ROADMAP.md](ROADMAP.md) for planned improvements.
 
 ## Requirements
 
@@ -78,394 +51,12 @@ glint [OPTIONS] <COMMAND>
 Commands:
   check    Lint a pipeline file — exits 0 (clean) or 1 (errors found)
   graph    Visualise the pipeline as a job tree or Mermaid graph
+  explain  Print description and fix for a lint rule
 ```
 
-Run `glint <command> --help` for command-specific options and examples.
+Run `glint <command> --help` for all flags. See [USAGE.md](USAGE.md) for full
-
+examples covering output formats, context simulation, remote includes, cache,
-### `glint check`
+graph modes, and project configuration.
-
-```bash
-glint check .gitlab-ci.yml
-```
-
-Exits `0` when no errors are found, `1` when at least one error is reported.
-
-### Output formats
-
-Pass `--format` to control the output. Plain text is the default.
-
-```bash
-# Default: ruff-style text (human-readable)
-glint check .gitlab-ci.yml
-
-# JSON — stable schema, machine-readable
-glint check --format json .gitlab-ci.yml
-
-# SARIF 2.1.0 — GitHub Code Scanning / GitLab SAST
-glint check --format sarif .gitlab-ci.yml > glint.sarif
-
-# JUnit XML — CI test-report artifact (GitLab: artifacts:reports:junit)
-glint check --format junit .gitlab-ci.yml > glint-junit.xml
-
-# GitHub Actions annotations — inline PR diff comments
-glint check --format github .gitlab-ci.yml
-```
-
-In structured formats (`json`, `sarif`, `junit`, `github`) the summary line
-(`OK: … no issues found` or `N finding(s): M error(s)`) is written to stderr
-so stdout contains only the machine-readable payload.
-
-**JSON schema (`schema_version: 1`):**
-```json
-{
-  "schema_version": 1,
-  "glint_version": "v0.2.18",
-  "pipeline": ".gitlab-ci.yml",
-  "findings": [
-    {"rule":"GL004","severity":"error","file":".gitlab-ci.yml","line":14,
-     "job":"deploy","message":"stage \"production\" is not defined in 'stages'"}
-  ],
-  "summary": {"total": 1, "errors": 1, "warnings": 0}
-}
-```
-
-**GitHub annotation lines:**
-```
-::error file=.gitlab-ci.yml,line=14,title=GL004::job "deploy": stage "production" is not defined in 'stages'
-```
-
-### Project configuration (`.glint.yml`)
-
-Place a `.glint.yml` file next to your pipeline (or anywhere in the directory tree up to the repository root) to configure glint for that project. glint searches upward from the pipeline file's directory, stopping at the first `.git` boundary.
-
-```yaml
-# .glint.yml
-
-# Suppress specific rules entirely.
-ignore:
-  - GL007   # we still use only:/except:, migration in progress
-  - GL032   # lots of dynamic variables injected by CI
-
-# Override the severity of specific rules.
-severity:
-  GL004: warning  # demote stage errors to warnings during a migration
-  GL035: error    # promote absolute-path warning to error for this project
-
-# Extra stages that are valid but not declared in the pipeline YAML itself
-# (e.g. injected by an include template we can't edit).
-stages:
-  - quality
-  - security
-
-# Default token — overridden by --token flag and GITLAB_TOKEN env.
-token: glpat-xxxx
-
-# Default GitLab instance URL.
-url: https://gitlab.example.com
-
-# Default cache directory for fetched remote includes.
-cache_dir: ~/.cache/glint
-```
-
-**Priority chain for token and URL:** `--token`/`--gitlab-url` flags > `.glint.yml` values > `GITLAB_TOKEN`/`CI_SERVER_URL` environment variables.
-
-### Inline suppression (`# glint: ignore`)
-
-Suppress a finding for a specific job by placing a `# glint: ignore RULE` comment immediately before the job definition:
-
-```yaml
-# glint: ignore GL007
-legacy-job:
-  stage: build
-  only:
-    - main
-  script: echo ok
-
-# Multiple rules — comma- or space-separated:
-# glint: ignore GL007, GL032
-another-job:
-  stage: build
-  script: echo ok
-
-# Suppress all rules for this job:
-# glint: ignore all
-noisy-job:
-  stage: build
-  script: echo ok
-```
-
-Inline suppressions are scoped to the single job they precede. They do not affect other jobs or pipeline-level findings. For project-wide suppression use `.glint.yml` `ignore:`.
-
-### Remote project includes
-
-Pipelines that include templates from other GitLab projects are supported.
-Provide a token so `glint` can fetch them:
-
-```bash
-# personal access token (read_api scope)
-GITLAB_TOKEN=glpat-xxxx glint check .gitlab-ci.yml
-
-# CI/CD job token (when running inside a pipeline)
-CI_JOB_TOKEN=$CI_JOB_TOKEN glint check .gitlab-ci.yml
-
-# self-hosted GitLab
-GITLAB_TOKEN=glpat-xxxx GITLAB_URL=https://gitlab.example.com glint check .gitlab-ci.yml
-
-# or via flags
-glint check --token glpat-xxxx --gitlab-url https://gitlab.example.com .gitlab-ci.yml
-```
-
-**Project includes** require a token; without one they are skipped with a
-warning and the rest of the pipeline is linted as-is.
-
-### Include cache and offline mode
-
-Pass `--cache-dir` to cache fetched remote templates so repeated runs skip the network:
-
-```bash
-# First run: fetches and caches
-glint check --cache-dir ~/.cache/glint .gitlab-ci.yml
-
-# Subsequent runs: served from cache
-glint check --cache-dir ~/.cache/glint .gitlab-ci.yml
-
-# Fully offline (uses ~/.cache/glint automatically when --cache-dir is absent)
-glint check --offline .gitlab-ci.yml
-glint check --offline --cache-dir ~/.cache/glint .gitlab-ci.yml
-```
-
-Cache entries are keyed by SHA-256 of the full request URL/coordinates and stored as plain YAML files in the cache directory. There is currently no automatic expiry — delete the directory or individual entries to force a fresh fetch.
-
-**Component includes** (`include: component: ...`) attempt the fetch
-unauthenticated, so public [CI/CD Catalog](https://gitlab.com/explore/catalog)
-components work without a token. A warning is emitted if the fetch fails.
-
-Token resolution order (first non-empty wins):
-
-| Source | Header used |
-|--------|-------------|
-| `--token` flag / `GITLAB_TOKEN` | `PRIVATE-TOKEN` |
-| `CI_JOB_TOKEN` | `JOB-TOKEN` |
-| `GITLAB_PRIVATE_TOKEN` | `PRIVATE-TOKEN` |
-
-Instance URL resolution order: `--gitlab-url` flag → `CI_SERVER_URL` →
-`GITLAB_URL` → `https://gitlab.com`
-
-### Component reference format
-
-```
-<host>/<project-path>/<component-name>@<version>
-
-gitlab.com/components/secret-detection/secret-detection@v0.1.0
-gitlab.com/my-org/ci-catalog/lint@main
-gitlab.example.com/platform/components/build@~latest
-```
-
-The component file is looked up in order:
-1. `templates/<component-name>.yml` (single-file layout)
-2. `templates/<component-name>/template.yml` (directory layout)
-
-Component input parameters (`with:`) are not validated — they are resolved by
-GitLab at runtime. Jobs in fetched components may use `$[[ inputs.xxx ]]`
-placeholders in fields like `stage`; `glint` skips those fields rather
-than producing false positive errors.
-
-### `glint graph`
-
-Visualise the pipeline. Without a mode word, prints a job tree and the include
-dependency graph separated by `---`.
-
-```bash
-# Default: job tree + include dependency graph
-glint graph .gitlab-ci.yml
-
-# Job tree only (stages → jobs, like the tree command)
-glint graph tree .gitlab-ci.yml
-
-# Include dependency graph → Mermaid flowchart to stdout
-glint graph includes .gitlab-ci.yml > includes.mmd
-
-# GitLab-like pipeline layout → PNG (or SVG fallback) written to --out dir
-glint graph pipeline .gitlab-ci.yml
-# prints the output file path, e.g.: glint-out/pipeline-20260607-143022.png
-
-# Mermaid to stdout + pipeline file path to stderr
-glint graph all .gitlab-ci.yml > includes.mmd
-
-# Custom output directory (pipeline mode)
-glint graph pipeline --out /tmp/graphs .gitlab-ci.yml
-```
-
-**Job tree** (`graph tree`) — stages as branches, jobs as leaves. Jobs with
-`when: manual`, `when: delayed`, or `trigger:` are annotated in brackets.
-
-**Include graph** (`graph includes`) — [Mermaid](https://mermaid.js.org) flowchart written to stdout.
-Pipe to a `.mmd` file or paste into [mermaid.live](https://mermaid.live).
-One node per include entry, colour-coded by type:
-- Orange (bold): the main pipeline file
-- Purple: `project:` includes
-- Green: `component:` includes
-- Blue: `local:` includes
-- Grey: `remote:` URL includes
-- Light orange: GitLab-provided `template:` includes
-
-**Pipeline graph** (`graph pipeline`) — GitLab CI-style SVG rendered to a timestamped file
-in the `--out` directory (default: `glint-out/`). Converted to PNG automatically
-when `rsvg-convert`, `inkscape`, or `magick` is available; falls back to SVG otherwise.
-Jobs are colour-coded by type:
-- Blue (`#1f75cb`): regular jobs
-- Orange (`#fc6d26`): `when: manual` jobs
-- Purple (`#6b4fbb`): `trigger:` jobs
-- Amber (`#fca326`): `when: delayed` jobs
-
-DAG mode (job-to-job Bézier arrows) activates automatically when any job has a `needs:` list.
-Classic mode draws L-shaped or straight connectors between stage columns otherwise.
-
-### Context simulation
-
-Pass `--branch`, `--tag`, or `--source` to `glint check` to see which jobs
-would run for a given pipeline event. The pipeline is still fully linted;
-context output is printed first.
-
-```bash
-# What runs on a push to develop?
-glint check --branch develop .gitlab-ci.yml
-
-# What runs when a v1.2.0 tag is pushed?
-glint check --tag v1.2.0 .gitlab-ci.yml
-
-# Merge request pipeline
-glint check --source merge_request_event .gitlab-ci.yml
-
-# Arbitrary variable overrides (repeatable)
-glint check --branch main --var DEPLOY_ENV=production .gitlab-ci.yml
-```
-
-**Evaluated:**
-- `rules:if:` — full expression language: `==`, `!=`, `=~`, `!~`, `&&`, `||`, `!`, `()`, `$VAR`, string literals, `null`
-- `only:` / `except:` — ref keywords (`branches`, `tags`, `merge_requests`, `schedules`, …), branch name globs (`feat/*`), and `/regex/` patterns
-- Variable expansion — `$VAR` / `${VAR}` references within variable values are expanded after all sources are merged; use `--list-vars` to inspect the resolved values
-
-**Not evaluated** (no git tree at lint time): `rules:changes:`, `rules:exists:`.
-Rules without an `if:` clause always match.
-
-**Predefined variables** set automatically by the shortcut flags:
-
-| Flag | Variables populated |
-|------|---------------------|
-| `--branch <name>` | `CI_COMMIT_BRANCH`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE=push` |
-| `--tag <name>` | `CI_COMMIT_TAG`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE=push` (clears `CI_COMMIT_BRANCH`) |
-| `--source <event>` | `CI_PIPELINE_SOURCE` |
-| `--var KEY=VALUE` | any variable; overrides shortcuts |
-
-### Example output
-
-```
-# Clean pipeline (implicit default: --branch main --source push)
-Context: branch=main, source=push
-
-Active  (5): build, deploy-staging, test, ...
-
-OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
-
-# With --branch develop context
-Context: branch=develop, source=push
-
-Active  (3): build, deploy-staging, test
-Skipped (2): deploy-prod, release-notes
-
-OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
-
-# With --tag v1.0.0 context
-Context: tag=v1.0.0, source=push
-
-Active  (4): build, deploy-prod, release-notes, test
-Skipped (1): deploy-staging
-
-OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
-
-# Pipeline with issues
-.gitlab-ci.yml:14: GL004 [error] job "deploy": stage "production" is not defined in 'stages'
-.gitlab-ci.yml:22: GL027 [error] job "test": needs unknown job "build-app"
-.gitlab-ci.yml:31: GL007 [warning] job "old-job": 'only'/'except' are deprecated; prefer 'rules'
-
-3 finding(s): 2 error(s)
-```
-
-## Lint rules
-
-Every finding includes a stable rule ID (e.g. `GL003`) that can be used to filter output or reference a specific check in documentation.
-
-### Pipeline-level
-
-| ID | Severity | Rule |
-|----|----------|------|
-| GL002 | ERROR | `workflow.rules[*].when` is not `always` or `never` |
-| GL001 | WARNING | No `stages` defined (GitLab falls back to default stages) |
-| GL036 | ERROR | `default.timeout` is not a valid GitLab CI duration string |
-| GL040 | WARNING | A stage name appears more than once in `stages:` |
-
-### Job-level — structure
-
-| ID | Severity | Rule |
-|----|----------|------|
-| GL003 | ERROR | Job is missing required `script` (or `run`) — non-trigger, non-template jobs |
-| GL004 | ERROR | Job references a `stage` not declared in `stages` |
-| GL005 | ERROR | `only` and `rules` used together on the same job |
-| GL006 | ERROR | `except` and `rules` used together on the same job |
-| GL007 | WARNING | `only`/`except` used (deprecated, prefer `rules`) |
-
-### Job-level — keyword constraints
-
-| ID | Severity | Rule |
-|----|----------|------|
-| GL008 | ERROR | `when` is not one of `on_success`, `on_failure`, `always`, `manual`, `delayed`, `never` |
-| GL009 | ERROR | `when: delayed` without `start_in` |
-| GL010 | ERROR | `start_in` set but `when` is not `delayed` |
-| GL011 | ERROR | `parallel` integer not in range 2–200, or map form missing `matrix` key |
-| GL012 | ERROR | `retry` integer not in range 0–2, or `retry.max` out of range |
-| GL013 | ERROR | `retry.when` contains an unrecognised failure type |
-| GL014 | ERROR | `allow_failure` is not a boolean or a map with `exit_codes` |
-| GL015 | ERROR | `interruptible` is not a boolean |
-| GL016 | ERROR | `trigger` job also has `script` |
-| GL017 | ERROR | `trigger` map missing `project` or `include` |
-| GL018 | ERROR | `coverage` is not a regex pattern wrapped in `/` |
-| GL019 | ERROR | `release` missing required `tag_name`, or is not a map |
-| GL020 | ERROR | `environment.url` set without `environment.name`, or invalid `environment.action` |
-| GL021 | ERROR | `artifacts.when` invalid, or `artifacts.expose_as` set without `artifacts.paths` |
-| GL022 | WARNING | `pages` job `artifacts.paths` does not include `public` |
-| GL023 | ERROR | `cache.when` or `cache.policy` has an invalid value |
-| GL024 | ERROR | `rules[*].when` is not one of the valid `when` values |
-| GL025 | ERROR | `image` map form missing `name` key |
-| GL026 | ERROR | `inherit.default` / `inherit.variables` is not a boolean or list |
-| GL034 | ERROR | `services:` map form missing `name`, or `alias` is not a valid DNS label |
-| GL036 | ERROR | `timeout:` is not a valid GitLab CI duration string (e.g. `1h 30m`, `90 minutes`) |
-| GL037 | ERROR | `id_tokens:` entry is missing the required `aud` key |
-| GL038 | ERROR | `secrets:` entry is missing a provider key (`vault`, `gcp_secret_manager`, or `azure_key_vault`) |
-| GL039 | WARNING | Job has `pages:` keyword but `artifacts.paths` does not include the publish directory |
-| GL041 | WARNING | `cache.key.files` entry looks like a glob pattern; must be an exact file path |
-
-### Cross-job graph
-
-| ID | Severity | Rule |
-|----|----------|------|
-| GL027 | ERROR/WARNING | `needs:` references a job that does not exist (WARNING when `optional: true`) |
-| GL028 | ERROR | `needs:` references a job in a later stage |
-| GL029 | ERROR | Circular dependency detected in `needs:` graph |
-| GL030 | ERROR | `dependencies:` references a job that does not exist |
-| GL031 | ERROR | `dependencies:` references a job in the same or a later stage |
-
-### Expression validation
-
-| ID | Severity | Rule |
-|----|----------|------|
-| GL032 | WARNING | `rules:if:` references `$VAR` not declared in `variables:` (pipeline, job, or `workflow:rules:variables:`) — may be a false positive for variables set in GitLab CI/CD project settings |
-| GL033 | WARNING | Every rule in `rules:` has `when: never` — job is permanently excluded from the pipeline (statically provable without context) |
-| GL035 | WARNING | `rules:changes` / `rules:exists` path is absolute; GitLab CI paths are relative to the repo root — absolute paths will never match |
-
-### Hidden jobs (templates)
-
-Jobs whose name starts with `.` are treated as reusable templates and skipped for most rules. This matches GitLab's own behaviour.
 
 ## Development
 

ROADMAP.md

@@ -4,53 +4,25 @@ This document tracks planned improvements to `glint`. Items are grouped by theme
 
 ---
 
-## Context-aware validation — ✓ single-context shipped in v0.2.0; expression evaluator hardened post-v0.2.0; implicit defaults and --list-vars shipped v0.2.11; variable expansion and scalar handling shipped v0.2.13; workflow evaluation and output fixes shipped v0.2.14
+## Context simulation
 
-Single-context simulation is fully implemented. Pass `--branch`, `--tag`, `--source`, or `--var` to either `glint check` or `glint graph`; jobs are evaluated and shown as active / manual / skipped.
+Pass `--branch`, `--tag`, `--source`, or `--var` to `glint check` or `glint graph` to evaluate `rules:if:` expressions and `only`/`except` filters against a specific pipeline event.
 
-```bash
+- ~~**Single-context simulation**~~ — ✓ shipped v0.2.0; `--branch`, `--tag`, `--source`, `--var` flags on both subcommands; jobs classified as active / manual / skipped
-# shipped: single-context simulation
+- ~~**`workflow:rules:variables:` propagation**~~ — ✓ shipped post-v0.2.0; variables from the matching workflow rule entry injected into the evaluation context before job `rules:if:` expressions are evaluated
-glint check --branch develop .gitlab-ci.yml
+- ~~**Expression evaluator: multi-line `if:` values**~~ — ✓ shipped post-v0.2.0; newlines in block-scalar and folded YAML `if:` values treated as whitespace
-glint check --tag v1.2.0 .gitlab-ci.yml
+- ~~**Expression evaluator: `${VAR}` syntax**~~ — ✓ shipped post-v0.2.0; `${CI_COMMIT_BRANCH}` equivalent to `$CI_COMMIT_BRANCH` everywhere
-glint check --source merge_request_event --var CI_MERGE_REQUEST_TARGET_BRANCH_NAME=main .gitlab-ci.yml
+- ~~**Expression evaluator: regex flags**~~ — ✓ shipped post-v0.2.0; `/pattern/i`, `/pattern/m`, `/pattern/s` supported
-glint graph tree --branch main .gitlab-ci.yml   # tree annotated with [skipped] / [manual]
+- ~~**Expression evaluator: variable as regex RHS**~~ — ✓ shipped post-v0.2.0; `$BRANCH =~ $PATTERN` where `$PATTERN` holds a `/regex/` string evaluates correctly
-```
+- ~~**Expression evaluator: bare `true`/`false` and integer literals**~~ — ✓ shipped post-v0.2.0; `$FLAG == true`, `$COUNT == 4` compare as decimal strings matching GitLab CI behaviour
-
+- ~~**Implicit default context**~~ — ✓ shipped v0.2.11; defaults to `--branch main --source push` when no context flag is given, so `rules:if:` is always evaluated
-**Shipped post-v0.2.0 (unreleased)**
+- ~~**`--list-vars` debug flag**~~ — ✓ shipped v0.2.11; prints sorted `KEY=VALUE` of all collected pipeline variables (root file + includes + workflow-rule union + effective context) to stderr
-
+- ~~**Variable expansion**~~ — ✓ shipped v0.2.13; `$VAR`/`${VAR}` references within variable values expanded after all sources are merged; transitive chains resolved; visible in `--list-vars`
-- ✓ **`workflow:rules:variables:` propagation** — variables defined on the matching `workflow:rules:` entry are injected into the evaluation context before job `rules:if:` expressions are evaluated. Pipeline-level `variables:` defaults are also available. Priority chain (highest wins): `--var` > shortcuts > workflow-rule vars > pipeline defaults.
+- ~~**Non-string scalar variables**~~ — ✓ shipped v0.2.13; `BUILD: true`, `RETRIES: 3` rendered and injected correctly instead of being silently dropped
-- ✓ **Expression evaluator: multi-line expressions** — newlines in block-scalar and folded YAML `if:` values are now treated as whitespace; `||` / `&&` on a continuation line evaluate correctly.
+- ~~**YAML `\/` escape in double-quoted strings**~~ — ✓ shipped v0.2.13; regex patterns like `/^us\//` in double-quoted `if:` blocks no longer cause a parse error
-- ✓ **Expression evaluator: `${VAR}` curly-brace syntax** — `${CI_COMMIT_BRANCH}` is equivalent to `$CI_COMMIT_BRANCH` everywhere.
+- ~~**Workflow rule strict evaluation**~~ — ✓ shipped v0.2.14; unparseable `if:` skips the rule instead of matching everything; prevents wrong variables being injected
-- ✓ **Expression evaluator: regex flags** — `/pattern/i`, `/pattern/m`, `/pattern/s` are now supported; `i` maps to `(?i)` in Go's regexp.
+- ~~**Single `=` operator**~~ — ✓ shipped v0.2.14; bare `=` accepted as alias for `==` in `rules:if:` expressions
-- ✓ **Expression evaluator: variable as regex RHS** — `$BRANCH =~ $PATTERN` where `$PATTERN` holds a `/regex/` string is evaluated correctly.
+- **Multi-context simulation** — run multiple contexts in one invocation and print a comparison table (`--context branch=main --context branch=develop --context tag=v1.0.0`)
-- ✓ **Expression evaluator: bare `true` / `false` keywords** — treated as the strings `"true"` / `"false"` matching GitLab CI's own behaviour; `$GATEWAY_ENABLED == true` now evaluates correctly.
-- ✓ **Expression evaluator: integer literals** — `$COUNT == 4`, `$ENABLED == 1`, `$DISABLED == 0` compare as decimal strings.
-
-~~**Implicit default context**~~ — ✓ shipped v0.2.11; `glint check` and `glint graph` default to `--branch main --source push` when no context flag is given, so `rules:if:` expressions are always evaluated out of the box.
-
-~~**`--list-vars` debug flag**~~ — ✓ shipped v0.2.11; prints sorted `KEY=VALUE` of all collected variables (pipeline YAML + included files + workflow-rule union + effective context) to stderr.
-
-**Shipped in v0.2.13**
-
-- ✓ **Variable expansion** — `$VAR` / `${VAR}` references within variable values are expanded after all sources are merged; transitive chains resolve over multiple passes; visible in `--list-vars` effective-context output.
-- ✓ **Non-string scalar variables** — `BUILD: true`, `RETRIES: 3` and similar bare boolean/integer values now render correctly in `--list-vars` and are injected into the evaluation context as string equivalents; previously shown as `(complex)` and silently dropped.
-- ✓ **YAML `\/` escape in double-quoted strings** — regex patterns like `/^us\//` in double-quoted `if:` blocks no longer cause a parse error; the raw bytes are preprocessed before YAML unmarshalling.
-
-**Shipped in v0.2.14**
-
-- ✓ **Workflow rule strict evaluation** — workflow `rules:if:` now uses strict mode (parse failure → skip rule, not match); fixes premature matching that blocked later rules and injected wrong variables.
-- ✓ **Single `=` operator** — `=` is now accepted as an alias for `==` in `rules:if:` expressions, matching common user intent.
-- ✓ **Source location through `extends:` resolution** — `File` and `Line` are now preserved when a job is rebuilt via extends, so findings reference the correct source location.
-- ✓ **Sorted findings output** — findings are sorted by `(File, Line, Rule)`; same-file issues group together in line order.
-- ✓ **Consistent warning format** — all warnings use ruff-style `path: [warning] message` format.
-- ✓ **`--version` / `-v` flag** — prints compiled version; version also shown at the top of every `--help` output.
-
-**Remaining work**
-
-- **Multi-context simulation** — run multiple contexts in one invocation and print a comparison table:
-  ```bash
-  glint check --context branch=main --context branch=develop --context tag=v1.0.0 .gitlab-ci.yml
-  ```
 - **Context-scoped linting** — skip `needs:`/`dependencies:` cross-checks for jobs that are statically unreachable in the given context
 - **`rules:changes:` evaluation** — path glob evaluation against the local git tree
 
@@ -70,7 +42,7 @@ The current rule set covers the most common sources of broken pipelines. These a
 - ~~**Duplicate stage names (GL040)**~~ — ✓ shipped v0.2.16; warns when a stage appears more than once in `stages:`
 - ~~**`cache:key:files` must be exact paths (GL041)**~~ — ✓ shipped v0.2.16; warns when entries look like glob patterns
 - ~~**Unreachable jobs**~~ — covered by GL033 (shipped v0.2.15); every-`when:never` rules block is statically dead
-- **`inherit:` completeness** — flag when a job overrides a default field that would require `inherit: default: false` to suppress
+- ~~**`inherit:` completeness (GL043)**~~ — ✓ shipped v0.2.20; warns when `inherit: default:` is declared but there's no `default:` block, or list form names fields not set in `default:`
 
 ---
 
@@ -118,7 +90,7 @@ The SVG renderer and terminal tree cover the basic layout. These would bring it
 
 - ~~**`needs: optional: true` false-positive errors**~~ — ✓ shipped post-v0.2.0; optional missing needs are downgraded to `[WARNING]`
 - ~~**`extends:` jobs with missing script false errors**~~ — ✓ shipped post-v0.2.0; jobs using `extends:` that have no `script` after resolution emit `[WARNING]` (the script may come from an unfetchable remote base)
-- **`rules:if:` static reachability** — report when a job's entire `rules:` block can never evaluate to `when: on_success` given the declared pipeline variables (pure static, no context required)
+- ~~**`rules:if:` static reachability (GL042)**~~ — ✓ shipped v0.2.20; warns when all `rules:if:` conditions evaluate to false given declared variable values (only fires when all referenced vars are declared in YAML)
 
 ---
 
@@ -141,8 +113,8 @@ The SVG renderer and terminal tree cover the basic layout. These would bring it
 
 ## Reliability and developer experience
 
-- ~~**Structured rule IDs**~~ — ✓ shipped post-v0.2.0; GL001–GL031 assigned; GL032 added v0.2.11; GL033 added v0.2.15; GL034–GL041 added v0.2.16; output formats (--format json/sarif/junit/github) added v0.2.18
+- ~~**Structured rule IDs**~~ — ✓ shipped post-v0.2.0; GL001–GL031 assigned; GL032 added v0.2.11; GL033 added v0.2.15; GL034–GL041 added v0.2.16; output formats (--format json/sarif/junit/github) added v0.2.18; GL042–GL043 added v0.2.20
-- **`--explain <rule-id>`** — print the rule description, rationale, and an example fix
+- ~~**`glint explain <rule-id>`**~~ — ✓ shipped v0.2.20; prints rule description, rationale, bad-YAML example, and fix; `glint explain` (no arg) lists all rules
 - ~~**Semantic versioning and first release**~~ — shipped as `v0.1.0` (2026-06-07)
 - ~~**Subcommand CLI**~~ — shipped as `v0.2.0` (2026-06-11); `glint check` / `glint graph [mode]` with ruff-style `--help`
 - **Changelog automation** — generate release notes from Conventional Commits via `git-cliff` or similar

Taskfile.yml

@@ -107,6 +107,18 @@ tasks:
         ignore_error: false
       - cmd: ./{{.BINARY}} check testdata/config_suppress/.gitlab-ci.yml
         ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/static_dead_rules.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/inherit_dead.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} check testdata/inherit_dead_fields.yml
+        ignore_error: false
+      - cmd: ./{{.BINARY}} explain GL007
+        ignore_error: false
+      - cmd: ./{{.BINARY}} explain gl042
+        ignore_error: false
+      - cmd: ./{{.BINARY}} explain
+        ignore_error: false
 
   lint-go:
     desc: Run go vet on all packages

USAGE.md

@@ -0,0 +1,314 @@
+# glint — usage reference
+
+Full examples and option descriptions for every command.
+For the lint rules reference see [FEATURES.md](FEATURES.md).
+
+---
+
+## `glint check`
+
+Lint a pipeline file. Exits `0` when no errors are found, `1` when at least
+one error is reported (warnings alone do not fail).
+
+```bash
+glint check .gitlab-ci.yml
+```
+
+### Output formats
+
+Pass `--format` to control the output. Plain text is the default.
+
+```bash
+# Default: ruff-style text (human-readable)
+glint check .gitlab-ci.yml
+
+# JSON — stable schema, machine-readable
+glint check --format json .gitlab-ci.yml
+
+# SARIF 2.1.0 — GitHub Code Scanning / GitLab SAST
+glint check --format sarif .gitlab-ci.yml > glint.sarif
+
+# JUnit XML — CI test-report artifact (GitLab: artifacts:reports:junit)
+glint check --format junit .gitlab-ci.yml > glint-junit.xml
+
+# GitHub Actions annotations — inline PR diff comments
+glint check --format github .gitlab-ci.yml
+```
+
+In structured formats (`json`, `sarif`, `junit`, `github`) the summary line is
+written to stderr so stdout contains only the machine-readable payload.
+
+**JSON schema (`schema_version: 1`):**
+```json
+{
+  "schema_version": 1,
+  "glint_version": "v0.2.20",
+  "pipeline": ".gitlab-ci.yml",
+  "findings": [
+    {"rule":"GL004","severity":"error","file":".gitlab-ci.yml","line":14,
+     "job":"deploy","message":"stage \"production\" is not defined in 'stages'"}
+  ],
+  "summary": {"total": 1, "errors": 1, "warnings": 0}
+}
+```
+
+**GitHub annotation lines:**
+```
+::error file=.gitlab-ci.yml,line=14,title=GL004::job "deploy": stage "production" is not defined in 'stages'
+```
+
+### Context simulation
+
+Pass `--branch`, `--tag`, or `--source` to evaluate `rules:if:` and
+`only`/`except` against a specific pipeline event. The pipeline is still fully
+linted; the context summary is printed first. When no context flag is given,
+glint defaults to `--branch main --source push`.
+
+```bash
+# What runs on a push to develop?
+glint check --branch develop .gitlab-ci.yml
+
+# What runs when a v1.2.0 tag is pushed?
+glint check --tag v1.2.0 .gitlab-ci.yml
+
+# Merge request pipeline
+glint check --source merge_request_event .gitlab-ci.yml
+
+# Arbitrary variable overrides (repeatable)
+glint check --branch main --var DEPLOY_ENV=production .gitlab-ci.yml
+
+# Debug variable resolution
+glint check --list-vars .gitlab-ci.yml
+```
+
+**Predefined variables** set by the shortcut flags:
+
+| Flag | Variables populated |
+|------|---------------------|
+| `--branch NAME` | `CI_COMMIT_BRANCH`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE=push` |
+| `--tag NAME` | `CI_COMMIT_TAG`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_PIPELINE_SOURCE=push`; clears `CI_COMMIT_BRANCH` |
+| `--source EVENT` | `CI_PIPELINE_SOURCE` |
+| `--var KEY=VALUE` | any variable; overrides shortcuts; repeatable |
+
+### Remote project includes
+
+Provide a token so glint can fetch `include: project:` templates:
+
+```bash
+# Personal access token (read_api scope)
+GITLAB_TOKEN=glpat-xxxx glint check .gitlab-ci.yml
+
+# CI/CD job token (when running inside a pipeline)
+CI_JOB_TOKEN=$CI_JOB_TOKEN glint check .gitlab-ci.yml
+
+# Self-hosted GitLab
+GITLAB_TOKEN=glpat-xxxx GITLAB_URL=https://gitlab.example.com glint check .gitlab-ci.yml
+
+# Via flags (override env vars)
+glint check --token glpat-xxxx --gitlab-url https://gitlab.example.com .gitlab-ci.yml
+```
+
+Project includes are skipped with a warning when no token is available; linting
+continues with whatever is resolved.
+
+**Token resolution order** (first non-empty wins):
+
+| Source | Header |
+|--------|--------|
+| `--token` flag / `GITLAB_TOKEN` env | `PRIVATE-TOKEN` |
+| `CI_JOB_TOKEN` env | `JOB-TOKEN` |
+| `GITLAB_PRIVATE_TOKEN` env | `PRIVATE-TOKEN` |
+
+**URL resolution order:** `--gitlab-url` flag → `CI_SERVER_URL` env → `GITLAB_URL` env → `https://gitlab.com`
+
+### Include cache and offline mode
+
+```bash
+# Cache fetched templates to disk (keyed by SHA-256 of the request coordinates)
+glint check --cache-dir ~/.cache/glint .gitlab-ci.yml
+
+# Fully offline — serve from cache, warn on misses, make no network calls
+glint check --offline .gitlab-ci.yml
+glint check --offline --cache-dir /path/to/cache .gitlab-ci.yml
+```
+
+`--offline` without `--cache-dir` uses `~/.cache/glint` automatically.
+There is no automatic cache expiry; delete the directory or individual entries
+to force a re-fetch.
+
+### Component reference format
+
+`include: component:` references follow the format:
+
+```
+<host>/<project-path>/<component-name>@<version>
+
+gitlab.com/components/secret-detection/secret-detection@v0.1.0
+gitlab.com/my-org/ci-catalog/lint@main
+gitlab.example.com/platform/components/build@~latest
+```
+
+The component file is looked up in order:
+1. `templates/<component-name>.yml` (single-file layout)
+2. `templates/<component-name>/template.yml` (directory layout)
+
+Public Catalog components work without a token. `with:` input parameters are
+substituted locally before parsing; they are not validated against the
+component spec.
+
+### Example output
+
+```
+# Clean pipeline
+Context: branch=main, source=push
+
+Active  (5): build, deploy-staging, test, lint, security-scan
+
+OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
+
+# With --branch develop
+Context: branch=develop, source=push
+
+Active  (3): build, deploy-staging, test
+Skipped (2): deploy-prod, release-notes
+
+OK: .gitlab-ci.yml — no issues found (5 job(s), 3 stage(s))
+
+# Pipeline with issues
+.gitlab-ci.yml:14: GL004 [error] job "deploy": stage "production" is not defined in 'stages'
+.gitlab-ci.yml:22: GL027 [error] job "test": needs unknown job "build-app"
+.gitlab-ci.yml:31: GL007 [warning] job "old-job": 'only'/'except' are deprecated; prefer 'rules'
+
+3 finding(s): 2 error(s)
+```
+
+---
+
+## `glint graph`
+
+Visualise the pipeline. Without a mode word, prints a job tree and the include
+dependency graph separated by `---`.
+
+```bash
+# Default: job tree + include dependency graph
+glint graph .gitlab-ci.yml
+
+# Job tree only
+glint graph tree .gitlab-ci.yml
+
+# Job tree with context (shows active/manual/skipped annotations)
+glint graph tree --branch develop .gitlab-ci.yml
+
+# Include dependency graph → Mermaid flowchart to stdout
+glint graph includes .gitlab-ci.yml > includes.mmd
+
+# GitLab-like pipeline layout → PNG/SVG written to --out dir
+glint graph pipeline .gitlab-ci.yml
+# prints the output path, e.g.: glint-out/pipeline-20260614-143022.png
+
+# Mermaid to stdout + pipeline file path to stderr
+glint graph all .gitlab-ci.yml > includes.mmd
+
+# Custom output directory
+glint graph pipeline --out /tmp/graphs .gitlab-ci.yml
+```
+
+**Job tree** — stages as branches, jobs as leaves; annotated with `[manual]`,
+`[delayed]`, `[trigger]` where applicable. Context flags apply the same
+evaluation as `glint check`.
+
+**Include graph** — [Mermaid](https://mermaid.js.org) flowchart; pipe to `.mmd`
+or paste into [mermaid.live](https://mermaid.live). Nodes are colour-coded by
+include type: orange (main file), purple (project), green (component), blue
+(local), grey (remote URL), light orange (GitLab template).
+
+**Pipeline graph** — GitLab CI-style SVG rendered to a timestamped file.
+Converted to PNG when `rsvg-convert`, `inkscape`, or `magick` is available.
+DAG mode (Bézier arrows between jobs) activates automatically when any job has
+a `needs:` list; classic mode uses stage-column connectors otherwise.
+
+---
+
+## `glint explain`
+
+Print the documentation for a specific lint rule.
+
+```bash
+# Description, example, and fix for GL007
+glint explain GL007
+
+# Case-insensitive
+glint explain gl007
+
+# List all rules with ID, severity, and title
+glint explain
+```
+
+---
+
+## Project configuration (`.glint.yml`)
+
+Place a `.glint.yml` anywhere in the directory tree from the pipeline file up
+to the first `.git` boundary. glint searches upward and uses the first file it
+finds.
+
+```yaml
+# Suppress rules globally for this project.
+ignore:
+  - GL007   # migrating from only:/except:
+  - GL032   # dynamic variables injected by CI
+
+# Override rule severity: error | warning | ignore
+# 'ignore' is equivalent to listing the rule under ignore:.
+severity:
+  GL004: warning   # demote during a stage migration
+  GL035: error     # promote to hard error for this project
+
+# Extra stage names valid beyond those declared in the pipeline YAML
+# (e.g. injected by an include template you don't own).
+stages:
+  - quality
+  - security
+
+# Default token — lower priority than --token and GITLAB_TOKEN.
+token: glpat-xxxx
+
+# Default GitLab instance URL.
+url: https://gitlab.example.com
+
+# Default cache directory for fetched remote includes.
+cache_dir: ~/.cache/glint
+```
+
+**Priority chain:** `--token`/`--gitlab-url` flags > `.glint.yml` > environment variables.
+
+---
+
+## Inline suppression (`# glint: ignore`)
+
+Suppress a finding for a specific job by placing a comment immediately before
+the job definition in the pipeline YAML:
+
+```yaml
+# glint: ignore GL007
+legacy-job:
+  stage: build
+  only: [main]
+  script: echo ok
+
+# Multiple rules — comma- or space-separated:
+# glint: ignore GL007, GL032
+other-job:
+  stage: build
+  script: echo ok
+
+# Suppress every rule for this job:
+# glint: ignore all
+noisy-job:
+  stage: build
+  script: echo ok
+```
+
+Suppressions are scoped to the single job they precede and do not affect other
+jobs or pipeline-level findings. For project-wide suppression, use `.glint.yml`
+`ignore:` instead.

cmd/glint/explain.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+
+	"git.k3nny.fr/glint/internal/linter"
+)
+
+func cmdExplain(args []string) {
+	if len(args) == 0 {
+		printRuleList()
+		return
+	}
+	ruleID := strings.ToUpper(args[0])
+	entry, ok := linter.RuleCatalog[ruleID]
+	if !ok {
+		fmt.Fprintf(os.Stderr, "glint explain: unknown rule %q\n\nRun 'glint explain' to list all rules.\n", ruleID)
+		os.Exit(2)
+	}
+	printRuleEntry(ruleID, entry)
+}
+
+func printRuleEntry(id string, e linter.RuleEntry) {
+	sev := strings.ToLower(string(e.Severity))
+	header := fmt.Sprintf("%s  [%s]  %s", id, sev, e.Title)
+	rule := fmt.Sprintf("\n%s\n%s\n\n%s\n",
+		header,
+		strings.Repeat("─", len(header)),
+		e.Description,
+	)
+	fmt.Print(rule)
+
+	if e.Example != "" {
+		fmt.Println("Example:")
+		fmt.Println()
+		for _, line := range strings.Split(e.Example, "\n") {
+			fmt.Printf("  %s\n", line)
+		}
+		fmt.Println()
+	}
+
+	if e.Fix != "" {
+		fmt.Println("Fix:")
+		fmt.Println()
+		for _, line := range strings.Split(e.Fix, "\n") {
+			fmt.Printf("  %s\n", line)
+		}
+		fmt.Println()
+	}
+}
+
+func printRuleList() {
+	ids := make([]string, 0, len(linter.RuleCatalog))
+	for id := range linter.RuleCatalog {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+
+	fmt.Printf("glint %s — lint rules\n\n", version)
+	for _, id := range ids {
+		e := linter.RuleCatalog[id]
+		sev := strings.ToLower(string(e.Severity))
+		fmt.Printf("  %-6s  [%-7s]  %s\n", id, sev, e.Title)
+	}
+	fmt.Println("\nUse 'glint explain <RULE>' for details on a specific rule.")
+}

cmd/glint/main.go

@@ -39,6 +39,7 @@ Usage: glint [OPTIONS] <COMMAND>
 Commands:
   check    Lint a pipeline file — exits 0 (clean) or 1 (errors found)
   graph    Visualise the pipeline as a job tree or Mermaid graph
+  explain  Show description and fix for a lint rule (e.g. glint explain GL007)
 
 Options:
   -h, --help     Print help
@@ -57,6 +58,8 @@ func main() {
 		cmdCheck(os.Args[2:])
 	case "graph":
 		cmdGraph(os.Args[2:])
+	case "explain":
+		cmdExplain(os.Args[2:])
 	case "-h", "--help", "help":
 		fmt.Fprintf(os.Stderr, "glint %s\n\n", version)
 		fmt.Fprint(os.Stderr, globalUsage)

internal/linter/explain.go

@@ -0,0 +1,819 @@
+package linter
+
+// RuleEntry holds the human-readable documentation for a single lint rule,
+// shown by 'glint explain <RULE>'.
+type RuleEntry struct {
+	Title       string   // short title (one line)
+	Severity    Severity // Error or Warning
+	Description string   // what triggers the rule and why it matters
+	Example     string   // YAML snippet that triggers the rule
+	Fix         string   // corrected YAML
+}
+
+// RuleCatalog maps stable rule IDs to their documentation entries.
+var RuleCatalog = map[string]RuleEntry{
+	RuleNoStages: {
+		Title:    "no stages defined",
+		Severity: Warning,
+		Description: "The pipeline has no 'stages:' block. GitLab falls back to the " +
+			"built-in default stages (build, test, deploy), which may not match your " +
+			"intended job ordering.",
+		Example: `# No stages: block
+build-job:
+  script: make build
+
+test-job:
+  script: make test`,
+		Fix: `stages:
+  - build
+  - test
+
+build-job:
+  stage: build
+  script: make build
+
+test-job:
+  stage: test
+  script: make test`,
+	},
+
+	RuleWorkflowWhen: {
+		Title:    "workflow.rules.when invalid value",
+		Severity: Error,
+		Description: "'workflow.rules[n].when' only accepts 'always' or 'never'. Any " +
+			"other value (such as 'on_success' or 'manual') is invalid and will cause " +
+			"the pipeline to fail to create.",
+		Example: `workflow:
+  rules:
+    - if: $CI_COMMIT_BRANCH
+      when: on_success   # invalid here`,
+		Fix: `workflow:
+  rules:
+    - if: $CI_COMMIT_BRANCH
+      when: always`,
+	},
+
+	RuleMissingScript: {
+		Title:    "missing required 'script' field",
+		Severity: Error,
+		Description: "Every non-trigger, non-pages job must define 'script:' (or 'run:' " +
+			"for CI Steps). A job with no script will fail immediately when GitLab tries " +
+			"to run it.",
+		Example: `my-job:
+  stage: test
+  image: python:3.12
+  # Missing script:`,
+		Fix: `my-job:
+  stage: test
+  image: python:3.12
+  script: pytest`,
+	},
+
+	RuleUnknownStage: {
+		Title:    "job references undeclared stage",
+		Severity: Error,
+		Description: "The job's 'stage:' value does not match any name in the pipeline's " +
+			"'stages:' list. GitLab will reject the pipeline configuration.",
+		Example: `stages:
+  - build
+  - test
+
+deploy-job:
+  stage: production   # not in stages:
+  script: ./deploy.sh`,
+		Fix: `stages:
+  - build
+  - test
+  - production
+
+deploy-job:
+  stage: production
+  script: ./deploy.sh`,
+	},
+
+	RuleOnlyRulesConflict: {
+		Title:    "'only:' and 'rules:' used together",
+		Severity: Error,
+		Description: "'only:' and 'rules:' are mutually exclusive. Using both on the " +
+			"same job is a configuration error that prevents the pipeline from being " +
+			"created.",
+		Example: `my-job:
+  only:
+    - main
+  rules:
+    - if: $CI_COMMIT_BRANCH
+  script: echo conflict`,
+		Fix: `# Remove only: and use rules: exclusively
+my-job:
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+  script: echo ok`,
+	},
+
+	RuleExceptRulesConflict: {
+		Title:    "'except:' and 'rules:' used together",
+		Severity: Error,
+		Description: "'except:' and 'rules:' are mutually exclusive. Using both on the " +
+			"same job is a configuration error that prevents the pipeline from being " +
+			"created.",
+		Example: `my-job:
+  except:
+    - tags
+  rules:
+    - if: $CI_COMMIT_BRANCH
+  script: echo conflict`,
+		Fix: `my-job:
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: never
+    - if: $CI_COMMIT_BRANCH
+  script: echo ok`,
+	},
+
+	RuleDeprecatedOnly: {
+		Title:    "'only:' / 'except:' deprecated",
+		Severity: Warning,
+		Description: "'only:' and 'except:' are deprecated in favour of 'rules:'. " +
+			"GitLab may remove support for these keywords in a future major version. " +
+			"'rules:' is more expressive and supports variable references, merge-request " +
+			"conditions, and fine-grained 'when:' control.",
+		Example: `my-job:
+  only:
+    - main
+  script: ./deploy.sh`,
+		Fix: `my-job:
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+  script: ./deploy.sh`,
+	},
+
+	RuleInvalidWhen: {
+		Title:    "'when:' has invalid value",
+		Severity: Error,
+		Description: "Job-level 'when:' accepts: on_success, on_failure, always, " +
+			"manual, delayed, never. Any other value is rejected by GitLab.",
+		Example: `my-job:
+  when: sometimes   # invalid
+  script: echo hi`,
+		Fix: `my-job:
+  when: on_success
+  script: echo hi`,
+	},
+
+	RuleDelayedNoStartIn: {
+		Title:    "'when: delayed' without 'start_in:'",
+		Severity: Error,
+		Description: "'when: delayed' requires a 'start_in:' duration (e.g. " +
+			"'30 minutes', '1 hour'). Without it GitLab rejects the job configuration.",
+		Example: `my-job:
+  when: delayed
+  script: echo hi`,
+		Fix: `my-job:
+  when: delayed
+  start_in: 30 minutes
+  script: echo hi`,
+	},
+
+	RuleStartInNoDelayed: {
+		Title:    "'start_in:' without 'when: delayed'",
+		Severity: Error,
+		Description: "'start_in:' is only meaningful when 'when: delayed'. Setting it " +
+			"alongside any other 'when:' value is a configuration error.",
+		Example: `my-job:
+  when: on_success
+  start_in: 30 minutes   # only valid with delayed
+  script: echo hi`,
+		Fix: `my-job:
+  when: delayed
+  start_in: 30 minutes
+  script: echo hi`,
+	},
+
+	RuleInvalidParallel: {
+		Title:    "'parallel:' value invalid",
+		Severity: Error,
+		Description: "'parallel:' must be an integer between 2 and 200 (inclusive), " +
+			"or a map with a 'matrix:' key for matrix jobs. Values outside this range " +
+			"or the wrong type are rejected by GitLab.",
+		Example: `my-job:
+  parallel: 1   # must be 2–200
+  script: echo hi`,
+		Fix: `my-job:
+  parallel: 5
+  script: echo hi`,
+	},
+
+	RuleInvalidRetry: {
+		Title:    "'retry:' value invalid",
+		Severity: Error,
+		Description: "'retry:' accepts an integer 0–2 or a map with optional 'max:' " +
+			"(0–2) and 'when:' keys. Values outside this range are rejected.",
+		Example: `my-job:
+  retry: 5   # max is 2
+  script: echo hi`,
+		Fix: `my-job:
+  retry: 2
+  script: echo hi`,
+	},
+
+	RuleInvalidRetryWhen: {
+		Title:    "'retry.when:' has invalid failure type",
+		Severity: Error,
+		Description: "'retry.when:' must be a recognised GitLab CI failure type " +
+			"(e.g. script_failure, runner_system_failure) or 'always'. Unknown " +
+			"values are rejected.",
+		Example: `my-job:
+  retry:
+    max: 2
+    when: disk_full   # not a valid failure type
+  script: echo hi`,
+		Fix: `my-job:
+  retry:
+    max: 2
+    when: runner_system_failure
+  script: echo hi`,
+	},
+
+	RuleInvalidAllowFailure: {
+		Title:    "'allow_failure:' invalid value",
+		Severity: Error,
+		Description: "'allow_failure:' must be a boolean (true/false) or a map with " +
+			"an 'exit_codes:' key. Other forms are rejected by GitLab.",
+		Example: `my-job:
+  allow_failure: maybe   # must be true/false or map
+  script: echo hi`,
+		Fix: `my-job:
+  allow_failure: true
+  script: echo hi`,
+	},
+
+	RuleInvalidInterruptible: {
+		Title:    "'interruptible:' is not a boolean",
+		Severity: Error,
+		Description: "'interruptible:' must be a boolean (true or false). Other types " +
+			"are rejected.",
+		Example: `my-job:
+  interruptible: yes   # must be a YAML boolean true/false
+  script: echo hi`,
+		Fix: `my-job:
+  interruptible: true
+  script: echo hi`,
+	},
+
+	RuleTriggerWithScript: {
+		Title:    "trigger job also defines 'script:'",
+		Severity: Error,
+		Description: "Jobs with a 'trigger:' key (downstream pipeline triggers) cannot " +
+			"use 'script:'. These are mutually exclusive — a trigger job has no runner " +
+			"environment to execute scripts in.",
+		Example: `trigger-job:
+  trigger:
+    project: mygroup/myproject
+  script: echo this will fail`,
+		Fix: `trigger-job:
+  trigger:
+    project: mygroup/myproject`,
+	},
+
+	RuleInvalidTrigger: {
+		Title:    "trigger: map missing 'project:' or 'include:'",
+		Severity: Error,
+		Description: "When 'trigger:' is a map it must specify either 'project:' " +
+			"(downstream project trigger) or 'include:' (dynamic child pipeline). " +
+			"Without one of these keys GitLab cannot determine what to trigger.",
+		Example: `trigger-job:
+  trigger:
+    strategy: depend   # missing project: or include:`,
+		Fix: `trigger-job:
+  trigger:
+    project: mygroup/downstream
+    strategy: depend`,
+	},
+
+	RuleInvalidCoverage: {
+		Title:    "'coverage:' is not a regex pattern",
+		Severity: Error,
+		Description: "'coverage:' must be a regex pattern wrapped in forward slashes " +
+			"(e.g. '/Coverage: \\d+\\.?\\d*%/'). GitLab uses this pattern to extract " +
+			"the coverage percentage from job output.",
+		Example: `my-job:
+  coverage: "\\d+%"   # missing surrounding /…/
+  script: pytest --cov`,
+		Fix: `my-job:
+  coverage: '/Coverage: \d+\.?\d*%/'
+  script: pytest --cov`,
+	},
+
+	RuleInvalidRelease: {
+		Title:    "'release:' missing required 'tag_name:'",
+		Severity: Error,
+		Description: "'release:' must be a map and must include a 'tag_name:' key. " +
+			"Without it GitLab cannot create the release.",
+		Example: `release-job:
+  script: echo releasing
+  release:
+    name: My Release   # missing tag_name:`,
+		Fix: `release-job:
+  script: echo releasing
+  release:
+    tag_name: $CI_COMMIT_TAG
+    name: My Release`,
+	},
+
+	RuleInvalidEnvironment: {
+		Title:    "'environment:' invalid url or action",
+		Severity: Error,
+		Description: "'environment.url' requires 'environment.name' to be set. " +
+			"'environment.action' must be one of: start, stop, prepare, verify, access.",
+		Example: `my-job:
+  script: ./deploy.sh
+  environment:
+    url: https://prod.example.com   # name: is required`,
+		Fix: `my-job:
+  script: ./deploy.sh
+  environment:
+    name: production
+    url: https://prod.example.com`,
+	},
+
+	RuleInvalidArtifacts: {
+		Title:    "'artifacts:' invalid configuration",
+		Severity: Error,
+		Description: "'artifacts.when' must be on_success, on_failure, or always. " +
+			"'artifacts.expose_as' requires 'artifacts.paths' to be set.",
+		Example: `my-job:
+  script: make
+  artifacts:
+    when: sometimes   # invalid value`,
+		Fix: `my-job:
+  script: make
+  artifacts:
+    when: on_failure
+    paths:
+      - build/logs/`,
+	},
+
+	RulePagesPublic: {
+		Title:    "pages job missing 'public' in artifacts.paths",
+		Severity: Warning,
+		Description: "The 'pages' job must include 'public' (or a path starting with " +
+			"'public/') in 'artifacts.paths' for GitLab Pages to deploy the site.",
+		Example: `pages:
+  script: hugo
+  artifacts:
+    paths:
+      - dist/   # should include public/`,
+		Fix: `pages:
+  script: hugo --destination public
+  artifacts:
+    paths:
+      - public/`,
+	},
+
+	RuleInvalidCache: {
+		Title:    "'cache:' invalid when or policy",
+		Severity: Error,
+		Description: "'cache.when' must be on_success, on_failure, or always. " +
+			"'cache.policy' must be pull, push, or pull-push.",
+		Example: `my-job:
+  script: npm ci
+  cache:
+    paths: [node_modules/]
+    policy: read-only   # invalid; use pull`,
+		Fix: `my-job:
+  script: npm ci
+  cache:
+    paths: [node_modules/]
+    policy: pull`,
+	},
+
+	RuleInvalidRulesWhen: {
+		Title:    "'rules[n].when:' has invalid value",
+		Severity: Error,
+		Description: "Inside a 'rules:' block, 'when:' must be one of: on_success, " +
+			"on_failure, always, manual, delayed, never. Other values are rejected.",
+		Example: `my-job:
+  rules:
+    - if: $CI_COMMIT_BRANCH
+      when: conditional   # not valid here
+  script: echo hi`,
+		Fix: `my-job:
+  rules:
+    - if: $CI_COMMIT_BRANCH
+      when: on_success
+  script: echo hi`,
+	},
+
+	RuleInvalidImage: {
+		Title:    "'image:' map form missing 'name:'",
+		Severity: Error,
+		Description: "When 'image:' is a map, it must include a 'name:' key specifying " +
+			"the Docker image. Without it GitLab cannot resolve which image to pull.",
+		Example: `my-job:
+  image:
+    entrypoint: ["/bin/sh"]   # missing name:
+  script: echo hi`,
+		Fix: `my-job:
+  image:
+    name: alpine:3.19
+    entrypoint: ["/bin/sh"]
+  script: echo hi`,
+	},
+
+	RuleInvalidInherit: {
+		Title:    "'inherit.default' or 'inherit.variables' invalid type",
+		Severity: Error,
+		Description: "'inherit.default' and 'inherit.variables' must each be a boolean " +
+			"(true/false) or a list of field/variable names. Other types are rejected.",
+		Example: `my-job:
+  inherit:
+    default: "no"   # must be true/false or a list
+  script: echo hi`,
+		Fix: `my-job:
+  inherit:
+    default: false
+  script: echo hi`,
+	},
+
+	RuleNeedsUnknown: {
+		Title:    "'needs:' references unknown job",
+		Severity: Error,
+		Description: "A job in the 'needs:' list does not exist in the pipeline. " +
+			"GitLab will refuse to create the pipeline.",
+		Example: `build:
+  stage: build
+  script: make
+
+test:
+  stage: test
+  needs: [build, lint]   # lint does not exist
+  script: make test`,
+		Fix: `lint:
+  stage: build
+  script: make lint
+
+build:
+  stage: build
+  script: make
+
+test:
+  stage: test
+  needs: [build, lint]
+  script: make test`,
+	},
+
+	RuleNeedsStageOrder: {
+		Title:    "'needs:' job is in a later stage",
+		Severity: Error,
+		Description: "A job listed in 'needs:' is in a later stage than the current " +
+			"job. GitLab does not allow needs: to reference future stages.",
+		Example: `stages: [build, test, deploy]
+
+test:
+  stage: test
+  needs: [deploy-job]   # deploy-job is in a later stage
+  script: make test
+
+deploy-job:
+  stage: deploy
+  script: ./deploy.sh`,
+		Fix: `stages: [build, test, deploy]
+
+test:
+  stage: test
+  needs: [build-job]
+  script: make test
+
+build-job:
+  stage: build
+  script: make`,
+	},
+
+	RuleNeedsCycle: {
+		Title:    "circular dependency in 'needs:' graph",
+		Severity: Error,
+		Description: "Two or more jobs in the 'needs:' graph form a cycle — A needs B " +
+			"and B needs A (directly or transitively). GitLab will reject the pipeline.",
+		Example: `job-a:
+  stage: test
+  needs: [job-b]
+  script: echo a
+
+job-b:
+  stage: test
+  needs: [job-a]
+  script: echo b`,
+		Fix: `job-a:
+  stage: test
+  script: echo a
+
+job-b:
+  stage: test
+  needs: [job-a]
+  script: echo b`,
+	},
+
+	RuleUnknownDependency: {
+		Title:    "'dependencies:' references unknown job",
+		Severity: Error,
+		Description: "A job listed in 'dependencies:' does not exist in the pipeline. " +
+			"GitLab will refuse to create the pipeline.",
+		Example: `test:
+  stage: test
+  dependencies: [build, missing-job]
+  script: make test`,
+		Fix: `build:
+  stage: build
+  script: make
+  artifacts:
+    paths: [dist/]
+
+test:
+  stage: test
+  dependencies: [build]
+  script: make test`,
+	},
+
+	RuleDependencyStage: {
+		Title:    "'dependencies:' job in same or later stage",
+		Severity: Error,
+		Description: "'dependencies:' can only reference jobs in earlier stages. " +
+			"Referencing a job in the same or a later stage is not allowed because " +
+			"artifacts would not yet be available.",
+		Example: `stages: [test, deploy]
+
+test:
+  stage: test
+  dependencies: [deploy-job]   # deploy is a later stage
+  script: make test
+
+deploy-job:
+  stage: deploy
+  script: ./deploy.sh`,
+		Fix: `stages: [build, test, deploy]
+
+build:
+  stage: build
+  script: make
+  artifacts:
+    paths: [dist/]
+
+test:
+  stage: test
+  dependencies: [build]
+  script: make test`,
+	},
+
+	RuleUndeclaredVariable: {
+		Title:    "'rules:if:' references undeclared variable",
+		Severity: Warning,
+		Description: "A 'rules:if:' expression references a variable that is not " +
+			"declared in any 'variables:' block in the pipeline YAML. This may be a " +
+			"typo, or the variable may be set in GitLab project settings (invisible to " +
+			"glint). Predefined CI_* and GITLAB_* variables are always exempt.",
+		Example: `variables:
+  APP_ENV: staging
+
+my-job:
+  rules:
+    - if: $DEPLOY_ENV == "prod"   # DEPLOY_ENV not declared
+  script: ./deploy.sh`,
+		Fix: `variables:
+  APP_ENV: staging
+  DEPLOY_ENV: staging   # declare it, or set it in GitLab project settings
+
+my-job:
+  rules:
+    - if: $DEPLOY_ENV == "prod"
+  script: ./deploy.sh`,
+	},
+
+	RuleDeadRules: {
+		Title:    "rules: block has all 'when: never' — job permanently excluded",
+		Severity: Warning,
+		Description: "Every rule in the job's 'rules:' block has an explicit " +
+			"'when: never'. No matter which conditions match, the job will never " +
+			"be included in any pipeline run.",
+		Example: `my-job:
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+      when: never
+    - when: never
+  script: echo unreachable`,
+		Fix: `# Option 1: remove the job entirely
+# Option 2: give at least one rule a non-never when:
+my-job:
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+      when: on_success
+    - when: never
+  script: echo deploy`,
+	},
+
+	RuleInvalidService: {
+		Title:    "'services:' map form missing 'name:' or invalid 'alias:'",
+		Severity: Error,
+		Description: "When a service entry is a map it must include a 'name:' key. " +
+			"'alias:' (if set) must be a valid DNS label: alphanumeric characters, " +
+			"hyphens, and dots only; must start and end with alphanumeric.",
+		Example: `my-job:
+  script: pytest
+  services:
+    - alias: my_db   # underscore is not valid in a DNS label`,
+		Fix: `my-job:
+  script: pytest
+  services:
+    - name: postgres:15
+      alias: my-db`,
+	},
+
+	RuleAbsoluteGlobPath: {
+		Title:    "'rules:changes' or 'rules:exists' uses absolute path",
+		Severity: Warning,
+		Description: "Paths in 'rules:changes' and 'rules:exists' are always relative " +
+			"to the repository root. An absolute path starting with '/' will never " +
+			"match any file and will silently disable the rule.",
+		Example: `my-job:
+  rules:
+    - changes:
+        - /src/**/*.go   # absolute — will never match
+  script: make`,
+		Fix: `my-job:
+  rules:
+    - changes:
+        - src/**/*.go
+  script: make`,
+	},
+
+	RuleInvalidTimeout: {
+		Title:    "'timeout:' is not a valid duration string",
+		Severity: Error,
+		Description: "'timeout:' must be a GitLab CI duration string composed of " +
+			"recognised time units: weeks (w), days (d), hours (h), minutes (m/min), " +
+			"seconds (s). Examples: '1h 30m', '90 minutes', '2 hours'.",
+		Example: `my-job:
+  timeout: "1:30:00"   # colon-separated format not supported
+  script: long-running-task.sh`,
+		Fix: `my-job:
+  timeout: 1h 30m
+  script: long-running-task.sh`,
+	},
+
+	RuleInvalidIDToken: {
+		Title:    "'id_tokens:' entry missing required 'aud:' key",
+		Severity: Error,
+		Description: "Each entry under 'id_tokens:' must be a map with an 'aud:' " +
+			"(audience) key. Without 'aud:' GitLab cannot generate the ID token " +
+			"and the job will fail.",
+		Example: `my-job:
+  id_tokens:
+    MY_TOKEN:
+      # missing aud:
+  script: vault-login.sh`,
+		Fix: `my-job:
+  id_tokens:
+    MY_TOKEN:
+      aud: https://vault.example.com
+  script: vault-login.sh`,
+	},
+
+	RuleInvalidSecret: {
+		Title:    "'secrets:' entry missing a provider key",
+		Severity: Error,
+		Description: "Each entry under 'secrets:' must specify a provider: one of " +
+			"'vault:', 'gcp_secret_manager:', or 'azure_key_vault:'. Without a " +
+			"provider GitLab cannot retrieve the secret.",
+		Example: `my-job:
+  secrets:
+    DB_PASSWORD:
+      path: secret/db/password   # no provider key
+  script: run.sh`,
+		Fix: `my-job:
+  secrets:
+    DB_PASSWORD:
+      vault:
+        engine:
+          name: kv-v2
+          path: secret
+        path: db/password
+        field: password
+  script: run.sh`,
+	},
+
+	RulePagesPublish: {
+		Title:    "'pages:' keyword publish directory missing from 'artifacts.paths'",
+		Severity: Warning,
+		Description: "A job using the 'pages:' keyword must include its publish " +
+			"directory in 'artifacts.paths'. Without this, GitLab Pages will not " +
+			"deploy the site.",
+		Example: `my-pages-job:
+  script: hugo
+  pages:
+    publish: public
+  artifacts:
+    paths:
+      - dist/   # missing public/`,
+		Fix: `my-pages-job:
+  script: hugo
+  pages:
+    publish: public
+  artifacts:
+    paths:
+      - public/`,
+	},
+
+	RuleDuplicateStage: {
+		Title:    "duplicate stage name in 'stages:'",
+		Severity: Warning,
+		Description: "A stage name appears more than once in the 'stages:' list. " +
+			"GitLab silently merges duplicate stage entries, which can make the " +
+			"pipeline order confusing.",
+		Example: `stages:
+  - build
+  - test
+  - test   # duplicate`,
+		Fix: `stages:
+  - build
+  - test`,
+	},
+
+	RuleInvalidCacheKeyFiles: {
+		Title:    "'cache.key.files' contains a glob pattern",
+		Severity: Warning,
+		Description: "'cache.key.files' must be a list of exact file paths. Glob " +
+			"patterns (*, ?, [...]) are not expanded — the literal glob string is " +
+			"used as the cache key, which probably doesn't match your intent.",
+		Example: `my-job:
+  script: npm ci
+  cache:
+    key:
+      files:
+        - package*.json   # glob — use exact path`,
+		Fix: `my-job:
+  script: npm ci
+  cache:
+    key:
+      files:
+        - package.json
+        - package-lock.json`,
+	},
+
+	RuleStaticDeadRules: {
+		Title:    "rules:if: block statically never activates",
+		Severity: Warning,
+		Description: "Every 'rules:if:' condition in this job evaluates to false " +
+			"using the variable values declared in the pipeline YAML. The job will " +
+			"never be included in any pipeline run. This check only fires when ALL " +
+			"referenced variables are declared in the YAML (predefined CI_* variables " +
+			"are not evaluated to avoid false positives).",
+		Example: `variables:
+  ENABLE_DEPLOY: "false"
+
+deploy:
+  rules:
+    - if: '$ENABLE_DEPLOY == "true"'   # always false: ENABLE_DEPLOY is "false"
+  script: ./deploy.sh`,
+		Fix: `variables:
+  ENABLE_DEPLOY: "true"   # fix the variable value
+
+deploy:
+  rules:
+    - if: '$ENABLE_DEPLOY == "true"'
+  script: ./deploy.sh
+
+# Or add an unconditional fallback:
+deploy:
+  rules:
+    - if: '$ENABLE_DEPLOY == "true"'
+    - when: manual   # allow manual trigger as a fallback
+  script: ./deploy.sh`,
+	},
+
+	RuleInheritNoDefault: {
+		Title:    "'inherit: default:' declared but no 'default:' block",
+		Severity: Warning,
+		Description: "A job declares 'inherit: default:' but the pipeline has no " +
+			"'default:' block, so the declaration has no effect. This can also fire " +
+			"when 'inherit: default: [list]' names fields that are not set in the " +
+			"'default:' block.",
+		Example: `# No default: block exists
+
+my-job:
+  inherit:
+    default: false   # no-op: nothing to opt out of
+  script: echo hi`,
+		Fix: `# Either add a default: block...
+default:
+  before_script:
+    - source venv/bin/activate
+
+my-job:
+  inherit:
+    default: false
+  script: echo hi
+
+# ...or remove the pointless inherit: declaration
+my-job:
+  script: echo hi`,
+	},
+}

internal/linter/if_reachability.go

@@ -0,0 +1,104 @@
+package linter
+
+import (
+	"git.k3nny.fr/glint/internal/cicontext"
+	"git.k3nny.fr/glint/internal/model"
+)
+
+// checkRulesIfReachability (GL042): warn when every rule in a job's rules: block
+// can be statically proven to never activate given the values of variables
+// declared in the pipeline YAML. Only fires when ALL variables referenced by the
+// rules:if: expressions are declared in the pipeline or job variables: blocks —
+// predefined CI_* / GITLAB_* variables or variables not declared in YAML are
+// treated as unknown (could have any runtime value) so the check is skipped
+// conservatively to avoid false positives.
+func checkRulesIfReachability(p *model.Pipeline) []Finding {
+	if len(p.Jobs) == 0 {
+		return nil
+	}
+
+	// Collect scalar string values from pipeline-level variables.
+	pipelineVars := make(map[string]string, len(p.Variables))
+	for k, v := range p.Variables {
+		if s, ok := cicontext.ScalarString(v); ok {
+			pipelineVars[k] = s
+		}
+	}
+
+	var findings []Finding
+	for name, job := range p.Jobs {
+		if len(job.Rules) == 0 {
+			continue
+		}
+
+		// Merge pipeline vars with job-level variable overrides.
+		jobVars := make(map[string]string, len(pipelineVars)+len(job.Variables))
+		for k, v := range pipelineVars {
+			jobVars[k] = v
+		}
+		for k, v := range job.Variables {
+			if s, ok := cicontext.ScalarString(v); ok {
+				jobVars[k] = s
+			}
+		}
+
+		if f := evalRulesReachability(name, job, jobVars); f != nil {
+			findings = append(findings, *f)
+		}
+	}
+	return findings
+}
+
+// evalRulesReachability returns a GL042 finding when the job's rules: block
+// can never activate given the provided variable map, or nil if the job
+// might activate (or the check cannot be applied conservatively).
+func evalRulesReachability(name string, job model.Job, jobVars map[string]string) *Finding {
+	lookup := func(k string) string { return jobVars[k] }
+
+	for _, rule := range job.Rules {
+		// Explicit when: never — this rule is provably dead; continue.
+		if rule.When == "never" {
+			continue
+		}
+
+		// No if: condition → this rule always matches → job CAN activate.
+		if rule.If == "" {
+			return nil
+		}
+
+		// Check whether all variables referenced in the if: expression are
+		// declared in the pipeline YAML. If any are not declared (predefined
+		// CI vars, project settings, etc.), we cannot evaluate the expression
+		// and must conservatively assume the job might activate.
+		refs := extractIfVars(rule.If)
+		allDeclared := true
+		for _, ref := range refs {
+			if _, ok := jobVars[ref]; !ok {
+				// Variable not in YAML (predefined or unknown) → cannot evaluate.
+				allDeclared = false
+				break
+			}
+		}
+		if !allDeclared {
+			return nil // conservative: job might activate
+		}
+
+		// All referenced variables are declared; evaluate the expression.
+		// Use strict mode (unparse → false) to avoid matching unparseable expressions.
+		if cicontext.EvalIfStrict(rule.If, lookup) {
+			// This rule's condition evaluates to true → job CAN activate.
+			return nil
+		}
+		// Expression evaluated to false → this rule cannot activate; continue.
+	}
+
+	// No rule could activate the job.
+	return &Finding{
+		Severity: Warning,
+		Rule:     RuleStaticDeadRules,
+		Job:      name,
+		File:     job.File,
+		Line:     job.Line,
+		Message:  "rules: block can never activate: all if: conditions evaluate to false given the declared pipeline variables",
+	}
+}

internal/linter/if_reachability_test.go

@@ -0,0 +1,152 @@
+package linter
+
+import (
+	"testing"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+func TestCheckRulesIfReachability(t *testing.T) {
+	makeJob := func(vars map[string]any, rules []model.Rule) model.Job {
+		return model.Job{Variables: vars, Rules: rules}
+	}
+
+	cases := []struct {
+		name        string
+		pipelineVars map[string]any
+		jobs        map[string]model.Job
+		wantHit     []string // job names that should produce GL042
+		wantMiss    []string // job names that should NOT produce GL042
+	}{
+		{
+			name:         "declared var always false — GL042 fires",
+			pipelineVars: map[string]any{"DEPLOY": "false"},
+			jobs: map[string]model.Job{
+				"deploy": makeJob(nil, []model.Rule{
+					{If: `$DEPLOY == "true"`, When: "on_success"},
+				}),
+			},
+			wantHit:  []string{"deploy"},
+			wantMiss: nil,
+		},
+		{
+			name:         "declared var matches — no finding",
+			pipelineVars: map[string]any{"DEPLOY": "true"},
+			jobs: map[string]model.Job{
+				"deploy": makeJob(nil, []model.Rule{
+					{If: `$DEPLOY == "true"`, When: "on_success"},
+				}),
+			},
+			wantHit:  nil,
+			wantMiss: []string{"deploy"},
+		},
+		{
+			name:         "predefined CI_ var — skip check conservatively",
+			pipelineVars: nil,
+			jobs: map[string]model.Job{
+				"branch-job": makeJob(nil, []model.Rule{
+					{If: `$CI_COMMIT_BRANCH == "never-exists"`, When: "on_success"},
+				}),
+			},
+			wantHit:  nil,
+			wantMiss: []string{"branch-job"},
+		},
+		{
+			name:         "undeclared var — skip check conservatively",
+			pipelineVars: nil,
+			jobs: map[string]model.Job{
+				"my-job": makeJob(nil, []model.Rule{
+					{If: `$UNKNOWN_VAR == "x"`, When: "on_success"},
+				}),
+			},
+			wantHit:  nil,
+			wantMiss: []string{"my-job"},
+		},
+		{
+			name:         "unconditional rule — job can always activate",
+			pipelineVars: map[string]any{"DEPLOY": "false"},
+			jobs: map[string]model.Job{
+				"my-job": makeJob(nil, []model.Rule{
+					{If: `$DEPLOY == "true"`, When: "never"},
+					{When: "on_success"},
+				}),
+			},
+			wantHit:  nil,
+			wantMiss: []string{"my-job"},
+		},
+		{
+			name:         "all rules when:never — GL042 fires (not GL033 territory overlap)",
+			pipelineVars: map[string]any{"DEPLOY": "false"},
+			jobs: map[string]model.Job{
+				"my-job": makeJob(nil, []model.Rule{
+					{If: `$DEPLOY == "true"`, When: "on_success"},
+					{When: "never"},
+				}),
+			},
+			// Rule 1 evaluates to false; Rule 2 is explicit never → all dead.
+			wantHit:  []string{"my-job"},
+			wantMiss: nil,
+		},
+		{
+			name:         "job-level var overrides pipeline var",
+			pipelineVars: map[string]any{"FLAG": "false"},
+			jobs: map[string]model.Job{
+				"my-job": makeJob(map[string]any{"FLAG": "true"}, []model.Rule{
+					{If: `$FLAG == "true"`, When: "on_success"},
+				}),
+			},
+			// Job-level FLAG="true" makes the if: evaluate to true → no finding.
+			wantHit:  nil,
+			wantMiss: []string{"my-job"},
+		},
+		{
+			name:         "no rules — nothing to check",
+			pipelineVars: map[string]any{"DEPLOY": "false"},
+			jobs: map[string]model.Job{
+				"my-job": makeJob(nil, nil),
+			},
+			wantHit:  nil,
+			wantMiss: []string{"my-job"},
+		},
+		{
+			name:         "boolean variable evaluates correctly",
+			pipelineVars: map[string]any{"FLAG": false}, // bool false
+			jobs: map[string]model.Job{
+				"my-job": makeJob(nil, []model.Rule{
+					{If: `$FLAG == "true"`, When: "on_success"},
+				}),
+			},
+			// ScalarString(false) → "false"; "false" == "true" → false → GL042 fires.
+			wantHit:  []string{"my-job"},
+			wantMiss: nil,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			p := &model.Pipeline{
+				Variables: tc.pipelineVars,
+				Jobs:      tc.jobs,
+			}
+			findings := checkRulesIfReachability(p)
+
+			hitSet := make(map[string]bool)
+			for _, f := range findings {
+				if f.Rule == RuleStaticDeadRules {
+					hitSet[f.Job] = true
+				}
+			}
+
+			for _, want := range tc.wantHit {
+				if !hitSet[want] {
+					t.Errorf("expected GL042 for job %q but it was not reported; findings: %v", want, findings)
+				}
+			}
+			for _, notWant := range tc.wantMiss {
+				if hitSet[notWant] {
+					t.Errorf("unexpected GL042 for job %q", notWant)
+				}
+			}
+		})
+	}
+}

internal/linter/inherit_completeness.go

@@ -0,0 +1,112 @@
+package linter
+
+import (
+	"fmt"
+	"strings"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+// checkInheritCompleteness (GL043): warn when a job's 'inherit: default:'
+// declaration is dead — either because there is no 'default:' block in the
+// pipeline, or because the list form references fields that are not defined
+// in the 'default:' block.
+func checkInheritCompleteness(p *model.Pipeline) []Finding {
+	var findings []Finding
+	for name, job := range p.Jobs {
+		findings = append(findings, checkJobInheritCompleteness(p, name, job)...)
+	}
+	return findings
+}
+
+func checkJobInheritCompleteness(p *model.Pipeline, name string, job model.Job) []Finding {
+	if job.Inherit == nil {
+		return nil
+	}
+	m, ok := job.Inherit.(map[string]any)
+	if !ok {
+		return nil
+	}
+	defaultVal, hasDefault := m["default"]
+	if !hasDefault {
+		return nil
+	}
+
+	// Case 1: no default: block at all — the entire declaration is a no-op.
+	if p.Default == nil {
+		return []Finding{{
+			Severity: Warning,
+			Rule:     RuleInheritNoDefault,
+			Job:      name,
+			File:     job.File,
+			Line:     job.Line,
+			Message:  "'inherit: default:' is declared but the pipeline has no 'default:' block — declaration has no effect",
+		}}
+	}
+
+	// Case 2: list form — check for field names not set in default:.
+	list, ok := defaultVal.([]any)
+	if !ok {
+		// bool form (true/false) with a non-nil default: block is always valid.
+		return nil
+	}
+
+	var dead []string
+	for _, item := range list {
+		field, ok := item.(string)
+		if !ok {
+			continue
+		}
+		if !defaultBlockHasField(p.Default, field) {
+			dead = append(dead, field)
+		}
+	}
+	if len(dead) == 0 {
+		return nil
+	}
+	return []Finding{{
+		Severity: Warning,
+		Rule:     RuleInheritNoDefault,
+		Job:      name,
+		File:     job.File,
+		Line:     job.Line,
+		Message: fmt.Sprintf(
+			"'inherit: default: [%s]': %s not defined in the 'default:' block — %s",
+			strings.Join(dead, ", "),
+			pluralIs(len(dead)),
+			"these entries have no effect",
+		),
+	}}
+}
+
+// defaultBlockHasField reports whether the given field name has a non-zero value
+// in the default: block. Unknown field names return true (conservative).
+func defaultBlockHasField(d *model.DefaultConfig, field string) bool {
+	switch field {
+	case "image":
+		return d.Image != nil
+	case "before_script":
+		return d.BeforeScript != nil
+	case "after_script":
+		return d.AfterScript != nil
+	case "cache":
+		return d.Cache != nil
+	case "artifacts":
+		return d.Artifacts != nil
+	case "retry":
+		return d.Retry != nil
+	case "timeout":
+		return d.Timeout != ""
+	case "tags":
+		return len(d.Tags) > 0
+	}
+	// Unknown field name — conservatively assume it might be defined.
+	return true
+}
+
+func pluralIs(n int) string {
+	if n == 1 {
+		return "this field is"
+	}
+	return "these fields are"
+}

internal/linter/inherit_completeness_test.go

@@ -0,0 +1,94 @@
+package linter
+
+import (
+	"testing"
+
+	"git.k3nny.fr/glint/internal/model"
+)
+
+func TestCheckInheritCompleteness(t *testing.T) {
+	cases := []struct {
+		name    string
+		default_ *model.DefaultConfig
+		inherit any // job.Inherit value
+		wantHit bool
+	}{
+		{
+			name:    "no inherit — no finding",
+			inherit: nil,
+			wantHit: false,
+		},
+		{
+			name:    "inherit: default: false, no default block — GL043",
+			inherit: map[string]any{"default": false},
+			wantHit: true,
+		},
+		{
+			name:    "inherit: default: true, no default block — GL043",
+			inherit: map[string]any{"default": true},
+			wantHit: true,
+		},
+		{
+			name:    "inherit: default: [image], no default block — GL043",
+			inherit: map[string]any{"default": []any{"image"}},
+			wantHit: true,
+		},
+		{
+			name:     "inherit: default: false, default block exists — no finding",
+			default_: &model.DefaultConfig{Image: "node:20"},
+			inherit:  map[string]any{"default": false},
+			wantHit:  false,
+		},
+		{
+			name:     "inherit: default: [image], image in default — no finding",
+			default_: &model.DefaultConfig{Image: "node:20"},
+			inherit:  map[string]any{"default": []any{"image"}},
+			wantHit:  false,
+		},
+		{
+			name:     "inherit: default: [before_script], before_script NOT in default — GL043",
+			default_: &model.DefaultConfig{Image: "node:20"},
+			inherit:  map[string]any{"default": []any{"before_script"}},
+			wantHit:  true,
+		},
+		{
+			name:     "inherit: default: [image, before_script], only image in default — GL043 for before_script",
+			default_: &model.DefaultConfig{Image: "node:20"},
+			inherit:  map[string]any{"default": []any{"image", "before_script"}},
+			wantHit:  true,
+		},
+		{
+			name:     "inherit: variables only — no default check",
+			default_: nil,
+			inherit:  map[string]any{"variables": false},
+			wantHit:  false,
+		},
+		{
+			name:     "inherit: unknown field in list — conservative, no finding",
+			default_: &model.DefaultConfig{Image: "node:20"},
+			inherit:  map[string]any{"default": []any{"nonexistent_field"}},
+			wantHit:  false, // unknown fields return true from defaultBlockHasField
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			job := model.Job{Inherit: tc.inherit}
+			p := &model.Pipeline{
+				Default: tc.default_,
+				Jobs:    map[string]model.Job{"test-job": job},
+			}
+			findings := checkInheritCompleteness(p)
+
+			hit := false
+			for _, f := range findings {
+				if f.Rule == RuleInheritNoDefault {
+					hit = true
+				}
+			}
+			if hit != tc.wantHit {
+				t.Errorf("GL043 hit=%v, want=%v; findings: %v", hit, tc.wantHit, findings)
+			}
+		})
+	}
+}

internal/linter/linter.go

@@ -62,6 +62,8 @@ func Lint(p *model.Pipeline) []Finding {
 	findings = append(findings, checkNeeds(p)...)
 	findings = append(findings, checkDependencies(p)...)
 	findings = append(findings, checkVariableRefs(p)...)
+	findings = append(findings, checkRulesIfReachability(p)...)
+	findings = append(findings, checkInheritCompleteness(p)...)
 	slices.SortStableFunc(findings, func(a, b Finding) int {
 		if c := cmp.Compare(a.File, b.File); c != 0 {
 			return c

internal/linter/rules.go

@@ -143,4 +143,15 @@ const (
 
 	// GL041: cache.key.files contains a glob pattern; it must be a list of exact file paths.
 	RuleInvalidCacheKeyFiles = "GL041"
+
+	// GL042: every rules:if: condition in a job's rules: block evaluates to false
+	// given the values of variables declared in the pipeline YAML, so the job can
+	// never be active. Only fires when all referenced variables are declared
+	// (predefined CI_* / GITLAB_* vars are not evaluated to avoid false positives).
+	RuleStaticDeadRules = "GL042"
+
+	// GL043: a job declares 'inherit: default:' (true, false, or list) but the
+	// pipeline has no 'default:' block, making the declaration a no-op. Also fires
+	// when 'inherit: default: [list]' names fields not set in the default: block.
+	RuleInheritNoDefault = "GL043"
 )

testdata/inherit_dead.yml

@@ -0,0 +1,26 @@
+stages:
+  - build
+  - test
+
+# No default: block — any inherit: default: declaration is a no-op.
+
+# GL043: inherit: default: false but no default: block.
+isolated-job:
+  stage: build
+  inherit:
+    default: false
+  script: echo isolated
+
+# GL043: inherit: default: [list] but no default: block.
+selective-inherit-job:
+  stage: test
+  inherit:
+    default: [image, tags]
+  script: echo selective
+
+# Not GL043: inherit only touches variables: (no default: check needed).
+vars-inherit-job:
+  stage: test
+  inherit:
+    variables: false
+  script: echo vars-only

testdata/inherit_dead_fields.yml

@@ -0,0 +1,20 @@
+stages:
+  - build
+  - test
+
+default:
+  image: node:20
+
+# GL043: before_script is in the list but not defined in default:.
+selective-bad:
+  stage: build
+  inherit:
+    default: [image, before_script]   # before_script not in default:
+  script: echo hi
+
+# Not GL043: image IS defined in default: — list is valid.
+selective-good:
+  stage: test
+  inherit:
+    default: [image]
+  script: echo hi

testdata/keywords_valid.yml

@@ -9,6 +9,10 @@ workflow:
       when: always
     - when: never
 
+default:
+  tags:
+    - docker
+
 variables:
   GO_VERSION: "1.26"
 

testdata/static_dead_rules.yml

@@ -0,0 +1,48 @@
+stages:
+  - deploy
+  - test
+
+variables:
+  DEPLOY: "false"
+  SKIP_TEST: "true"
+
+# GL042: both if: conditions always evaluate to false given the declared variables.
+always-dead-deploy:
+  stage: deploy
+  rules:
+    - if: '$DEPLOY == "true"'
+      when: on_success
+  script: echo deploy
+
+# GL042: if: is false, explicit when:on_success rule — still never fires.
+always-dead-test:
+  stage: test
+  rules:
+    - if: '$SKIP_TEST == "false"'
+      when: on_success
+  script: echo test
+
+# Not GL042: references a predefined CI_ variable → unknown value → skip check.
+predefined-var-job:
+  stage: test
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "nonexistent-branch"'
+      when: on_success
+  script: echo branch
+
+# Not GL042: has an unconditional rule (no if: → always matches).
+unconditional-job:
+  stage: test
+  rules:
+    - if: '$DEPLOY == "true"'
+      when: never
+    - when: on_success
+  script: echo always
+
+# Not GL042: references undeclared variable → unknown → conservative.
+undeclared-var-job:
+  stage: test
+  rules:
+    - if: '$UNDECLARED_VAR == "something"'
+      when: on_success
+  script: echo undeclared