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