Introduction

Built for readers whose attention is stretched — ADHD, dyslexia, fatigue, a second language, or an accessibility-sensitive context.

lucid-lint reads your Markdown or plain text and flags the moments that make prose hard to process. It does not rewrite your voice. It hands you a short list and gets out of the way.

What makes it different

Most prose tools measure style (write-good), grammar (Antidote), or a surface readability score (Flesch). lucid-lint measures cognitive load — the mental effort a reader spends to understand a sentence. It flags the patterns that the research behind Sweller, Gibson, Graesser, and Coh-Metrix single out.

• Bilingual EN/FR from day one, with equal quality.
• Deterministic by default. Identical input produces identical output. LLM-based rules live in optional plugins.
• CI-native. Plain-text and JSON outputs; exit codes that pre-commit and GitHub Actions understand without a wrapper.
• Profile-based. Pick dev-doc, public, or falc (Easy-to-Read), then override per rule if you want.

Project status

lucid-lint is at v0.2 (released 2026-04-22). All 25 rules listed in RULES.md are shipped (17 from v0.1, 8 added during the v0.2 cycle), alongside the hybrid scoring model — a global X / max score plus five per-category sub-scores, computed on top of the diagnostics. Pre-1.0: breaking changes remain possible between minor versions. See the roadmap for what comes next.

Quick taste

A clean file earns the full 100/100 and a wordmark banner — the peak-end moment of a passing lint run:

~~~~~ ⟨ • ⟩ ─────  lucid-lint  v0.2.0
                   cognitive accessibility linter · prose · EN / FR
                   ────────────────────────────────────────────────

No issues found.

────────────────────────────────────────────────────────────
score: 100/100
       structure    █████  20/20
       rhythm       █████  20/20
       lexicon      █████  20/20
       syntax       █████  20/20
       readability  █████  20/20

cargo install lucid-lint

# Lint a file
lucid-lint check README.md

# Strictest profile (Easy-to-Read / FALC)
lucid-lint check --profile=falc docs/

# Stdin
echo "This is a test sentence." | lucid-lint check -

# JSON for CI
lucid-lint check --format=json docs/

# Fail the build if the aggregate score drops below 85/100
lucid-lint check --min-score=85 docs/

Where to next

• Installation — how to install it.
• Quick start — a five-minute walkthrough.
• Profiles — pick the one that fits.
• Rules reference — all twenty-five rules explained.
• Accessibility — the WCAG AAA bar and how the site itself dogfoods the project.

Reading preferences

License

Dual-licensed under MIT or Apache-2.0, at your option.

Installation

lucid-lint ships through four routes. Pick the one that matches your environment.

One-line installer (Linux, macOS, WSL)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.sh | sh

The script is generated by cargo-dist for every tagged release. It detects your platform, downloads the matching prebuilt binary from the GitHub release, and places it on $PATH (default: $CARGO_HOME/bin if set, else ~/.cargo/bin).

Audit before running

curl … | sh is fast but opaque. To read the script before executing it:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.sh -o install.sh
less install.sh
sh install.sh

The script is short — under 200 lines of POSIX shell — so a quick read is realistic. It pins the release version it was generated for, verifies the downloaded archive’s expected size, and exits non-zero on any mismatch.

Pin a specific version

latest resolves to the most recent release. To pin a known-good version:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bastien-gallay/lucid-lint/releases/download/v0.2.2/lucid-lint-installer.sh | sh

One-line installer (Windows PowerShell)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.ps1 | iex"

Same cargo-dist machinery, PowerShell flavour. Drops the binary into %CARGO_HOME%\bin when CARGO_HOME is set, else %USERPROFILE%\.cargo\bin.

To audit before running, save the script and inspect it:

irm https://github.com/bastien-gallay/lucid-lint/releases/latest/download/lucid-lint-installer.ps1 -OutFile install.ps1
notepad install.ps1
.\install.ps1

Via Cargo

cargo install lucid-lint

This compiles from source via crates.io and places the binary in your Cargo bin directory (default ~/.cargo/bin/). Slower than the prebuilt installer but useful when the prebuilt targets don’t match your platform.

From source

git clone https://github.com/bastien-gallay/lucid-lint
cd lucid-lint
cargo install --path .

Pre-built binaries

Each release ships pre-built binaries for:

• Linux (x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl)
• macOS (aarch64-apple-darwin, x86_64-apple-darwin)
• Windows (x86_64-pc-windows-msvc)

The shell and PowerShell installers above pick the right archive automatically. To install manually, download from the GitHub releases page and put the extracted binary on $PATH.

Verify the installation

lucid-lint --version

System requirements

• Rust 1.75 or newer (only needed if building from source or via cargo install).
• No runtime dependencies.

Quick start

This page walks through linting your first document.

Lint a single file

lucid-lint check README.md

Output:

warning <path>/README.md:14:1 Sentence is 27 words long (maximum 22). Consider splitting it into shorter sentences. [structure.sentence-too-long]

summary: 1 warnings.
→ run 'lucid-lint explain <rule-id>' — seen here: structure.sentence-too-long
────────────────────────────────────────────────────────────
score: 88/100
       structure    ██▏░░  8/20
       rhythm       █████  20/20
       lexicon      █████  20/20
       syntax       █████  20/20
       readability  █████  20/20

The trailing block is the scoring summary — a global X / 100 score followed by the full per-category breakdown.

Lint several files

lucid-lint check docs/*.md CHANGELOG.md

Lint a directory

lucid-lint check docs/

All files with .md, .markdown, or .txt extensions will be processed.

Use stdin

echo "This is a test sentence." | lucid-lint check -

Pipe from Pandoc

For formats that lucid-lint does not parse natively yet:

pandoc report.docx -t markdown | lucid-lint check -

Choose a profile

# Strictest: Easy-to-Read
lucid-lint check --profile=falc docs/

# Looser: developer documentation
lucid-lint check --profile=dev-doc docs/

See Profiles for details.

Change the output format

# JSON for CI
lucid-lint check --format=json docs/

See CI integration for CI recipes.

Exit codes

The two gates stack. See CI integration for combination recipes.

Profiles

A profile is a preset bundle of rule thresholds tuned for a specific audience.

Available profiles

dev-doc

For technical documentation, API references, ADRs, and developer-facing content.

Thresholds are loose: technical readers have higher tolerance for long sentences, nominalizations, and domain-specific jargon.

public (default)

For general-audience content: marketing pages, product descriptions, blog posts.

Thresholds are moderate. Plain-language guidelines apply.

falc

For content that follows the Facile À Lire et à Comprendre / Easy-to-Read European standard.

Thresholds are strict: short sentences, simple vocabulary, no passive voice, no undefined acronyms.

Choosing a profile

Start with the profile that matches the intent of the content. Override specific rules if needed via lucid-lint.toml.

Threshold comparison

See the rule reference for exact thresholds per rule and per profile.

The overall pattern is:

• dev-doc: 30 words per sentence, 4 commas, 7 sentences per paragraph
• public: 22 words per sentence, 3 commas, 5 sentences per paragraph
• falc: 15 words per sentence, 2 commas, 3 sentences per paragraph

The same file linted three times under dev-doc, public, and falc in turn — the score drops as the profile tightens:

Overriding a profile

Any per-rule threshold set in lucid-lint.toml takes precedence over the profile preset.

[default]
profile = "public"

[rules.sentence-too-long]
max_words = 18   # stricter than public's 22

Conditions

A condition tag describes the cognitive condition a rule primarily targets. Conditions are orthogonal to profiles: a profile (dev-doc, public, falc) sets the strictness of the always-on rules; conditions enable additional rules tuned for a specific audience.

The fixed ontology

The set is fixed. New tags are a deliberate, versioned change.

How filtering works

For every rule the engine evaluates:

• A rule tagged general is always enabled.
• A rule without general runs only when at least one of its tags appears in the user’s active condition list.

All 17 v0.2 rules carry general, so the default behavior is unchanged. Future tagged rules (e.g. lexicon.all-caps-shouting for a11y-markup, syntax.nested-negation for aphasia + adhd) opt in via this list.

Configuring conditions

In lucid-lint.toml:

[default]
profile = "falc"
conditions = ["dyslexia", "aphasia"]

On the command line (comma-separated, repeatable):

lucid-lint check --profile falc --conditions dyslexia,aphasia docs/

FALC retains its regulatory meaning. Adding dyslexia does not relax or rename it — it layers dyslexia-specific signals on top.

Why tags, not parallel profiles

Three strictness levels × N conditions explodes combinatorially. Keeping the two axes orthogonal preserves the regulatory meaning of falc while letting users compose audience-specific overlays. See ROADMAP entries F71 and F72.

Configuration

lucid-lint is configured via a lucid-lint.toml file at the project root (optional) and CLI flags (overrides the file).

File layout

# lucid-lint.toml

[default]
profile = "public"

[rules.sentence-too-long]
max_words = 22

[rules.passive-voice]
max_per_paragraph = 2

Sections

[default]

Top-level defaults applied to the whole run.

[rules.<rule-id>]

Per-rule configuration. The fields available depend on the rule. See the rule pages in Rules reference.

[scoring]

Tunables for the hybrid scoring model. All fields are optional; missing fields fall back to the shipped defaults (category_max = 20, category_cap = 15).

[scoring]
category_max = 20
category_cap = 15

[scoring.weights]
sentence-too-long = 3
weasel-words      = 2

The [scoring.weights] sub-table is keyed by rule id. Unknown ids are ignored, so removing a rule in a future version does not break older configs.

Precedence

From lowest to highest:

1. Profile preset (e.g., public)
2. lucid-lint.toml overrides
3. CLI flags

An unset CLI flag defers to the TOML value; an unset TOML field defers to the profile preset.

Discovery

lucid-lint walks up from the current working directory to the first lucid-lint.toml it finds, stopping at the nearest .git repo boundary. Passing --config <path> skips auto-discovery and loads the given file directly; a missing explicit path is an error, but a missing auto-discovered file is not.

Excluding paths

Large documentation repositories routinely contain generated output, vendored text, and snapshots that would drown the linter in noise. Use the exclude field in [default] — or the --exclude <GLOB> CLI flag — to skip them at discovery time, before parsing.

[default]
exclude = [
    "vendor/**",
    "**/fixtures/**",
    "CHANGELOG.md",
]

Equivalently on the command line:

lucid-lint check --exclude 'vendor/**,**/fixtures/**,CHANGELOG.md' docs

Notes:

• Matching. Globs are matched against the path relative to the walked root. Passing lucid-lint check docs with exclude = ["drafts/**"] skips docs/drafts/....
• Prune, don’t visit. A matching directory is not descended into — large excluded trees cost nothing to walk.
• Explicit files bypass. If you pass docs/CHANGELOG.md directly on the command line, it is linted even when CHANGELOG.md is in the exclude list. If you named the path, you meant it.
• Additive. CLI --exclude and TOML exclude are unioned, not overridden. Comma-separate multiple patterns in a single flag, or repeat --exclude.

Silencing rules globally

Markdown documents support inline-disable directives for local silencing, but plain text and stdin have no such escape hatch. [[ignore]] fills that gap — and works uniformly across all input formats.

[[ignore]]
rule_id = "unexplained-abbreviation"

[[ignore]]
rule_id = "weasel-words"

Each [[ignore]] entry removes every diagnostic whose rule_id matches, across Markdown files, plain text, and stdin. The filter is applied after all rules have run but before scoring, so the score reflects the post-filter view too.

Notes:

• Global scope. The filter is not per-file. Inline directives remain the recommended escape hatch for spot silencing in Markdown — reach for [[ignore]] only when a rule is genuinely noisy project-wide.
• Unknown ids tolerated. Entries referencing rules that no longer exist are dropped silently, so removing a rule in a future release does not break older configs.
• Future fields. A reason = "..." field on each entry is tracked as F-suppression-reason-field — when it lands it will be surfaced in reports and optionally required via config.

Per-rule overrides

TOML-driven config is wired rule-by-rule as each Config gains a dedicated accessor. Two rules honour it today:

[rules.readability-score]

[rules.readability-score]
formula = "kandel-moles"  # or "flesch-kincaid", "auto"

Pins the readability formula regardless of detected language. auto (default) preserves the F-readability-formulas-extra per-language selection.

[rules.unexplained-abbreviation]

[rules.unexplained-abbreviation]
whitelist = ["WCAG", "ARIA", "ADHD", "LLM"]

Entries are additive over the profile baseline (F31). Use this to restore project-specific acronyms — accessibility standards, domain initialisms, engineering-practice terms — that the v0.2 baseline no longer ships. Each entry is silenced globally across the document, same as if it had been defined inline via Expansion (ACRONYM).

[rules."structure.excessive-commas"]

[rules."structure.excessive-commas"]
max_commas = 2

Overrides the per-sentence comma ceiling (default: 4 / 3 / 2 for dev-doc / public / falc). Must be a positive integer — 0 or negative values are rejected at load time. The override replaces the profile preset; it is not additive.

Tables for other rules parse without error but have no runtime effect. Extending this list is a mechanical per-rule change and will continue through the v0.2.x cycle.

Scoring

v0.2 adds a hybrid scoring model on top of the existing diagnostics. Every run now answers two questions at once:

1. What specifically is wrong? — the diagnostics list, unchanged from v0.1.
2. How bad is this document overall? — a new global score plus five per-category sub-scores.

The two surfaces are complementary. Scores are summaries; diagnostics remain the actionable signal.

What the score means

The score takes the form X / max — an arbitrary maximum rather than a 0–100 normalized number. v0.2 ships with max = 100 (five categories × twenty points), but the number is treated as a test-and-learn calibration: the scale may shift in a future minor release as rule weights are tuned against real corpora.

The rules of thumb for today’s calibration:

The colour bands are a reader aid, not a pass / fail contract. For CI gating, use --min-score with a concrete number you picked.

The five categories

Every rule belongs to exactly one category. v0.2 fixes the taxonomy at five buckets:

See the rules reference for the rule-to-category mapping.

How a score is computed

For a single document:

per_rule_cost     = Σ (weight × severity_multiplier)        over hits
per_category_cost = min(Σ per_rule_cost / (words / 1000),   ← density
                        category_cap)                        ← cap
category_score    = category_max − per_category_cost         (clamped ≥ 0)
global_score      = Σ category_score

Three mechanics stack:

• Weighted sum — each hit costs weight × severity_multiplier. The default weight table lives in scoring::default_weight_for and emphasises rules whose hits carry the most cognitive load (readability-score = 5, length / subordination / passive / unclear-antecedent = 2, everything else = 1).
• Density normalization — costs are divided by words / 1000 so a 10 000-word handbook is not punished for having more hits than a 400-word README. Documents shorter than 200 words are treated as 200-word documents, so tiny fixtures are not artificially penalized.
• Per-category cap — no single category can lose more than category_cap out of category_max. A single noisy rule eats at most 75 % of its own category (15 / 20 by default) and cannot leak into the others.

The severity multiplier is info = 1, warning = 3, error = 5.

Reading the TTY output

The terminal formatter prints each diagnostic, a short summary line, then a score block: the global number followed by every category score with an eight-step sparkline bar.

The same run rendered as plain text, for screen readers and copy-paste:

warning examples/sample.md:7:1 Sentence is 35 words long (maximum 30). Consider splitting it into shorter sentences. [section: A paragraph with a long sentence] [structure.sentence-too-long]
warning examples/sample.md:7:11 Weasel phrase "rather" weakens the statement. Replace with concrete language or remove it. [section: A paragraph with a long sentence] [lexicon.weasel-words]
info    examples/sample.md:1:1 Flesch-Kincaid grade 6.8 (target ≤ 14.0). [readability.score]
info    examples/sample.md:7:1 Sentence starts with a bare demonstrative "this". Name the referent to avoid forcing the reader to guess. [section: A paragraph with a long sentence] [syntax.unclear-antecedent]
warning examples/sample.md:7:1 Line is 210 characters wide (maximum 120). [section: A paragraph with a long sentence] [structure.line-length-wide]

summary: 3 warnings, 2 info.
→ run 'lucid-lint explain <rule-id>' — seen here: structure.sentence-too-long, lexicon.weasel-words, readability.score + 2 more
────────────────────────────────────────────────────────────
score: 45/100
       structure    █▎░░░  5/20
       rhythm       █████  20/20
       lexicon      █▎░░░  5/20
       syntax       ██▌░░  10/20
       readability  █▎░░░  5/20

All five categories are always displayed so the breakdown stays structurally stable run-to-run. A perfect document reads score: 100/100 with every bar full (█████). When the same rule fires two or more times on one file, the hits cluster under a compact header and any shared message or section is hoisted up so it only appears once.

Reading the JSON output

The JSON schema is at version = 2 in v0.2. New fields:

{
  "version": 2,
  "diagnostics": [
    {
      "rule_id": "structure.sentence-too-long",
      "severity": "warning",
      "location": { "file": { "kind": "path", "path": "draft.md" }, "line": 12, "column": 1, "length": 42 },
      "section": "Introduction",
      "message": "Sentence is 27 words long (maximum 22).",
      "weight": 2
    }
  ],
  "summary": { "info": 0, "warning": 1, "error": 0, "total": 1 },
  "score": { "value": 88, "max": 100 },
  "category_scores": [
    { "category": "structure",   "value": 8,  "max": 20 },
    { "category": "rhythm",      "value": 20, "max": 20 },
    { "category": "lexicon",     "value": 20, "max": 20 },
    { "category": "syntax",      "value": 20, "max": 20 },
    { "category": "readability", "value": 20, "max": 20 }
  ]
}

Category values are lowercase strings in the fixed order listed above. Consumers that parsed the v0.1 schema should:

• bump their expected version from 1 to 2;
• replace the old category names (length → structure, lexical → lexicon, style → syntax, global → readability);
• ignore unknown fields so future additive schema changes don’t break them.

Gating CI with --min-score

The check subcommand takes an optional --min-score=N flag. The run exits 1 if the aggregate global score is below N, independently of the severity-based gate.

# Fail the build if overall quality drops below 85/100
lucid-lint check --min-score=85 docs/

Both gates stack: the run fails if either the severity gate trips or the score gate trips. Pick one or both depending on your workflow:

• Severity gate only (v0.1 behaviour): catches newly introduced warnings, doesn’t react to a slow drift.
• Score gate only (--fail-on-warning=false --min-score=85): tolerates individual warnings but fails when density drifts past your threshold.
• Both (default + --min-score=85): both spikes and drifts fail the build.

Tuning weights in lucid-lint.toml

Projects can override the calibration in their lucid-lint.toml:

[scoring]
category_max = 20
category_cap = 15

[scoring.weights]
sentence-too-long = 3
weasel-words      = 2

Missing fields fall back to the shipped defaults. The [scoring.weights] sub-table is keyed by rule id; unknown ids are ignored so removing a rule later doesn’t break older configs.

What’s deferred

The brainstorm that shaped F14 (see brainstorm/20260420-score-semantics.md) kept the model minimal. Decorations promoted only when user feedback requires them:

• Letter grades (A–F) — tracked as F-score-letter-grade. Promoted if the numbers feel noisy or hard to compare across documents.
• Traffic-light + pass/fail margin display — tracked as F-score-traffic-light. Promoted if CI users ask for a stronger glance signal.
• Reading-time-seconds as alternative unit — tracked as F-reading-time-score. Needs a validated heuristic plus companion metrics (comfort, fatigue) so it doesn’t monopolize the read.
• Section-level sub-scores — tracked as F-section-scoring. Once document + project roll-ups are proven in the wild.
• Project-level multi-file roll-up — tracked as F-project-scoring-rollup. The CLI in v0.2 treats all passed paths as a single document for scoring purposes.

Suppressing diagnostics

lucid-lint supports two inline directives for silencing diagnostics in Markdown input. They are intended for the rare cases where a rule fires on intentional prose (a quoted weasel word, a didactic heavy-nominalization example, a legitimate passive). Prefer rewriting the prose first; reach for a directive when the detection is a known false positive or when the author has considered the warning and chosen to keep the text.

Line form

<!-- lucid-lint disable-next-line structure.sentence-too-long -->

A long sentence that is intentional and should not be flagged.

• Syntax. HTML comment, one rule id per directive. Multiple line directives may precede the same target line.
• Scope. The next non-blank line in the source.
• Optional reason. <!-- lucid-lint disable-next-line lexicon.weasel-words reason="quoting the style guide" --> — surfaced in JSON output; will be required via config in a future release (tracked as F-suppression-reason-field in the roadmap).

Block form (v0.2, F18)

<!-- lucid-lint-disable structure.sentence-too-long -->

A long sentence.

Another long sentence in the same scope.

<!-- lucid-lint-enable -->

• Opening. <!-- lucid-lint-disable <rule-id> --> opens a scope for one rule.
• Closing. <!-- lucid-lint-enable --> closes every currently-open scope. Passing a rule id (<!-- lucid-lint-enable <rule-id> -->) closes only that rule’s scope, which lets overlapping disables for different rules nest cleanly.
• Scope. Every line between the two comments (inclusive).
• Unterminated disable. Extends to end-of-document — useful for whole-file opt-outs, but prefer the planned disable-file directive (F-suppression-disable-file) once it lands.
• One rule per comment. Multi-rule lists are tracked as F-suppression-disable-file.

Common properties

• Applies to Markdown only. Plain text and stdin cannot carry HTML comments. Config-based ignores ([[ignore]] in lucid-lint.toml) covering .txt and stdin are tracked as F19.
• Unknown rule ids are silently ignored. This keeps directives forward-compatible across lint versions.
• Suppressed diagnostics cost zero score. The suppression and scoring models are consistent — silencing a diagnostic removes it from the weighted-sum cost. No hidden double-penalty.

Deferred

The following extensions are tracked on the roadmap:

See also

• Configuration — TOML-level thresholds and profile overrides.
• Scoring — how suppressed diagnostics affect the global and per-category scores.
• Rule-specific notes on when a suppression is idiomatic — see the ## Suppression section on any rule page under Rules reference.

CI integration

lucid-lint is designed for CI. It returns:

• 0 when no issues (or only info) are found
• 1 when warnings are found
• 2 on runtime error (invalid args, unreadable file)

GitHub Actions

name: Docs lint

on:
  pull_request:
    paths:
      - '**/*.md'
  push:
    branches: [main]
    paths:
      - '**/*.md'

jobs:
  lucid-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install lucid-lint
        run: cargo install lucid-lint
      - name: Lint docs
        run: lucid-lint check --profile=public docs/ README.md

Pre-commit

Add to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: lucid-lint
        name: lucid-lint
        entry: lucid-lint check --profile=public
        language: system
        types: [markdown]

Reviewdog

To surface diagnostics as pull request review comments:

lucid-lint check --format=json docs/ | reviewdog -f=rdjson -reporter=github-pr-review

Note: RDJSON adapter is not shipped. For native code-review surfacing, prefer the GitHub Code Scanning workflow below.

GitHub Code Scanning (SARIF)

--format=sarif emits a SARIF v2.1.0 log that GitHub’s Code Scanning ingests directly: each diagnostic becomes a code-scanning alert annotated on the PR diff.

name: Lucid lint (code scanning)

on:
  pull_request:
    paths: ['**/*.md']
  push:
    branches: [main]
    paths: ['**/*.md']

permissions:
  security-events: write
  contents: read

jobs:
  lucid-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo install lucid-lint
      - name: Run lucid-lint and emit SARIF
        run: |
          lucid-lint check \
            --profile=public \
            --format=sarif \
            --fail-on-warning=false \
            docs/ README.md > lucid-lint.sarif
      - name: Upload SARIF to Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: lucid-lint.sarif
          category: lucid-lint

Notes:

• --fail-on-warning=false lets the upload step always run; rely on Code Scanning’s own gating in the PR UI rather than the lint exit code.
• Each rule appears once in runs[0].tool.driver.rules with its category, default severity, default scoring weight, and a helpUri pointing at the per-rule mdBook page.
• Per-result properties.weight and properties.section carry the scoring weight and the heading the diagnostic was found under.

Exit code control

To avoid failing CI on warnings (e.g., during a gradual adoption phase), you can invert the default:

lucid-lint check --fail-on-warning=false docs/

This always returns 0 except on runtime error.

Gating on score

You can also gate the build on the aggregate scoring model. The run exits 1 if the global score is below the threshold, independently of the severity gate.

jobs:
  lucid-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo install lucid-lint
      - name: Lint and gate on score
        run: lucid-lint check --min-score=85 docs/ README.md

Both gates stack — the run fails if either trips. Pick the combination that fits your adoption curve:

A gated run that fails — lucid-lint prints its usual summary, then the shell surfaces the non-zero exit code:

$ lucid-lint check --min-score=85 examples/sample.md
…
score: 45/100
       structure    █▎░░░  5/20
       rhythm       █████  20/20
       lexicon      █▎░░░  5/20
       syntax       ██▌░░  10/20
       readability  █▎░░░  5/20
$ echo "exit: $?"
exit: 1

Rules reference

lucid-lint ships 25 rules as of v0.2 (17 from v0.1 plus 8 added during the v0.2 cycle). Each rule has a dedicated page below with category, severity, default weight, thresholds per profile, examples, and suppression guidance.

The compact reference at RULES.md remains the single-file overview kept in the repository root. The academic and normative sources behind every rule are consolidated on the References page.

Categories

Every rule belongs to exactly one of five fixed buckets. The taxonomy is authoritative — the scoring model composes per-category sub-scores into the global X / max.

Authoritative source. The category of each rule is determined by Category::for_rule in src/types.rs. The mapping above mirrors that function. A coverage test (tests/rule_docs_coverage.rs) keeps the per-rule pages, the category helper, and the scoring weights in lock-step.

Severity levels

Reading a rule at the terminal

Each rule bundles its reference page into the binary. Run lucid-lint explain <rule-id> to print the same content this website serves — useful when CI only gives you a diagnostic id and no browser:

lucid-lint explain structure.sentence-too-long

Contributing a rule

See Contributing for the rule-addition checklist — every new rule must land with a page in this section.

structure.sentence-too-long

What it flags

Sentences whose length exceeds a per-profile ceiling. The intrinsic cognitive load of a sentence grows non-linearly with its word count (Graesser et al. 2004, Coh-Metrix); FALC caps at 15 words, Plain English at 20. Long sentences increase the probability of a reader under attentional load losing the thread mid-read.

At a glance

Detection

Split text into sentences via strong punctuation (., !, ?, …, paragraph breaks). Count Unicode word tokens, excluding punctuation. Contractions (don't) and elisions (l'accessibilité) count as one word when the apostrophe sits between two letters. Code blocks are skipped.

Parameters

Examples

Three ideas, colour-matched across the rewrite — position already pairs them, the tint just confirms the rewrite loses none. lucid-lint reports; the rewrite is always yours.

English

Before (flagged):

The caching subsystem, which was introduced in an earlier milestone, turned out to interact poorly with the new request pipeline under sustained load, and the investigation that followed required multiple rounds of profiling.

What lucid-lint check --profile public reports:

warning input.md:1:1 Sentence is 33 words long (maximum 22). Consider splitting it into shorter sentences. [structure.sentence-too-long]

After (your rewrite):

The caching subsystem was introduced earlier. It interacts poorly with the new request pipeline under sustained load. The investigation required several rounds of profiling.

French

Before (flagged):

Le sous-système de cache introduit lors d’un jalon précédent interagit mal avec le nouveau pipeline de requêtes sous charge soutenue, et l’enquête a nécessité plusieurs rondes de profilage.

What lucid-lint check --profile public reports:

warning input.md:1:1 Sentence is 29 words long (maximum 22). Consider splitting it into shorter sentences. [structure.sentence-too-long]

After (your rewrite):

Le cache a été introduit lors d’un jalon précédent. Il interagit mal avec le nouveau pipeline sous charge soutenue. L’enquête a nécessité plusieurs rondes de profilage.

Suppression

See Suppressing diagnostics for the inline and block forms.

See also

• rhythm.consecutive-long-sentences — catches rhythm; its threshold must stay lower than max_words here.
• Scoring model — structure.sentence-too-long carries weight 2 because the cognitive cost compounds with length.

References

• Sweller (1988)
• Plain Language US (2011)
• CAN-ASC-3.1:2025

See References for the full bibliography.

structure.paragraph-too-long

What it flags

Paragraphs that overrun either a sentence-count or a word-count threshold. A paragraph is a visual reprise unit: long paragraphs dilute the reprise point for readers who interrupt often. Both metrics are checked so that a short-but-dense paragraph (one 80-word sentence) is still caught — structure.sentence-too-long covers the complementary case.

At a glance

Detection

Split on blank lines (Markdown paragraph convention). Count sentences and words per paragraph. Flag paragraphs exceeding either threshold.

Parameters

Examples

A paragraph of eight medium sentences under the public profile will fire on max_sentences. A paragraph containing a single 120-word sentence will fire on max_words (and also on structure.sentence-too-long).

Suppression

See Suppressing diagnostics.

See also

• structure.sentence-too-long
• rhythm.consecutive-long-sentences

References

• Sweller (1988)
• Graesser et al. (2004)
• CAN-ASC-3.1:2025

See References for the full bibliography.

structure.heading-jump

What it flags

Heading-level jumps that break the document’s mental map (e.g. H2 → H4). Each level must follow the previous by at most +1. Readers with attentional difficulties lean heavily on heading hierarchy to reposition after an interruption; a broken hierarchy destroys that cue. Also flags the first heading being deeper than H2 when allow_first_heading_any_level is false, and missing H1 when require_h1 is true.

References. WCAG 2.1 SC 1.3.1 (Info and Relationships) and 2.4.6 (Headings and Labels); RGAA 9.1.

At a glance

Detection

Parse Markdown headings (#, ##, …). Walk them in source order; report each heading whose level exceeds the previous by more than one. Deterministic, no false positives.

Parameters

A binary rule — no per-profile thresholds.

Examples

Flagged:

# Overview
#### Details    ← jumps from H1 to H4

Clean:

# Overview
## Section
### Subsection

Suppression

See Suppressing diagnostics.

See also

• structure.deeply-nested-lists — the list-level equivalent signal.

References

• WCAG 2.1 — 1.3.1 & 2.4.6

See References for the full bibliography.

structure.deeply-nested-lists

What it flags

Bulleted list items nested beyond a reasonable depth. A deeply nested list forces the reader to reconstruct a complex mental hierarchy — horizontal indentation stops being a positional cue and becomes noise. Four levels of indent are too many for readers with attentional difficulties to track.

At a glance

Detection

Parse Markdown via pulldown-cmark; extract list items with their indentation level; flag items deeper than max_depth. Deterministic, no false positives.

Parameters

Example

Under public (max depth 3):

- Level 1
  - Level 2
    - Level 3
      - Level 4    ← flagged

Diagnostic message

Includes repair guidance: flatten the structure, split into multiple lists, or promote sub-items to subsections with headings.

Suppression

See Suppressing diagnostics.

References

• WCAG 2.1

See References for the full bibliography.

structure.line-length-wide

What it flags

Author-chosen lines wider than the per-profile ceiling. WCAG 1.4.8 (AAA) caps rendered text at roughly 80 characters per line because longer lines force the eye to track further between saccades and increase re-reading on return sweep — a known difficulty for dyslexic readers (BDA Dyslexia Style Guide).

“Author-chosen” matters: in Markdown, soft-wrapped lines collapse to spaces at parse time because the renderer reflows them to fit the viewport. Their source length tells us nothing about what the reader sees. Only line breaks the author kept on purpose are checked here — Markdown hard breaks (<br> or two trailing spaces) and explicit newlines in plain-text input. A soft-wrapped Markdown paragraph is exempt no matter how long its joined text is. Use structure.paragraph-too-long to bound paragraph density.

At a glance

Detection

For every paragraph that carries an authorial line break, scan each line’s width in grapheme clusters and report lines above max_line_length.

A Markdown paragraph with no hard break inside it (the common case for prose) is exempt — the parser collapses its soft breaks to spaces, so what remains is one logical line whose source length tracks the viewport, not the rendered width WCAG 1.4.8 targets. Plain-text input is treated symmetrically: a paragraph with no inner \n is exempt; one with internal newlines is checked line by line.

Fenced and indented code blocks are excluded upstream by the Markdown parser. Headings, list items, and table cells are out of scope by construction — paragraph-too-long, sentence-too-long, and the heading rules cover the cognitive-load concerns that apply to those blocks.

Parameters

FALC matches the WCAG 1.4.8 AAA recommendation of 80 characters.

Known caveats

Long single-line prose paragraphs in Markdown source are intentionally exempt. The rule used to fire on them and produced large amounts of noise on real prose; v0.2.x narrows the rule to author-chosen breaks only. Pair this rule with structure.paragraph-too-long if you also want a ceiling on the joined paragraph length.

Headings and list items are not measured by this rule. Their wrap behavior depends on the renderer (display type, list indent), and the underlying cognitive concerns are covered by other rules.

Suppression

See Suppressing diagnostics.

See also

• structure.paragraph-too-long
• structure.sentence-too-long
• Conditions

References

• WCAG 2.1 — 1.4.8 (AAA)
• Legge & Bigelow (2011)

See References for the full bibliography.

structure.mixed-numeric-format

What it flags

Sentences that mix digit numerals (42, 3.14, 1,000, 1 000) with spelled-out numerals (two, trois, twenty, cent) within the same sentence. Presenting numbers inconsistently forces the reader to switch surface forms mid-clause and re-anchor the referent — a known load for readers with dyscalculia and a plain-language anti-pattern.

At a glance

Detection

For each sentence emitted by the tokenizer, scan for digit-numeric tokens and for entries in the per-language spelled-numeral list. If at least one of each kind co-occurs, emit a single diagnostic for the sentence citing one representative token of each kind.

Digit tokens accept ASCII digits plus an optional decimal (.) or thousands separator (,, narrow space U+0020) when flanked by digits on both sides. Spelled-out matches are case-insensitive ASCII compares against en::SPELLED_NUMERALS and fr::SPELLED_NUMERALS.

The ambiguous forms one (EN) and un / une (FR) are excluded from the spelled-numeral list because they double as indefinite pronouns and articles. This keeps the false-positive rate manageable at the cost of missing genuine mixed-format cases whose only spelled-out numeral is one. Metropolitan French and Swiss / Belgian regional forms (septante, huitante, octante, nonante) are all included.

Sentences are produced by the shared tokenizer (see src/parser/tokenizer.rs), so abbreviations, decimals, and ellipses do not spuriously split sentences. Fenced and indented code blocks are excluded upstream by the Markdown parser.

Parameters

None. The rule has no configurable threshold — a single co-occurrence of the two surface forms is sufficient.

Known caveats

• Sentences whose only spelled-out numeral is one / un / une are not flagged, by design (see Detection).
• Ordinals (first, premier, 2nd, 3e) are out of scope. 2nd currently reads as a digit token (2) followed by a word (nd), which does not match the spelled-numeral list — no false positive.
• Roman numerals (IV, XIV) are neither digits nor spelled-out numerals for this rule.

Suppression

See Suppressing diagnostics.

See also

• readability.score
• Conditions

References

• ISO 80000-1:2022
• Chicago Manual of Style (17th ed.)

See References for the full bibliography.

structure.excessive-commas

What it flags

Sentences whose comma count exceeds a per-profile ceiling. The comma is the most frequent marker of syntactic complexity; rather than disentangle the cause (subordination, apposition, enumeration, parenthetical), the rule uses density as a leading indicator of overload.

At a glance

Detection

Count commas per sentence, report those above max_commas.

Interaction. When structure.long-enumeration fires on the same sentence, this rule is suppressed for that sentence to avoid double-reporting. The shared enumeration detector discounts Oxford-style enumeration commas (3+ short items, plus a relaxed rhythmic pass for 1–4-word items, plus runs closed by plus as well as and / or — see “Known false positives” below) and commas inside (A, B, C, …) parenthesised token lists (3+ short comma-separated segments inside balanced parens) — all language-agnostic.

Parameters

Known false positives

Remaining false positives mostly come from bare lists with no terminal connector (e.g. Rules touched: A, B, C) and Oxford runs interrupted by an interleaved parenthetical; these are tracked as F22 in the roadmap for further v0.3 sub-slices.

Suppression

See Suppressing diagnostics.

See also

• structure.long-enumeration
• structure.deep-subordination

References

• Gibson (1998)

See References for the full bibliography.

structure.long-enumeration

What it flags

Inline prose enumerations that would be clearer as a bulleted list — 5+ comma-separated items closed by a coordinator (and, or, et, ou).

At a glance

Detection

Sequence of min_items or more short comma-separated segments ending with , and / , or / , plus / , et / , ou (Oxford comma optional). Shared detector also informs structure.excessive-commas.

Parameters

Diagnostic message

Suggests converting the enumeration to a bulleted list.

Examples

lucid-lint reports; the rewrite is always yours.

English

Six items, colour-matched across the rewrite — each inline term lines up with its bullet.

Before (flagged):

The dish contains tomato, onion, garlic, basil, parsley, and thyme.

What lucid-lint check --profile public reports:

warning input.md:1:1 Inline enumeration of 5 items. Consider converting it into a bulleted list so readers can scan the items. [structure.long-enumeration]

After (your rewrite):

The dish contains:

• tomato
• onion
• garlic
• basil
• parsley
• thyme

Suppression

See Suppressing diagnostics.

References

• Plain Language US (2011)

See References for the full bibliography.

structure.deep-subordination

What it flags

Cascading subordinate clauses: multiple relative pronouns or subordinating conjunctions chained without a strong-punctuation break. Each open referent has to sit in working memory until it closes — Gibson’s Dependency Locality Theory (1998) ties processing cost directly to that distance.

At a glance

Detection

Walk the sentence between strong-punctuation breaks; count consecutive subordinators. Flag when the count exceeds max_consecutive_subordinators. Pronoun enumerations (qui, que, dont, où) are skipped — the detector recognises the list form and does not treat it as cascading.

Parameters

Language lists

• 🇫🇷 Relative pronouns: qui, que, dont, où, lequel, laquelle, lesquels, lesquelles
• 🇫🇷 Subordinators: parce que, afin que, bien que, quoique, puisque, pour que, tandis que
• 🇬🇧 Relative pronouns: which, that, who, whom, whose
• 🇬🇧 Subordinators: because, although, while, since, whereas, unless, until

Examples

Each highlighted token is one subordinator counted by the rule. Four in a row triggers the dev-doc threshold (3); two in a row triggers public and falc.

Flagged (FR):

Le document qui a été rédigé par l’équipe que nous avons constituée et qui couvre les points que nous avions discutés…

Flagged (EN):

The report that was drafted by the team which we formed last month and which covers the topics that we had discussed…

Not flagged (enumeration form, recognised by the detector):

Les pronoms relatifs en français sont : qui, que, dont, où.

And the matching English form:

The English relative pronouns are: which, that, who, whom, whose.

Suppression

See Suppressing diagnostics.

References

• Gibson (1998)

See References for the full bibliography.

structure.italic-span-long

Experimental in v0.2.x. Off by default; opt in via --experimental structure.italic-span-long or [experimental] enabled = ["structure.italic-span-long"] in lucid-lint.toml. Flips to Stable at the v0.3 cut as part of the F-experimental-rule-status cohort flip. See Conditions for the dyslexia condition tag that gates this rule under user-active conditions.

What it flags

Italic spans (*…* / _…_) longer than a configurable word threshold. Slanted glyphs degrade letter-shape recognition for readers with dyslexia — a robust finding behind the British Dyslexia Association’s recommendation to keep italic emphasis to a short phrase rather than running a full sentence in italics. Long italic runs also harm scanability for readers whose attention is already taxed (fatigue, second-language reading, low-vision conditions).

At a glance

Detection

Walks the typed inline tree captured on each Paragraph (F143 substrate) and flags every Inline::Emphasis span whose visible word count exceeds the per-profile threshold. Code blocks and inline code are excluded by the parser, so an italic span inside a code fence never fires. Strong (**bold**) does not trigger this rule — only emphasis (*italic* / _italic_).

The diagnostic location points at the opening delimiter, so the squiggle in your editor lands on the visible * or _ rather than an arbitrary column inside the paragraph.

Parameters

Tune via lucid-lint.toml:

[rules."structure.italic-span-long"]
max_words = 6

Examples

English

Before (flagged):

The team eventually concluded that the proposed migration plan would require careful coordination across three regional offices and an extended freeze window before any deployment could begin.

What lucid-lint check --profile public --experimental structure.italic-span-long --conditions dyslexia reports:

warning input.md:1:36 Italic span is 17 words long (maximum 8). Long italic runs strain dyslexic readers; consider shortening the emphasized phrase or removing the italics. [structure.italic-span-long]

After (your rewrite):

The team eventually concluded that the proposed migration plan would require careful coordination. Three regional offices and an extended freeze window are prerequisites before any deployment.

The italics now mark a single load-bearing word — the kind of emphasis the BDA style guide endorses.

French

Before (flagged):

L’équipe a fini par conclure que le plan de migration proposé nécessiterait une coordination soignée entre trois bureaux régionaux et une fenêtre de gel prolongée avant tout déploiement.

What lucid-lint check --profile public --experimental structure.italic-span-long --conditions dyslexia reports:

warning input.md:1:35 Italic span is 18 words long (maximum 8). Long italic runs strain dyslexic readers; consider shortening the emphasized phrase or removing the italics. [structure.italic-span-long]

After (your rewrite):

L’équipe a fini par conclure que le plan de migration nécessiterait une coordination soignée. Trois bureaux régionaux et une fenêtre de gel prolongée sont indispensables avant tout déploiement.

Suppression

See Suppressing diagnostics for the inline and block forms. Inline disable also works on this rule:

<!-- lucid-lint disable-next-line structure.italic-span-long -->
A *deliberately long italic span that the rule would normally flag* lives here.

See also

• Conditions — the dyslexia tag that gates this rule.
• F-experimental-rule-status — experimental rule status — substrate that lets this rule ship in v0.2.x without affecting default scores.
• F143 — inline AST layer — substrate that exposes emphasis-span boundaries to this rule.

References

• British Dyslexia Association — Dyslexia Style Guide (2018). Recommends keeping italics to short phrases for letter-shape recognition.
• Rello & Baeza-Yates (2013) — broader academic context on dyslexia-friendly typography.

See References for the full bibliography.

structure.number-run

Experimental in v0.2.x. Off by default; opt in via --experimental structure.number-run or [experimental] enabled = ["structure.number-run"] in lucid-lint.toml. Flips to Stable at the v0.3 cut as part of the F-experimental-rule-status cohort flip. See Conditions for the dyscalculia condition tag that gates this rule under user-active conditions.

What it flags

Sentences that pack more than a configurable number of numeric tokens together. plainlanguage.gov is explicit on the framing — “Don’t put a lot of numbers together in one sentence” and “Avoid placing too many statistics close together” — and readers with dyscalculia carry the cost first: each numeric token forces a quantity-to-symbol re-anchoring that does not benefit from running prose context the way ordinary words do. Citation salads ((Smith 2020, Jones 2021, Wei 2022, Park 2023)), benchmark tables flattened into prose, and statistic-heavy paragraphs are the typical hits.

At a glance

Detection

Walks each paragraph’s sentence stream (post-flattening, so fenced code blocks are already excluded by the parser) and counts numeric tokens per sentence. A numeric token is a contiguous run of ASCII digits, optionally containing one decimal separator (. or ,) followed by more digits. Hyphen, colon, slash, and whitespace split tokens.

The diagnostic location points at the first numeric token in the offending sentence, so the squiggle in your editor lands on the visible cluster rather than the start of the sentence.

Parameters

Tune via lucid-lint.toml:

[rules."structure.number-run"]
max_numbers = 5

Examples

English

Before (flagged):

The 2024 cohort sat 1,200 students across 4 campuses, posted a 92.5% pass rate on the 3 reviewed papers, and improved 18 points over the prior year.

What lucid-lint check --profile public --experimental structure.number-run --conditions dyscalculia reports:

warning input.md:1:5 Sentence packs 8 numeric tokens (maximum 4). plain-language guidance recommends not placing many numbers or statistics together in one sentence; split the sentence or move some figures to a list or table. [structure.number-run]

After (your rewrite):

The 2024 cohort sat 1,200 students across 4 campuses. They posted a 92.5% pass rate on the reviewed papers and improved 18 points over the prior year.

The figures still travel together, but each sentence carries a load a dyscalculic reader can re-anchor without losing the running referent.

French

Before (flagged):

La promotion 2024 a réuni 1 200 étudiants sur 4 campus, affiché un taux de réussite de 92,5 % sur les 3 copies revues, et progressé de 18 points par rapport à l’année précédente.

After (your rewrite):

La promotion 2024 a réuni 1 200 étudiants sur 4 campus. Le taux de réussite atteint 92,5 % sur les copies revues et progresse de 18 points par rapport à l’année précédente.

Suppression

See Suppressing diagnostics for the inline and block forms. Inline disable also works on this rule:

<!-- lucid-lint disable-next-line structure.number-run -->
The 2024 cohort sat 1,200 students across 4 campuses, posted a 92.5% pass rate on the 3 reviewed papers, and improved 18 points.

See also

• Conditions — the dyscalculia tag that gates this rule.
• structure.mixed-numeric-format — sibling rule on numeric form consistency. Atomic split: mixed-numeric-format cares whether digits and spelled-out numerals share one sentence; number-run cares about how many numeric tokens cluster regardless of form.
• F-experimental-rule-status — experimental rule status — substrate that lets this rule ship in v0.2.x without affecting default scores.

References

• plainlanguage.gov — Use short, simple sentences. “Don’t put a lot of numbers together in one sentence.”
• plainlanguage.gov — Use numerals. Companion guidance on consistent numeric form (the grounding for mixed-numeric-format).

See References for the full bibliography.

rhythm.consecutive-long-sentences

What it flags

Streaks of long sentences within the same paragraph. An isolated long sentence is manageable; several in a row fatigue attention even when each individual sentence is under the structure.sentence-too-long ceiling. This rule catches the rhythm.

At a glance

Detection

Walk sentences sequentially inside each paragraph. Maintain a running count of consecutive sentences above word_threshold. Fire once per streak that reaches max_consecutive.

Parameters

Relation to structure.sentence-too-long

Both rules look at sentence length but catch different problems:

Because word_threshold sits below max_words, this rule catches the rhythm even when no individual sentence trips sentence-too-long. The invariant word_threshold < max_words (per profile) keeps the two from co-firing on the same sentence.

Examples

Five ideas, colour-matched across the rewrite — only the rhythm changes. lucid-lint reports; the rewrite is always yours.

English

Before (flagged):

The migration introduced a caching layer that sits in front of every read from the primary database. The team observed unexpected latency spikes whenever the cache invalidated under sustained write load. A subsequent investigation traced the regression to a thundering-herd pattern that fired on every cold key. The metrics dashboard misreported the issue as a generic timeout because the trace propagation was incomplete. The fix coalesced concurrent fills, added jittered TTLs, and instrumented the cache layer with a dedicated span emitter.

Five sentences, each over 20 words — the streak fatigues attention.

What lucid-lint check --profile dev-doc reports:

warning input.md:1:1 5 consecutive sentences exceed 20 words (max 3). Vary sentence length or split the streak. [rhythm.consecutive-long-sentences]

After (your rewrite):

The migration introduced a caching layer in front of the primary database. Latency spiked whenever the cache invalidated under heavy writes. The cause was a thundering-herd pattern on cold keys. Metrics misreported it as a generic timeout — trace propagation was broken. The fix coalesced concurrent fills, added jittered TTLs, and emitted a dedicated span.

French

Before (flagged):

La migration a introduit une couche de cache qui se place devant chaque lecture de la base primaire. L’équipe a observé des pics de latence inattendus chaque fois que le cache s’invalidait sous une charge d’écriture soutenue. Une enquête ultérieure a relié la régression à un motif de troupeau tonnant qui se déclenchait sur chaque clé froide. Le tableau de bord des métriques signalait à tort un délai d’attente générique parce que la propagation de la trace était incomplète. Le correctif a fusionné les remplissages concurrents, ajouté un TTL avec gigue, et instrumenté la couche de cache avec un émetteur de span dédié.

What lucid-lint check --profile dev-doc reports:

warning input.md:1:1 5 consecutive sentences exceed 20 words (max 3). Vary sentence length or split the streak. [rhythm.consecutive-long-sentences]

After (your rewrite):

La migration a introduit une couche de cache devant la base primaire. La latence montait dès que le cache s’invalidait sous écritures soutenues. Le coupable : un troupeau tonnant sur les clés froides. Les métriques signalaient un délai générique — la trace était cassée. Le correctif fusionne les remplissages, ajoute un TTL avec gigue et émet un span dédié.

Suppression

See Suppressing diagnostics for the inline and block forms.

See also

• structure.sentence-too-long — catches individual long sentences; this rule catches the streak even when each sentence is under that ceiling.
• Scoring model — rhythm.consecutive-long-sentences carries the default weight 1; the cognitive cost is the cumulative streak, not any single sentence.

References

• Sweller (1988)
• Sweller, Ayres & Kalyuga (2011)

See References for the full bibliography.

rhythm.repetitive-connectors

What it flags

Overuse of a single logical connector inside a short window of sentences. Connectors (opposition, cause, consequence, sequence, illustration, addition) are attentional anchors; repeated, they flatten the sense of progression. Sanders & Noordman (2000), Connectives as processing signals; Graesser et al. (2004), local cohesion.

At a glance

Detection

Sliding window of window_size sentences. Per connector, count occurrences in the window. Fire once per cluster that crosses max_per_window.

Parameters

Default connector lists

• 🇫🇷 Opposition: cependant, toutefois, en revanche, néanmoins, pourtant, mais
• 🇫🇷 Cause: parce que, car, puisque, en effet
• 🇫🇷 Consequence: donc, ainsi, par conséquent, c’est pourquoi
• 🇫🇷 Sequence: d’abord, ensuite, puis, enfin, premièrement
• 🇫🇷 Illustration: par exemple, notamment, en particulier
• 🇫🇷 Addition: de plus, en outre, également, par ailleurs
• 🇬🇧 Opposition: however, nevertheless, yet, although, but
• 🇬🇧 Cause: because, since, as, for
• 🇬🇧 Consequence: therefore, thus, consequently, hence, so
• 🇬🇧 Sequence: first, then, next, finally
• 🇬🇧 Illustration: for example, notably, in particular, such as
• 🇬🇧 Addition: moreover, furthermore, also, additionally

Examples

lucid-lint reports; the rewrite is always yours.

English

Five actions, colour-matched across the rewrite — only the connectors change.

Before (flagged):

We analysed the data. Then we built the model. Then we validated the results. Then we published the report. Then we archived the raw data.

Four then in five sentences — no progression felt.

What lucid-lint check --profile public reports:

warning input.md:1:1 Connector "then" appears 4 times within 5 consecutive sentences (max 3). Vary the connector or restructure the passage. [rhythm.repetitive-connectors]

After (your rewrite):

We analysed the data. From it we built the model. Validation followed, and once the results held up we published the report. The raw data was archived last.

French

Five actions, colour-matched across the rewrite — only the connectors change.

Before (flagged):

Nous avons analysé les données. Ensuite nous avons construit le modèle. Ensuite nous avons validé les résultats. Ensuite nous avons publié le rapport. Ensuite nous avons archivé les données brutes.

Quatre ensuite en cinq phrases — aucune progression ressentie.

What lucid-lint check --profile public reports:

warning input.md:1:1 Connector "ensuite" appears 4 times within 5 consecutive sentences (max 3). Vary the connector or restructure the passage. [rhythm.repetitive-connectors]

After (your rewrite):

Nous avons analysé les données. À partir de là nous avons construit le modèle. La validation a suivi, et dès que les résultats ont tenu nous avons publié le rapport. Les données brutes ont été archivées en dernier.

Suppression

See Suppressing diagnostics for the inline and block forms.

See also

• structure.sentence-too-long — long sentences and connector overuse often co-occur; flagging both surfaces a richer rhythm signal.
• Scoring model — rhythm.repetitive-connectors carries the default weight 1; the cost is local rather than compounding.

References

• Sanders & Noordman (2000)
• Graesser et al. (2004)

See References for the full bibliography.

lexicon.low-lexical-diversity

What it flags

Passages with excessive repetition of content words. A monotonous text loses reader attention and often signals unstructured thinking. The rule is not an anti-jargon detector: technical terms (API, request, cache) are expected to repeat — the signal targets non-technical content words.

At a glance

Detection

Sliding window of window_size words. Within the window, compute unique_words / total_words over non-stopword, non-code-block tokens. Fire when the ratio falls below min_ratio.

Parameters

Suppression

See Suppressing diagnostics.

References

• Herdan (1960)
• McCarthy & Jarvis (2010)
• Graesser et al. (2004)

See References for the full bibliography.

lexicon.excessive-nominalization

What it flags

Sentences densely packed with nominalizations — verbs turned into abstract nouns. Two problems compound: nominalized text is more abstract (costlier to process) and hides the agent (“who does what” is obscured). FALC and the US Plain Writing Act both recommend strong verbs over nominalizations.

At a glance

Detection

Walk the sentence. Flag words whose suffix matches the language’s nominalization list. Fire when the count per sentence crosses max_per_sentence.

• 🇫🇷 Suffixes: -tion, -sion, -ment, -ance, -ence, -age, -ité, -isme, -ure
• 🇬🇧 Suffixes: -tion, -sion, -ment, -ance, -ence, -ity, -ism, -ness, -al

Parameters

Known false positives

Technical vocabulary (function, implementation, configuration) contains many legitimate nominalizations, which is why dev-doc relaxes the threshold. The -al suffix in English is too broad (flags crucial, horizontal, positional despite these not being abstract nouns) and is tracked for review in F-excessive-nominalization-suffix-refine on the roadmap.

Example

Nominalizations colour-matched to their active-verb counterparts in the rewrite.

Before (heavy):

La réalisation de l’analyse de la conformité permettra l’identification des axes d’amélioration.

After (lighter):

Nous analyserons la conformité. Cela permettra d’identifier les axes à améliorer.

Suppression

See Suppressing diagnostics.

References

• Plain Language US (2011)
• CAN-ASC-3.1:2025

See References for the full bibliography.

lexicon.unexplained-abbreviation

What it flags

Acronyms used without a nearby definition. Each forced interruption to guess or look up an acronym breaks the flow and raises the risk of losing attention.

References. WCAG 2.1 SC 3.1.4 (Abbreviations); RGAA 9.4.

At a glance

Detection (v0.2, two-pass — F9)

1. Pre-scan the whole document for acronyms defined in either canonical form:

   • Full Expansion (ACRONYM) — example: World Wide Web (WWW)
   • ACRONYM (Full Expansion) — example: WWW (World Wide Web)

   The “expansion” side must contain at least two alphabetic words, so short parenthetical notes like (TBD) or (check later) do not count as definitions.

2. Match sequences of 2+ consecutive uppercase letters (optionally with digits) in the main text.

3. Filter each candidate against three layers, in order:

   1. Defined in document (from the pre-scan) — strongest.
   2. User whitelist from [rules.unexplained-abbreviation].whitelist.
   3. Baseline whitelist (profile-driven).

4. Flag each remaining occurrence.

A single definition anywhere in the document silences every occurrence of the same acronym — matching how readers actually use documentation (scroll back once to find the expansion, remember it thereafter).

Parameters

Default whitelist (v0.2, narrowed by F31): the infrastructure stack — URL, HTML, CSS, JSON, XML, HTTP, HTTPS, UTF, IO, API, CLI, GUI, OS, CPU, RAM, SSD, USB, IDE, SDK, CI, CD — plus common FR/EN acronyms and RFC 2119 emphasis keywords (PDF, SMS, GPS, ID, OK, FAQ, MUST, SHALL, SHOULD, …).

[rules.unexplained-abbreviation]
whitelist = ["WCAG", "ARIA", "ADHD", "LLM"]

User-whitelist entries are additive over the baseline — they extend it, never replace it.

Suppression

See Suppressing diagnostics.

See also

• lexicon.jargon-undefined — the content-word equivalent.

References

• WCAG 2.1 — 3.1.4
• CAN-ASC-3.1:2025

See References for the full bibliography.

lexicon.weasel-words

What it flags

Vague qualifiers that weaken a statement. A weasel word adds an invisible cognitive load: the reader has to decide whether the claim matters, is true, or measurable. References: Wikipedia style guide (Avoid weasel words), Strunk & White, FALC.

At a glance

Detection

Word-boundary match against a per-language list. Case-insensitive. One diagnostic per occurrence.

• Inline code spans. A hit inside `…` is skipped. Wrap a weasel term in backticks when you are discussing the word itself.
• Directional pairings. rather than (EN) and plutôt que (FR) are conjunctions meaning “instead of” — not hedges — and are skipped.

Parameters

Default lists (v0.1)

• 🇫🇷 quelques, certains, parfois, plutôt, assez, globalement, généralement, souvent, en général, la plupart, il semble que, il semblerait que, on pourrait dire que, on dit souvent, beaucoup de, peu de, presque, quasiment, environ, à peu près
• 🇬🇧 some, many, often, just, simply, clearly, obviously, seemingly, arguably, basically, essentially, virtually, various, numerous, sort of, kind of, a bit, rather, quite, fairly, relatively, mostly, generally

Known false positives

Two patterns still fire in v0.2: straight-quoted terms ("many X" without backticks) and "many X" where X is a concrete noun. Both are queued under F23 on the roadmap. Wrap the quoted term in backticks, or use an inline disable comment, to opt out.

Suppression

Use <!-- lucid-lint disable-next-line lexicon.weasel-words --> when the weasel is intentional (quotation, legitimate subset reference, meta-discussion). See Suppressing diagnostics.

References

• Strunk & White (1999)
• CAN-ASC-3.1:2025

See References for the full bibliography.

lexicon.jargon-undefined

What it flags

Domain-specific terms used without definition. Jargon is contextual: acceptable among specialists, exclusionary otherwise. Like acronyms, jargon creates reading interruptions for the non-specialist; unlike acronyms, these are content words, not uppercase sequences.

References. US Plain Language, FALC, WCAG 2.1 SC 3.1.3 (Unusual Words).

At a glance

Detection

1. Maintain multiple jargon lists per domain (tech, legal, medical, admin).
2. User activates the relevant lists via profile.
3. Flag each occurrence of a listed term.

Profile activation

Configuration

In v0.2, the active lists are set by the profile and are not yet user-overridable from lucid-lint.toml. Per-rule TOML overrides — adding custom domain terms, silencing specific entries, or activating a non-default list combination — are tracked as F126 on the roadmap.

Default starter lists (community contributions welcome)

• Tech: idempotent, orthogonal, deterministic, polymorphic, serialization, deserialization, synchronous, asynchronous, concurrency, thread-safe, side-effect, referential transparency, memoization, currying, hoisting, closure, monad, immutable, stateless, refactoring
• Legal (mostly FR): apériteur, clause résolutoire, force majeure, cessation de paiement, préjudice subi, onéreux, nonobstant, préalablement, susmentionné, infra, supra, ad hoc, de facto, in fine, subséquemment
• Medical: anamnèse, étiologie, pathognomonique, iatrogène, nosocomial, décompensation, récidive, rémission, syndromique
• Admin (mostly FR): attributaire, solliciter, diligenter, instruction du dossier, pièces justificatives, circulaire, délibération, arrêté préfectoral, transmission des pièces, ayant droit

Suppression

See Suppressing diagnostics.

See also

• lexicon.unexplained-abbreviation

References

• WCAG 2.1 — 3.1.3
• Plain Language US (2011)
• CAN-ASC-3.1:2025

See References for the full bibliography.

lexicon.all-caps-shouting

What it flags

Runs of consecutive ALL-CAPS words.

ALL-CAPS prose strips the shape cues that dyslexic readers rely on to disambiguate words:

• Ascenders — the strokes that rise above the body of letters like b, d, h, k, l.
• Descenders — the strokes that drop below the baseline in g, p, q, y.
• X-height contrast — the height difference between short letters like a, e, o and tall ones like h, l.

In all-caps, every letter sits on the same baseline at the same height. The reader loses the silhouette of the word and has to decode letter by letter. ALL-CAPS also triggers many screen readers to spell out the run letter by letter unless the surrounding markup says otherwise.

WCAG 3.1.5 and the BDA Dyslexia Style Guide both recommend lowercase or sentence case for emphasis.

At a glance

Detection

Per paragraph, scan for runs of consecutive ALL-CAPS words. Minor connectors (,, ;, :, -, whitespace) keep a run alive; a lowercase word, a period, or paragraph break ends it.

A word is ALL-CAPS when it is at least 2 letters long and contains no lowercase letter. Single ALL-CAPS tokens are treated as abbreviations and are the responsibility of lexicon.unexplained-abbreviation.

Code blocks are excluded by the Markdown parser before the rule runs.

Parameters

dev-doc tolerates a 2-word emphasis run (DO NOT) common in technical docs.

Examples

lucid-lint reports; the rewrite is always yours.

English

One emphasis phrase, colour-matched across the rewrite — the shouting becomes typographic emphasis without losing the stress.

Before (flagged):

Please DO NOT touch this.

DO NOT reads as shouting.

What lucid-lint check --profile public reports:

warning input.md:1:8 2 consecutive ALL-CAPS words read as shouting and degrade legibility for dyslexic readers. Use sentence case and rely on emphasis (italics, bold) or a callout instead. [lexicon.all-caps-shouting]

After (your rewrite):

Please do not touch this.

Known false positives

A chain of three or more acronyms in prose (API HTTP TLS) is structurally indistinguishable from shouting and will fire. Suppress on the line if the chain is intentional, or restructure the prose.

Suppression

See Suppressing diagnostics.

See also

• lexicon.unexplained-abbreviation
• Conditions

References

• Arditi & Cho (2007)
• Nielsen Norman Group
• Bringhurst (2013)

See References for the full bibliography.

lexicon.redundant-intensifier

What it flags

Intensifiers — adverbs that try to upgrade the confidence of a statement without adding information. very important reduces to important, or better, to a quantified claim. plainlanguage.gov (Chapter 4) and the CDC Clear Communication Index flag intensifiers as a plain-language anti-pattern.

The rule is a deliberate sibling of lexicon.weasel-words: weasel words downgrade confidence (hedges, qualifiers); redundant intensifiers upgrade it. The two lists are disjoint by construction.

At a glance

Detection

Per paragraph, lowercase the text and look for each intensifier phrase in the per-language list (en::INTENSIFIERS, fr::INTENSIFIERS) using the shared word-bounded search. Hits inside fenced or inline code spans are ignored. Documents whose language is Unknown are skipped rather than guessed, matching lexicon.weasel-words.

Parameters

custom_intensifiers_en / _fr add phrases to the defaults. disable removes phrases from them (exact lowercase match).

Known caveats

• very in the fixed phrase very well (as acknowledgment) still triggers — plain-language guides flag it anyway, so the rule does not carve out an exception. Suppress via inline directive if the context genuinely calls for it.
• Metalinguistic references (“the word ‘very’ is an intensifier”) trigger unless the target word is in backticks. Use inline code spans for such references.

Suppression

See Suppressing diagnostics.

See also

• lexicon.weasel-words
• lexicon.jargon-undefined
• Conditions

References

• Strunk & White (1999)
• Quirk et al. (1985)
• Zinsser (2006)

See References for the full bibliography.

lexicon.consonant-cluster

What it flags

Words whose longest run of consecutive consonants meets or exceeds a per-profile threshold. Dense consonant clusters are a known decoding barrier for dyslexic readers (BDA Dyslexia Style Guide): the reader must hold more phonemes in working memory before the next vowel “releases” the syllable.

Typical English offenders at the public threshold of 5 include strengths (n-g-t-h-s), twelfths (l-f-t-h-s), sixths (x-t-h-s in a 4-run plus context). Typical French offenders at the falc threshold of 4 include constructions (n-s-t-r).

At a glance

Detection

Per source line, walk the grapheme stream once. A word is a maximal run of alphabetic characters; hyphens, apostrophes, and whitespace close the word (so dys-lexic is two words, not one ten-letter cluster). Within a word, track the longest run of consecutive consonants. Emit one diagnostic per word whose longest run meets min_run_length.

Vowels are language-aware — French accented forms (é, è, ê, à, â, î, ï, ô, ö, ù, û, ü, ÿ, œ, æ) count as vowels. The English fallback still accepts common latin-1 accented vowels so borrowed words (café, naïve) decode correctly. y is treated as a vowel in every language (lenient), which avoids awkward false positives on words like fly, rhythm.

Parameters

dev-doc is tolerant — technical prose regularly names things like strengths and benchmarks. falc (plain-language audience) catches any 4-consonant run.

Known caveats

• The rule is blind to syllable structure: it counts raw consonant graphemes, not phonemes. A word like hatching (5 letters: t-c-h-n-g — a run of 5) reads fluently to most readers because tch is a single English digraph. Suppress with an inline directive when a hit is unavoidable.
• Script-agnostic for any alphabetic script, but the vowel lists are tuned for Latin scripts only. Words in Cyrillic, Greek, Arabic, etc., will likely trigger whenever the language flag is en or fr — in practice such content is out of scope for a bilingual EN/FR linter.

Suppression

See Suppressing diagnostics.

See also

• lexicon.all-caps-shouting
• readability.score
• Conditions

References

• Seidenberg et al. (1984)
• Treiman et al. (2006)

See References for the full bibliography.

lexicon.homophone-density

Experimental in v0.2.x. Off by default; opt in via --experimental lexicon.homophone-density or [experimental] enabled = ["lexicon.homophone-density"] in lucid-lint.toml. Flips to Stable at the v0.3 cut as part of the F-experimental-rule-status cohort flip. See Conditions for the dyslexia and aphasia condition tags that gate this rule under user-active conditions.

What it flags

Paragraphs whose share of homophones — words that sound alike but spell differently (their / there / they're, to / too / two, cours / court, amande / amende) — exceeds a configurable percentage. Homophones force a phonological-then-orthographic disambiguation pass: the ear resolves the word, the eye must then pick the right spelling from context. That extra hop is cheap on its own and expensive in a cluster. The British Dyslexia Association style guide flags homophones as a known friction point for dyslexic readers, and the FALC orthographic-clarity guidelines recommend rephrasing dense homophone runs for aphasic and plain-language audiences.

At a glance

Detection

For each paragraph, walk the word stream once, count alphabetic words as the denominator, and count words that appear in the per-language homophone table as hits. If hits / total strictly exceeds the per-profile threshold, emit one diagnostic anchored at the paragraph’s start line. Paragraphs with fewer than 20 content words are skipped — below that floor, a single homophone produces a misleading double-digit percentage. The diagnostic message names up to two example homophones the rule actually saw, so the location is the paragraph but the fix candidates are concrete.

The homophone tables (HOMOPHONE_GROUPS_EN, HOMOPHONE_GROUPS_FR in src/language/) lean toward content-word pairs whose orthographic confusion genuinely distorts meaning. Ultra-frequent French function-word homophones (et / est, a / à, ou / où) are intentionally excluded: they appear in nearly every sentence and would push baseline density past every threshold, drowning out the signal the rule is meant to catch.

When the document’s detected language is Unknown the rule has no table to apply and skips silently rather than guessing.

Parameters

Tune via lucid-lint.toml:

[rules."lexicon.homophone-density"]
max_density_percent = 4.0

Examples

English

Before (flagged):

Their report shows there were too many decisions to make and two teams could not affect the launch nor lose the schedule despite careful planning across each region and product line every quarter.

What lucid-lint check --profile public --experimental lexicon.homophone-density --conditions dyslexia reports:

warning input.md:1:1 Paragraph density of homophones is 21.2% (7 of 33 content words (e.g. their, there)); maximum 5.0%. Dense homophone runs raise the phonological-decoding load for dyslexic and aphasic readers; rephrase to disambiguate. [lexicon.homophone-density]

After (your rewrite):

The report shows that the team made many decisions and that the two squads kept the launch on schedule despite careful planning across each region and product line every quarter.

The rephrase swaps their / there / to / too / two for context-anchored alternatives (the report, that, the team, kept, the two squads), bringing density well below the threshold.

French

Before (flagged):

Pendant le cours du matin la cuisinière prépare le foie de veau avant la pause de midi puis revient à sa tâche après avoir rangé les ustensiles sur la grande table en bois clair.

What lucid-lint check --profile public --experimental lexicon.homophone-density --conditions dyslexia reports:

warning input.md:1:1 Paragraph density of homophones is 11.8% (4 of 34 content words (e.g. cours, foie)); maximum 5.0%. Dense homophone runs raise the phonological-decoding load for dyslexic and aphasic readers; rephrase to disambiguate. [lexicon.homophone-density]

After (your rewrite):

Pendant la séance du matin la cuisinière prépare le foie de veau avant la coupure de midi puis reprend son travail après avoir rangé les ustensiles sur la grande table en bois clair.

cours becomes séance, pause becomes coupure, tâche becomes travail — three of the four homophone hits disappear without losing meaning.

Suppression

See Suppressing diagnostics for the inline and block forms. Inline disable also works on this rule:

<!-- lucid-lint disable-next-line lexicon.homophone-density -->
Their report shows there were too many decisions to make and two teams could not lose the launch.

See also

• Conditions — the dyslexia and aphasia tags that gate this rule.
• F-experimental-rule-status — experimental rule status — substrate that lets this rule ship in v0.2.x without affecting default scores.

References

• British Dyslexia Association — Dyslexia Style Guide (2018). Flags homophones as a friction point for dyslexic readers.
• Falc — Information pour tous (2009). FALC orthographic-clarity guidelines for aphasic and plain-language audiences.

See References for the full bibliography.

syntax.passive-voice

What it flags

Passive-voice constructions. Passive hides the agent and lengthens the sentence without adding information. Legitimate exceptions exist (unknown agent, scientific style, intentional focus on the action) — the rule flags, the author decides.

References. US Plain Language; Strunk & White; FALC.

At a glance

Detection (v0.1 heuristic)

• 🇬🇧 be (conjugated) + past participle [+ by …]. Handles regular -ed and the irregular-participle table.
• 🇫🇷 être (conjugated) + past participle [+ par …], plus se faire + infinitif. Harder than EN because of participle agreement (gender/number) and confusion with (a) subject attribute (il est content vs il est vu) and (b) compound-tense être auxiliary (elle est partie — passé composé, active).

Expect ~70–80% precision. A POS-parser-based replacement is planned for a future lucid-lint-nlp plugin.

Parameters

Suppression

Use inline disables on intentional passives. See Suppressing diagnostics.

References

• Strunk & White (1999)
• Plain Language US (2011)
• CAN-ASC-3.1:2025

See References for the full bibliography.

syntax.unclear-antecedent

What it flags

Pronouns whose antecedent is not obvious in the immediate context. Ambiguous pronominal reference is one of the costliest comprehension breaks for readers with attentional difficulties: each ambiguity forces a conscious return-and-search.

References. Strunk & White; FALC (“prefer name repetition over pronouns”); Graesser et al. Coh-Metrix (referential cohesion).

At a glance

Detection (v0.1 heuristic)

Exact detection requires anaphora resolution (advanced NLP). v0.1 catches the two most frequent patterns:

1. Bare demonstrative pronouns at sentence start (This/That/These/Those, Ceci/Cela/Ce) not followed by a noun.
2. Personal pronouns at paragraph start (no antecedent in the preceding context).

Severity is info because the heuristic is approximate — the noise level warrants a soft signal.

Parameters

Pronoun lists

• 🇫🇷 ce, cela, ceci, ça, celui-ci, celle-ci, il, elle, ils, elles
• 🇬🇧 this, that, these, those, it, they, them

Example

Les performances étaient médiocres avec le cache LRU. Cela a motivé le changement.

Cela refers to the performance? The cache? Ambiguous.

Suppression

See Suppressing diagnostics.

References

• Strunk & White (1999)
• Gibson (1998)
• Graesser et al. (2004)

See References for the full bibliography.

syntax.nested-negation

What it flags

Sentences that stack multiple negations. Two or more negations in the same sentence force the reader to mentally toggle truth values — a known burden for readers with aphasia and attention-fragile readers (ADHD), and a load multiplier for everyone reading under cognitive pressure. Plain-language guidelines (FALC, CDC Clear Communication Index, plainlanguage.gov) recommend rewriting double negatives as positives.

At a glance

Detection

Count the negations per sentence; report sentences whose count exceeds max_negations.

• English — sum of word-boundary matches against the language’s negation list (not, no, never, none, nothing, nobody, nowhere, neither, nor, cannot, without) plus occurrences of the contracted n't suffix (don't, won't, isn't, doesn't, …).
• French — pair-based bipartite counting. Each ne / n' clitic contributes one negation and pairs with its nearest second-position particle (pas, rien, jamais, plus, personne, aucun, aucune, guère, nulle part) within a short window; the pairing just consumes the particle to avoid double-counting. Unpaired particles in a ne-sentence contribute one more — this catches forms like rien used as a nominal negative subject. Guards: pas / plus never count when unpaired (too ambiguous outside ne …); rien preceded by de is treated as the idiom de rien and skipped; particles in a sentence with no ne clitic are skipped too (plus de courage, personne d'autre). Standalones sans / non always count.

Parameters

Examples

lucid-lint reports; the rewrite is always yours.

English

Three negations → three affirmatives, colour-matched across the rewrite. The not simply drops — the simplification shows.

Before (flagged):

We do not say nothing is never possible.

Three negations (not, nothing, never).

What lucid-lint check --profile public reports:

warning input.md:1:1 Sentence stacks 3 negations (maximum 2). Rewrite as a positive statement or split the negations across separate sentences. [syntax.nested-negation]

After (your rewrite):

We say something is possible.

French

Passes under public:

Nous ne sommes pas prêts.

Bipartite ne ... pas counts as one negation.

Before (flagged):

Nous ne disons pas que rien n’est jamais possible.

Three negations: ne…pas (one bipartite), rien (unpaired), n'…jamais (one bipartite).

What lucid-lint check --profile public reports:

warning input.md:1:1 Sentence stacks 3 negations (maximum 2). Rewrite as a positive statement or split the negations across separate sentences. [syntax.nested-negation]

After (your rewrite):

Nous disons que quelque chose est possible.

Suppression

See Suppressing diagnostics.

See also

• syntax.passive-voice
• structure.deep-subordination
• Conditions

References

• Clark & Chase (1972)
• Carpenter & Just (1975)
• Kaup et al. (2006)

See References for the full bibliography.

syntax.conditional-stacking

What it flags

Sentences that chain multiple conditional clauses. Each if / when / unless / quand / si opens a branch the reader must keep on a mental stack until the outer clause resolves; two or three of them stacked in one sentence is a known load multiplier for readers with aphasia, ADHD, and anyone reading under cognitive pressure. Plain-language guidelines (FALC, plainlanguage.gov) recommend splitting conditional chains into separate sentences or a bullet list.

At a glance

Detection

Per sentence, count the conditional connectors and report counts above max_conditionals.

• English — sum of word-bounded matches against the language list (if, unless, when, whenever, while, until, provided, assuming, in case, as long as, as soon as, even if, only if).
• French — sum of word-bounded matches against the language list (si, sauf si, à moins que, à moins de, quand, lorsque, lorsqu', dès que, tant que, pourvu que, à condition que, à condition de, au cas où, même si, en cas de) plus the elliptic clitics s'il / s'ils.

Parameters

Examples

Three conditionals, colour-matched across the rewrite — position already pairs them, the tint just confirms each branch carries through. lucid-lint reports; the rewrite is always yours.

English

Before (flagged):

If we ship, when the build passes, unless the gate fails, we deploy.

What lucid-lint check --profile public reports:

warning input.md:1:1 Sentence stacks 3 conditional clauses (maximum 2). Split the conditions across separate sentences or convert them to a bullet list. [syntax.conditional-stacking]

After (your rewrite):

We deploy when all three checks hold:

• the ship command ran,
• the build passes,
• the gate does not fail.

French

Before (flagged):

Si nous expédions, quand le test passe, à moins que la barrière échoue, nous déployons.

Three conditional connectors (si, quand, à moins que). French rewrite to come with the FR translation pass.

Known false positives

The English list mixes pure conditionals with temporal conjunctions (when, while) that often introduce conditional-like sub-clauses. Pure-temporal usages may produce a false positive on long sentences. Use disable-next-line when the temporal reading is unambiguous.

Suppression

See Suppressing diagnostics.

See also

• syntax.nested-negation
• structure.deep-subordination
• Conditions

References

• Johnson-Laird & Byrne (1991)
• Evans & Over (2004)
• Gibson (1998)

See References for the full bibliography.

syntax.dense-punctuation-burst

What it flags

Local bursts of punctuation: a sliding window of grapheme clusters that contains too many qualifying marks (,, ;, :, —, –). Tight clusters of marks signal layered subordination, parenthetical interjections, or list-within-list constructions that are hard to parse for readers with cognitive or attentional difficulties (IFLA easy-to-read guidelines).

Distinct from structure.excessive-commas, which counts commas across an entire sentence. A sentence with 8 commas spread evenly across 200 characters does not trigger here, while a sentence with 3 commas inside a 30-character span does.

At a glance

Detection

Per source line, walk the grapheme stream once and collect the column of every qualifying mark. When a window of window_graphemes graphemes holds min_marks or more marks, emit a burst spanning the first to the last mark in the window, then advance past that last mark so overlapping windows do not double-fire on the same cluster.

Code blocks (fenced and indented) are excluded upstream by the Markdown parser. Sentence terminators (., !, ?) and brackets do not count toward the burst.

Parameters

dev-doc tolerates a 3-mark cluster (often unavoidable in technical lists adjacent to prose). FALC keeps the same density floor as public but widens the window to catch slightly looser bursts.

Known caveats

• The rule operates per source line. A burst that wraps across a hard line break in the source is not detected; in practice this is rare because dense punctuation is also dense in source bytes.
• Em dash (—, U+2014) and en dash (–, U+2013) qualify; the ASCII double-hyphen surrogate (--) does not, on the assumption that authors who care about readability use the proper Unicode forms.

Suppression

See Suppressing diagnostics.

See also

• structure.excessive-commas
• structure.sentence-too-long
• Conditions

References

• Sweller (1988)
• Gibson (1998)

See References for the full bibliography.

syntax.parenthetical-depth

Experimental in v0.2.x. Off by default; opt in via --experimental syntax.parenthetical-depth or [experimental] enabled = ["syntax.parenthetical-depth"] in lucid-lint.toml. Flips to Stable at the v0.3 cut as part of the F-experimental-rule-status cohort flip. See Conditions for the adhd and general condition tags.

What it flags

A sentence whose maximum balanced-bracket nesting depth across () and [] reaches the profile threshold. Stacked parentheticals force the reader to track multiple suspended frames at once — a recognised “hard sentence” signal in the plainlanguage.gov and Hemingway editing traditions, and a particular cost for ADHD readers, who carry the working-memory load first.

The rule complements structure.excessive-commas, which already discounts flat (A, B, C) enumerations at depth 1. This rule fires only at depth 2 or more, so the two rules are mechanically orthogonal: one flat parenthesised list never trips this rule.

At a glance

Detection

For each sentence, the rule walks the post-flattening paragraph text (so fenced code blocks are already excluded by the parser) and tracks a single running depth counter.

Algorithm

1. Walk the sentence one character at a time.
2. Increment depth on ( or [; decrement on ) or ].
3. A close that would push depth below zero resets depth to zero — the rule fails open on unbalanced markup, mirroring the posture of the parenthesised_list_comma_count helper used by structure.excessive-commas.
4. Track the maximum depth reached and the position of the opener that achieved it.
5. Emit one diagnostic per sentence when max_depth ≥ the profile threshold, anchored at the deepest opener.

Skips (false-positive guards)

• Code spans / fenced code blocks: already excluded upstream by the Markdown parser.
• Unbalanced brackets: the depth-floor reset prevents stray closes from inflating later depths.

Deferred (not in MVP)

Em-dash pairs (— … —), curly braces ({}), and comma-flanked appositives are intentionally out of scope at v0.2.x. Em-dash pair detection is fragile (en/em-dash confusion, hyphen ambiguity) and would smuggle scope back in.

Parameters

max_depth is the inclusive nesting depth at which the rule fires. A sentence whose deepest bracket frame is one level shallower stays silent.

Tune via lucid-lint.toml:

[rules."syntax.parenthetical-depth"]
max_depth = 3

Examples

English

Before (flagged):

The migration tool (which now supports rollbacks (see --reverse, added in 0.4.2 [tracked in #312])) is opt-in.

What lucid-lint check --profile public --experimental syntax.parenthetical-depth --conditions adhd reports:

warning input.md:1:21 Nested parentheticals reach depth 3; readers must hold 3 suspended thoughts to reach the close. Split the sentence or unnest the inner bracket (plainlanguage.gov, Hemingway). [syntax.parenthetical-depth]

After (your rewrite):

The migration tool is opt-in. It now supports rollbacks via --reverse, added in 0.4.2 (tracked in #312).

The two top-level parentheticals are gone; the remaining one sits flat at depth 1. A reader no longer has to push three suspended thoughts on the stack to reach the close.

French

Before (flagged):

Le module (qui dépend du noyau (chargé au démarrage [voir le manuel])) est facultatif.

What lucid-lint check --profile public --experimental syntax.parenthetical-depth --conditions adhd reports:

warning input.md:1:23 Nested parentheticals reach depth 3; readers must hold 3 suspended thoughts to reach the close. Split the sentence or unnest the inner bracket (plainlanguage.gov, Hemingway). [syntax.parenthetical-depth]

After (your rewrite):

Le module est facultatif. Il dépend du noyau, chargé au démarrage. Voir le manuel pour les détails.

Three sentences, no nested brackets. The dependency chain is now linear and the reader recovers each fact in the order it appears.

Suppression

See Suppressing diagnostics for the inline and block forms. Inline disable also works on this rule:

<!-- lucid-lint disable-next-line syntax.parenthetical-depth -->
The migration tool (which now supports rollbacks (see `--reverse`, added in 0.4.2 [tracked in #312])) is opt-in.

See also

• Conditions — the adhd and general tags that gate this rule.
• structure.excessive-commas — sibling rule on flat parenthesised enumerations. Atomic split: excessive-commas discounts depth-1 (A, B, C) lists; this rule fires only at depth ≥ 2.
• syntax.dense-punctuation-burst — sibling rule on local punctuation density. Both signal hard-to-parse sentences from different angles.
• F-experimental-rule-status — experimental rule status — substrate that lets this rule ship in v0.2.x without affecting default scores.

References

• plainlanguage.gov — Write short sentences. Plain-language guidance treats stacked qualifiers and nested parentheticals as the canonical “long sentence” symptom.
• Hemingway editing tradition — surfaces “hard to read” sentences when they layer multiple suspended ideas; nested parentheticals are the cleanest mechanical reading of that signal.

See References for the full bibliography.

readability.score

What it flags

A document-level readability index. Readability formulas are the historical synthetic signal for text complexity — simple, reproducible, recognized by US/UK government guidelines and WCAG. Treat it like cyclomatic complexity: a metric first, a warning second.

At a glance

Detection (v0.2 — per-language formula)

The formula is selected by the document’s detected language:

English — Flesch-Kincaid Grade Level:

0.39 × (words / sentences) + 11.8 × (syllables / words) − 15.59

The result is a US-school grade. Compared directly to max_grade_level.

French — Kandel & Moles (1958):

207 − 1.015 × (words / sentences) − 73.6 × (syllables / words)

The result is an ease score on roughly 0..100 (higher = easier), Flesch-style. To stay comparable across languages, the rule converts it to a grade-equivalent with the standard linear approximation (100 − score) / 10, and compares that against max_grade_level. The diagnostic message surfaces both the native ease score and the grade-equivalent.

Unknown language falls back to Flesch-Kincaid.

Additional formulas (Gunning Fog, SMOG, Dale-Chall, Scolarius) and multi-formula --readability-verbose reports remain on the roadmap.

Parameters

Override formula via --readability-formula on the CLI; auto uses the detected language, other values pin the formula.

Output modes

• Always reported as info (for observability, even when under the threshold).
• Reported as warning when the grade level exceeds max_grade_level.

Suppression

Suppressing a document-level metric is rarely the right answer; adjust max_grade_level in lucid-lint.toml instead. See Configuration.

References

• Flesch (1948)
• Kincaid et al. (1975)
• CAN-ASC-3.1:2025

See References for the full bibliography.

readability.large-number-unanchored

Experimental in v0.2.x. Off by default; opt in via --experimental readability.large-number-unanchored or [experimental] enabled = ["readability.large-number-unanchored"] in lucid-lint.toml. Flips to Stable at the v0.3 cut as part of the F-experimental-rule-status cohort flip. See Conditions for the dyscalculia and general condition tags.

What it flags

A large numeral or magnitude word that appears in a sentence with no nearby anchor — no unit, no percentage, no currency symbol, no ratio, no comparator phrase. The CDC Clear Communication Index asks whether numbers are clear and meaningful for the primary audience; plainlanguage.gov is more direct on the mechanism — “Use Numbers Effectively” recommends giving every large figure a comparison or denominator the reader can ground. Readers with dyscalculia carry the cost first: a context-free “4.8 milliards” forces an unaided magnitude estimate that ordinary prose context does not provide.

The rule complements structure.number-run, which fires on numeric clusters (≥ N tokens in one sentence). This rule fires on a single large or magnitude-word numeral that lacks anchoring context.

At a glance

Detection

For each sentence, the rule walks the post-flattening paragraph text (so fenced code blocks are already excluded by the parser) and searches for unanchored candidates.

Candidate definition

A sentence-level candidate is either:

1. A numeric token whose digit count is ≥ 4 and whose integer value is ≥ the profile threshold. The scanner collapses common thousands separators (,, ., ASCII space, NBSP, thin space, narrow NBSP) between digit groups so 1 000 (FR) and 1,000 (EN) both count as one 4-digit token with value 1000.
2. A magnitude word — million(s), billion(s), trillion(s) in EN; million(s), milliard(s), billion(s), trillion(s) in FR. Whole-word, case-insensitive.

Skips (false-positive guards)

• Year-shaped: exactly 4 contiguous digits with no thousands or decimal separators and value in 1000..=2999. 2024 and 1789 are years, not magnitudes.
• Ordinal: digit run immediately followed by a letter (1st, 12th).
• Figure / page / section reference: candidate preceded (within 16 bytes, same sentence) by Figure, Fig., Page, Section, §, p., pp., #, or the FR equivalents (figure, page, section, tableau, chapitre, annexe).

Anchor types (sentence-scoped)

Any of the following anywhere in the sentence anchors all candidates in that sentence:

• Percent sign (%).
• Currency symbol ($, €, £, ¥).
• Unit token from a small curated list (km, kg, m², °C, L, Hz, MB, Mo, …).
• Ratio pattern: X out of Y, X sur Y, or X / Y between digits.
• Comparator phrase from the per-language lexicon (EN: roughly, approximately, more than, the size of, …; FR: soit environ, équivalent à, environ, plus de, par rapport à, …).

The diagnostic location points at the first surviving candidate in the offending sentence, so the squiggle in your editor lands on the visible numeral rather than the start of the sentence.

Parameters

min_value is the inclusive lower bound on the integer value of a numeric candidate. Tokens that meet the digit-count gate but fall below min_value are skipped — page-number-like quantities already get the figure-ref skip; this is a second safety net.

Tune via lucid-lint.toml:

[rules."readability.large-number-unanchored"]
min_value = 50000

Examples

English

Before (flagged):

The proposal mentions several billion in vague spending across regions.

What lucid-lint check --profile public --experimental readability.large-number-unanchored --conditions dyscalculia reports:

warning input.md:1:32 Magnitude word appears with no anchor in this sentence (no unit, percentage, ratio, or comparison phrase). plain-language guidance recommends pairing magnitude words with a unit or a comparison the reader can ground. [readability.large-number-unanchored]

After (your rewrite):

The proposal mentions several billion dollars in vague spending across regions, roughly the annual budget of a mid-sized state agency.

The figure now sits next to a unit (dollars) and a comparator phrase (roughly the annual budget); both anchor the magnitude for a reader who cannot ground it from raw scale.

French

Before (flagged):

Le budget atteint 4 800 000 000 selon le rapport final.

What lucid-lint check --profile public --experimental readability.large-number-unanchored --conditions dyscalculia reports:

warning input.md:1:19 Large numeral (10-digit, value ≈ 4800000000) appears with no anchor in this sentence (no unit, percentage, ratio, or comparison phrase). plain-language guidance recommends giving large numbers a comparison or denominator the reader can ground. [readability.large-number-unanchored]

After (your rewrite):

Le budget atteint 4,8 milliards d’euros, soit environ 6 % du PIB selon le rapport final.

The figure is now accompanied by a unit (euros), a percentage (6 %), and a comparator phrase (soit environ). A reader who cannot estimate “4,8 milliards” raw now has three independent anchors.

Suppression

See Suppressing diagnostics for the inline and block forms. Inline disable also works on this rule:

<!-- lucid-lint disable-next-line readability.large-number-unanchored -->
The proposal mentions several billion in vague spending across regions.

See also

• Conditions — the dyscalculia and general tags that gate this rule.
• structure.number-run — sibling rule on numeric clustering. Atomic split: number-run fires on clusters of numeric tokens; this rule fires on a single unanchored large numeral.
• structure.mixed-numeric-format — another sibling on numeric form consistency (digits vs spelled-out).
• F-experimental-rule-status — experimental rule status — substrate that lets this rule ship in v0.2.x without affecting default scores.

References

• plainlanguage.gov — Use numbers effectively. “Help your reader visualize numbers… Compare numbers to something the reader is familiar with.”
• CDC Clear Communication Index — Numbers. Item 6 asks whether numbers are clear and meaningful for the primary audience.

See References for the full bibliography.

Architecture overview

lucid-lint is a small Rust crate with a deliberately simple pipeline.

Pipeline

 input text
     │
     ▼
┌──────────────────────────┐
│ Language detection       │   stop-word ratio heuristic
└─────────────┬────────────┘
              │
              ▼
┌──────────────────────────┐
│ Parser                   │   pulldown-cmark or plain text
│ (Markdown | plain)       │
└─────────────┬────────────┘
              │
              ▼
┌──────────────────────────┐
│ Document model           │   Section > Paragraph > Sentence
└─────────────┬────────────┘
              │
              ▼
┌──────────────────────────┐
│ Rules                    │   Each rule gets the document + language
│ (sentence-too-long, ...) │
└─────────────┬────────────┘
              │
              ▼
┌──────────────────────────┐
│ Diagnostics              │   rule_id, severity, location, section,
│                          │   message, weight
└─────────────┬────────────┘
              │
              ▼
┌──────────────────────────┐     v0.2+
│ Scoring                  │   density-normalized, category-capped
│ (Scorecard)              │   5 fixed categories
└─────────────┬────────────┘
              │
              ▼
┌──────────────────────────┐
│ Output formatter         │   TTY (default) or JSON
│                          │   — carries diagnostics + scorecard
└──────────────────────────┘

Key types

• Diagnostic — the output unit. Carries weight (seeded from scoring::default_weight_for) as of v0.2.
• Rule (trait) — fn check(document, language) -> Vec<Diagnostic>.
• Document — the parser’s output. Section-aware.
• Scorecard — global: Score plus [CategoryScore; 5] in fixed Structure · Rhythm · Lexicon · Syntax · Readability order.
• Report — diagnostics + scorecard + word_count, returned by Engine::lint_* since v0.2.
• Engine — bundles a profile, rule set, and optional ScoringConfig; exposes lint_str, lint_file, lint_stdin.

Design principles

These principles are enforced in code review. See Design decisions for background.

1. Make impossible states impossible — newtypes, enums with data, NonZeroU32.
2. Functional style where it helps — iterator chains, pure rule functions.
3. Atomic rules — one rule, one signal.
4. Deterministic core — no network, no LLM, no env-dependent behavior.
5. YAGNI — no speculative abstractions.

Module layout

src/
├── lib.rs             — library root
├── main.rs            — binary entry point
├── cli.rs             — clap CLI
├── config.rs          — profile presets, config file parsing
├── engine.rs          — orchestration
├── language/          — detection + per-language data
├── parser/            — Markdown + plain + tokenizer + document model
├── rules/             — one file per rule
├── scoring.rs         — hybrid scoring model (v0.2+)
├── output/            — TTY + JSON formatters
└── types.rs           — domain types (Diagnostic, Severity, Location, ...)

Design decisions

This page records design decisions made during v0.1 that are worth revisiting before changing.

Linter model vs scoring model

Decision: v0.1 shipped as a classic linter with info / warning severities. v0.2 added a hybrid scoring model (global score + per-category sub-scores + diagnostics) on top, without removing the linter form.

Rationale: shipping the linter form first let us validate detection quality on real corpora before adding the aggregation layer. The scoring layer is additive — consumers that only care about diagnostics ignore the scorecard.

Hybrid scoring model (v0.2)

Decision: global + 5 per-category sub-scores, all in X / max form. Composition stacks a weighted sum, density normalization (per 1 000 words, floored at 200), and a per-category cap. 5 fixed categories: Structure · Rhythm · Lexicon · Syntax · Readability. New Diagnostic.weight field, new --min-score=N CLI flag.

Rationale (full brainstorm at brainstorm/20260420-score-semantics.md):

• X / max over 0–100: arbitrary max lets us re-tune without claiming the 80 we ship today is the same 80 next release. The /impeccable skill already uses this convention.
• 5 fixed categories: couples nothing to a rule rename; uses the category_of(rule_id) helper already decided in v0.1. Derive-from- prefix (plan B) was rejected because it would require renaming 17 rules for F14 alone.
• Three composition mechanics stacked: no single one covers every failure mode. Density alone punishes short docs; weights alone lose to a runaway rule; caps alone can’t reflect cost magnitude.
• Letter grades, traffic lights, pass/fail margin, reading-time-seconds were cut from the v0.2 design after a first-principles pass (F-score-letter-grade–F-reading-time-score in ROADMAP). They duplicate function-1 (at-a-glance) that the number already serves.
• Actionability (function-2) is delivered by the diagnostics list, not the score. So sub-scores can afford to be minimal — F37 makes sure diagnostic messages hold up the actionability side of the contract.

Diagnostic struct

Decision: a Diagnostic carries rule_id, severity, location, section, message, and (as of v0.2) weight.

What’s NOT stored and why:

• category — derivable from rule_id via Category::for_rule. Storing it would duplicate information and risk drift.
• suggestion — still deferred; current messages are actionable on their own.

What IS stored and why:

• section — recomputing it after the fact would require re-parsing the document to walk headings and match locations. The storage cost is an Option<String> per diagnostic; the recompute cost is a second full parse.
• weight (v0.2) — seeded at emission from scoring::default_weight_for so that user overrides (via config) and rule-level overrides (via with_weight) both flow through aggregation without a second lookup.

Deterministic core, plugins for the rest

Decision: the core ships only deterministic rules. LLM-based rules, network-backed rules, or ML-model-backed rules live in optional plugin crates (planned v0.3).

Rationale: a pre-commit hook that takes 5 seconds and varies between runs is worse than no hook. Determinism is non-negotiable in the happy path.

Bilingual EN/FR from day one

Decision: every language-dependent rule supports English and French from v0.1.

Rationale: most French-speaking OSS developers write docs in English. Targeting French only would miss the majority. Supporting both from day one is cheap and signals the ambition.

Single readability formula in v0.1

Decision: v0.1 uses Flesch-Kincaid Grade Level for all languages. Language-specific formulas (Kandel-Moles for French, SMOG, Coleman-Liau) are deferred to v0.2.

Rationale: Flesch-Kincaid is understood, reproducible, and well-behaved. Adding three more formulas before validating the basics would be premature optimization.

Markdown + plain text + stdin, Pandoc for the rest

Decision: native support for .md, .markdown, .txt, and stdin in v0.1. Other formats (AsciiDoc, HTML, docx, PDF) use Pandoc as a pre-processor.

Rationale: Markdown covers the overwhelming majority of open-source and technical writing. Pandoc is free, ubiquitous, and removes the burden of maintaining multiple parsers.

One file per rule

Decision: each rule lives in its own file under src/rules/ with a consistent structure (struct, config, Rule impl, tests).

Rationale: makes adding a rule a well-defined operation (new file from template), and makes reviewing easy (one rule, one PR, one file to read).

Stop-word heuristic for language detection

Decision: v0.1 detects language by stop-word ratio. No external dependency.

Rationale: short, deterministic, no runtime cost. For the cases where it fails (very short texts, code-heavy docs), the unknown fallback is safe.

Profile presets as enum variants

Decision: profiles are Profile::DevDoc | Public | Falc. They cannot be defined in user config in v0.1.

Rationale: adding custom profiles is a speculative abstraction until someone asks for it. Per-rule overrides are enough to cover 95% of the “I want a slightly different preset” cases.

ROADMAP source-of-truth pipeline (v0.2.x+)

Decision: ROADMAP.md is demoted from edited source to generated artifact. The source-of-truth becomes a structured set of files under .roadmap/ (gitignored), one markdown file per feature with TOML front-matter, plus narrative chunks. A small Rust workspace member (crates/roadmap-cli) provides add / generate / validate / rename subcommands. The generator is invoked locally during release prep; the regenerated ROADMAP.md is committed on the release-prep PR. CI does not regenerate. Scoped under F-roadmap-toml-source.

Rationale:

• Branch protection on main (in place since 2026-05-03 via F-repo-config-hardening) forces every ROADMAP.md tweak through the worktree → branch → PR → CI → merge → cleanup cycle. Forecast steady-state was 10–30 ROADMAP-only edits per week. The PR review value on those edits is null (solo author), so the ceremony was pure overhead.
• Path-scoped ruleset bypass on ROADMAP.md would weaken the branch-protection signals tracked by the OpenSSF Scorecard / Best Practices badges. Demoting the file from main source preserves those signals untouched.
• Per-feature files give per-feature git diffs, kill schema lock-in (front-matter is per-file optional), and let narrative sections live as plain markdown rather than TOML strings.
• Rust over Python for the generator: reuses pulldown-cmark already in dependencies, folds tests into cargo test, single-toolchain maintenance, and stays extractable as a standalone crate if the tool matures.
• Local generator (not CI) avoids granting CI any access to .roadmap/ (gitignored and machine-local). Release cadence — not real-time — was an accepted trade-off; the public ROADMAP.md artifact updates per v* tag.
• Day-1 blockers on landing: deterministic <a id="…"> anchor emission (so existing [F46](#f46)-style cross-links from PRs and commits keep resolving), an add templating subcommand (so creating a feature is one keystroke, not a regression), and a round-trip determinism test (regenerate the artifact, diff against committed, fail on drift).

Emergency fallback: if crates/roadmap-cli work overruns budget, the file moves instead to a roadmap orphan branch with direct push and the same .md shape — preserves Scorecard signals via a different mechanism, at the cost of a non-standard branch layout. Documented as the escape hatch but not the chosen path.

References to follow before changing these

• RULES.md — the authoritative rule reference
• ROADMAP.md — future work tracked
• CODING_STANDARDS.md — day-to-day conventions

lucid-lint — Roadmap

Future rules, refinements, and platform extensions tracked from v0.1 onwards.

Status as of 2026-05-02: v0.1 shipped 2026-04-20 (17 rules). v0.2.0 shipped 2026-04-22 (25 rules + hybrid scoring + SARIF + condition tags), v0.2.1 + v0.2.2 shipped 2026-04-23, v0.2.3 shipped 2026-04-29 (structure.line-length-wide author-break-aware + encoding hygiene F110/F111/F112 + correctness wins). The v0.2.x patch cycle is active: F25 closed 2026-05-01 (FR pair-completeness 41/41); the FR content-staleness gate is --strict on main since 2026-05-01 and on PRs since 2026-05-02 (F92 sub-task fully closed); F35b/F35c, F104, F105, F107, F123 all shipped. v0.3 strategy locked 2026-05-02: the breaking change is the 5-rule cohort (F46 / F49 / F51 / F53 / F57) flipping from default-off to default-on. Each rule ships in v0.2.x as Experimental via the F-experimental-rule-status substrate — visible, opt-in for dogfooding, no score regression — then flips to Stable at the v0.3 cut. v0.4 is a horizon bet list.

Legend

At a glance

Version-centric and topic-centric summary views. The sections below this one are the authoritative topic-centric tables; use them when you need origin, rationale, or full history. Use this section when you need to answer “what’s next?” or “what’s the 0.3 shape?” in a glance.

Version snapshot

Feature catalog (active work)

Filtered to 🔴 Next + 🚧 In-progress. The narrative sections later in this file are the source of truth; this catalog is a derived index, hand-maintained alongside the narrative. If you spot drift, the narrative wins.

Sort: target version (current cycle first) → status (🚧 in-progress before ☐ next) → F-ID.

Topic heatmap

Where the active energy is. Counts include 🔴 Next only; shipped items excluded.

Cadence and gating

• v0.2.x is a rolling patch cycle, not a single release target. Each Must or Should ships as soon as it’s green on just check + CI; any 🔴-tagged row is eligible to ride the next patch cut.
• v0.3 opens only when the v0.2.x Must queue is empty and at least one breaking change is justified. Until then, breaking changes are held — non-breaking items that would otherwise fit 0.3 (e.g. F-score-letter-grade letter grade) can slide into 0.2.x if they mature first.
• v0.4 items do not progress by tenure. Each carries an unlock signal — a concrete event that promotes it from horizon to scheduled. See “v0.4 — horizon” at the bottom of this document.

v0.4 — horizon (bets, not commitments)

Routed 2026-04-24 in .personal/brainstorm/20260424-next-cycles.md. Each bet lists the signal that unlocks it, so horizon items don’t drift into Must by tenure alone. No commitments; this is “what could be true in ~6 months if 0.2 and 0.3 land cleanly”.

Deliberately off the 0.4 list:

• F-score-letter-grade / F-score-traffic-light letter grade + traffic light — routed to 0.3 Should; if they slip they go to 0.3.x, not 0.4.
• Full F29 numeric codes — parked until a rename actually happens.
• F-sentence-diversity-density, F-comma-density-relative speculative rule refinements — stay speculative until a concrete dogfood case surfaces.
• F-per-family-subscores per-family sub-scores — category sub-scores (F14) already ship; unclear what “family” adds beyond that.

v0.3+ — Advanced plugins

LLM-enhanced detection

The plugin would add rules like unclear-antecedent-semantic that use an LLM to detect semantic ambiguities the pattern-based heuristics miss.

Disabled by default due to non-determinism, API cost, and latency incompatible with pre-commit hooks.

Advanced NLP

Candidate rules for the plugin:

• POS-based syntax.passive-voice detection (replaces v0.1 heuristic)
• Full anaphora resolution for syntax.unclear-antecedent
• Dependency-tree-based structure.deep-subordination
• Semantic similarity between adjacent sentences (discourse cohesion signal inspired by Coh-Metrix)

New rules (v0.3 candidates)

Deferred from v0.2 because they require corpus work, lexicon builds, or depend on earlier features (F9, F14). Naming uses the provisional category.rule-name prefix pending F29.

Developer experience (v0.3)

Ecosystem interop

Motivation: lucid-lint and Markdown-syntax linters (markdownlint, Vale, proselint, textlint) can flag the same line from different angles. Cognitive-load rules that happen to share a substrate with a structural check should stay shipped in core — users without markdownlint, users who disabled the matching markdownlint rule, and users feeding non-Markdown input (plain text, .docx via F-docx-support, HTML via F-html-support) all rely on lucid-lint for that coverage. The pain point is editor LSP sessions where two servers report the same span with different severities and different wording, not CLI pipelines where tools run sequentially.

Scope audit at 2026-04-20: after the structure.heading-jump reframing (cognitive “comprehension cliff” at skip ≥ 2 levels, distinct from MD001’s strict +1 rule), structure.deeply-nested-lists is the only lucid-lint rule that remains functionally equivalent to a markdownlint rule (MD007). The mechanism below is designed to scale — Vale, proselint, textlint overlaps are likely as the rule set grows — rather than to solve a single-rule problem.

Adoption channels

Filed 2026-04-25 from the adoption-channels brainstorm (.personal/brainstorm/20260425-adoption-channels.md). This section tracks distribution and integration channels — work that lives in this repo (release artifacts, plugins, docs pages, IDE / CI integrations).

Pure promotion / outreach plays (DINUM submission, awesome-list PRs, audit-and-PR on famous OSS docs, W3C COGA submission, conference talks, social-media cadence, Hacker News, etc.) moved to .personal/promotion-channels.md on 2026-05-01. The freed F-IDs (F111, F112, F113, F117, F118, F119) are considered lost — not reused. F110 (Vale style pack — code) was renumbered to F137 (since renamed to F-vale-style-pack under the slug convention) to free F110 for the encoding-hygiene canonical entry already shipped in v0.2.3.

The regulatory tailwind (EAA enforceable since 2025-06-28; RGAA 5 ships end-2026 with DGCCRF / Arcom sanctions up to 50k€ + renewable) shapes the must-list — F-vale-style-pack (Vale pack) leans directly on it. Bilingual EN/FR is the differentiator that makes the FR-government channel viable.

Infrastructure & Static Analysis

Hardened quality stack for the project’s internal hygiene, balancing CI speed with high-signal security and prose audits. Routed 2026-05-04.

Research track

Bets that don’t commit to a ship date. Tracked to ensure they’re not forgotten.

Additional research directions captured for posterity but not yet ID’d:

• Reader-model scoring — tiny local model predicts processing time and accuracy per paragraph; output is a cognitive-load heatmap. Deterministic at inference, data-hungry at training.
• TTS / screen-reader prosody rules — detect prosody breakdown (mid-sentence acronyms, awkward punctuation cadence). Needs a TTS corpus.
• Cross-document terminology drift — same concept named three ways across a corpus (“user” / “customer” / “client”). Requires multi-file analysis infrastructure; performance implications.
• Eye-tracking corpus collaboration — partnership with a reading lab to ground thresholds in behavioural data.
• LSP server — live diagnostics in editors; same core, different frontend.
• --fix / quickfix suggestions — safe rules only (e.g. structure.long-enumeration → concrete list skeleton). Controversial for prose; needs guardrails.
• lucid-lint baseline — record per-project medians; rules flag regressions rather than absolutes (ESLint-style).
• Profile composition (extends = "falc") — reduce duplication across projects.
• Community rule-pack registry — cargo-style publication of domain packs (medical, legal, edu, journalism).
• lucid-lint-style plugin — adverb overuse, show-don’t-tell, and other aesthetic rules excluded from core by design.
• lucid-lint-a11y plugin — alternative home for a11y-markup- tagged rules if the tag proves insufficient to separate them from prose rules.

v0.2 / v0.2.x — Must-ship shipped, patch cycle in progress

Release cadence

The 2026-04-22 reprioritisation favoured a tight 0.2.0 cut over a fat one: anything non-blocking slides to 0.2.x patch releases, which exist precisely to absorb per-rule polish and per-surface slices. v0.2.0, v0.2.1, and v0.2.2 are shipped; v0.2.x remains open as a rolling patch cycle. 0.2.x routing was reviewed on 2026-04-24 in .personal/brainstorm/20260424-next-cycles.md (not tracked; .personal/ is gitignored).

v0.2.0 — Blocking items (all ✅ shipped 2026-04-22)

v0.2.1 — ✅ Released 2026-04-23

Localhost 404.html rendering fix (F-example-fixtures-part2 part 1), per-rule TOML override for structure.excessive-commas (third rule wired after readability.score.formula and lexicon.unexplained-abbreviation.whitelist), scraped-prose fixtures pipeline (examples/texts.yaml + just texts), TTY-capture GIFs via vhs tapes, v0.1 / v0.2 staleness sweep, idea-highlight motif extended to the structure.sentence-too-long rule page. First crates.io publish since v0.1.1 — packaging switched from exclude to an explicit include list so docs/src/rules/*.md reach the tarball (needed by src/explain.rs’s include_str!).

v0.2.2 — ✅ Released 2026-04-23

F87 — FR syntax.nested-negation pair-based counting over ne / n' clitics and second-position particles (pas, rien, jamais, …).

v0.2.x — MoSCoW routing (patch cycle, post-release)

Routed 2026-04-24 from the active-work view. Each row here has a full entry under a topic section below; priority column reflects the routing decision.

Must — 🔴 Next

Should — ships as the next patch absorbs it

Could — nice-to-have

F-excessive-nominalization-suffix-refine (nominalization suffix refine), F43 (RULES.md drift cleanup), F73 (font-leak CI gate), F-docs-final-polish (final polish pass), F-explain-fancy-rendering (fancy explain rendering), F-suppression-disable-file (disable-file), F-text-source-adapters / F-text-before-after-refine / F-texts-yaml-url-maintenance (fixture hygiene), F-mdbook-lint-coexistence (mdbook-lint coexistence guide), F-pre-commit-hook-listing (pre-commit hook listing once --check mode stabilises).

Won’t (pushed to 0.3)

F-score-letter-grade letter grade, F-score-traffic-light traffic light, F-per-family-subscores per-family sub-scores, F-lucid-stance-unify .lucid-stance unify, F-fix-mode --fix mode (narrow).

v0.3 and later (already scoped)

Detail under “New rules (v0.3 candidates)” and the ## v0.4 — horizon section below.

• F22 v0.3 slice — 3–4-word Oxford items, non-Oxford / “plus”-closed lists, interleaved parentheticals (first slice shipped in 0.2.x).
• F-readability-formulas-extra remainder — SMOG, Dale-Chall, Scolarius, --readability-verbose.
• Five condition-tag rules — F46, F49, F51, F53, F57. F46 carries a slip-flag: if FR corpus tuning for homophone density exceeds ~2 days, it slides to 0.3.x.
• Full F29 — demoted to 🟢 Speculative on 2026-04-24. F29-slim already fixed the category-drift problem by construction; numeric codes (STR-001) only earn their cost on a real rename, and there are zero scheduled renames. Revisit when one actually happens.

Architecture

Encoding / input handling

The linter is a UTF-8 → diagnostics function. Encoding conversion is the user’s responsibility, exactly once, before lint-time (iconv or “save as UTF-8”). Invalid UTF-8 fails at the read boundary (std::fs::read_to_string returns an io::Error). Other encodings (Windows-1252, Latin-1, Shift-JIS, …) are explicit non-goals: any in-process transcoder would violate the deterministic-core prime directive (charset detection is heuristic, “same input, same output” no longer holds). The entries below cover the valid-UTF-8 edge cases the test surface should pin.

Rules refinement