Reformat roadmap

.gitignore

@@ -2,3 +2,4 @@ target/
 **/*.rs.bk
 Cargo.lock
 .crush/
+.grepai/

docs/documentation-style-guide.md

@@ -1,33 +1,35 @@
 # Documentation style guide
 
-This guide outlines conventions for authoring documentation for Concordat.
-Apply these rules to keep the documentation clear and consistent for developers.
+This guide outlines conventions for authoring documentation for software by
+df12 Productions. Apply these rules to keep the documentation clear and
+consistent for developers.
 
 ## Spelling
 
 - Use British English based on the
-  [Oxford English Dictionary](https://public.oed.com/) locale `en-GB`, which
-  denotes English for the Great Britain market:
+  [Oxford English Dictionary](https://public.oed.com/) (en-GB-oxendict):
   - suffix -ize in words like _realize_ and _organization_ instead of
      -ise endings,
   - suffix ‑lyse in words not traced to the Greek ‑izo, ‑izein suffixes,
      such as _analyse_, _paralyse_ and _catalyse_,
   - suffix -our in words such as _colour_, _behaviour_ and _neighbour_,
   - suffix -re in words such as _calibre_, _centre_ and _fibre_,
-  - double "l" in words such as _cancelled_, _counsellor_ and _cruellest_,
-  - maintain the "e" in words such as _likeable_, _liveable_ and _rateable_,
+  - double “l” in words such as _cancelled_, _counsellor_ and _cruellest_,
+  - maintain the “e” in words such as _likeable_, _liveable_ and _rateable_,
   - suffix -ogue in words such as _analogue_ and _catalogue_,
   - and so forth.
-- The word **"outwith"** is acceptable.
-- Keep United States (US) spelling when used in an API, for example, `color`.
-- The project uses the filename `LICENSE` for community consistency.
+- The words **“outwith”** and **“caveat”** are acceptable.
+- Keep United States (US) spelling when used in an external API, command, or
+  library, for example, `color`.
+- The name of the project licence file is spelled `LICENSE` for community
+  consistency.
 
 ## Punctuation and grammar
 
-- Use the Oxford comma: "ships, planes, and hovercraft" where it aids
+- Use the Oxford comma: “ships, planes, and hovercraft” where it aids
   comprehension.
-- Company names are treated as collective nouns: "Concordat Industries are
-  expanding".
+- Company names are treated as collective nouns: “df12 Productions are
+  expanding”.
 - Avoid first and second person personal pronouns outside the `README.md`
   file.
 
@@ -39,7 +41,8 @@ Apply these rules to keep the documentation clear and consistent for developers.
 
 ## Markdown rules
 
-- Follow [markdownlint](https://github.com/DavidAnson/markdownlint)
+- Follow
+  [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)
   recommendations[^1].
 - Provide code blocks and lists using standard Markdown syntax.
 - Always provide a language identifier for fenced code blocks; use `plaintext`
@@ -83,8 +86,9 @@ contents of the manual.
   argument.
 - Document the return value with `# Returns`.
 - Document any panics or errors with `# Panics` or `# Errors` as appropriate.
-- Place examples under `# Examples` and mark the code block with `no_run`, so
-  they do not execute during documentation tests.
+- Place examples under `# Examples` for public functions.
+- Use examples for private functions only where they assist in understanding
+  the purpose of the function, and mark these as `ignore`.
 - Put function attributes after the doc comment.
 
 ```rust,no_run
@@ -161,6 +165,158 @@ navigability:
 - Tasks (execution units) – Small, measurable pieces of work with clear
   acceptance criteria. How it gets done.
 
+### Roadmap formatting conventions
+
+- **Dotted numbering:** Number phases, steps, and headline tasks using dotted
+  notation:
+  - Phases: 1, 2, 3, …
+  - Steps: 1.1, 1.2, 1.3, …
+  - Headline tasks: 1.1.1, 1.1.2, 1.1.3, …
+- **Checkboxes:** Precede task and sub-task items with a GitHub Flavored
+  Markdown (GFM) checkbox (`[ ]`) to track completion status.
+- **Dependencies:** Note non-linear dependencies explicitly. Where a task
+  depends on another task outside its immediate sequence, cite the dependency
+  using dotted notation (e.g. “Requires 2.3.1”).
+- **Success criteria:** Include explicit success criteria only where not
+  immediately obvious from the task description.
+- **Design document citations:** Where applicable, cite the relevant design
+  document section for each task (e.g. “See design-doc.md §3.2”).
+
+### Roadmap example
+
+```markdown
+## 1. Core infrastructure
+
+### 1.1. Logging subsystem
+
+- [ ] 1.1.1. Introduce central logging service
+  - [ ] Define log message schema. See design-doc.md §2.1.
+  - [ ] Implement log collector daemon.
+  - [ ] Add structured logging to API layer.
+- [ ] 1.1.2. Add error dashboards. Requires 1.1.1.
+  - [ ] Deploy Grafana instance.
+  - [ ] Create error rate dashboard (target: <1% error rate visible within 5 min).
+
+### 1.2. Authentication
+
+- [ ] 1.2.1. Implement role-based access control (RBAC). Requires 1.1.1.
+  - [ ] Define role hierarchy. See design-doc.md §4.3.
+  - [ ] Add RBAC middleware to API endpoints.
+  - [ ] Write integration tests for permission boundaries.
+```
+
+## Architectural decision records (ADRs)
+
+Use ADRs to document significant architectural and design decisions. ADRs
+capture the context, options considered, and rationale behind decisions,
+providing a historical record for future maintainers.
+
+### Naming convention
+
+Name ADR files using the pattern `adr-NNN-short-description.md`, where `NNN` is
+a zero-padded sequence number (e.g. `adr-001-async-fixtures-and-tests.md`).
+Place ADRs in the `docs/` directory.
+
+### Required sections
+
+Every ADR must include the following sections in order:
+
+- **Status:** One of `Proposed`, `Accepted`, `Superseded`, or `Deprecated`. For
+  `Accepted` status, include the date and a brief summary of what was decided.
+- **Date:** The date the ADR was created or last updated (format: YYYY-MM-DD).
+- **Context and Problem Statement:** Describe the situation, constraints, and
+  the problem or question that prompted the decision. Include enough background
+  for readers unfamiliar with the history.
+
+### Conditional sections
+
+Include these sections as appropriate to the decision's complexity:
+
+- **Decision Drivers:** Key factors, requirements, or constraints that
+  influenced the decision. Use bullet points.
+- **Requirements:** For complex decisions, separate functional and technical
+  requirements into subsections.
+- **Options Considered:** Describe the alternatives evaluated. Use a comparison
+  table when contrasting multiple options across several dimensions.
+- **Decision Outcome / Proposed Direction:** State the chosen approach and
+  summarize the rationale. For `Proposed` ADRs, describe the recommended
+  direction.
+- **Goals and Non-Goals:** Clarify what the decision aims to achieve and what
+  is explicitly out of scope.
+- **Migration Plan:** For decisions requiring phased implementation, break the
+  work into numbered phases with clear goals and deliverables.
+- **Known Risks and Limitations:** Document trade-offs, potential issues, and
+  constraints of the chosen approach.
+- **Outstanding Decisions:** For `Proposed` ADRs, list open questions that must
+  be resolved before acceptance.
+- **Architectural Rationale:** Explain how the decision aligns with broader
+  architectural principles and project goals.
+
+### Formatting guidance
+
+- Use second-level headings (`##`) for major sections.
+- Use third-level headings (`###`) for subsections (e.g. phases, option names).
+- Use tables to compare options when multiple dimensions are relevant. Include
+  a caption below the table (e.g. “_Table 1: Trade-offs between X and Y._”).
+- Include code snippets with language identifiers when illustrating technical
+  approaches. Use `no_run` for illustrative Rust code that should not be
+  executed.
+- Add screen reader descriptions before complex diagrams or code blocks.
+- Reference external sources using inline links or footnotes.
+
+### ADR template
+
+```markdown
+# Architectural decision record (ADR) NNN: <title>
+
+## Status
+
+<Proposed | Accepted | Superseded | Deprecated>.
+
+## Date
+
+YYYY-MM-DD.
+
+## Context and problem statement
+
+<Describe the situation, constraints, and the question being addressed.>
+
+## Decision Drivers
+
+- <Driver 1>
+- <Driver 2>
+
+## Options considered
+
+### Option A: <Name>
+
+<Description, consequences, and trade-offs.>
+
+### Option B: <Name>
+
+<Description, consequences, and trade-offs.>
+
+| Topic     | Option A | Option B |
+| --------- | -------- | -------- |
+| <Factor>  | <Value>  | <Value>  |
+
+_Table 1: Comparison of options._
+
+## Decision outcome / proposed direction
+
+<State the chosen or recommended approach and summarize the rationale.>
+
+## Known risks and limitations
+
+- <Risk or limitation 1>
+- <Risk or limitation 2>
+
+## Outstanding decisions
+
+- <Open question 1>
+- <Open question 2>
+```
+
 ______________________________________________________________________
 
 [^1]: A linter that enforces consistent Markdown formatting.