This repository treats metadata-to-doc synchronization as a first-class quality gate, not a best-effort cleanup task.

The core principle​

Human-written explanation should stay human.

Mechanically derivable data should be generated and tested.

For us, that includes:

• README rules matrix
• presets rules matrix
• rule metadata snapshots and integrity contracts

What this prevents​

Without canonical generation, drift appears quickly:

• rule added to a preset but matrix unchanged
• fix/suggestion capability changes but docs lag
• links and IDs diverge between source and docs

That leads to wrong migration guidance and unnecessary issue churn.

How we enforce it​

• sync scripts produce canonical matrix sections
• CI checks fail when docs and generated sections diverge
• docs integrity tests enforce stable heading/catalog conventions

The result is less manual bookkeeping and fewer review-time surprises.

Practical maintenance advice​

When changing rules or preset composition:

1. update rule source and metadata
2. run matrix sync scripts
3. run docs integrity and snapshot suites
4. only then review prose-level docs edits

This ordering keeps intent and generated truth aligned.

Related docs​

• Rule catalog and docs synchronization chart
• Preset composition and rule matrix chart
• Presets page

The goal is not “run typed rules everywhere immediately.” The goal is predictable behavior under real project conditions.

The contract we want​

A healthy typed-rule setup has three explicit outcomes:

1. Typed path available: semantic checks run with parser services + checker.
2. Optional typed path unavailable: semantic branch is skipped safely.
3. Required typed path unavailable: fail fast with a clear configuration signal.

That split keeps failures actionable and prevents silent drift.

Why guard-first design matters​

In large codebases, parser-service availability is not uniform:

• different tsconfig scopes
• mixed package boundaries
• generated or excluded files

Guard-first execution avoids brittle behavior by making typed entry conditions explicit.

Rollout pattern that works​

• Start in one folder/package.
• Measure with --stats before and after enabling typed checks.
• Promote from warn to error once baseline noise is gone.
• Expand scope only when performance and diagnostics stay stable.

What to track​

• typed-rule error rate tied to config gaps
• lint runtime deltas after enabling typed presets
• rule-level hotspots that call checker APIs most often

If those stay stable, typed linting remains a quality upgrade instead of a workflow tax.

Related docs​

• Typed service path inventory
• Typed rule semantic analysis flow
• Type-aware linting readiness guide