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

F22 context. The v0.1 rule is a flat comma-per-sentence threshold. In technical docs that routinely enumerate short items, this fires often even when the sentence is perfectly scannable. Candidate relaxations to evaluate (needs corpus research — don’t pick blindly):

• Discount commas inside parenthesis-like elements ((...), [...], en/em-dash pairs). A parenthetical enumeration is already visually bracketed; its commas are not adding subordination load.
• Discount commas after a colon : when what follows is a list of short items. Colon + short items is idiomatic prose-enumeration and reads well.
• Short-item enumeration exemption: if all comma-separated segments are 1–2 words, treat the enumeration as a single “flattened list” token for counting purposes (a max_short_enum_items parameter, or implicit).
• Interaction with structure.long-enumeration: the shared enumeration::detect_enumerations helper already discounts Oxford- style enumeration commas from structure.excessive-commas (3+ short items). F22 is specifically about the cases that helper still misses: parentheticals, post-colon lists, and non-Oxford enumerations (“A, B, C and D” without the final comma).

Research inputs to gather before deciding: FR/EN corpus samples of technical docs, a handful of real false positives from dogfooding and downstream projects, how textlint / Vale / write-good handle parentheticals. Decide between relaxation parameters vs. a smarter token-aware counter.

Performance / hygiene (0.2.x)

Findings filed from the 2026-04-24 code-review stream-2 pass on src/. Each has a concrete source reference so it survives past the .personal/<date>-today.md scratchpad.

New rules (v0.2)

New rule candidates raised in the rule-system-growth brainstorm (2026-04-20). Naming uses a provisional category.rule-name prefix pending F29 harmonisation. Grounding column points at the standard or research that justifies the rule.

Must-ship v0.2 (blocking release):

Should-ship v0.2 (cuttable under time pressure, in suggested cut order):

Cut order if schedule slips: F47 → F54 → F62 → F52 → F50 → F11. F55 and F56 are non-negotiable (trivial implementation cost, strong grounding).

Format support

Example-text fixtures

Scraper + cleaner + converter triplet under scripts/texts_*.py populates examples/public/ (committable public_ok sources) from examples/texts.yaml. First batch landed 21 fixtures. The follow-ups below close the remaining rough edges.

Documentation rules plugin

Docs.rs / API reference polish

Polish items for the auto-generated rustdoc surface at https://docs.rs/lucid-lint. The crate-level banner pointing readers to the mdBook + repo + RULES.md was added 2026-05-01 (src/lib.rs); module-level //! headers are already in place and #![warn(missing_docs)] is satisfied. Items below are deferred extras.

Docs site — bilingual

Docs site — content

Docs site — theming

Docs site — reading preferences

Quality features

Scope control

File/directory discovery. Distinct from suppression (below): scope control excludes inputs before they are scanned; suppression hides diagnostics after scanning.

Suppression mechanism

v0.1 ships the minimal inline-disable directive (see brainstorm brainstorm/20260419-inline-disable-feature.md). Extensions deferred:

Reporting / DX

TTY-output decoration on the lucid-lint check summary surface. Distinct from the rule engine (no diagnostic semantics change), from suppression (which hides diagnostics), and from scoring (which weights them) — this section covers what the user reads after the diagnostic list. JSON / SARIF stay structural until a second consumer asks.

v0.1 — Released 2026-04-20

Shipped in the tag: all 17 rules across 5 phases, the minimal inline-disable directive, and the mdBook documentation site (Lucid light / Lucid dark themes, Atkinson Hyperlegible Next / Literata / Commit Mono / OpenDyslexic typography layer, reading-preferences demonstrator, accessibility page, EN/FR header switch with v0.2 FR-stub). See CHANGELOG.md for the full release notes.

Rules (17 / 17) ✅

Phase 1 — Deterministic structural rules

Phase 2 — Simple text rules

Phase 3 — Lexical rules with word lists

Phase 4 — Global metric

Phase 5 — Heuristic rules (hardest)

Cross-cutting features

Design decisions from v0.1 session

Diagnostic structure

Decided: v0.1 diagnostics carry only what cannot be trivially recomputed.

#![allow(unused)]
fn main() {
pub struct Diagnostic {
    pub rule_id: String,
    pub severity: Severity,
    pub location: Location,
    pub section: Option<String>,  // H2 (or configured level) containing the diagnostic
    pub message: String,
}
}

Kept : section is stored at emission. Recomputing it a posteriori would require re-parsing the Markdown to walk headings and match locations. Expensive. Storing it is cheap.

Omitted : category is a pure function of rule_id. A category_of(rule_id) -> Category utility derives it in O(1). No duplication in diagnostics.

Omitted : weight and suggestion are not used in v0.1 and will be introduced when the hybrid scoring model (F14) lands.

This aligns with the “open to change, not abstracted for change” principle applied earlier to format handling: struct fields can be added later without breaking JSON serialization compatibility.

Points deferred from v0.1 session

A number of configuration and ergonomics questions were raised but postponed. They will be addressed before or during v0.2:

Configuration

• Config file format decision: TOML (recommended), YAML, or JSON
• Config filename convention
• Profile name finalization (dev-doc, public, falc confirmed)
• Naming convention for rules (kebab-case confirmed, flat vs. hierarchical namespace)
• Rule codes (short codes like LL001 vs. name-only)
• Suppression mechanism (# lucid-lint disable-next, block disable/enable, ignore file)

Output

• TTY format (colors, snippets, condensed report)
• Structured format: JSON schema, SARIF exactness, native format
• Exit code granularity (0/1 vs. graduated)

Architecture

• Language detection: simple heuristic (stop-words) vs. dedicated crate (whatlang)
• Parallelism: rayon for multi-file processing
• Glob patterns and .lucidignore (now tracked as F78)
• Core library exposed as lucid-lint-core for third-party integration

Project

• Repo structure: single crate vs. Cargo workspace
• Reference corpus for testing
• README v0.1 content and positioning
• Tagline and visual identity

Contribution invitation

Future rules and plugins can be proposed by the community. The default jargon and stoplists (lexicon.jargon-undefined, lexicon.weasel-words, lexicon.low-lexical-diversity) are especially welcome targets for community pull requests to expand coverage across domains and languages.