SEC-002 Section order

Overview

Validates that section headings appear in the order given by order. If any heading in order appears out of order, an error is reported. Headings not listed in order are ignored.

Why it matters

Even with the same template, individual writers can shuffle the order of sections. When readers move across documents, consistent ordering lets them anticipate where information lives. Inconsistent ordering forces them to re-search every document, raising cognitive cost.

Options

Field	Type	Required	Description
order	string[]	Yes	Array of section headings in their expected order
level	number	—	Heading level to validate (when set, headings are grouped by parent and validated per group)
section	string	—	When level is set, restrict validation to a specific parent heading
files	string	—	Glob of files this rule applies to

When level is set, only headings at that level are extracted, grouped by parent, and validated within each group. Combine with section to restrict validation to a specific parent heading.

Bad example

# ADR-001

## Decision

Adopt JWT.

## Background

We need to choose an authentication mechanism.

With order: ["Background", "Decision", "Consequences"], Background appearing after Decision triggers a violation.

docs/adr/001.md
  line 7  error  Section "Background" must appear before "Decision"  SEC-002

After fix

# ADR-001

## Background

We need to choose an authentication mechanism.

## Decision

Adopt JWT.

Configuration example

{
  "rule": "sec002",
  "options": {
    "order": ["Background", "Decision", "Consequences"],
    "level": 2,
    "files": "adr/*.md"
  }
}

Related rules

• SEC-001 Required sections — Validates that the sections exist before checking their order
• STR-001 Required files — Validates file existence at the project level