This feature hub defines the normative contract for **rules pipeline contract** and links newcomer-oriented reference articles.

## Implementation anchors
- `compiler/crates/beskid_analysis/src/analysis/rules/` defines staged rule groups.
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs` classifies emitted diagnostics.
- `compiler/crates/beskid_analysis/src/services/` wires semantic services used by CLI/LSP.

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-SEM-0010` … `D-COMP-SEM-0012`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Rules pipeline contract - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Rules pipeline contract - Design model](./articles/design-model/)
- [Rules pipeline contract - Examples](./articles/examples/)
- [Rules pipeline contract - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Rules pipeline contract - Flow and algorithm](./articles/flow-and-algorithm/)
- [Rules pipeline contract - Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## Context

Sibling articles under this feature previously restated requirements in inconsistent forms.

## Decision

This feature hub **owns** normative MUST/SHOULD contract text. Sibling articles **must not** redefine hub requirements and **should** link here for authority.

## Consequences

Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

## Verification anchors

- `site/website/src/content/docs/platform-spec/compiler/semantic-pipeline/rules-pipeline-contract/index.mdx`
- `article bundle under the same feature directory.`

## Context

Implementation crates accumulated informal notes that diverged from published contracts.

## Decision

Normative platform-spec prose and ADRs under this feature **supersede** informal comments in implementation crates until explicitly migrated into spec text.

## Consequences

Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

## Verification anchors

- `compiler/crates/beskid_analysis/src/analysis/rules/`
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs`
- `compiler/crates/beskid_analysis/src/services/`

## Context

Monolithic semantic passes blocked incremental invalidation.

## Decision

Semantic rules are grouped in `analysis/rules/staged/` with explicit stage boundaries wired through `services.rs` for CLI and LSP.

## Consequences

New rules declare their stage; cross-stage dependencies are documented in the hub articles.

## Verification anchors

- `compiler/crates/beskid_analysis/src/analysis/rules/`.

This article documents **contracts and edge cases** for **rules pipeline contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/analysis/rules/` defines staged rule groups.
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs` classifies emitted diagnostics.
- `compiler/crates/beskid_analysis/src/services/` wires semantic services used by CLI/LSP.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

## Staged pipeline

Semantic rules run as ordered **`SemanticPipelineRule`** stages on the **post-merge** syntax snapshot (`syntax_generation_id`).

```mermaid
flowchart LR
  merge[mod merge + reparse]
  gate[syntax generation gate]
  s1[early binding stages]
  s8[stage8_metaprogramming]
  structural[structural semantic checks]
  hir[HIR normalization]
  merge --> gate --> s1 --> s8 --> structural --> hir
```

## Anchored code paths

- `compiler/crates/beskid_analysis/src/analysis/rules/staged.rs`
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs`
- `compiler/crates/beskid_analysis/src/services/`

## Meta contributions and staged rules

After the mod host merges **emit** contributions into the syntax model and bumps `syntax_generation_id`, the staged semantic pipeline (`SemanticPipelineRule` in `compiler/crates/beskid_analysis/src/analysis/rules/staged.rs`) **must** run on the **post-merge** program snapshot. **`stage8_metaprogramming`** is reserved for meta-specific semantic checks that still belong to ordinary diagnostics (for example validating attributes produced by meta); it **must not** replace the mod host’s collect/generate/analyze/rewrite orchestration.

**Inspector-only meta** that does not emit still runs **before** the semantic diagnostics gate on the same snapshot generation so diagnostics from meta and builtin rules share one ordering pass unless explicitly partitioned by diagnostic phase metadata.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **examples** for **rules pipeline contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/analysis/rules/` defines staged rule groups.
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs` classifies emitted diagnostics.
- `compiler/crates/beskid_analysis/src/services/` wires semantic services used by CLI/LSP.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

This article documents **faq and troubleshooting** for **rules pipeline contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/analysis/rules/` defines staged rule groups.
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs` classifies emitted diagnostics.
- `compiler/crates/beskid_analysis/src/services/` wires semantic services used by CLI/LSP.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.

## Execution order

1. Host finishes **mod collect/generate/merge** and bumps `syntax_generation_id`.
2. **Inspector-only meta** runs (if any) without mutating the merged tree.
3. `SemanticPipelineRule` stages execute in registration order within `staged.rs`.
4. **`stage8_metaprogramming`** validates meta-produced attributes; it does **not** replace mod host orchestration.
5. Diagnostics publish to CLI/LSP snapshot; pipeline continues only if policy allows after error count.
6. HIR normalization, resolution, and **`lower.type_check`** consume the same generation id before codegen lowering (see [Semantic pipeline / Stage ordering](/platform-spec/compiler/semantic-pipeline/stage-ordering/design-model/)).

```mermaid
sequenceDiagram
  participant Host
  participant ModHost
  participant Rules as SemanticPipelineRule
  participant Lower
  Host->>ModHost: collect generate merge
  ModHost-->>Host: syntax_generation_id++
  Host->>Rules: run staged rules
  Rules-->>Host: diagnostics
  Host->>Lower: lower_program on stable snapshot
```

## Anchored code paths

- `compiler/crates/beskid_analysis/src/analysis/rules/`
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs`
- `compiler/crates/beskid_analysis/src/services/`

This article documents **verification and traceability** for **rules pipeline contract** in the reference compiler.

## What this covers
For newcomers, this page explains where the contract shows up in day-to-day compiler work and which code paths are most useful first reads.

## Anchored code paths
- `compiler/crates/beskid_analysis/src/analysis/rules/` defines staged rule groups.
- `compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs` classifies emitted diagnostics.
- `compiler/crates/beskid_analysis/src/services/` wires semantic services used by CLI/LSP.

## Practical notes
- Prefer tracing from CLI/test entry points into analysis/codegen crates before changing internals.
- Treat diagnostics and tests as part of the contract, not optional implementation details.
- If behavior changes, update this article and add/adjust tests in `compiler/crates/beskid_tests` or `compiler/crates/beskid_e2e_tests`.