Skip to content
contextlint

REF-003 Stability consistency

Overview

Section titled “Overview”

Validates that an item’s stability does not exceed the stability of the items it depends on. Inconsistencies — such as a stable item depending on an experimental item — are reported as warning. This is a project-scope rule and is evaluated across all documents loaded via include.

Why it matters

Section titled “Why it matters”

Stability labels (experimental / review / stable, etc.) signal how trustworthy an item is. When a stable requirement depends on an experimental one, every change in the dependency forces the stable item to follow, eroding the meaning of the label. The reverse direction (experimental → stable) is fine. This rule validates the consistency of stability labels mechanically.

Options

Section titled “Options”
FieldTypeRequiredDescription
stabilityColumnstringYesColumn name that holds the stability label
stabilityOrderstring[]YesOrder of stability levels (least stable → most stable)
definitionsstringYesGlob of files that declare IDs
referencesstring[]YesArray of globs for files that reference IDs
idColumnstring—Column name that holds the ID in the definition file (default: ID)
idPatternstring—Regex of values to treat as IDs

In stabilityOrder, items later in the array are considered “more stable”. For example, with ["experimental", "review", "stable"], stable is the most stable. A violation is raised when the stability written on a referencing row is more stable (a higher index) than the stability of the item it references.

Bad example

Section titled “Bad example”
docs/requirements.md:
| ID     | Description       | Stability    |
| ------ | ----------------- | ------------ |
| REQ-01 | User registration | experimental |


docs/design.md:
| ID     | Related | Stability |
| ------ | ------- | --------- |
| DSN-01 | REQ-01  | stable    |

With stabilityOrder: ["experimental", "review", "stable"], the stable DSN-01 referencing the experimental REQ-01 triggers a violation.

docs/design.md
  line 4  warning  Item "REQ-01" has stability "experimental" in docs/requirements.md, but is referenced from a row with stability "stable"  REF-003

After fix

Section titled “After fix”

Either align the referrer’s stability to that of the dependency, or raise the dependency’s stability.

docs/requirements.md:
| ID     | Description       | Stability |
| ------ | ----------------- | --------- |
| REQ-01 | User registration | stable    |

Configuration example

Section titled “Configuration example”
{
  "rule": "ref003",
  "options": {
    "stabilityColumn": "Stability",
    "stabilityOrder": ["experimental", "review", "stable"],
    "definitions": "**/requirements.md",
    "references": ["**/design.md", "**/tests.md"],
    "idColumn": "ID",
    "idPattern": "^REQ-\\d+$"
  }
}
Section titled “Related rules”