From c8ce6271cd6d0055771d7318fb5a94afaa3d5e37 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Sat, 4 Jul 2026 08:40:06 +0200 Subject: [PATCH 1/2] issue_23: Fix artifact heading levels --- .../adr-001-backend-api-boundary.adoc | 22 +++++------ .../adr-002-mobile-local-first-entry.adoc | 14 +++---- ...r-003-server-owned-budget-calculation.adoc | 14 +++---- .../qs-001-budget-total-integrity.adoc | 6 +-- .../qs-002-expense-entry-latency.adoc | 6 +-- .../qs-003-offline-expense-capture.adoc | 6 +-- .../r-001-private-data-exposure.adoc | 10 ++--- .../r-002-sync-conflict-loss.adoc | 10 ++--- example/templates/adr.adoc | 38 +++++++++---------- example/templates/quality-scenario.adoc | 16 ++++---- example/templates/risk.adoc | 18 ++++----- .../adr-001-asciidoc-primary-source.adoc | 36 +++++++++--------- .../adr-002-generated-output-not-source.adoc | 36 +++++++++--------- .../adr-003-source-fragments-location.adoc | 36 +++++++++--------- .../adr-004-github-pages-static-html.adoc | 36 +++++++++--------- .../adr-005-engine-independent-skills.adoc | 36 +++++++++--------- .../qs-001-reproducible-generation.adoc | 16 ++++---- ...02-missing-relation-target-validation.adoc | 16 ++++---- .../qs-003-reusable-fragments-render.adoc | 16 ++++---- .../qs-004-ai-suggestion-reviewability.adoc | 16 ++++---- .../qs-005-adapter-boundary.adoc | 16 ++++---- .../r-001-ai-suggestions-as-truth.adoc | 18 ++++----- .../r-002-unstable-generated-output.adoc | 18 ++++----- ...-003-source-fragments-break-rendering.adoc | 18 ++++----- .../r-004-heavy-metadata-authoring.adoc | 18 ++++----- ...-005-ruby-seen-as-target-architecture.adoc | 18 ++++----- .../r-006-unclear-adapter-boundaries.adoc | 18 ++++----- templates/adr.adoc | 38 +++++++++---------- templates/quality-scenario.adoc | 16 ++++---- templates/risk.adoc | 18 ++++----- 30 files changed, 300 insertions(+), 300 deletions(-) diff --git a/example/src/docs/arc42/09-architecture-decisions/adr-001-backend-api-boundary.adoc b/example/src/docs/arc42/09-architecture-decisions/adr-001-backend-api-boundary.adoc index d8eb049..44d0c9c 100644 --- a/example/src/docs/arc42/09-architecture-decisions/adr-001-backend-api-boundary.adoc +++ b/example/src/docs/arc42/09-architecture-decisions/adr-001-backend-api-boundary.adoc @@ -20,37 +20,37 @@ relations: metadata_version: '1.0' --- [[adr-001-backend-api-boundary]] -= ADR-001: Backend API Boundary +== ADR-001: Backend API Boundary -== Status +=== Status Proposed. -== Decision +=== Decision We propose a versioned HTTP JSON API as the boundary between web UI, mobile app, and backend. -== Context +=== Context The application has two clients and one backend system of record. Both clients need the same budget commands and summaries. -== Considered Options +=== Considered Options -=== HTTP JSON API +==== HTTP JSON API Simple to consume from web and mobile clients. -=== GraphQL +==== GraphQL Flexible for clients, but more complexity than the first increment needs. -=== Client-specific backends +==== Client-specific backends Allows tailored client APIs, but duplicates budget behavior early. -== Pugh Matrix +=== Pugh Matrix [cols="2,1,1,1", options="header"] |=== @@ -61,10 +61,10 @@ Allows tailored client APIs, but duplicates budget behavior early. s| Sum s| 3 s| 0 s| -2 |=== -== Consequences +=== Consequences * Web UI and mobile app share the same backend contract. * API versioning must be managed deliberately. -include::generated/adr-001-backend-api-boundary-traceability.adoc[] +include::generated/adr-001-backend-api-boundary-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/09-architecture-decisions/adr-002-mobile-local-first-entry.adoc b/example/src/docs/arc42/09-architecture-decisions/adr-002-mobile-local-first-entry.adoc index 83bb751..cac278e 100644 --- a/example/src/docs/arc42/09-architecture-decisions/adr-002-mobile-local-first-entry.adoc +++ b/example/src/docs/arc42/09-architecture-decisions/adr-002-mobile-local-first-entry.adoc @@ -27,23 +27,23 @@ relations: metadata_version: '1.0' --- [[adr-002-mobile-local-first-entry]] -= ADR-002: Mobile Local-First Expense Entry +== ADR-002: Mobile Local-First Expense Entry -== Status +=== Status Proposed. -== Decision +=== Decision We propose that the mobile app stores pending expense commands locally and syncs them when connectivity returns. -== Context +=== Context Expense entry often happens away from a stable network. Losing an entry makes the budget less trustworthy. -== Pugh Matrix +=== Pugh Matrix [cols="2,1,1,1", options="header"] |=== @@ -54,10 +54,10 @@ the budget less trustworthy. s| Sum s| 1 s| 1 s| -1 |=== -== Consequences +=== Consequences * Users can enter expenses offline. * Sync conflict handling becomes an explicit architecture concern. -include::generated/adr-002-mobile-local-first-entry-traceability.adoc[] +include::generated/adr-002-mobile-local-first-entry-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/09-architecture-decisions/adr-003-server-owned-budget-calculation.adoc b/example/src/docs/arc42/09-architecture-decisions/adr-003-server-owned-budget-calculation.adoc index 5759d97..d30ef2f 100644 --- a/example/src/docs/arc42/09-architecture-decisions/adr-003-server-owned-budget-calculation.adoc +++ b/example/src/docs/arc42/09-architecture-decisions/adr-003-server-owned-budget-calculation.adoc @@ -20,22 +20,22 @@ relations: metadata_version: '1.0' --- [[adr-003-server-owned-budget-calculation]] -= ADR-003: Server-Owned Budget Calculation +== ADR-003: Server-Owned Budget Calculation -== Status +=== Status Proposed. -== Decision +=== Decision We propose to calculate budget totals and remaining amounts on the backend. -== Context +=== Context The web UI and mobile app should display the same budget state. Client-only calculation would duplicate business rules. -== Pugh Matrix +=== Pugh Matrix [cols="2,1,1,1", options="header"] |=== @@ -46,10 +46,10 @@ calculation would duplicate business rules. s| Sum s| 3 s| -3 s| 2 |=== -== Consequences +=== Consequences * Budget rules have one implementation point. * Backend availability affects live budget summaries. -include::generated/adr-003-server-owned-budget-calculation-traceability.adoc[] +include::generated/adr-003-server-owned-budget-calculation-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/10-quality-requirements/qs-001-budget-total-integrity.adoc b/example/src/docs/arc42/10-quality-requirements/qs-001-budget-total-integrity.adoc index 6deae5d..c79eba8 100644 --- a/example/src/docs/arc42/10-quality-requirements/qs-001-budget-total-integrity.adoc +++ b/example/src/docs/arc42/10-quality-requirements/qs-001-budget-total-integrity.adoc @@ -20,9 +20,9 @@ relations: metadata_version: '1.0' --- [[qs-001-budget-total-integrity]] -= QS-001: Budget Total Integrity +== QS-001: Budget Total Integrity -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -35,5 +35,5 @@ metadata_version: '1.0' | Response Measure | Assumption: service-level tests cover create, edit, delete, and retry cases with no unexplained total drift. |=== -include::generated/qs-001-budget-total-integrity-traceability.adoc[] +include::generated/qs-001-budget-total-integrity-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/10-quality-requirements/qs-002-expense-entry-latency.adoc b/example/src/docs/arc42/10-quality-requirements/qs-002-expense-entry-latency.adoc index 21ef38e..3798f4b 100644 --- a/example/src/docs/arc42/10-quality-requirements/qs-002-expense-entry-latency.adoc +++ b/example/src/docs/arc42/10-quality-requirements/qs-002-expense-entry-latency.adoc @@ -20,9 +20,9 @@ relations: metadata_version: '1.0' --- [[qs-002-expense-entry-latency]] -= QS-002: Expense Entry Latency +== QS-002: Expense Entry Latency -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -35,5 +35,5 @@ metadata_version: '1.0' | Response Measure | Assumption: p95 interaction time stays below 2 seconds after the user submits the form. |=== -include::generated/qs-002-expense-entry-latency-traceability.adoc[] +include::generated/qs-002-expense-entry-latency-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/10-quality-requirements/qs-003-offline-expense-capture.adoc b/example/src/docs/arc42/10-quality-requirements/qs-003-offline-expense-capture.adoc index 463f8a6..2b83cac 100644 --- a/example/src/docs/arc42/10-quality-requirements/qs-003-offline-expense-capture.adoc +++ b/example/src/docs/arc42/10-quality-requirements/qs-003-offline-expense-capture.adoc @@ -20,9 +20,9 @@ relations: metadata_version: '1.0' --- [[qs-003-offline-expense-capture]] -= QS-003: Offline Expense Capture +== QS-003: Offline Expense Capture -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -35,5 +35,5 @@ metadata_version: '1.0' | Response Measure | Assumption: no pending expense is lost across app restart during the outage. |=== -include::generated/qs-003-offline-expense-capture-traceability.adoc[] +include::generated/qs-003-offline-expense-capture-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/11-risks-and-technical-debt/r-001-private-data-exposure.adoc b/example/src/docs/arc42/11-risks-and-technical-debt/r-001-private-data-exposure.adoc index 1ffeb51..b199e8e 100644 --- a/example/src/docs/arc42/11-risks-and-technical-debt/r-001-private-data-exposure.adoc +++ b/example/src/docs/arc42/11-risks-and-technical-debt/r-001-private-data-exposure.adoc @@ -20,15 +20,15 @@ relations: metadata_version: '1.0' --- [[r-001-private-data-exposure]] -= R-001: Private Budget Data Exposure +== R-001: Private Budget Data Exposure -== Risk Statement +=== Risk Statement Because budget data contains personal spending patterns, weak authorization, transport security, or logging may expose sensitive information to unauthorized parties. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -40,10 +40,10 @@ parties. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options Use authenticated API access, server-side authorization, transport encryption, password hashing, and log redaction. -include::generated/r-001-private-data-exposure-traceability.adoc[] +include::generated/r-001-private-data-exposure-traceability.adoc[leveloffset=+1] diff --git a/example/src/docs/arc42/11-risks-and-technical-debt/r-002-sync-conflict-loss.adoc b/example/src/docs/arc42/11-risks-and-technical-debt/r-002-sync-conflict-loss.adoc index b4f8c50..6634801 100644 --- a/example/src/docs/arc42/11-risks-and-technical-debt/r-002-sync-conflict-loss.adoc +++ b/example/src/docs/arc42/11-risks-and-technical-debt/r-002-sync-conflict-loss.adoc @@ -20,15 +20,15 @@ relations: metadata_version: '1.0' --- [[r-002-sync-conflict-loss]] -= R-002: Sync Conflict Causes Expense Loss +== R-002: Sync Conflict Causes Expense Loss -== Risk Statement +=== Risk Statement Because the mobile app queues offline commands, a retry or conflict may lose, duplicate, or misapply an expense unless commands are idempotent and conflicts are visible. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -40,10 +40,10 @@ are visible. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options Use client-generated command IDs, idempotent backend processing, and explicit conflict feedback. -include::generated/r-002-sync-conflict-loss-traceability.adoc[] +include::generated/r-002-sync-conflict-loss-traceability.adoc[leveloffset=+1] diff --git a/example/templates/adr.adoc b/example/templates/adr.adoc index e3cc6ba..39ee8ad 100644 --- a/example/templates/adr.adoc +++ b/example/templates/adr.adoc @@ -17,45 +17,45 @@ relations: reviewed: false --- [[adr-000-short-title]] -= ADR-000: Short Decision Topic +== ADR-000: Short Decision Topic -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to choose the selected option. -== Context +=== Context Describe the problem, forces, constraints, affected architecture artifacts, and source-code evidence inspected before writing this decision. -== Decision Drivers +=== Decision Drivers * Driver 1. * Driver 2. * Driver 3. -== Considered Options +=== Considered Options -=== Option 1: Name +==== Option 1: Name Describe benefits, costs, risks, and fit to the drivers. -=== Option 2: Name +==== Option 2: Name Describe benefits, costs, risks, and fit to the drivers. -=== Option 3: Name +==== Option 3: Name Describe benefits, costs, risks, and fit to the drivers. -== Pugh Matrix +=== Pugh Matrix Use `+1` for better support, `0` for neutral support, and `-1` for weaker support. Mark cells with `?` when assessment requires human review. Add each @@ -72,21 +72,21 @@ the sum for that option is `?`. s| Sum s| ? s| 0 s| ? |=== -== Consequences +=== Consequences -=== Positive +==== Positive * Positive consequence. -=== Negative +==== Negative * Negative consequence. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * Follow-up decision or implementation concern. -== Impact +=== Impact [cols="1,1,3", options="header"] |=== @@ -95,7 +95,7 @@ s| Sum s| ? s| 0 s| ? | xref:risk.adoc#risk-000-short-title[RISK-000-short-title] | introduced | Explain the risk impact. |=== -== Traceability +=== Traceability [cols="1,1,3", options="header"] |=== @@ -103,14 +103,14 @@ s| Sum s| ? s| 0 s| ? | `addresses` | xref:quality-scenario.adoc#qs-000-short-title[QS-000-short-title] | Explain the relation. |=== -== Assumptions +=== Assumptions * Assumption requiring review. -== Open Questions +=== Open Questions * Question for the accountable owner. -== Review Notes +=== Review Notes State what must be confirmed before this ADR can be marked reviewed or accepted. diff --git a/example/templates/quality-scenario.adoc b/example/templates/quality-scenario.adoc index 7c7c79f..7efba61 100644 --- a/example/templates/quality-scenario.adoc +++ b/example/templates/quality-scenario.adoc @@ -17,16 +17,16 @@ relations: reviewed: false --- [[qs-000-short-title]] -= QS-000: Short Quality Scenario Title +== QS-000: Short Quality Scenario Title -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -39,15 +39,15 @@ assumptions until confirmed. | Response Measure | Measurable threshold or target. |=== -== Rationale +=== Rationale Explain why this scenario matters and which stakeholder outcome it supports. -== Assumptions +=== Assumptions * Assumption requiring review. -== Traceability +=== Traceability [cols="1,1,3", options="header"] |=== @@ -55,11 +55,11 @@ Explain why this scenario matters and which stakeholder outcome it supports. | `depends_on` | xref:adr.adoc#adr-000-short-title[ADR-000-short-title] | Explain the relation. |=== -== Open Questions +=== Open Questions * Question for the accountable owner. -== Review Notes +=== Review Notes Mark this scenario as reviewed only after the measure, environment, and stakeholder value are confirmed. diff --git a/example/templates/risk.adoc b/example/templates/risk.adoc index 5d47a13..abd40f5 100644 --- a/example/templates/risk.adoc +++ b/example/templates/risk.adoc @@ -17,20 +17,20 @@ relations: reviewed: false --- [[risk-000-short-title]] -= RISK-000: Short Risk Title +== RISK-000: Short Risk Title -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because , may occur, leading to . -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -42,17 +42,17 @@ Because , may occur, leading to . | Confidence | Low, medium, or high. |=== -== Mitigation Options +=== Mitigation Options * Mitigation option. * Monitoring or review option. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -== Traceability +=== Traceability [cols="1,1,3", options="header"] |=== @@ -60,10 +60,10 @@ assessment and mitigation path. | `depends_on` | xref:adr.adoc#adr-000-short-title[ADR-000-short-title] | Explain the relation. |=== -== Open Questions +=== Open Questions * Question for risk owner. -== Review Notes +=== Review Notes State what must be confirmed before this risk can be marked reviewed or accepted. diff --git a/src/docs/arc42/09-architecture-decisions/adr-001-asciidoc-primary-source.adoc b/src/docs/arc42/09-architecture-decisions/adr-001-asciidoc-primary-source.adoc index d178abf..057404a 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-001-asciidoc-primary-source.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-001-asciidoc-primary-source.adoc @@ -32,50 +32,50 @@ relations: metadata_version: '1.0' --- [[adr-001-asciidoc-primary-source]] -= ADR-001: Primary Architecture Source Format +== ADR-001: Primary Architecture Source Format -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to use AsciiDoc as the primary architecture source format. -== Context +=== Context The toolkit follows a Docs-as-Code approach and uses arc42 documentation under `src/docs/`. The current technology constraints already name AsciiDoc as the primary documentation source. The repository also uses PlantUML and `include::[]` for reusable source fragments. -== Decision Drivers +=== Decision Drivers * Support arc42 documentation and local static rendering. * Support reusable source fragments without duplicating source text. * Keep source files reviewable in pull requests. -== Considered Options +=== Considered Options -=== Option 1: AsciiDoc as primary source +==== Option 1: AsciiDoc as primary source AsciiDoc fits the current repository structure, supports includes, and matches the Docs-as-Code Toolkit ecosystem. -=== Option 2: Markdown as primary source +==== Option 2: Markdown as primary source Markdown is familiar to many contributors, but it gives weaker native support for structured includes and arc42-style publishing. -=== Option 3: Mixed source formats +==== Option 3: Mixed source formats Mixed formats may help some contributors, but they increase validation, generation, and style complexity. -== Pugh Matrix +=== Pugh Matrix [.pugh-matrix] [cols="2,1,1,1", options="header"] @@ -87,35 +87,35 @@ generation, and style complexity. s| Sum s| 3 s| 0 s| -1 |=== -== Consequences +=== Consequences -=== Positive +==== Positive * Architecture content can use native AsciiDoc includes for shared fragments. * The publication path can start with plain Asciidoctor-generated HTML. -=== Negative +==== Negative * Contributors need basic AsciiDoc knowledge. * Reusable fragments create rendering risk if they assume a fixed heading level or target format. This is tracked by xref:r-003-source-fragments-break-rendering[]. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * Markdown may still be used outside the architecture source set when it is not part of the arc42 publication path. -include::generated/adr-001-asciidoc-primary-source-traceability.adoc[] +include::generated/adr-001-asciidoc-primary-source-traceability.adoc[leveloffset=+1] -== Assumptions +=== Assumptions * The first publication path remains Asciidoctor-generated static HTML. -== Open Questions +=== Open Questions * Which non-HTML publication targets must be supported in version 1? -== Review Notes +=== Review Notes Confirm that AsciiDoc remains the preferred source format before marking this ADR reviewed or accepted. diff --git a/src/docs/arc42/09-architecture-decisions/adr-002-generated-output-not-source.adoc b/src/docs/arc42/09-architecture-decisions/adr-002-generated-output-not-source.adoc index e2f42ea..385bbb0 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-002-generated-output-not-source.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-002-generated-output-not-source.adoc @@ -26,49 +26,49 @@ relations: metadata_version: '1.0' --- [[adr-002-generated-output-not-source]] -= ADR-002: Generated Documentation As Source Truth +== ADR-002: Generated Documentation As Source Truth -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to keep generated documentation out of source control. -== Context +=== Context xref:q-arch-005[Q-ARCH-005] states that generated documentation should not be committed to the repository. It should be created locally and in CI/CD, then published to a separate location. -== Decision Drivers +=== Decision Drivers * Keep reviewed source content separate from derived output. * Reduce merge conflicts and review noise. * Make generation reproducible in local and CI workflows. -== Considered Options +=== Considered Options -=== Option 1: Do not commit generated documentation +==== Option 1: Do not commit generated documentation Generated documentation is created on demand and published outside the source repository. -=== Option 2: Commit generated documentation +==== Option 2: Commit generated documentation Generated files are versioned together with source files, making output visible but adding churn and merge conflicts. -=== Option 3: Commit generated documentation and verify in CI +==== Option 3: Commit generated documentation and verify in CI Generated files are committed and regenerated in CI for drift detection. This adds review visibility but keeps generated output in the source tree. -== Pugh Matrix +=== Pugh Matrix [.pugh-matrix] [cols="2,1,1,1", options="header"] @@ -80,33 +80,33 @@ adds review visibility but keeps generated output in the source tree. s| Sum s| 3 s| -2 s| 0 |=== -== Consequences +=== Consequences -=== Positive +==== Positive * Pull requests focus on source artifacts and metadata. * Generated output can be recreated from committed inputs. -=== Negative +==== Negative * Contributors need a documented command to generate and preview output. * CI or publishing must provide access to rendered documentation. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * Generated views may still be used as CI artifacts or published files. -include::generated/adr-002-generated-output-not-source-traceability.adoc[] +include::generated/adr-002-generated-output-not-source-traceability.adoc[leveloffset=+1] -== Assumptions +=== Assumptions * CI/CD can publish generated documentation outside the repository. -== Open Questions +=== Open Questions * Which local command should contributors run before opening a pull request? -== Review Notes +=== Review Notes Confirm the publication location and local validation command before accepting this ADR. diff --git a/src/docs/arc42/09-architecture-decisions/adr-003-source-fragments-location.adoc b/src/docs/arc42/09-architecture-decisions/adr-003-source-fragments-location.adoc index ad8346c..d847008 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-003-source-fragments-location.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-003-source-fragments-location.adoc @@ -26,49 +26,49 @@ relations: metadata_version: '1.0' --- [[adr-003-source-fragments-location]] -= ADR-003: Reusable Source Fragment Location +== ADR-003: Reusable Source Fragment Location -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to store reusable source fragments under `src/docs/fragments/`. -== Context +=== Context The toolkit distinguishes reusable source fragments from generated fragments. xref:q-arch-007[Q-ARCH-007] still marks the final fragment location as open. The current arc42 draft already uses `src/docs/fragments/` as the proposed convention. -== Decision Drivers +=== Decision Drivers * Keep reusable source content near the architecture documentation. * Avoid confusing reviewed source fragments with generated output. * Keep include paths predictable. -== Considered Options +=== Considered Options -=== Option 1: `src/docs/fragments/` +==== Option 1: `src/docs/fragments/` Fragments live under the documentation source tree and remain clearly separate from generated output. -=== Option 2: `src/docs/shared/` +==== Option 2: `src/docs/shared/` The name is general, but less explicit about fragment semantics. -=== Option 3: Generated-output directory +==== Option 3: Generated-output directory This would mix source truth and derived output and contradict xref:q-arch-009[Q-ARCH-009]. -== Pugh Matrix +=== Pugh Matrix [.pugh-matrix] [cols="2,1,1,1", options="header"] @@ -80,36 +80,36 @@ xref:q-arch-009[Q-ARCH-009]. s| Sum s| 3 s| 1 s| -3 |=== -== Consequences +=== Consequences -=== Positive +==== Positive * Fragments are reviewed source content and can be included from multiple documents. * Generated output remains outside the source-fragment area. -=== Negative +==== Negative * Shared fragments can break several documents at once when they use fixed heading levels or target-specific constructs. This is tracked by xref:r-003-source-fragments-break-rendering[]. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * Fragment structure rules still need human confirmation through xref:q-arch-008[Q-ARCH-008]. -include::generated/adr-003-source-fragments-location-traceability.adoc[] +include::generated/adr-003-source-fragments-location-traceability.adoc[leveloffset=+1] -== Assumptions +=== Assumptions * Source fragments stay in reviewed source directories, never generated output. -== Open Questions +=== Open Questions * Which fragment structures are allowed for every supported target format? -== Review Notes +=== Review Notes Confirm xref:q-arch-007[Q-ARCH-007] and xref:q-arch-008[Q-ARCH-008] before accepting this ADR. diff --git a/src/docs/arc42/09-architecture-decisions/adr-004-github-pages-static-html.adoc b/src/docs/arc42/09-architecture-decisions/adr-004-github-pages-static-html.adoc index fcfb840..6e64a19 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-004-github-pages-static-html.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-004-github-pages-static-html.adoc @@ -32,49 +32,49 @@ relations: metadata_version: '1.0' --- [[adr-004-github-pages-static-html]] -= ADR-004: First Publication Target +== ADR-004: First Publication Target -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to use GitHub Pages with plain Asciidoctor-generated static HTML as the first publication target. -== Context +=== Context xref:q-ops-004[Q-OPS-004] and xref:q-ops-005[Q-OPS-005] identify GitHub Pages and plain Asciidoctor-generated static HTML as the first publication path. The toolkit may later support more formats, but version 1 needs a simple publication target. -== Decision Drivers +=== Decision Drivers * Keep the first publication workflow simple. * Use the existing AsciiDoc source model. * Avoid early dependency on a larger publishing platform. -== Considered Options +=== Considered Options -=== Option 1: GitHub Pages with plain Asciidoctor HTML +==== Option 1: GitHub Pages with plain Asciidoctor HTML This option uses static files and a familiar open-source hosting path. -=== Option 2: Dedicated documentation server +==== Option 2: Dedicated documentation server A separate server can provide more control, but adds operational burden early. -=== Option 3: Multiple publication targets from the start +==== Option 3: Multiple publication targets from the start This supports portability early, but expands validation and rendering work before the source model is stable. -== Pugh Matrix +=== Pugh Matrix [.pugh-matrix] [cols="2,1,1,1", options="header"] @@ -86,33 +86,33 @@ before the source model is stable. s| Sum s| 2 s| 0 s| 0 |=== -== Consequences +=== Consequences -=== Positive +==== Positive * The first publication workflow stays small and reviewable. * Fragment rendering can be tested against one concrete target first. -=== Negative +==== Negative * Non-HTML publication needs later design and verification. * GitHub Pages availability and repository settings become operational inputs. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * The decision does not prevent later PDF, site-generator, or docs-toolbox publication paths. -include::generated/adr-004-github-pages-static-html-traceability.adoc[] +include::generated/adr-004-github-pages-static-html-traceability.adoc[leveloffset=+1] -== Assumptions +=== Assumptions * GitHub Pages is available for the repository that publishes the toolkit docs. -== Open Questions +=== Open Questions * Which publication targets follow after static HTML? -== Review Notes +=== Review Notes Confirm the hosting path and CI publishing workflow before accepting this ADR. diff --git a/src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc b/src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc index c45a540..e1abf1a 100644 --- a/src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc +++ b/src/docs/arc42/09-architecture-decisions/adr-005-engine-independent-skills.adoc @@ -32,50 +32,50 @@ relations: metadata_version: '1.0' --- [[adr-005-engine-independent-skills]] -= ADR-005: Engine-Specific Runtime Integration Boundary +== ADR-005: Engine-Specific Runtime Integration Boundary -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to keep core skills engine-independent and move runtime integration to adapter documentation. -== Context +=== Context `AGENTS.md` states that Codex-specific, Vibe-specific, or other runtime integration belongs under `adapters/`. xref:q-arch-006[Q-ARCH-006] still marks the exact adapter documentation boundary as open. -== Decision Drivers +=== Decision Drivers * Keep reusable skills independent of one AI engine. * Let runtime-specific integrations evolve without changing core contracts. * Preserve portability across AI assistants and documentation workflows. -== Considered Options +=== Considered Options -=== Option 1: Engine-independent core with adapters +==== Option 1: Engine-independent core with adapters Core contracts and skills remain engine-independent. Runtime details live under `adapters/`. -=== Option 2: Put runtime guidance directly into skills +==== Option 2: Put runtime guidance directly into skills This keeps one file close to the workflow, but couples reusable skills to specific AI engines. -=== Option 3: Separate one skill set per engine +==== Option 3: Separate one skill set per engine This makes engine behavior explicit, but duplicates architecture rules and raises drift risk. -== Pugh Matrix +=== Pugh Matrix [.pugh-matrix] [cols="2,1,1,1", options="header"] @@ -87,35 +87,35 @@ raises drift risk. s| Sum s| 2 s| 0 s| 0 |=== -== Consequences +=== Consequences -=== Positive +==== Positive * Core contracts can be reused by different AI engines. * Runtime-specific details can change without rewriting shared skill rules. -=== Negative +==== Negative * Contributors must decide whether a detail belongs in a core skill or an adapter until xref:q-arch-006[Q-ARCH-006] is resolved. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * Adapter conventions need examples as the project learns more engine differences. -include::generated/adr-005-engine-independent-skills-traceability.adoc[] +include::generated/adr-005-engine-independent-skills-traceability.adoc[leveloffset=+1] -== Assumptions +=== Assumptions * Engine-independent rules can be expressed without losing necessary runtime behavior. -== Open Questions +=== Open Questions * Which workflow details belong in adapters instead of core skills? -== Review Notes +=== Review Notes Confirm xref:q-arch-006[Q-ARCH-006] with concrete engine evidence before accepting this ADR. diff --git a/src/docs/arc42/10-quality-requirements/qs-001-reproducible-generation.adoc b/src/docs/arc42/10-quality-requirements/qs-001-reproducible-generation.adoc index 6519895..c3b541c 100644 --- a/src/docs/arc42/10-quality-requirements/qs-001-reproducible-generation.adoc +++ b/src/docs/arc42/10-quality-requirements/qs-001-reproducible-generation.adoc @@ -20,16 +20,16 @@ relations: metadata_version: '1.0' --- [[qs-001-reproducible-generation]] -= QS-001: Reproducible Generation +== QS-001: Reproducible Generation -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -42,25 +42,25 @@ assumptions until confirmed. | Response Measure | Assumption: the second run produces no meaningful diff. |=== -== Rationale +=== Rationale This scenario concretizes QG-001 Reproducibility. It supports xref:adr-002-generated-output-not-source[] because generated output is useful outside source control only when it can be recreated from the same committed inputs. -== Assumptions +=== Assumptions * "Meaningful diff" excludes timestamps, local paths, ordering drift, and other non-source changes. -include::generated/qs-001-reproducible-generation-traceability.adoc[] +include::generated/qs-001-reproducible-generation-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which generated views require golden-file regression tests first? -== Review Notes +=== Review Notes Confirm the exact diff policy and verification command before marking this scenario reviewed. diff --git a/src/docs/arc42/10-quality-requirements/qs-002-missing-relation-target-validation.adoc b/src/docs/arc42/10-quality-requirements/qs-002-missing-relation-target-validation.adoc index c07bf30..973aada 100644 --- a/src/docs/arc42/10-quality-requirements/qs-002-missing-relation-target-validation.adoc +++ b/src/docs/arc42/10-quality-requirements/qs-002-missing-relation-target-validation.adoc @@ -20,16 +20,16 @@ relations: metadata_version: '1.0' --- [[qs-002-missing-relation-target-validation]] -= QS-002: Missing Relation Target Validation +== QS-002: Missing Relation Target Validation -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -42,22 +42,22 @@ assumptions until confirmed. | Response Measure | Evidence target: command exits non-zero and names the missing target ID. |=== -== Rationale +=== Rationale This scenario concretizes QG-003 Traceability. Stable IDs are useful only when invalid relation targets are detected before review. -== Assumptions +=== Assumptions * The local validation command is documented for contributors. -include::generated/qs-002-missing-relation-target-validation-traceability.adoc[] +include::generated/qs-002-missing-relation-target-validation-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which validation output format is most useful for local runs and CI logs? -== Review Notes +=== Review Notes Confirm the local validation command and expected error wording before marking this scenario reviewed. diff --git a/src/docs/arc42/10-quality-requirements/qs-003-reusable-fragments-render.adoc b/src/docs/arc42/10-quality-requirements/qs-003-reusable-fragments-render.adoc index 422e963..59d06f4 100644 --- a/src/docs/arc42/10-quality-requirements/qs-003-reusable-fragments-render.adoc +++ b/src/docs/arc42/10-quality-requirements/qs-003-reusable-fragments-render.adoc @@ -20,16 +20,16 @@ relations: metadata_version: '1.0' --- [[qs-003-reusable-fragments-render]] -= QS-003: Reusable Fragments Render Correctly +== QS-003: Reusable Fragments Render Correctly -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -42,24 +42,24 @@ assumptions until confirmed. | Response Measure | Assumption: generated HTML contains one rendered copy per include location and no broken include directive. |=== -== Rationale +=== Rationale This scenario concretizes QG-004 Content reuse. The toolkit's `Write once. Publish everywhere.` rule needs source fragments that render cleanly wherever they are included. -== Assumptions +=== Assumptions * Static HTML is the first supported render target. * More targets require additional render checks. -include::generated/qs-003-reusable-fragments-render-traceability.adoc[] +include::generated/qs-003-reusable-fragments-render-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which render targets beyond static HTML must be covered in version 1? -== Review Notes +=== Review Notes Confirm the supported target formats and fixture expectations before marking this scenario reviewed. diff --git a/src/docs/arc42/10-quality-requirements/qs-004-ai-suggestion-reviewability.adoc b/src/docs/arc42/10-quality-requirements/qs-004-ai-suggestion-reviewability.adoc index f1629ef..4da6910 100644 --- a/src/docs/arc42/10-quality-requirements/qs-004-ai-suggestion-reviewability.adoc +++ b/src/docs/arc42/10-quality-requirements/qs-004-ai-suggestion-reviewability.adoc @@ -20,16 +20,16 @@ relations: metadata_version: '1.0' --- [[qs-004-ai-suggestion-reviewability]] -= QS-004: AI Suggestions Remain Reviewable +== QS-004: AI Suggestions Remain Reviewable -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -42,23 +42,23 @@ assumptions until confirmed. | Response Measure | Assumption: status or prose marker is visible in the reviewed artifact. |=== -== Rationale +=== Rationale This scenario concretizes QG-002 Reviewability. The repository permits AI-assisted drafting, but accepted architecture truth must remain a human review decision. -== Assumptions +=== Assumptions * Proposed or draft metadata is visible in review. * Human acceptance is recorded before an artifact becomes accepted. -include::generated/qs-004-ai-suggestion-reviewability-traceability.adoc[] +include::generated/qs-004-ai-suggestion-reviewability-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which marker is mandatory: metadata status, visible prose, or both? -== Review Notes +=== Review Notes Confirm the review marker convention before marking this scenario reviewed. diff --git a/src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc b/src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc index 992253f..f8f32ca 100644 --- a/src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc +++ b/src/docs/arc42/10-quality-requirements/qs-005-adapter-boundary.adoc @@ -20,16 +20,16 @@ relations: metadata_version: '1.0' --- [[qs-005-adapter-boundary]] -= QS-005: Runtime-Specific Guidance Stays In Adapters +== QS-005: Runtime-Specific Guidance Stays In Adapters -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -42,23 +42,23 @@ assumptions until confirmed. | Response Measure | Evidence target: runtime-specific changes are located under `adapters/`. |=== -== Rationale +=== Rationale This scenario concretizes QG-005 Portability. Core skills should stay useful across engines while adapters carry runtime-specific guidance. -== Assumptions +=== Assumptions * Reviewers can identify runtime-specific guidance during repository review. -include::generated/qs-005-adapter-boundary-traceability.adoc[] +include::generated/qs-005-adapter-boundary-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which examples define the line between core skill guidance and adapter guidance? -== Review Notes +=== Review Notes Confirm xref:q-arch-006[Q-ARCH-006] with concrete engine examples before marking this scenario reviewed. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc index 1f10085..1663514 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-001-ai-suggestions-as-truth.adoc @@ -26,22 +26,22 @@ relations: metadata_version: '1.0' --- [[r-001-ai-suggestions-as-truth]] -= R-001: AI Suggestions Are Mistaken For Reviewed Architecture Truth +== R-001: AI Suggestions Are Mistaken For Reviewed Architecture Truth -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because AI-generated architecture content can look complete, reviewers may mistake suggested content for accepted architecture truth, leading to unreviewed decisions, risks, or requirements entering the source documentation. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -53,25 +53,25 @@ decisions, risks, or requirements entering the source documentation. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options * Keep AI-created or AI-modified artifacts `proposed` or `draft` with `reviewed: false`. * Use visible review notes in ADRs, quality scenarios, and risks. * Check xref:qs-004-ai-suggestion-reviewability[] during pull-request review. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -include::generated/r-001-ai-suggestions-as-truth-traceability.adoc[] +include::generated/r-001-ai-suggestions-as-truth-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which review marker is mandatory in every AI-assisted artifact? -== Review Notes +=== Review Notes Confirm review-marker rules and pull-request checks before marking this risk reviewed. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-002-unstable-generated-output.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-002-unstable-generated-output.adoc index ea4daef..4fcd270 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-002-unstable-generated-output.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-002-unstable-generated-output.adoc @@ -20,22 +20,22 @@ relations: metadata_version: '1.0' --- [[r-002-unstable-generated-output]] -= R-002: Generated Output Becomes Unstable +== R-002: Generated Output Becomes Unstable -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because generators may depend on unordered metadata, timestamps, local paths, or environment-specific behavior, generated output may change without source changes, leading to review noise and loss of trust in generated views. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -47,25 +47,25 @@ changes, leading to review noise and loss of trust in generated views. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options * Enforce deterministic ordering and avoid timestamps, random values, and local paths in generated views. * Add golden-file regression tests for generated views. * Verify xref:qs-001-reproducible-generation[] in local and CI workflows. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -include::generated/r-002-unstable-generated-output-traceability.adoc[] +include::generated/r-002-unstable-generated-output-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which generated outputs need golden-file tests in version 1? -== Review Notes +=== Review Notes Confirm generation determinism rules and regression-test scope before marking this risk reviewed. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-003-source-fragments-break-rendering.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-003-source-fragments-break-rendering.adoc index 7e13263..aa1693f 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-003-source-fragments-break-rendering.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-003-source-fragments-break-rendering.adoc @@ -20,23 +20,23 @@ relations: metadata_version: '1.0' --- [[r-003-source-fragments-break-rendering]] -= R-003: Reusable Source Fragments Break Rendered Target Formats +== R-003: Reusable Source Fragments Break Rendered Target Formats -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because reusable source fragments can be included in several document locations, a fragment with fixed heading assumptions or target-specific markup may render incorrectly, leading to broken output in one or more publication formats. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -48,25 +48,25 @@ formats. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options * Keep fragments heading-neutral unless the include location explicitly expects a heading. * Avoid formatter-specific constructs until target formats are known and tested. * Add render regression tests for xref:qs-003-reusable-fragments-render[]. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -include::generated/r-003-source-fragments-break-rendering-traceability.adoc[] +include::generated/r-003-source-fragments-break-rendering-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which fragment structures are allowed for every supported output target? -== Review Notes +=== Review Notes Confirm fragment conventions and render-test scope before marking this risk reviewed. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-004-heavy-metadata-authoring.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-004-heavy-metadata-authoring.adoc index 4c7cf45..7783eb2 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-004-heavy-metadata-authoring.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-004-heavy-metadata-authoring.adoc @@ -26,22 +26,22 @@ relations: metadata_version: '1.0' --- [[r-004-heavy-metadata-authoring]] -= R-004: Metadata Authoring Feels Too Heavy +== R-004: Metadata Authoring Feels Too Heavy -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because every architecture artifact needs explicit metadata and relations, small teams may perceive authoring as too heavy, leading to partial adoption or abandoned traceability. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -53,7 +53,7 @@ abandoned traceability. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options * Keep the first adoption slice focused on setup, templates, dogfood documentation, and clear validation messages. @@ -61,18 +61,18 @@ abandoned traceability. * Use xref:qs-002-missing-relation-target-validation[] to make metadata errors actionable. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -include::generated/r-004-heavy-metadata-authoring-traceability.adoc[] +include::generated/r-004-heavy-metadata-authoring-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which metadata fields are mandatory for version 1 beyond the current schema? -== Review Notes +=== Review Notes Confirm the minimum metadata set and onboarding workflow before marking this risk reviewed. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-005-ruby-seen-as-target-architecture.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-005-ruby-seen-as-target-architecture.adoc index 3bc532b..c8cecdb 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-005-ruby-seen-as-target-architecture.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-005-ruby-seen-as-target-architecture.adoc @@ -20,22 +20,22 @@ relations: metadata_version: '1.0' --- [[r-005-ruby-seen-as-target-architecture]] -= R-005: Ruby Is Mistaken For A Fixed Target Architecture +== R-005: Ruby Is Mistaken For A Fixed Target Architecture -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because the current validator and generator are implemented in Ruby, contributors may treat Ruby as the accepted long-term implementation language, leading to premature coupling and reduced openness for future runtime choices. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -47,7 +47,7 @@ leading to premature coupling and reduced openness for future runtime choices. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options * Keep the technology constraints clear that Ruby is the current implementation language only. @@ -56,19 +56,19 @@ leading to premature coupling and reduced openness for future runtime choices. * Use xref:q-dev-001[Q-DEV-001] and xref:q-dev-004[Q-DEV-004] as review evidence for future runtime decisions. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -include::generated/r-005-ruby-seen-as-target-architecture-traceability.adoc[] +include::generated/r-005-ruby-seen-as-target-architecture-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * When should the project decide the long-term implementation language for validators and generators? -== Review Notes +=== Review Notes Confirm decision timing and language-selection criteria before marking this risk reviewed. diff --git a/src/docs/arc42/11-risks-and-technical-debt/r-006-unclear-adapter-boundaries.adoc b/src/docs/arc42/11-risks-and-technical-debt/r-006-unclear-adapter-boundaries.adoc index 898616c..9447c8f 100644 --- a/src/docs/arc42/11-risks-and-technical-debt/r-006-unclear-adapter-boundaries.adoc +++ b/src/docs/arc42/11-risks-and-technical-debt/r-006-unclear-adapter-boundaries.adoc @@ -20,22 +20,22 @@ relations: metadata_version: '1.0' --- [[r-006-unclear-adapter-boundaries]] -= R-006: Adapter Boundaries Remain Unclear +== R-006: Adapter Boundaries Remain Unclear -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because differences between AI engines are not yet well understood, runtime-specific guidance may be placed inconsistently, leading to coupling in core skills or duplicated adapter documentation. -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -47,25 +47,25 @@ core skills or duplicated adapter documentation. | Confidence | Medium. |=== -== Mitigation Options +=== Mitigation Options * Keep runtime details under `adapters/` until xref:q-arch-006[Q-ARCH-006] is resolved. * Review runtime-specific changes against xref:qs-005-adapter-boundary[]. * Add concrete examples when engine differences become known. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -include::generated/r-006-unclear-adapter-boundaries-traceability.adoc[] +include::generated/r-006-unclear-adapter-boundaries-traceability.adoc[leveloffset=+1] -== Open Questions +=== Open Questions * Which concrete runtime differences must be documented under adapters? -== Review Notes +=== Review Notes Confirm xref:q-arch-006[Q-ARCH-006] with examples before marking this risk reviewed. diff --git a/templates/adr.adoc b/templates/adr.adoc index e3cc6ba..39ee8ad 100644 --- a/templates/adr.adoc +++ b/templates/adr.adoc @@ -17,45 +17,45 @@ relations: reviewed: false --- [[adr-000-short-title]] -= ADR-000: Short Decision Topic +== ADR-000: Short Decision Topic -== Status +=== Status Proposed. This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner. -== Decision +=== Decision We propose to choose the selected option. -== Context +=== Context Describe the problem, forces, constraints, affected architecture artifacts, and source-code evidence inspected before writing this decision. -== Decision Drivers +=== Decision Drivers * Driver 1. * Driver 2. * Driver 3. -== Considered Options +=== Considered Options -=== Option 1: Name +==== Option 1: Name Describe benefits, costs, risks, and fit to the drivers. -=== Option 2: Name +==== Option 2: Name Describe benefits, costs, risks, and fit to the drivers. -=== Option 3: Name +==== Option 3: Name Describe benefits, costs, risks, and fit to the drivers. -== Pugh Matrix +=== Pugh Matrix Use `+1` for better support, `0` for neutral support, and `-1` for weaker support. Mark cells with `?` when assessment requires human review. Add each @@ -72,21 +72,21 @@ the sum for that option is `?`. s| Sum s| ? s| 0 s| ? |=== -== Consequences +=== Consequences -=== Positive +==== Positive * Positive consequence. -=== Negative +==== Negative * Negative consequence. -=== Neutral or Follow-Up +==== Neutral or Follow-Up * Follow-up decision or implementation concern. -== Impact +=== Impact [cols="1,1,3", options="header"] |=== @@ -95,7 +95,7 @@ s| Sum s| ? s| 0 s| ? | xref:risk.adoc#risk-000-short-title[RISK-000-short-title] | introduced | Explain the risk impact. |=== -== Traceability +=== Traceability [cols="1,1,3", options="header"] |=== @@ -103,14 +103,14 @@ s| Sum s| ? s| 0 s| ? | `addresses` | xref:quality-scenario.adoc#qs-000-short-title[QS-000-short-title] | Explain the relation. |=== -== Assumptions +=== Assumptions * Assumption requiring review. -== Open Questions +=== Open Questions * Question for the accountable owner. -== Review Notes +=== Review Notes State what must be confirmed before this ADR can be marked reviewed or accepted. diff --git a/templates/quality-scenario.adoc b/templates/quality-scenario.adoc index 7c7c79f..7efba61 100644 --- a/templates/quality-scenario.adoc +++ b/templates/quality-scenario.adoc @@ -17,16 +17,16 @@ relations: reviewed: false --- [[qs-000-short-title]] -= QS-000: Short Quality Scenario Title +== QS-000: Short Quality Scenario Title -== Status +=== Status Proposed. The response measure is a reviewable target. Treat uncertain values as assumptions until confirmed. -== Scenario +=== Scenario [cols="1,3", options="header"] |=== @@ -39,15 +39,15 @@ assumptions until confirmed. | Response Measure | Measurable threshold or target. |=== -== Rationale +=== Rationale Explain why this scenario matters and which stakeholder outcome it supports. -== Assumptions +=== Assumptions * Assumption requiring review. -== Traceability +=== Traceability [cols="1,1,3", options="header"] |=== @@ -55,11 +55,11 @@ Explain why this scenario matters and which stakeholder outcome it supports. | `depends_on` | xref:adr.adoc#adr-000-short-title[ADR-000-short-title] | Explain the relation. |=== -== Open Questions +=== Open Questions * Question for the accountable owner. -== Review Notes +=== Review Notes Mark this scenario as reviewed only after the measure, environment, and stakeholder value are confirmed. diff --git a/templates/risk.adoc b/templates/risk.adoc index 5d47a13..abd40f5 100644 --- a/templates/risk.adoc +++ b/templates/risk.adoc @@ -17,20 +17,20 @@ relations: reviewed: false --- [[risk-000-short-title]] -= RISK-000: Short Risk Title +== RISK-000: Short Risk Title -== Status +=== Status Proposed. This risk is AI-assisted. It identifies a concern for review and does not decide risk acceptance. -== Risk Statement +=== Risk Statement Because , may occur, leading to . -== Assessment +=== Assessment [cols="1,3", options="header"] |=== @@ -42,17 +42,17 @@ Because , may occur, leading to . | Confidence | Low, medium, or high. |=== -== Mitigation Options +=== Mitigation Options * Mitigation option. * Monitoring or review option. -== Decision or Acceptance +=== Decision or Acceptance The risk remains under analysis until the accountable owner confirms the assessment and mitigation path. -== Traceability +=== Traceability [cols="1,1,3", options="header"] |=== @@ -60,10 +60,10 @@ assessment and mitigation path. | `depends_on` | xref:adr.adoc#adr-000-short-title[ADR-000-short-title] | Explain the relation. |=== -== Open Questions +=== Open Questions * Question for risk owner. -== Review Notes +=== Review Notes State what must be confirmed before this risk can be marked reviewed or accepted. From 96f8fa69ab8a1084b9b80aa6dc8de1fc220131d1 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Sat, 4 Jul 2026 18:29:57 +0200 Subject: [PATCH 2/2] Asciidoc rendering adopted so includes do not break the rendered result --- scripts/validate-metamodel.rb | 1 + test/validate_metamodel_test.rb | 1 + 2 files changed, 2 insertions(+) diff --git a/scripts/validate-metamodel.rb b/scripts/validate-metamodel.rb index e87c3ec..c77b1df 100755 --- a/scripts/validate-metamodel.rb +++ b/scripts/validate-metamodel.rb @@ -777,6 +777,7 @@ def render(chapter, details, output_path = include_output_path(chapter)) sorted.each do |artifact| target = artifact.path.expand_path.relative_path_from(output_path.dirname).to_s + lines << '' lines << "include::#{target}[]" lines << '' end diff --git a/test/validate_metamodel_test.rb b/test/validate_metamodel_test.rb index c692781..dfa5a7a 100644 --- a/test/validate_metamodel_test.rb +++ b/test/validate_metamodel_test.rb @@ -281,6 +281,7 @@ def test_chapter_include_fragment_output_is_deterministic_and_sorted_by_artifact assert_equal first, second assert_includes first, '// Generated from arc42 chapter metadata for DOC-01000-introduction-and-goals. Do not edit manually.' + assert_includes first, "\n\ninclude::../01-introduction-and-goals/doc-01001-quality-goals.adoc[]\n\n" assert_operator first.index('include::../01-introduction-and-goals/doc-01001-quality-goals.adoc[]'), :<, first.index('include::../01-introduction-and-goals/doc-01002-requirements-overview.adoc[]') ensure