This feature hub defines the normative contract for **dependency graph and cycle policy** and links newcomer-oriented reference articles.

## Implementation anchors
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs` models multi-project dependency layouts.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` checks graph expectations.
- `compiler/crates/beskid_cli/src/commands/doc.rs` consumes resolved dependency context for docs.

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-COMP-PROJ-0001` … `D-COMP-PROJ-0003`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Dependency graph and cycle policy - Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Dependency graph and cycle policy - Design model](./articles/design-model/)
- [Dependency graph and cycle policy - Examples](./articles/examples/)
- [Dependency graph and cycle policy - FAQ and troubleshooting](./articles/faq-and-troubleshooting/)
- [Dependency graph and cycle policy - Flow and algorithm](./articles/flow-and-algorithm/)
- [Dependency graph and cycle policy - 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/resolution-and-projects/dependency-graph-and-cycle-policy/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_tests/src/projects/corelib/layout.rs`
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs`
- `compiler/crates/beskid_cli/src/commands/doc.rs`

## Context

Silent cycle handling broke workspace diagnostics parity.

## Decision

Directed cycles **must** be reported during graph build; `Mod` cycles **must** include mod id in the diagnostic path.

## Consequences

Policy knobs (`error`, `warn`, permissive) select abort vs continue; default remains fail-closed for release builds.

## Verification anchors

- `beskid_analysis::projects::graph`
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs`.

This article documents **contracts and edge cases** for **dependency graph and cycle policy** 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_tests/src/projects/corelib/layout.rs` models multi-project dependency layouts.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` checks graph expectations.
- `compiler/crates/beskid_cli/src/commands/doc.rs` consumes resolved dependency context for docs.

## 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`.

## Graph model

Each workspace node is a **`Project.proj`** with typed edges:

| Edge kind | Meaning |
| --- | --- |
| Registry dependency | Resolved version pin from lockfile |
| Path dependency | Relative project root inside workspace |
| Transitive closure | Used for `CompilePlan` and doc workspace scan |

```mermaid
flowchart LR
  app[App project]
  lib[Lib dependency]
  modp[Mod project]
  core[corelib package]
  app --> lib
  app --> core
  modp --> lib
```

## Cycle policy

Directed cycles **must** be reported during graph build. Policy knobs (`error`, `warn`, permissive) select whether resolution aborts or continues with diagnostics. Cycles involving **`Mod`** projects **must** include the mod id in the diagnostic path.

## Mermaid presentation

User-visible dependency graphs **must** be emitted through `beskid_graph::adapters::project` from the built `ProjectGraph`. The analysis resolver remains the build authority; Mermaid is presentation-only.

## Anchored code paths

- `beskid_analysis::projects::graph` resolver and validator
- `beskid_graph::adapters::project` — canonical Mermaid emitter
- `compiler/crates/beskid_tests/src/projects/corelib/layout.rs` — multi-project layouts
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` — graph expectations
- `compiler/crates/beskid_cli/src/commands/doc.rs` — docs consume resolved graph

This article documents **examples** for **dependency graph and cycle policy** 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_tests/src/projects/corelib/layout.rs` models multi-project dependency layouts.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` checks graph expectations.
- `compiler/crates/beskid_cli/src/commands/doc.rs` consumes resolved dependency context for docs.

## 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 **dependency graph and cycle policy** 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_tests/src/projects/corelib/layout.rs` models multi-project dependency layouts.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` checks graph expectations.
- `compiler/crates/beskid_cli/src/commands/doc.rs` consumes resolved dependency context for docs.

## 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`.

## Build algorithm

```mermaid
flowchart TD
  nodes[Collect manifest nodes]
  edges[Expand dependency edges]
  topo[Topological sort attempt]
  cycle{Cycle detected?}
  diag[Emit cycle diagnostic]
  ok[Freeze ResolvedGraph]
  nodes --> edges --> topo --> cycle
  cycle -->|yes| diag
  cycle -->|no| ok
```

1. Parse each member `Project.proj` and register a graph node (package id + project type).
2. Add edges for registry and path dependencies; normalize path roots against workspace policy.
3. Run cycle detection on the directed graph; apply configured severity.
4. Expose `ResolvedGraph` to `build_compile_plan_with_policy` and doc workspace scan.
5. **`Mod`** nodes trigger additional capability validation before the graph is considered sound.

## Anchored code paths

- `beskid_analysis::projects::graph::resolver`
- `compiler/crates/beskid_tests/src/projects/corelib/`
- `compiler/crates/beskid_cli/src/commands/doc.rs`

This article documents **verification and traceability** for **dependency graph and cycle policy** 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_tests/src/projects/corelib/layout.rs` models multi-project dependency layouts.
- `compiler/crates/beskid_tests/src/projects/corelib/mod.rs` checks graph expectations.
- `compiler/crates/beskid_cli/src/commands/doc.rs` consumes resolved dependency context for docs.

## 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`.