DocBoring v0.14.2
SPECIFICATION v2.1

Authoring & Validation Specification

This specification defines the canonical directory layout, mandatory YAML frontmatter fields, and static lint checks enforced by the DocBoring compiler.

Repository Directory Layout

Documents must reside under the configured input.root directory using lowercase kebab-case filenames prefixed by a four-digit monotonic identifier for ADRs and RFCs:

engineering-docs/
├── docboring.yaml
└── docs/
    ├── index.md
    ├── adr/
    │   ├── 0001-deterministic-storage-layout.md
    │   └── 0002-idempotent-webhook-retries.md
    └── rfc/
        ├── 0014-grpc-deadline-propagation.md
        └── 0015-read-replica-routing.md

Frontmatter Schema

Every Markdown source file must begin with a delimited YAML frontmatter block containing the fields below. Unknown top-level keys emit warning DB004 unless declared under custom.

Field Type Required Description
id String (^[A-Z]+-[0-9]{4}$) Yes Globally unique document identifier such as ADR-0001 or RFC-0014.
title String (≤ 120 chars) Yes Concise technical title rendered in the HTML document header and index table.
status Enum Yes Must match an entry in validation.allowed_statuses.
owners List<String> Yes At least one GitHub handle or team alias responsible for technical accuracy.
updated ISO-8601 Date Yes Last verified review date (YYYY-MM-DD) checked against max_stale_days.
supersedes List<String> No References prior document IDs marked as deprecated by this decision.

Lifecycle State Machine

When status transitions to superseded or deprecated, the validator verifies that at least one active document references the deprecated ID in its supersedes array, preventing orphaned architectural dead ends.

---
id: ADR-0002
title: Idempotent Webhook Retry Policy
status: accepted
owners:
  - "@platform-core"
updated: 2026-09-18
supersedes: []
---

## Context
Downstream payment processors deliver webhooks with at-least-once semantics...

Lint Rule Codes

Code Severity Condition
DB001 Error Missing or syntactically invalid YAML frontmatter block.
DB002 Error Duplicate id detected across two Markdown documents.
DB003 Error Broken relative link or missing heading fragment anchor (#section).
DB005 Warning Document updated timestamp exceeds configured staleness threshold.
DB008 Error Raw inline HTML <script> tag forbidden in zero-JS output mode.