Fix included artifact heading levels and refresh dogfood example

[dieterbaier]

Problem

Included architecture artifacts currently break the assembled AsciiDoc heading hierarchy. The assembled architecture document should be the only level-0 document title. Whenever a source file is included at the same semantic level as the include macro, the include should use leveloffset=+1 so the included document becomes a child section.

Current ADR, quality scenario, and risk source artifacts start with level-0 headings, for example:

• src/docs/arc42/09-architecture-decisions/adr-001-asciidoc-primary-source.adoc starts with = ADR-001: ....
• src/docs/arc42/10-quality-requirements/qs-001-reproducible-generation.adoc starts with = QS-001: ....
• src/docs/arc42/11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc starts with = R-001: ....

The generated chapter include fragments include those files without a level offset, for example:

include::../09-architecture-decisions/adr-001-asciidoc-primary-source.adoc[]
include::../10-quality-requirements/qs-001-reproducible-generation.adoc[]
include::../11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc[]

Rendered result: ADRs, QSs, and risks become top-level sibling chapters of arc42 Chapter 9/10/11 instead of child sections. A render smoke check showed examples such as:

• ADR-001 rendered as chapter 10, after Architecture Decisions rendered as chapter 9.
• QS-001 rendered as chapter 16, after Quality Requirements rendered as chapter 15.
• R-001 rendered as chapter 22, after Risks And Technical Debt rendered as chapter 21.

Likely root cause

The missing rule is spread across templates, generator, tests, and instructions:

• templates/adr.adoc, templates/quality-scenario.adoc, and templates/risk.adoc define standalone artifacts with = level-0 titles.
• The corresponding example templates are byte-identical and carry the same level-0 titles.
• ChapterIncludeFragmentGenerator in scripts/validate-metamodel.rb emits include::#{target}[] for every detail artifact and does not compute or add leveloffset.
• test/validate_metamodel_test.rb currently asserts the no-offset include output, so the test suite locks in the wrong behavior.
• general-semantic-contracts.md, skills/adr/SKILL.md, skills/quality-scenario/SKILL.md, skills/risk/SKILL.md, and skills/bootstrap-project/SKILL.md say to use generated include fragments and templates, but do not explicitly state the AsciiDoc heading-level rule for included standalone artifacts.

Concrete changes to analyze and implement

1. Decide the canonical rule:

   • Prefer keeping standalone ADR/QS/R files as standalone source artifacts with = titles, because they can render independently.
   • Generated chapter include fragments should include standalone detail artifacts with leveloffset=+1 when their first heading is =.
   • Existing source detail pages that already start with == may not need an offset, but the generator should either detect the first heading level or apply a documented consistent policy.

2. Update ChapterIncludeFragmentGenerator:

   • Detect each included artifact's first AsciiDoc section level after YAML front matter.
   • Add leveloffset=+1 when including a file whose first heading is at the same level as the including chapter context.
   • Preserve deterministic sorting by artifact ID.
   • Keep generated index fragments directly included in their chapter context where appropriate.

3. Update generated include fragments after generator changes:

   • src/docs/arc42/generated/doc-09000-architecture-decisions-includes.adoc should no longer let ADRs render as sibling chapters.
   • src/docs/arc42/generated/doc-10000-quality-requirements-includes.adoc should no longer let QS files render as sibling chapters.
   • src/docs/arc42/generated/doc-11000-risks-and-technical-debt-includes.adoc should no longer let risk files render as sibling chapters.
   • Check all other generated chapter include fragments for the same heading-level issue.

4. Update tests:

   • Change the existing chapter include fragment tests that currently assert include::...[].
   • Add a regression test with a generated include fragment containing one = artifact and one == artifact, or otherwise codify the chosen policy.
   • Add a render-oriented regression check if feasible: rendered arc42 output should not promote ADR/QS/R artifacts to top-level siblings of Chapter 9/10/11.

5. Update instructions and docs:

   • Add the heading-level/include-offset rule to general-semantic-contracts.md under Docs-as-Code / arc42 include rules.
   • Add the same rule, or a pointer to it, in ADR/QS/R/bootstrap skills where they mention templates and generated include fragments.
   • Update README generator documentation to state how generated include fragments handle section levels.

6. Decide whether templates should remain level-0:

   • If standalone rendering is required, keep = in templates/adr.adoc, templates/quality-scenario.adoc, and templates/risk.adoc and solve via generated leveloffset.
   • If these artifacts are never meant to render standalone, change templates to ==. This would simplify includes but weakens standalone source artifact rendering. Current evidence points toward preserving standalone = and fixing includes.

Dogfood example findings

The example/ directory is no longer fully aligned with the current toolkit conventions:

• example/scripts/validate-metamodel.rb is older than the root script and lacks ChapterIncludeFragmentGenerator entirely.
• example/metamodel/*.yaml matches the root metamodel schemas.
• example/templates/adr.adoc, example/templates/quality-scenario.adoc, and example/templates/risk.adoc match the root templates, including the level-0 heading issue.
• example/src/docs/arc42/doc-09000-architecture-decisions.adoc, doc-10000-quality-requirements.adoc, and doc-11000-risks-and-technical-debt.adoc still manually list detail artifacts instead of using generated chapter include fragments.
• example/src/docs/arc42/doc-01000-introduction-and-goals.adoc also manually includes detail documents.
• Example validation currently passes with no warnings, so the validator does not detect this drift.
• Rendering the example shows the same hierarchy issue: ADRs, QSs, and risks render as sibling chapters rather than children of their arc42 chapters.

Keeping consuming projects up to date

Add an explicit toolkit update story for repositories that copy skills, templates, scripts, metamodel schemas, and examples from this toolkit. Possible approach:

• Add a toolkit-version metadata file or manifest in bootstrapped projects listing copied asset versions/checksums and source paths.
• Provide a small update/check command that compares local copied assets against the current toolkit release or main.
• Treat copied toolkit assets as upstream-managed unless the consuming project records local overrides.
• Add documentation for update modes: report-only, apply non-conflicting updates, and open a PR with copied asset refreshes.
• Make the example a first-class dogfood fixture in CI so drift between root toolkit assets and example/ is visible.

Acceptance criteria

• Assembled root arc42 output has only the main document as level 0, and ADR/QS/R artifacts render below their owning chapter.
• Generated chapter include fragments apply the chosen leveloffset policy deterministically.
• Tests cover generated include level offsets and fail on the current behavior.
• README, semantic contract, and relevant skills document the include-level rule.
• example/ uses the current generator behavior and no longer manually maintains chapter detail includes where generated fragments exist.
• Example scripts/templates/metamodel are either current or intentionally versioned as copied toolkit assets.
• Validation and render checks pass for both root docs and example/.

[dieterbaier]

• Ad 1 Decide the canonical rule:
  • I'd change the template so every document which is intended to be part of a wrapping documentation. So, an ADR should start with Level 1 ('== ...'). If one would really like to have such a document rendered standalone on Level 0, you can sill wrap that document with a dedicated Level 0 document

[dieterbaier]

Comment analysis and slicing proposal:

The follow-up comment decides the central policy question differently from the initial issue draft: ADR/QS/R artifacts should start at level 1 (==) because they are intended to be part of a wrapping architecture document. If a standalone level-0 render is needed, it should be produced by a small wrapper document.

That makes this too broad for one PR unless the PR becomes large and hard to review. I split the work into four reviewable slices:

1. Slice #22.1: Move included ADR/QS/R artifacts to section-level headings #23 - Move included ADR/QS/R artifacts and templates to section-level headings.
2. Slice #22.2: Codify include heading policy in generator tests and docs #24 - Codify the include heading policy in generator tests and docs.
3. Slice #22.3: Refresh dogfood example to current toolkit rules #25 - Refresh the dogfood example to the current toolkit rules.
4. Slice #22.4: Define toolkit asset update mechanism for consuming projects #26 - Define the toolkit asset update mechanism for consuming projects.

Recommended order:

1. Implement Slice #22.1: Move included ADR/QS/R artifacts to section-level headings #23 first because it establishes the source-level policy and removes the immediate render hierarchy bug.
2. Implement Slice #22.2: Codify include heading policy in generator tests and docs #24 next so tests and contracts prevent the bug from returning.
3. Implement Slice #22.3: Refresh dogfood example to current toolkit rules #25 after Slice #22.1: Move included ADR/QS/R artifacts to section-level headings #23/Slice #22.2: Codify include heading policy in generator tests and docs #24 so the example can be refreshed against the finalized source and generator behavior.
4. Treat Slice #22.4: Define toolkit asset update mechanism for consuming projects #26 as a design/documentation slice; it can proceed after the concrete drift is understood, but it does not need to block Slice #22.1: Move included ADR/QS/R artifacts to section-level headings #23.

Related note: #15 still covers generated-index wrapper cleanup. It may touch nearby chapter files, but it is a separate concern from heading levels and copied toolkit drift.

[dieterbaier]

Update: The sliced issues are now linked as real GitHub sub-issues of #22 via GitHub sub-issue relationships: #23, #24, #25, and #26. No markdown-task-list fallback is needed.