Skip to content

ADR-0027: Single Bridge with Enforcement, Not Layered Mechanisms

Status

Field Value
Status Accepted
Supersedes —
Superseded by —
Amends —

Context

The docs build has evolved by addition: each new content shape brought a new bridge mechanism into the gen-files pipeline, and prior mechanisms were kept. The shape recurs across ADR-0006, ADR-0007, and the BK-167 framework landing — each step solved a real problem by introducing one more way to put a repo file on the docs site, and none retired the previous way.

Audit-012 reports the structural result: parallel mechanisms with no rule for which applies, link breakage that the build does not catch, and an exclusion set that no single file describes. The audit is the symptom inventory; this ADR addresses the root cause.

BK-167 wrote the rule (AUTHORING.md Rule 4: exactly one bridge applies) but did not pick or enforce the mechanism, so the rule and the build disagreed.

Decision

One documentation bridge, kept single by an enforcement gate. Three coupled sub-decisions, each stated once:

  • One bridge, by construction. A single source-discovery function and a single render function carry all dual content; other discovery and render helpers are removed, not deprecated. New content shapes extend this one mechanism instead of adding a parallel one. The function names and the removal set are owned by spec 047 (DOCFRAME-001, DOCFRAME-005). Reverse if a content shape genuinely cannot be served by extending the single bridge, forcing a second mechanism.
  • Classification next to the file, not in a manifest. Each .md declares its class via an HTML-comment marker, with a directory-default fallback (per AUTHORING.md Rule 1); a file with no marker and no default is unclassified and fails the gate. The marker cannot drift from the file because it is part of it, unlike a central manifest that lives apart from what it classifies. Marker contract: spec 047 (DOCFRAME-002). Reverse if structured per-page metadata is ever needed that an HTML comment cannot carry (moving to YAML frontmatter, per Alternatives).
  • Enforcement at PR time. A check script fails the build if any framework rule is violated, including the "one bridge" rule itself. This is the half the prior ADRs (0006, 0007, BK-167) left out: without a check that detects the second bridge, "use one bridge" silently degrades to a preference, which is exactly how the accumulation happened. Gate contract: spec 047 (DOCFRAME-004). Reverse if the one-bridge rule itself is retired.

Consequences

  • One discovery function, one render function. Reviewers can read the bridge end to end without crossing layers.
  • Excluded files are auditable from the file itself plus the directory defaults; no central exclusion list is needed or permitted.
  • Contributors learn one marker syntax. The cost is paid once per classified-non-default file.
  • The docs build fails on link breakage, on Jinja in dual files, and on any return of a parallel bridge, in CI rather than in audit.

Alternatives considered

Keep parallel mechanisms, document the rule for which applies. Rejected: this is the state AUTHORING.md Rule 4 already forbids, and it is the state ADR-0006 → ADR-0007 → BK-167 arrived at by accumulation. Repeating it under a new label does not change the dynamic.

Central classification manifest. Rejected: introduces a second source of truth that drifts from the files, and recreates the audit problem the marker resolves.

YAML frontmatter instead of HTML comments. Acceptable on substance; deferred for cost. Frontmatter requires a YAML parser on the gate hot path and a syntax convention on every classified file. The HTML comment is parseable in regex and invisible in every Markdown renderer. If a later need (e.g. structured per-page metadata) justifies frontmatter, this ADR can be superseded.

Move sdd/ under docs-src/design/. Rejected: the recurring pattern is "add a mechanism to fit the path"; moving the path to fit the mechanism is the same pattern with the arrow reversed. The bridge's role is to adapt the build to canonical repo paths. Skills, agents, and ripple-check entries treat sdd/ as canonical.