import-boundary-enforcement

name	import-boundary-enforcement
description	Make the architecture's layering machine-enforced so it can't silently erode. Use when a monorepo has a layered/acyclic package graph but nothing prevents back-edges or deep-internal imports, when many agents or contributors edit concurrently, or right after giving a package a curated public API. Use to add a lint rule that bans deep dist/internal imports and forbidden cross-package edges.
hints	- Encode the real layer DAG (leaves → core → adapters → apps) as the allowed edges; everything else is denied. - Ban deep compiled-internal imports (e.g. `@pkg/dist/*`) and app→app + lower→higher back-edges explicitly. - Introduce rules in `warn` first (or changed-files-only) to avoid a flag day on a large existing tree, then ratchet to `error`. - The rule is worthless unless CI fails on violation AND a pre-commit hook catches it early — wire both. - Pair with `micro-repo-extraction`: the boundary lint lands together with the curated exports map, not before.

Import-Boundary Enforcement

Overview

A clean layered architecture decays the moment it is only a convention. With many agents and contributors editing in parallel, a single core → app back-edge or a deep dist/* import slips in and nothing fails until a human notices weeks later. This skill turns the layering into a lint rule that fails CI, so the boundary defends itself.

When to Use

• The package graph is layered and acyclic by intention but unenforced
• You just gave a package a curated public API and want to stop callers reaching past it
• Concurrent agents/contributors keep eroding the architecture
• You need build order + boundaries to hold at fleet/automation scale

When NOT to use: a tiny single-package project with no layering to protect; or before the public API exists (you'd be banning the only imports that work).

Workflow

1. Write down the allowed edge set. From the dependency audit, list every legitimate package→package edge (the DAG). Everything not listed is denied.
2. Choose the tool. eslint-plugin-import (no-restricted-paths) + eslint-plugin-boundaries, or dependency-cruiser for a standalone graph rule. Prefer whatever already runs in CI.
3. Encode three bans: (a) deep compiled-internal imports (@pkg/dist/* and any private subpath), (b) back-edges (lower layer importing a higher one; an app importing another app), (c) cycles.
4. Roll out in warn first (or scoped to changed files) to avoid a remediation wave on a large tree; fix violations; then promote to error.
5. Gate it: make the lint a required CI check and add it to the pre-commit hook so violations are caught before push.

Patterns

• Allowlist, not denylist: enumerate permitted edges; deny the rest. New packages must be explicitly allowed — friction in the right place.
• Warn-then-error ratchet: never drop a hard rule on thousands of files at once; warn, clean, ratchet.
• Two gates: pre-commit for fast feedback, CI for the hard wall. One without the other leaks.
• Co-land with the API: the ban on deep imports is only safe once the curated entrypoints exist for callers to use instead.

Common Rationalizations

Excuse	Reality
"Everyone knows the layering, we don't need a rule."	Conventions aren't enforced; the next concurrent edit breaks them silently.
"We'll turn it on as error right away."	A flag day red-lights every open PR. Warn first, then ratchet.
"The lint is enough; CI doesn't need it."	A local-only rule is advisory. If CI is green on a violation, the boundary is fiction.
"Deep imports are fine, they work."	They couple callers to compiled layout and freeze the internals — the exact rot you're fixing.

Red Flags

• The rule exists but isn't a required status check.
• It was added as error and now every PR is red — you skipped the ratchet.
• The allowed-edge list drifts from the real graph (new package added, rule not updated).
• Pre-commit passes but CI has no boundary check (or vice-versa).

Verification

• Add a deliberately-bad import (a back-edge and a deep dist/*) on a scratch branch → lint and CI fail with a clear message.
• Remove it → green.
• A new legitimate package without an allowlist entry fails until added — confirms it's an allowlist.
• Pre-commit blocks the bad import locally before it can be pushed.