REF-004 Zone dependencies

Overview

Validates that Markdown links crossing zone boundaries (subdirectories under zonesDir) are explicitly declared in the dependency section of the source zone’s overview.md. Cross-zone references that are not declared are reported as error.

Why it matters

When documentation is organized into zones (responsibility-scoped directories) such as auth/, payment/, and notification/, dependencies between zones grow over time as implicit links. Even when the design says “auth does not depend on payment”, links can be authored freely and will accumulate undetected. This rule enforces “every cross-zone dependency must be declared in overview.md’s dependency section”, keeping the documentation structure aligned with the design intent.

Options

Field	Type	Required	Description
zonesDir	string	Yes	Path to the directory containing zones
dependencySection	string	—	Heading of the section that declares dependencies (default: Dependencies)

Each subdirectory directly under zonesDir is treated as one zone. Each zone is expected to contain an overview.md with the heading specified by dependencySection, and a table under that heading listing the names of the dependent zones.

Bad example

docs/zones/auth/overview.md:
# Auth zone

## Dependencies

| Zone |
| ---- |

docs/zones/auth/login.md:
See [billing logic](../payment/charge.md) for details.

auth/login.md links to the payment zone, but payment is not declared in the Dependencies section of auth/overview.md, which triggers a violation.

docs/zones/auth/login.md
  line 1  error  Cross-zone reference to "payment" zone, but "payment" is not listed in the "Dependencies" section of auth/overview.md  REF-004

After fix

Declare the dependency explicitly in overview.md.

docs/zones/auth/overview.md:
# Auth zone

## Dependencies

| Zone    |
| ------- |
| payment |

If the dependency was unintended, remove the link or rethink the source zone.

Configuration example

{
  "rule": "ref004",
  "options": {
    "zonesDir": "docs/zones",
    "dependencySection": "Dependencies"
  }
}

Related rules

• REF-001 Broken links — Validates that linked files exist
• GRP-001 Traceability chain — Validates the dependency graph between IDs
• GRP-002 Circular references — Detects circular dependencies between documents