Slice #22.2: Codify include heading policy in generator tests and docs

[dieterbaier]

Parent: #22

Goal

Update generator behavior, regression tests, and documentation rules so generated chapter include fragments remain compatible with the canonical heading policy from #22.

Background

ChapterIncludeFragmentGenerator currently emits plain include macros:

include::../09-architecture-decisions/adr-001-asciidoc-primary-source.adoc[]

The tests currently assert this behavior. After #22, ADR/QS/R artifacts should start at ==, so the generator may not need leveloffset=+1 for those artifacts anymore. But the generator and tests still need an explicit rule for included source files and for any future artifact whose first heading level differs from the include context.

Scope

• Define the generator policy for heading levels:
  • For normal generated chapter detail includes, the included artifact should already start at the chapter-child level (==) and can be included without leveloffset.
  • If the generator encounters a detail artifact that starts with =, either emit a warning/error or apply a documented leveloffset, depending on the decided validation policy.
• Update test/validate_metamodel_test.rb so it no longer locks in the old accidental behavior.
• Add focused regression coverage for heading-level handling in chapter include fragments.
• Add or document a render smoke check that catches ADR/QS/R artifacts becoming top-level sibling chapters.
• Update README.md, general-semantic-contracts.md, and relevant skills to state the heading-level contract for included artifacts.

Acceptance Criteria

• Tests express the desired heading-level policy.
• The validator/generator catches or prevents included detail artifacts from accidentally rendering at level 0.
• Generator output remains deterministic and sorted by artifact ID.
• README and semantic contracts explain when to use == and when leveloffset is required.
• ruby -Itest test/validate_metamodel_test.rb passes.
• A render check demonstrates the assembled root arc42 hierarchy is correct.