Skip to content

copilot-instructions.md

Latest commit

 

History

History
294 lines (221 loc) · 30.8 KB

copilot-instructions.md

File metadata and controls

294 lines (221 loc) · 30.8 KB

Copilot Instructions

Build & Test

# Build
dotnet build InventarWorkerService.sln

# Run all tests
dotnet test

# Unit tests only
dotnet test InventarWorkerCommonTest/InventarWorkerCommonTest.csproj
dotnet test CtrlWorkerCommonTest/CtrlWorkerCommonTest.csproj

# Single test method
dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"

# Integration tests (requires InventarWorkerService running on http://localhost:5000 first)
dotnet run --project InventarWorkerService/InventarWorkerService.csproj
dotnet test InventarWorkerServiceIntegrationTest/InventarWorkerServiceIntegrationTest.csproj

# Collect coverage (CI gate >=70%, target >=80%)
dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults

# Check package currency
dotnet list package --outdated

# Regenerate documentation when API/XML docs change
docfx docfx.json

The generated DocFX directories api/ and _site/ are build artifacts. Keep them out of Git. Published documentation is deployed automatically from main via .github/workflows/docs-pages.yml.

Branching Workflow (Mandatory)

  • main is protected and must not receive direct feature commits.
  • Create a new branch for each feature/fix/change.
  • Merge to main only through pull requests with test evidence.
  • When a dedicated feature branch has implemented the requirements of a Lastenheft, rename that file to Lastenheft_<topic>.<feature-branch>.md so the delivered scope stays traceable.
  • Work branches may use either the existing topic naming or the numbered Spec-Kit form NNN-short-description.

Directory.Build.props carries the repo-wide Version, AssemblyVersion, and FileVersion values for all projects using Major.Minor.Patch.Build:

  • Minor = current Spec-Kit feature/branch number, interpreted numerically as the canonical PR number for versioning (002 -> 2) and used immediately even before a GitHub PR exists
  • Patch = current commit count in that feature/PR branch (after committing the current change)
  • Build = manual build counter incremented before every dotnet build or dotnet test

On numbered Spec-Kit branches, align those three version fields before pushing.

Architecture

This is a .NET 10 / C# 14.0 multi-project solution for cross-platform IT hardware/software inventory.

Data flow:

Each machine runs InventarWorkerService (REST agent)
    ↑ queried by HarvesterWorkerService (central collector → SQLite/MongoDB/PostgreSQL)
    ↑ also queried by InventarViewerApp (Terminal.Gui TUI → local SQLite)

Projects:

  • InventarWorkerService — ASP.NET Core Worker + REST API on each monitored machine. Endpoints: GET /api/inventar/hardware|software|full|status. Swagger at /swagger in Development.
  • HarvesterWorkerService — Central collector; reads machine list from SQLite, calls each agent, writes inventory to SQLite/MongoDB/PostgreSQL.
  • InventarViewerApp — Terminal.Gui TUI; calls agent API via RestSharp (ApiService), persists locally via Dapper+SQLite (DatabaseService).
  • InventarWorkerCommon — Shared domain library. New shared models go here; new services register via DI in the consuming project's Program.cs.
  • CtrlWorkerCommon/App/Cmdlet/PS — Windows Service control utilities and PowerShell cmdlets.

Worker loop timing: 30_000ms in #if DEBUG, 86_400_000ms (24h) in Release.

Service deployment: Runs as Windows Service (AddWindowsService), systemd (AddSystemd), or launchd.

Key Conventions

Language split: Explanatory texts in comments/docs MUST be bilingual (German first, then English, CEFR B2). UI labels and log messages remain German.

Naming:

  • Types/methods/properties/constants: PascalCase
  • Local variables, parameters, private fields: camelCase (private fields prefixed _)
  • Test methods: <UnitUnderTest>_<Scenario>_<ExpectedOutcome>
  • DB table/column names: PascalCase

Nullable reference types are enabled everywhere — use string? for optional values.

Toolchain: Use .NET 10 with C# 14.0.

Async: All I/O-bound public service methods return Task or Task<T>.

Coverage: CI coverage must be >=70% and must target >=80%.

Serialization: System.Text.Json with camelCase naming policy throughout. Do not use Newtonsoft.Json. All existing usage of Newtonsoft.Json MUST be migrated to System.Text.Json and the Newtonsoft.Json NuGet package MUST be removed from all projects and the solution.

Dependencies: Keep NuGet packages on latest stable versions; document any pinning exceptions.

HTTP client: RestSharp in InventarViewerApp; integration tests use Playwright's APIRequestContext.

Data access: Dapper + Microsoft.Data.Sqlite. SQL is written as explicit raw strings with IF NOT EXISTS guards, PascalCase identifiers, and indices on frequently queried columns.

ServiceStatusWriter writes three output types per service: status (JSON), statistics (JSON), log (text). Identified by a service name prefix — default "" for the agent, "harvester-service" for the harvester.

CSV import: CsvHelper with explicit class maps (see InventarWorkerCommon/Services/Csv).

Error handling: Catch at boundary layers (API controllers return StatusCode(500, new { error = ... }); TUI shows MessageBox.ErrorQuery). Use using statements on DB connections.

XML doc comments are mandatory on all public API members; CS1591 must not be globally suppressed.

Didactic comments: Add bilingual block/line comments for non-public members/variables where XML docs do not apply.

DocFX sync: Run docfx docfx.json whenever API signatures or XML documentation changes. The generated api/ metadata and _site/ HTML output must remain untracked. GitHub Pages deployment is handled by .github/workflows/docs-pages.yml.

Test framework: MSTest. Use [TestInitialize]/[TestCleanup] for per-test setup. Assert default property values (empty strings, 0, false, null) explicitly in unit tests.

Where to Put New Code

What Where
Shared domain models InventarWorkerCommon/Models/
New services (shared) InventarWorkerCommon/Services/ + register in Program.cs
New API endpoints InventarWorkerService/Controllers/ + add integration test
New DB tables/views Extend SqliteDbService; add indices; use IF NOT EXISTS
App-specific persistence/services Under the app's own Services/ folder

Project Statistics

  • When shared AI-agent guidance, workflow conventions, or statistics methodology changes, review and update AGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md together when they are affected.
  • Shared guidance must not be updated in only one of these files; any intentional agent-specific divergence must be documented in the same change.
  • Maintain docs/project-statistics.md as the living statistics ledger for the repository.
  • Update the file after each completed Spec-Kit implementation phase, after each agent-driven repository change, or when a refresh is explicitly requested.
  • Within the ## Fortschreibungsprotokoll table, keep entries in strict chronological order: oldest entry at the top, newest and most recently added entry at the bottom; entries with the same date keep their insertion order.
  • Keep a final top-level ## Gesamtstatistik block as the last section of docs/project-statistics.md; do not append any later top-level section after it.
  • Inside that final ## Gesamtstatistik block, keep compact ASCII-only diagrams directly below the textual overall summary so the overall artifact mix, documented branch/phase curves, acceleration factors, and the comparison between experienced-developer effort, Thorsten-solo effort, and visible AI-assisted delivery stay readable in plain Markdown.
  • Keep each short CEFR-B2 explanation directly adjacent to its matching ASCII diagram group, and keep the statistics block text-first so Braille displays, screen readers, and text browsers do not depend on color or layout alone.
  • Each update must capture branch or phase, observable work window, production/test/documentation line counts, main work packages, the conservative manual baseline of 80 manually created lines per workday across code, tests, and documentation, and the repo-specific Thorsten-Solo comparison baseline of 100 lines per workday for this native .NET codebase.
  • When effort is converted into months, use explicit assumptions such as 21.5 workdays per month and, if applicable, 30 vacation days per year under a TVoeD-style calendar.
  • When reporting acceleration, compare both manual references against visible Git active days and label the result as a blended repository speedup rather than a stopwatch measurement.
  • When hour values are shown, convert the day-based estimates with the TVoeD working-day baseline of 7.8 hours (7h 48m) per day.

Inclusion & Accessibility

  • Explanatory documentation for learner-facing and governance content MUST be bilingual with German first and English second at CEFR-B2 readability.
  • Large normative documents such as Pflichtenheft*.md and Lastenheft*.md may use a synchronized English sidecar with suffix .EN.md instead of one oversized inline-bilingual file; the German version remains canonical unless explicitly marked otherwise.
  • Follow Programmierung #include<everyone>: Diese Lernbeispiele richten sich an Azubis (Fachinformatiker AE/SI), die auf Deutsch und Englisch arbeiten, sowie an sehbehinderte Lernende, die Braille-Displays, Screen-Reader oder Textbrowser nutzen. Barrierefreiheit ist Pflichtanforderung, kein Nice-to-have. / These learning examples target apprentices working in German and English, and visually impaired learners using Braille displays, screen readers, or text browsers. Accessibility is mandatory.
  • Treat WCAG 2.2 conformance level AA as the practical baseline for generated HTML documentation.
  • If docfx output is regenerated, the same work item must also run a text-oriented accessibility review with Playwright + @axe-core/playwright and lynx.
  • Recommended A11y toolchain for DocFX-based repos: Node 24 LTS, npm, Playwright, @axe-core/playwright, and lynx.

Workspace Baseline (vollständig aus RiderProjects/.github/copilot-instructions.md)

Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifische Regeln in dieser Datei haben Vorrang, wenn sie konkreter sind. GitHub Copilot liest keine übergeordneten copilot-instructions.md-Dateien automatisch; daher sind die Workspace-Regeln hier vollständig eingebettet.

Dokumentation

  • Leitprinzip: Programmierung #include<everyone> — Diese Lernbeispiele richten sich an Azubis (Fachinformatiker AE/SI), die auf Deutsch und Englisch arbeiten, sowie an sehbehinderte Lernende, die Braille-Displays, Screen-Reader oder Textbrowser nutzen. Barrierefreiheit ist Pflichtanforderung, kein Nice-to-have. / These learning examples target apprentices working in German and English, and visually impaired learners using Braille displays, screen readers, or text browsers. Accessibility is mandatory.
  • Deutsch und Englisch zielen beide auf CEFR-B2-Lesbarkeit; Reihenfolge: Deutsch zuerst, Englisch danach.
  • Die deutsche Fassung ist kanonisch, außer dieses Repository markiert eine andere Sprache explizit als primär.
  • Große normative Dokumente (Pflichtenheft*.md, Lastenheft*.md) verwenden eine synchronisierte .EN.md-Sidecar-Datei statt einer überlangen Inline-Zweisprachigkeit.
  • Bilinguales CEFR-B2-Deliverable ist ein formales Abnahmekriterium für learner-facing Dokumentation und aktive Anforderungsartefakte.

Barrierefreiheit (Accessibility)

  • Generiertes HTML-Dokumentation muss WCAG 2.2 Level AA erfüllen.
  • Semantische Überschriften, Listen, Tabellen und ASCII/Text-First-Diagramme bevorzugen.
  • Wesentliche Bedeutung NICHT nur durch Farbe, Layout oder Maus-only-Affordances kodieren.
  • Guides, Statistiken, Beispiele und generierte API-Dokumentation müssen in text-first Assistive-Setups lesbar bleiben.
  • Der dokumentierte A11Y-Nachweispfad ist ein formales Abnahmekriterium für learner-facing Dokumentation und aktive Anforderungsartefakte.

DocFX-Review-Regel

  • Wenn ein Repository Dokumentation mit docfx neu generiert, muss dasselbe Work-Item auch den passenden A11Y-Review ausführen.
  • Bevorzugtes Toolchain: Node 24 LTS, npm, @axe-core/playwright, lynx.
  • Playwright + axe für automatisierte Smoke-Checks verwenden; lynx als zusätzlichen Textbrowser-Prüfpfad.

Statistik-Ledger

  • docs/project-statistics.md als lebendes Ledger pflegen, wenn diese Datei im Repository existiert.
  • Den abschließenden Top-Level-Block ## Gesamtstatistik als letzten Abschnitt halten.
  • ASCII-Diagramme textbrowserfreundlich halten und kurze CEFR-B2-Erklärungen direkt neben das jeweilige Diagramm platzieren.
  • Dokumentierte Beschleunigungsfaktoren aus Agentic AI plus Spec-Kit/SDD einschließen sowie einen Vergleich zwischen experienced-developer-Aufwand, Thorsten-solo-Aufwand und dem sichtbaren AI-assisted-Delivery-Fenster (sofern dieses Repository diese Metriken führt).

Änderungsdisziplin

  • Nicht davon ausgehen, dass eine Cross-Repository-Regel projekt-spezifische Build-, Test- oder Release-Anforderungen ersetzt.
  • Wenn eine gemeinsame Regel sich ändert und mehrere Repositories betroffen sind, lokale Projektguidance und das jeweilige Statistik-Ledger gemeinsam aktualisieren.
  • CODEX_CROSS_REPO_PROMPTS.md synchron halten, wenn sich übergreifende Prompting-Guidance ändert, damit der wiederverwendbare Prompt mit der aktuellen Baseline übereinstimmt.

Level-2-Umgebungsregister / Level-2 Environment Registry

  • Die zentrale constitution.md enthält das verbindliche Level-2 Project Environment Registry.
  • Spec-Kit-Pläne und Copilot-Arbeit in Level-2-Projekten müssen die passende Registry-Zeile als verbindlichen Kontext für Runtime, Build/Test, A11Y, Statistik und Agentenflächen verwenden.
  • Änderungen an einer Level-2-Runtime, Toolchain oder Statistik-Basis müssen constitution.md, .specify/memory/constitution.md und betroffene KI-Agenten-Dateien gemeinsam prüfen.

The central constitution.md contains the binding Level-2 Project Environment Registry. Spec-Kit plans and Copilot work in Level-2 projects must use the matching registry row as binding context for runtime, build/test, A11Y, statistics, and agent surfaces. Changes to Level-2 runtime, toolchain, or statistics baselines require a joint review of constitution.md, .specify/memory/constitution.md, and affected AI-agent files.

Memory-Safe Languages (MSL) / Speichersichere Sprachen

  • Level-2-Projekte SOLLEN eine speichersichere Sprache (Memory-Safe Language, MSL) als primäre Laufzeit verwenden, wenn die Zielplattform es erlaubt.
  • Verbindliche MSL-Erlaubnisliste, Regeln und Begründungspflicht: siehe constitution.md, Prinzip XI.
  • MSL-Kurzliste: Rust, Swift, C#, F#, Java, Kotlin, Scala, Go, Dart, Python, Ruby, JavaScript, TypeScript, Haskell, OCaml, Erlang, Elixir, Ada, SPARK.
  • Nicht MSL (Begründung im Level-2-constitution.md erforderlich): C, C++, klassisches Objective-C, Assembly, cc65-C89, Zig (pre-1.0), Nim (manual), D ohne GC.
  • In Nicht-MSL-Repositories (z. B. C64Projects/cc65) die im Level-2-constitution.md hinterlegte Begründung im Plan- und Task-Kontext erwähnen.
  • speckit.constitution und speckit.specify SOLLEN bei Nicht-MSL-Primärsprache einen nicht blockierenden Hinweis ausgeben (Tooling-Aufgabe, separate Umsetzung).
  • Änderungen an dieser Empfehlung erfordern ein gemeinsames Update in constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md und .github/copilot-instructions.md.

Level-2 projects SHOULD use a memory-safe language (MSL) as their primary runtime when the target platform allows. Authoritative rules: constitution.md, Principle XI. MSL short list: Rust, Swift, C#/F#, Java/Kotlin/Scala, Go, Dart, Python, Ruby, JavaScript/TypeScript, Haskell, OCaml, Erlang/Elixir, Ada/SPARK. Non-MSL languages (C, C++, Assembly, cc65, Zig pre-1.0, …) require a documented justification in the Level-2 constitution.md. In non-MSL repositories (e.g. C64Projects/cc65), surface the documented justification in plans and tasks. speckit.constitution and speckit.specify SHOULD emit a non-blocking advisory warning when the primary language is not an MSL — tracked as a separate tooling task. Changes to this recommendation require a joint update across constitution.md, .specify/memory/constitution.md, and all four agent guidance files.

Sichere Code-Erzeugung / Secure Code Generation (ISO 27001/27002 A.8.28)

  • KI-generierter Code MUSS den etablierten Secure-Coding-Best-Practices der Zielsprache und des Frameworks folgen. LLMs erzeugen nicht zuverlässig sicheren Code; explizite Durchsetzung ist erforderlich.
  • Verbindliche Regeln und sprachspezifische Anforderungen: siehe constitution.md, Prinzip XII.
  • Sprachspezifische Kurzregeln:
    • C / C89: Bounds-Checking, kein gets(), kein ungeprüftes sprintf()/strcpy(), CERT C.
    • C# / .NET: parametrisierte Queries, Output-Encoding gegen XSS, Anti-Forgery-Tokens, sichere Deserialisierung, Microsoft Secure Coding Guidelines.
    • SQL: nur parametrisierte Statements, kein dynamisches SQL aus nicht vertrauenswürdigem Input.
    • Bash: Variable in Anführungszeichen ("$var"), kein eval auf nicht vertrauenswürdigem Input, -- End-of-Options.
    • PowerShell: Set-StrictMode -Version Latest, validierte Parameter, kein Invoke-Expression auf nicht vertrauenswürdigem Input.
  • Kryptografie: aktuelle Algorithmen (AES-256, RSA >= 3072, SHA-256+, Ed25519); veraltete (MD5, SHA-1 für Signaturen, DES, RC4) nur mit expliziter Risikobegründung.
  • Fehlerbehandlung darf keine internen Zustände, Stack-Traces oder Verbindungszeichenketten an Endbenutzer preisgeben.
  • Hinzugefügte Abhängigkeiten müssen aktiv gepflegt sein und dürfen keine bekannten kritischen CVEs aufweisen.
  • Code-Reviews MÜSSEN eine Sicherheitsperspektive für Eingabeverarbeitung, Authentifizierung, Autorisierung, Kryptografie und Datei-/Netzwerk-I/O enthalten.
  • Änderungen an dieser Regel erfordern ein gemeinsames Update in constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md und .github/copilot-instructions.md.

AI-generated code MUST follow the secure-coding best practices of the target language and framework. Authoritative rules: constitution.md, Principle XII. Language-specific short rules: C/C89 — bounds checking, no gets(), CERT C; C#/.NET — parameterised queries, output encoding, anti-forgery tokens, Microsoft Secure Coding Guidelines; SQL — parameterised statements only; Bash — quoted variables, no eval on untrusted input, -- sentinel; PowerShell — Set-StrictMode, no Invoke-Expression on untrusted input. Cryptography: use current algorithms (AES-256, SHA-256+, Ed25519); deprecated (MD5, SHA-1 for signatures, DES, RC4) only with explicit risk acknowledgement. Error handling must not expose internals. Dependencies must have no known critical CVEs. Code reviews must include a security perspective for input handling, auth, crypto, and I/O. Changes require a joint update across constitution.md, .specify/memory/constitution.md, and all four agent guidance files.

Sichere Software-Architektur / Secure Software Architecture (ISO 27001/27002 A.8.27)

  • KI-generierte und menschlich geschriebene Software-Architektur MUSS etablierten sicheren Architekturprinzipien folgen. Sicherer Code (Prinzip XII) ohne sichere Architektur reicht nicht aus — beide Ebenen müssen zusammenwirken.
  • Verbindliche Regeln und sprachspezifische Architekturvorgaben: siehe constitution.md, Prinzip XIII.
  • Verbindliche Architekturprinzipien:
    • Trust Boundaries: Explizite Vertrauensgrenzen definieren; alle Eingaben an Vertrauensgrenzen validieren und bereinigen.
    • Defense in Depth: Mindestens zwei unabhängige Sicherheitsschichten für kritische Assets.
    • Least Privilege: Jede Komponente, jeder Dienst und Prozess arbeitet mit minimalen Berechtigungen.
    • Fail-Safe Defaults: Zugriff standardmäßig verweigern, explizit gewähren; Fehlerpfade fallen in sicheren Zustand zurück.
    • Angriffsfläche reduzieren: Ungenutzte Endpunkte, Dienste und Debug-Funktionen deaktivieren oder entfernen.
    • Separation of Concerns: Authentifizierung, Autorisierung, Logging und Eingabevalidierung als Cross-Cutting Concerns implementieren, nicht ad-hoc verstreuen.
    • Sichere Konfiguration: Secrets in plattformgeeigneten Secret-Stores (z. B. Azure Key Vault, macOS Keychain), nie im Quellcode oder in Git-tracked Config-Dateien.
    • Supply-Chain-Sicherheit: Abhängigkeiten aus verifizierten Registries; Lock-Files committen; verwundbare Abhängigkeiten vor Release ersetzen.
  • Änderungen an dieser Regel erfordern ein gemeinsames Update in constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md und .github/copilot-instructions.md.

AI-generated and human-written software architecture MUST follow secure-architecture principles. Authoritative rules: constitution.md, Principle XIII. Core principles: trust boundaries (validate all input at system boundaries), defense in depth (at least two independent security layers), least privilege (minimum required permissions), fail-safe defaults (deny by default), attack surface reduction (disable unused features), separation of concerns (auth/logging/validation as cross-cutting concerns), secure configuration (secrets in secret stores, never in code or Git), supply-chain security (verified registries, lock files, no known-vulnerable dependencies). Principles XII + XIII together form the complete secure-development approach: XII = tactical code-level security, XIII = strategic architecture-level security. Changes require a joint update across constitution.md, .specify/memory/constitution.md, and all four agent guidance files.

Allgemeine Architektur-Governance / General Architecture Governance

  • Struktur-, Schnittstellen-, Qualitätsattribut-, Laufzeit-, Deployment- oder Wartbarkeitsänderungen müssen iSAQB/arc42-Architekturevidenz prüfen.
  • Standardpfad: docs/architecture/; ADRs fuer allgemeine Architekturentscheidungen liegen unter docs/architecture/adr/.
  • Verfügbare Templates: architecture-vision-template.md, context-view-template.md, building-block-view-template.md, runtime-view-template.md, deployment-view-template.md, architecture-decision-template.md, architecture-risks-template.md, quality-scenarios-template.md.

Structural, interface, quality-attribute, runtime, deployment, or maintainability changes must evaluate iSAQB/arc42 architecture evidence. Default path: docs/architecture/; general architecture ADRs live under docs/architecture/adr/. Use the matching templates when the artefact applies.

Sicherheitsdokumentation / Security Documentation (XII–XVIII Extensions)

  • Jedes Level-2-Projekt MUSS die folgenden Sicherheitsdokumente pflegen, basierend auf den Templates in .specify/templates/:
    • Bedrohungsmodell / Threat Model (threat-model-template.md) — STRIDE-Methodik, Trust Boundaries, Risikobewertung, CAPEC-Referenzen (Prinzip XIII + XVII)
    • Security Architecture Decision Records (S-ADR) (adr-template.md) — architektonische Sicherheitsentscheidungen mit Compliance-Nachweis (Prinzip XIII)
    • arc42 Section 8 Sicherheits-Querschnittskonzepte (arc42-security-template.md) — Authentifizierung, Autorisierung, Verschlüsselung, Eingabevalidierung, Fehlerbehandlung, Logging, Abhängigkeiten, Deployment (Prinzip XIII)
    • Sicherheits-Checkliste / Security Checklist (security-checklist-template.md) — sprachspezifische Code-Review-Checkliste (Prinzip XII)
    • Abhängigkeits-Audit / Dependency Audit (dependency-audit-template.md) — CVE-Tracking, Lizenz-Compliance, Supply-Chain-Sicherheit (Prinzip XII)
    • MSL-Anwendbarkeit / MSL Applicability (msl-applicability-template.md) — Laufzeit-/Sprachwahl und Begründung (Prinzip XI)
    • Sichere Sprachregeln / Secure Coding Language Rules (secure-coding-language-rules-template.md) — sprachspezifische Sicherheitsregeln (Prinzip XII)
    • Sicherheits-Qualitätsszenarien / Security Quality Scenarios (security-quality-scenarios-template.md) — iSAQB CPSA-F Qualitätsszenario-Methodik (Prinzip XII + XIII, SHOULD)
    • ASVS-Verifikation / ASVS Verification (asvs-verification-template.md) — OWASP ASVS Level, Scope und Evidenz (Prinzip XV, Web-/API-Projekte MUST)
    • Supply-Chain-Evidenz / Supply Chain Evidence (supply-chain-evidence-template.md) — SBOM, VEX, SLSA, OpenSSF Scorecard (Prinzip XVI, releasefähige Projekte MUST)
    • Zero-Trust-Anwendbarkeit / Zero Trust Applicability (zero-trust-applicability-template.md) — NIST SP 800-207-Bewertung (Prinzip XVIII, verteilte Systeme SHOULD)
    • SAMM-Bewertung / SAMM Assessment (samm-assessment-template.md) — OWASP SAMM Reifegrad und Verbesserungsplan (Prinzip XVIII, langlebige Projekte SHOULD)
    • CRA-Anwendbarkeit / CRA Applicability (cra-applicability-template.md) — EU Cyber Resilience Act Scope und Nachweise (Prinzip XIX)
  • Projektspezifische Instanzen werden in docs/security/ gepflegt; S-ADRs als einzelne Dateien in docs/security/adr/.

Every Level-2 project MUST maintain security documents based on templates in .specify/templates/: threat model (STRIDE+CAPEC), S-ADRs, arc42 Section 8 security concepts, security checklist, dependency audit, MSL applicability, secure-coding language rules, security quality scenarios (SHOULD), ASVS verification (web/API MUST), supply-chain evidence (release-capable MUST), Zero Trust applicability note (distributed systems SHOULD), SAMM assessment (long-lived projects SHOULD), and CRA applicability evidence. Project-specific instances live in docs/security/; S-ADRs in docs/security/adr/. See constitution.md, Principles XI–XIX for authoritative requirements.

Gemeinsame Governance-Ergaenzung / Shared Governance Addendum

  • Alle nutzerseitigen Artefakte muessen barrierefrei gedacht und geprueft werden: CLI-Ausgaben, Dokumentation, HTML, UI und generierte Templates; WCAG 2.2 Level AA ist die Standard-Basis, sobald die Kriterien auf das Artefakt anwendbar sind.

  • All user-facing artefacts must be designed and reviewed for accessibility: CLI output, documentation, HTML, UI, and generated templates; WCAG 2.2 Level AA is the default baseline wherever the criteria apply.

  • Fuer C#/.NET-Repositories gilt standardmaessig eine Thorsten-Solo-Basis von 125 Zeilen/Arbeitstag, sofern das Repo keinen abweichenden, begruendeten Wert dokumentiert.

  • The default Thorsten-solo baseline for C#/.NET repositories is 125 lines/workday unless the repository documents a justified deviation.

Sicherheitsstandards & Anwendbarkeit / Security Standards & Applicability

  • Vor jeder Level-2-Aufgabe die anwendbaren Sicherheitsstandards aus constitution.md, Prinzipien XIV-XVIII bestimmen und explizit benennen.
  • NIST SSDF und CWE Top 25 gelten immer für Level-2-Arbeit.
  • OWASP ASVS gilt für Web-, API-, HTTP- und authentifizierte Dienste; der gewählte ASVS-Level muss benannt werden.
  • SBOM gilt für releasefähige oder verteilbare Artefakte; VEX, wenn bekannte Schwachstellen in ausgelieferten oder geprüften Komponenten bewertet werden müssen.
  • SLSA gilt als Soll-Vorgabe für CI/CD- oder veröffentlichte Artefakte; Zero Trust ist für verteilte, servicebasierte, cloudnahe oder remote-verwaltete Systeme explizit zu prüfen.
  • CAPEC soll in Bedrohungsmodellen für die risikoreichsten Angriffswege verwendet werden; OWASP SAMM soll für langlebige Projekte/Workspaces in Verbesserungspläne einfließen.
  • OWASP Cheat Sheet Series, OWASP Proactive Controls und bei öffentlichen OSS-Repositories oder kritischen Abhängigkeiten OpenSSF Scorecard sind als ergänzende Referenzen zu berücksichtigen.
  • Nichtanwendbarkeit immer als N/A mit kurzer Begründung dokumentieren; keine stillschweigende Auslassung.

At the start of every Level-2 task, determine and name the applicable security standards from constitution.md, Principles XIV-XVIII. NIST SSDF and CWE Top 25 always apply. OWASP ASVS applies to web/API/HTTP/auth-bearing services; SBOM applies to releasable or distributable artefacts; VEX applies when known vulnerabilities in shipped/evaluated components need a disposition statement. SLSA is the target model for CI/CD and published artefacts; Zero Trust must be explicitly evaluated for distributed, service-based, cloud, or remotely managed systems. CAPEC, OWASP SAMM, OWASP Cheat Sheet Series, OWASP Proactive Controls, and OpenSSF Scorecard are supporting references where relevant. Record non-applicability as N/A with justification rather than omitting it silently.

Agentischer Security-Workflow / Agentic Security Workflow

  • In spec.md, plan.md und tasks.md die anwendbaren Standards samt Evidenzpfad festhalten.
  • Bei Bedrohungsmodellen STRIDE als Basis und bei risikoreichen Flows zusätzlich relevante CAPEC-Patterns verwenden.
  • Bei Web/API-Features den ASVS-Level und den Verifikationsumfang in docs/security/ oder gleichwertiger Projektdokumentation ablegen.
  • Bei Release-/Artefakt-Arbeit SBOM, VEX, Provenance/SLSA-Nachweise und gegebenenfalls OpenSSF Scorecard in Release- oder Sicherheitsdokumentation einplanen.
  • Bei Architekturänderungen Zero Trust-Anwendbarkeit und bei langlebigen Projekten SAMM-Folgeaktionen prüfen.
  • Bei allgemeinen Architekturänderungen iSAQB/arc42-Evidenz unter docs/architecture/ prüfen.
  • Bei A11Y-relevanten Artefakten docs/accessibility/-Evidenz und Sprach-Tags fuer Markdown-Codebloecke pruefen.
  • Default-Evidenzpfad: docs/security/asvs-verification.md, docs/security/supply-chain-evidence.md, docs/security/zero-trust-applicability.md, docs/security/samm-assessment.md; Abweichungen nur mit lokal dokumentierter Begründung.

Capture the applicable standards and the evidence path in spec.md, plan.md, and tasks.md. Use STRIDE as the base for threat modeling and add relevant CAPEC patterns for the highest-risk flows. For web/API work, record the chosen ASVS level and verification scope in docs/security/ or equivalent project documentation. For release and artefact work, plan SBOM, VEX, provenance/SLSA evidence, and OpenSSF Scorecard review where applicable. For security architecture, evaluate Zero Trust; for long-lived projects, consider OWASP SAMM follow-up actions. For general architecture changes, evaluate iSAQB/arc42 evidence under docs/architecture/. For A11Y-relevant artefacts, check docs/accessibility/ evidence and language-tagged Markdown code blocks. The default evidence path is docs/security/asvs-verification.md, docs/security/supply-chain-evidence.md, docs/security/zero-trust-applicability.md, and docs/security/samm-assessment.md, unless the repository documents a justified equivalent location.

For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan