go/docs/docs-format.md

# Docs format

This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense.

The ADR body uses the [MADR 4](https://adr.github.io/madr/) layout; `Consequences` is mandatory. The frontmatter, naming and cross-reference rules are specific to this format.

## 1. Files and directories

- ADRs live in `docs/adr/`, plans in `docs/plans/`, relative to the repository root. Both are flat: subdirectories are not scanned and are errors.
- A missing directory is treated as empty. `docs/adr` and `docs/plans` MUST be real directories: a symlink in their place is an error, and neither may resolve outside the repository through a symlinked parent such as `docs`.
- Entries whose name starts with `.` (such as `.DS_Store` or editor swap files) are ignored. `README.md` in either directory is skipped. Every other entry MUST be a regular file whose name matches section 2 and ends in `.md`. Any other file, directory or name is an error. There are no other exceptions: no templates and no companion files; every `.md` file is a record.
- Files are UTF-8 without a byte order mark. LF and CRLF line endings are both accepted.

## 2. Names and IDs

A record file is named `YYYYMMDDTHHMMSSmmmZ-slug.md`, for example `20261023T204512345Z-use-example-queue.md`.

- The timestamp is UTC to the millisecond and MUST be a real date and time.
- The slug is lowercase `a-z0-9` words joined by single hyphens: no leading, trailing or doubled hyphen, 1 to 80 characters.
- The filename without `.md` (the stem) is the record's permanent ID. Never rename a record, even to fix its slug; change the title instead.
- IDs MUST be unique across `docs/adr` and `docs/plans` (compared by the timestamp-and-slug stem).
- Tools create `docs/<type>/<stem>.md` exclusively (`O_EXCL`) and advance the timestamp by 1 ms on `EEXIST`, or while any record in either directory has the same stem. This is tool behavior and does not affect validity.

## 3. Frontmatter

Every record starts with a YAML frontmatter block: the first line is exactly `---`, and the block ends at the next line that is exactly `---`. The block MUST be a mapping containing exactly the keys listed for the record type, no more, no fewer, each once. Key order is free. Empty lists are written `[]`. A key with no value (null) is an error.

A plain `~`, `null`, `Null` or `NULL` is null, the same as an empty value, and is an error. Every other scalar is a string with no type resolution: its parsed text, whether quoted or not. For example, `date` may be quoted or unquoted, `title: 2026` is the string `2026`, and `title: "null"` is the string `null`. A block scalar (`|`, `>`) is its parsed text. Anchors, aliases, explicit tags and multiple YAML documents are errors. "Single line" means the parsed value contains no line break.

### 3.1 ADR keys

| Key | Type | Rule |
| --- | --- | --- |
| `title` | string | Non-empty, single line. |
| `date` | `YYYY-MM-DD` | Valid date. Equals the date in the filename (UTC). |
| `status` | enum | `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`. |
| `implementation` | enum | `not-started`, `in-progress`, `implemented`, `deferred`, `not-applicable`. |
| `summary` | string | Non-empty, single line. |
| `tags` | list of strings | Non-empty list. Each tag is lowercase `a-z0-9` words joined by single hyphens; no duplicates. |
| `supersedes` | list of references | May be empty. |
| `superseded_by` | list of references | May be empty. |
| `related` | list of references | May be empty. |
| `tracking` | list of references | May be empty. |
| `implemented_by` | list of references | May be empty. |

### 3.2 Plan keys

| Key | Type | Rule |
| --- | --- | --- |
| `status` | enum | `draft`, `active`, `completed`, `cancelled`. |
| `tracking` | list of references | May be empty unless `active`. |
| `adrs` | list of references | May be empty. |
| `completion` | list of references | May be empty unless `completed` or `cancelled`. |

A plan has no `title` key; its title is its H1.

### 3.3 References in frontmatter

Every list item is a string. No list may contain duplicates. Which kinds of reference each key accepts:

| Key | Accepts |
| --- | --- |
| `supersedes`, `superseded_by`, plan `adrs` | Repo-root paths to ADRs (`/docs/adr/<id>.md`). |
| `related` | Repo-root paths to any record (`/docs/adr/...` or `/docs/plans/...`). |
| ADR `tracking` | `http` or `https` URLs, or repo-root paths to plans (`/docs/plans/<id>.md`). |
| Plan `tracking` | `http` or `https` URLs. |
| `implemented_by`, `completion` | `http` or `https` URLs (pull request, commit, release), or repo-root paths to existing files. |

See section 7 for what a valid path or URL is. A record MUST NOT reference itself. An ADR whose delivery is tracked by a plan lists the plan in `tracking`; other record-to-record links go in `related`.

Reference lists MUST be durable: an item that is a bare issue number such as `#123` or `owner/repo#123`, or one of the placeholders "this PR", "this pull request" or "this commit" (any case), is rejected. Use a full URL. This applies to whole list items in frontmatter reference lists only; `title`, `summary` and body text are not inspected for it.

## 4. Status

`status` is the decision; `implementation` is delivery of that decision. They are independent except where stated.

ADR `status`:

- `proposed`: under discussion; not binding.
- `accepted`: the decision stands. Accepting is the owner's act.
- `rejected`: considered and declined. Requires `implementation: not-applicable`.
- `deprecated`: once accepted, no longer recommended, with no replacement.
- `superseded`: replaced by another ADR. Requires non-empty `superseded_by`.

ADR `implementation`:

- `not-started`, `in-progress`, `deferred`: delivery state.
- `implemented`: requires non-empty `implemented_by`.
- `not-applicable`: nothing to deliver (required for `rejected`; allowed for any other status).

Per-status requirements, summarized:

| Condition | Requirement |
| --- | --- |
| `status: superseded` | `superseded_by` non-empty. |
| `superseded_by` non-empty | `status: superseded`. |
| `status: rejected` | `implementation: not-applicable`. |
| `implementation: implemented` | `implemented_by` non-empty. |

Plan `status`:

| Status | Meaning | `tracking` | `completion` |
| --- | --- | --- | --- |
| `draft` | Being written. | any | MUST be empty |
| `active` | Work under way. | MUST be non-empty | MUST be empty |
| `completed` | All steps done. | any | MUST be non-empty |
| `cancelled` | Abandoned. | any | MUST be non-empty |

## 5. Supersession

- If ADR A lists B in `supersedes`, then B MUST list A in `superseded_by`, and the reverse. Both records exist and are ADRs.
- Supersession MUST NOT form a cycle.
- The superseding record (A, the one whose `supersedes` lists the other) MUST have status `accepted`, or `superseded` or `deprecated` (it was accepted once and has since moved on). It MUST NOT be `proposed` or `rejected`.
- While a replacement is `proposed`, list the ADR it would replace in `related`. On acceptance, in the same change, move it to `supersedes` and set the target's `status: superseded` and `superseded_by`.
- A superseded record keeps its original `date` and filename; only its `status` and `superseded_by` change.

## 6. Body

The body is Markdown (CommonMark) after the frontmatter. Headings inside fenced code blocks or HTML comments do not count. Only headings at the top level of the document count. Required section headings are matched case-sensitively and exactly, at level 2 (`##`). A section runs until the next heading of level 1 or 2, so its subsections belong to it. A required section MUST appear exactly once and contain non-empty prose: at least one paragraph (including paragraphs inside blockquotes), list item or table cell of text. HTML comments and code (fenced, indented or inline) do not count as prose. Extra sections are allowed anywhere.

Heading text is the raw source after the `#` markers, trimmed, with any closing `#` run removed; it is compared byte for byte, with no inline-markup rendering. Setext headings are read as the equivalent ATX heading.

### 6.1 ADR

- The first heading is an H1 whose heading text equals `title`. There is one H1.
- Required H2 sections: `Context and Problem Statement`, `Considered Options`, `Decision Outcome`.
- `Decision Outcome` MUST contain exactly one `### Consequences` (H3) subsection with non-empty prose, and at least one prose block before its first H3 subsection. A level-2 `## Consequences` is an error.
- Optional MADR sections (for example `Decision Drivers`, `Pros and Cons of the Options`, `More Information`) MAY be added.

### 6.2 Plan

- The first heading is a non-empty H1: the plan title. There is one H1.
- Required H2 sections: `Scope`, `Steps`, `Validation`.
- `## Outcome` is optional for every status. Closed plans still require `completion` (section 4).

### 6.3 Placeholders

A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code.

## 7. References and links

A reference is either a repo-root path or a URL. This applies to frontmatter reference lists and to every Markdown link and image destination in the body (inline, reference-style and autolinks; bare URLs in text are not checked). In the body, link rules apply only to Markdown link destinations: forge autolink shortcuts in plain text (`#123`, `owner/repo#123`, `@user`, commit SHAs) and raw HTML (`<a href>`, `<img src>`) are not inspected. Every link reference definition is checked, whether or not it is used.

Repo-root path:

- Starts with a single `/` and is relative to the repository root, for example `/docs/adr/20261023T204512345Z-use-example-queue.md`. A leading `//` (protocol-relative `//host/...`) is rejected.
- Repo-root links render correctly on Git forges (GitHub, Gitea) but not in every Markdown viewer.
- The destination is percent-decoded before the existence check (`%20` is a space). A `?query` is an error.
- The target MUST exist as a regular file inside the repository, and the path MUST match the target's case exactly, component by component, even on case-insensitive filesystems. Symlinks that resolve outside the repository are rejected.
- In body links only, a `#fragment` suffix is allowed; the fragment is not verified. In frontmatter, a fragment is an error.
- Rejected: relative paths (`foo.md`, `./foo.md`), any `..` segment and backslashes. Other non-existent targets, including machine paths such as `/Users/...` or `/home/...`, fail the existence rule; `file:` URLs fail the scheme rule.

URL:

- Scheme `http` or `https` with a host, for example `https://example.com/org/repo/pull/42`. Credentials in the URL (`user:pass@`) are rejected. URLs are not fetched.

Always allowed in body prose only: in-page anchors (`#section`) and `mailto:` links. Any other scheme is rejected.

## 8. What `docs check` reports

`docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem:

```
path:line: message
```

`path` is relative to the root using `/` separators. `line` is the best location of the problem (the key, heading or link), or `1` for file-level problems. Output is sorted by path, then line, then message. The exit status is `1` if any problem is reported, `2` for usage errors, and `0` otherwise, in which case a one-line summary of the records checked is printed.

It reports violations of everything above:

- unexpected files, directories or names; bad timestamps or slugs; duplicate IDs;
- missing, malformed or unterminated frontmatter; unknown, missing, duplicate or null keys; wrong types or values; `date` not matching the filename;
- status/implementation/field combinations from section 4;
- supersession problems from section 5, and self-references;
- missing, repeated or empty required sections; H1 problems; `{{docs:todo}}` markers;
- invalid, unresolvable or non-durable references and links.

It does not judge whether a decision is good, whether a record should have been written, or whether a link's fragment exists.

## 9. Minimal valid examples

`docs/adr/20261023T204512345Z-use-example-queue.md`:

```markdown
---
title: Use Example Queue for background jobs
date: 2026-10-23
status: proposed
implementation: not-started
summary: Run background jobs on Example Queue.
tags:
  - jobs
supersedes: []
superseded_by: []
related: []
tracking: []
implemented_by: []
---

# Use Example Queue for background jobs

## Context and Problem Statement

Jobs currently run inline and block requests.

## Considered Options

* Example Queue
* Keep running jobs inline

## Decision Outcome

Chosen option: Example Queue, because it decouples jobs from requests.

### Consequences

* We operate one more service.
```

`docs/plans/20261023T210000000Z-adopt-example-queue.md`:

```markdown
---
status: draft
tracking: []
adrs:
  - /docs/adr/20261023T204512345Z-use-example-queue.md
completion: []
---

# Adopt Example Queue

## Scope

Move the email job to Example Queue.

## Steps

1. Add the queue client.
2. Move the email job.

## Validation

The email job runs from the queue in staging.
```