refactor(contract): split architecture-documentation into vocabulary contract + arc42-authoring skill

skill/arc42-authoring/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: arc42-authoring
+description: Produce and maintain arc42 architecture documentation with cross-section traceability, structured quality scenarios, and decision–risk wiring. Use when scaffolding a new arc42 document, extending an existing one, or verifying traceability between chapters.
+metadata:
+  author: LLM-Coding
+  version: "0.1"
+  source: https://github.com/LLM-Coding/Semantic-Anchors
+license: MIT
+---
+
+# arc42 Authoring
+
+Procedural guidance for producing arc42 architecture documentation that goes beyond the template's built-in help text.
+
+## On invocation
+
+When this skill is invoked:
+
+1. **Check whether an arc42 document already exists.** Look for `src/docs/` or `docs/arc42/` in the project. If found, work incrementally — do not re-scaffold.
+
+2. **If no arc42 exists, scaffold first.** Use docToolchain `downloadTemplate` to create the "with-help" template into `src/docs/`. Each chapter's help text is its structural spec — fill and then replace it.
+
+3. **Apply the traceability rules** from [references/traceability-rules.md](references/traceability-rules.md) as you produce or review each chapter. These rules are the project's value-add over plain arc42.
+
+4. **For Chapter 10 quality scenarios**, use the six-part Quality Attribute Scenario format from [references/chapter-10-quality-scenarios.md](references/chapter-10-quality-scenarios.md).
+
+5. **For Chapter 11 Risks and Technical Debt**, follow [references/chapter-11-structure.md](references/chapter-11-structure.md).
+
+6. **For Chapter 8 Crosscutting Concepts**, follow [references/chapter-8-baseline.md](references/chapter-8-baseline.md).
+
+7. **For ADR–Risk wiring**, apply the rules in [references/adr-risk-wiring.md](references/adr-risk-wiring.md).
+
+## When to use this skill
+
+- Scaffolding a new arc42 document for a greenfield project
+- Extending an arc42 document after architecture decisions change
+- Reviewing arc42 documentation for completeness and cross-section traceability
+- Producing Chapter 10 quality scenarios in the six-part form
+- Structuring Chapter 11 with the Risks/Technical-Debt split
+
+## When NOT to use this skill
+
+- For reverse-engineering existing code into documentation — use `socratic-code-theory-recovery` instead (Phase 2 of that skill produces arc42 from an answered Question Tree)
+- For the vocabulary of what arc42, ADRs, C4, and QAS *are* — that is the `architecture-documentation` contract (always-on)

skill/arc42-authoring/references/adr-risk-wiring.md

@@ -0,0 +1,47 @@
+# ADR–Risk Wiring
+
+## Rule
+
+Each ADR's **Consequences** section names the risks the decision creates:
+
+- If the risk is already tracked in Chapter 11: reference its ID (e.g., "introduces R-003").
+- If the risk is new: either add it to Chapter 11 with a new R-NNN ID, or record the consequence as "explicitly accepted without a tracked risk" (for trivial consequences).
+
+## Inverse direction
+
+Conversely, Chapter 11 risks that are *caused by* a decision reference the ADR that introduced them.
+
+## Unconfirmed decisions
+
+When the rationale behind a decision is inferred (not confirmed by the team):
+
+- ADR Status: **"Accepted (inferred)"**
+- Pugh Matrix cells needing team judgment: marked `?` rather than guessed
+
+This preserves honesty — the documentation records what is known vs. what is assumed.
+
+## Scaffolding
+
+When creating a new ADR, use this template:
+
+```
+# ADR-NNN: <Title>
+
+## Status
+Accepted | Accepted (inferred) | Proposed | Superseded by ADR-NNN
+
+## Context
+<Why this decision is needed>
+
+## Decision
+<What was decided>
+
+## Pugh Matrix
+| Criterion | Option A | Option B (Baseline) | Option C |
+|-----------|----------|---------------------|----------|
+| ...       | +1       | 0                   | -1       |
+
+## Consequences
+- <Positive consequence>
+- <Negative consequence → R-NNN>
+```

skill/arc42-authoring/references/chapter-10-quality-scenarios.md

@@ -0,0 +1,28 @@
+# Chapter 10 — Quality Scenarios
+
+## Format: Six-Part Quality Attribute Scenario (Bass/Clements/Kazman)
+
+Every Chapter 10 quality scenario is written in this form:
+
+| Part | Description | Example |
+|------|-------------|---------|
+| **Source** | Who or what triggers the stimulus | End user, CI pipeline, attacker |
+| **Stimulus** | The event or condition | 1000 concurrent requests, node failure, SQL injection attempt |
+| **Artifact** | What is affected | Order Service, API Gateway, Database |
+| **Environment** | Under what conditions | Normal operation, peak load, degraded mode |
+| **Response** | What the system does | Queues excess requests, fails over, rejects input |
+| **Response Measure** | Literal, testable figure | p99 < 200ms, failover < 30s, zero data exposure |
+
+The **Response Measure** carries a literal figure, so the requirement is testable rather than an adjective ("fast", "secure", "available").
+
+## Chapter 1.2 vs. Chapter 10
+
+- **Chapter 1.2** lists only the top 3–5 quality goals — the ones that drive architecture decisions.
+- **Chapter 10** may elaborate further quality characteristics beyond those top goals.
+- Each Chapter 10 scenario is marked as either:
+  - **Concretising** a Chapter 1.2 top goal (cross-link which one), or
+  - **Derived** — a quality requirement that does not trace to a top goal but matters for the system.
+
+## Deriving scenarios from code
+
+When evidence exists in code (timeouts, budgets, SLOs, test thresholds), derive scenarios as `[ANSWERED]` with `file:line` evidence. Never invent target numbers — only the quality-goal *ranking* is a team decision.

skill/arc42-authoring/references/chapter-11-structure.md

@@ -0,0 +1,36 @@
+# Chapter 11 — Risks and Technical Debt
+
+## Structure
+
+Chapter 11 separates into two subsections:
+
+### 11.1 Risks
+
+Each risk carries:
+
+| Column | Description |
+|--------|-------------|
+| **ID** | R-NNN (stable identifier for cross-referencing from ADRs) |
+| **Risk** | What could go wrong |
+| **Probability** | Low / Medium / High |
+| **Impact** | Low / Medium / High |
+| **Priority** | Derived from probability × impact |
+| **Mitigation** | Cross-reference to Chapter 8 concept or quality scenario that mitigates it |
+
+Risks are ordered by priority (highest first).
+
+### 11.2 Technical Debt
+
+Each debt item:
+
+| Column | Description |
+|--------|-------------|
+| **ID** | TD-NNN |
+| **Debt** | What the shortcut is |
+| **Building Block** | Cross-reference to specific Chapter 5 building block it burdens |
+| **Impact** | What happens if not addressed |
+| **Effort** | Estimated effort to resolve |
+
+## ADR ↔ Risk wiring
+
+See [adr-risk-wiring.md](adr-risk-wiring.md) for how ADR Consequences connect to Risk IDs.

skill/arc42-authoring/references/chapter-8-baseline.md

@@ -0,0 +1,21 @@
+# Chapter 8 — Crosscutting Concepts Baseline
+
+## Required baseline concepts
+
+arc42 leaves Chapter 8 open. This skill requires five baseline crosscutting concepts, in this order:
+
+| Section | Concept | Key rule |
+|---------|---------|----------|
+| 8.1 | **Threat Model** | STRIDE; threats get IDs (T-001…) |
+| 8.2 | **Security** | Every mitigation references the T-IDs it closes |
+| 8.3 | **Test** | Testing pyramid; tests trace to Use Cases and Business Rules |
+| 8.4 | **Observability** | Logs, metrics, traces, audit trails |
+| 8.5 | **Error Handling** | Retry, circuit breaker, fallback, recovery |
+
+## Extension rule
+
+Add further Chapter 8.x concepts (persistence, i18n, accessibility, configuration, performance) **only when the system actually has that concern**. Do not add empty sections.
+
+## Back-referencing
+
+Chapter 8 concepts back-reference the Chapter 9 ADR that decided them. If no ADR exists for a concept, either create one or note the concept as "established practice, no decision required."

skill/arc42-authoring/references/scaffolding.md

@@ -0,0 +1,19 @@
+# Scaffolding
+
+## Initial setup with docToolchain
+
+Scaffold the arc42 "with-help" template into the project's `src/docs/` directory:
+
+```bash
+docToolchain downloadTemplate
+```
+
+Each chapter's help text is its structural spec — fill and then replace the help text as the documentation matures.
+
+## Diagram conventions
+
+- **Format**: PlantUML, not Mermaid
+- **Building blocks**: C4 via PlantUML's bundled C4-PlantUML standard library
+- **Include form**: `!include <C4/...>` (angle brackets = stdlib), never the remote `https://` URL, never vendored file copies
+- **Style**: C4 containers and components, not generic boxes
+- **Coverage**: Every context, building-block, and runtime chapter carries at least one diagram

skill/arc42-authoring/references/traceability-rules.md

@@ -0,0 +1,26 @@
+# Cross-Section Traceability Rules
+
+arc42 templates do not enforce these connections between chapters. This skill does.
+
+## The five rules
+
+1. **Quality Goal → Strategy**: Every Chapter 1.2 quality goal maps to a named approach in Chapter 4 (Solution Strategy).
+
+2. **Context ↔ Building Blocks**: The external systems in Chapter 3 (System Scope and Context) and the Chapter 5 Level-1 building-block view are the same set — one system boundary in both.
+
+3. **Building Block → Runtime**: Every Chapter 5 building block appears in at least one Chapter 6 runtime scenario. Chapter 6 includes at least one error/recovery scenario, not only the happy path.
+
+4. **ADR Index**: Chapter 9 carries an in-document ADR index (ADR | Title | Status), even when the ADRs live in a separate register.
+
+5. **Building Block Completeness**: Each Chapter 5 building block states responsibility, interface, and source location.
+
+## Verification checklist
+
+After producing or updating chapters, verify:
+
+- [ ] Every Chapter 1.2 goal appears by name in Chapter 4
+- [ ] Chapter 3 external systems = Chapter 5 Level-1 boundary elements
+- [ ] No Chapter 5 building block is absent from Chapter 6
+- [ ] Chapter 6 contains ≥1 error/recovery scenario
+- [ ] Chapter 9 index is up to date
+- [ ] Every Chapter 5 block has: responsibility, interface, source location