Parent: #22
Goal
Adopt the canonical heading policy from the parent issue discussion: architecture detail artifacts that are intended to be included into an assembled/wrapping document start at section level 1 (==), not document level 0 (=).
This applies at least to ADR, quality scenario, and risk artifacts.
Background
The parent issue initially considered preserving standalone = headings and compensating with leveloffset. The follow-up decision is different:
an ADR should start with Level 1 (== ...). If one would really like to have such a document rendered standalone on Level 0, you can still wrap that document with a dedicated Level 0 document
So the source artifacts themselves should match their normal include context.
Scope
- Update
templates/adr.adoc, templates/quality-scenario.adoc, and templates/risk.adoc so their first visible heading is ==.
- Update existing root source artifacts:
src/docs/arc42/09-architecture-decisions/adr-*.adoc
src/docs/arc42/10-quality-requirements/qs-*.adoc
src/docs/arc42/11-risks-and-technical-debt/r-*.adoc
- Update example templates and example ADR/QS/R source artifacts consistently, or explicitly defer example changes to the dogfood slice if that keeps review smaller.
- Preserve YAML front matter, stable IDs, anchors, statuses, summaries, and traceability includes.
- Check whether generated traceability fragments still land at the intended child level after the heading change.
Acceptance Criteria
- ADR/QS/R templates start with
==, not =.
- Existing ADR/QS/R source artifacts in the root docs start with
==, not =.
- No level-0 heading remains in an included ADR/QS/R artifact.
- Rendered root arc42 output no longer promotes ADR/QS/R artifacts to top-level sibling chapters.
- Validation and render checks pass.
Parent: #22
Goal
Adopt the canonical heading policy from the parent issue discussion: architecture detail artifacts that are intended to be included into an assembled/wrapping document start at section level 1 (
==), not document level 0 (=).This applies at least to ADR, quality scenario, and risk artifacts.
Background
The parent issue initially considered preserving standalone
=headings and compensating withleveloffset. The follow-up decision is different:So the source artifacts themselves should match their normal include context.
Scope
templates/adr.adoc,templates/quality-scenario.adoc, andtemplates/risk.adocso their first visible heading is==.src/docs/arc42/09-architecture-decisions/adr-*.adocsrc/docs/arc42/10-quality-requirements/qs-*.adocsrc/docs/arc42/11-risks-and-technical-debt/r-*.adocAcceptance Criteria
==, not=.==, not=.