Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,13 @@ Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifisc
- Ä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/`:
Expand All @@ -236,14 +243,17 @@ Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifisc
- **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, security quality scenarios (SHOULD), ASVS verification (web/API MUST), supply-chain evidence (release-capable MUST), Zero Trust applicability note (distributed systems SHOULD), and SAMM assessment (long-lived projects SHOULD). Project-specific instances live in `docs/security/`; S-ADRs in `docs/security/adr/`. See `constitution.md`, Principles XII–XVIII for authoritative requirements.*
*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

Expand Down Expand Up @@ -272,9 +282,11 @@ Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifisc
- 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 architectural changes, evaluate `Zero Trust`; for long-lived projects, consider `OWASP SAMM` follow-up actions. 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.*
*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.*

<!-- SPECKIT START -->
For additional context about technologies to be used, project structure,
Expand Down
116 changes: 106 additions & 10 deletions .specify/memory/constitution.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,40 @@
<!--
Sync Impact Report
Version change: 1.11.0 -> 1.12.0
Version change: 1.12.0 -> 1.13.0
Modified principles:
- None (purely additive)
- II. Cross-Platform Parity & Documentation (aligned with preset-specific Bash/PowerShell rules)
- VII. Programmierung #include<everyone> — Inclusion & Accessibility By Default (added evidence and code-block tagging)
- XII. Secure Code Generation (added MSL and CRA evidence templates)
- XIV. Secure Development Standards & Applicability Matrix (added general architecture evidence routing)
- XVI. Supply-Chain Transparency & Build Integrity (kept CRA-linked all-level SBOM scope)
- XIX. EU Cyber Resilience Act (CRA) Compliance Awareness (linked dedicated CRA template)
Added sections:
- None
- XX. General iSAQB / arc42 Architecture Governance
Removed sections:
- None
Templates requiring updates:
- ✅ .specify/templates/plan-template.md
- ✅ .specify/templates/spec-template.md
- ✅ .specify/templates/tasks-template.md
- ✅ .specify/templates/a11y-checklist-template.md
- ✅ .specify/templates/a11y-evidence-template.md
- ✅ .specify/templates/bilingual-content-check-template.md
- ✅ .specify/templates/cli-a11y-review-template.md
- ✅ .specify/templates/agent-parity-checklist-template.md
- ✅ .specify/templates/man-page-template.md
- ✅ .specify/templates/powershell-help-template.md
- ✅ .specify/templates/script-parity-checklist-template.md
- ✅ .specify/templates/architecture-vision-template.md
- ✅ .specify/templates/context-view-template.md
- ✅ .specify/templates/building-block-view-template.md
- ✅ .specify/templates/runtime-view-template.md
- ✅ .specify/templates/deployment-view-template.md
- ✅ .specify/templates/architecture-decision-template.md
- ✅ .specify/templates/architecture-risks-template.md
- ✅ .specify/templates/quality-scenarios-template.md
- ✅ .specify/templates/msl-applicability-template.md
- ✅ .specify/templates/secure-coding-language-rules-template.md
- ✅ .specify/templates/cra-applicability-template.md
- ✅ .specify/templates/asvs-verification-template.md
- ✅ .specify/templates/supply-chain-evidence-template.md
- ✅ .specify/templates/zero-trust-applicability-template.md
Expand All @@ -21,12 +45,13 @@ Runtime guidance requiring updates:
- ✅ CLAUDE.md
- ✅ GEMINI.md
- ✅ .github/copilot-instructions.md
- ✅ docs/project-statistics.md
- ✅ .specify/memory/constitution.md (mirror)
Follow-up TODOs:
- None
-->

# Constitution v1.12.0
# Constitution v1.13.0

# home-baseline Constitution

Expand Down Expand Up @@ -80,9 +105,11 @@ synchronized across devices without exposing any credentials.

### II. Cross-Platform Parity & Documentation

Every critical script MUST exist in two variants:
- Bash (`.sh`) for macOS/Linux
- PowerShell Core 7+ (`.ps1`) for Windows
Every critical script-shaped tool MUST exist in two variants:
- Bash 3.x-compatible (`.sh`) for macOS/Linux unless a higher Bash version is
documented as a hard project requirement.
- PowerShell Core 7+ (`.ps1`) for Windows and as a portable shell on other
platforms.

Both variants MUST provide identical functionality and produce equivalent output.
A new script is not considered complete until:
Expand All @@ -94,6 +121,18 @@ A new script is not considered complete until:

All files MUST be committed together in the same commit.

Implementation discipline:
- Bash scripts SHOULD use `set -euo pipefail` or document the exception.
- Bash scripts MUST quote variable expansions and MUST NOT use `eval` on
untrusted input.
- PowerShell scripts MUST use `Set-StrictMode -Version Latest` and SHOULD use
`-NoProfile` for non-interactive subprocess calls.
- Both variants MUST behave equivalently in dry-run mode (`--dry-run` /
`-WhatIf`) where the tool mutates state.
- Script-parity evidence SHOULD use `script-parity-checklist-template.md`;
Bash man pages and PowerShell help SHOULD use the matching templates in
`.specify/templates/`.

**Rationale**: The workspace is used on macOS and Windows. Bash-only or PowerShell-only scripts create a second-class experience. Professional documentation ensures maintainability and ease of use across platforms.

### III. Bootstrap Automation
Expand Down Expand Up @@ -211,6 +250,15 @@ Mandatory rules:
- WCAG 2.2 Level AA is the default accessibility baseline wherever the criteria are applicable.
- User-facing artefacts MUST remain usable with keyboard-only interaction, screen readers, Braille displays, and text browsers.
- Text-first fallbacks MUST be preferred for status reporting, diagrams, and operational guidance.
- Every Markdown code block in user-facing or learner-facing documentation MUST
carry a language tag such as `bash`, `powershell`, `csharp`, `json`, or
`text`; bare fenced code blocks are not allowed.
- Non-decorative images, diagrams, and ASCII charts MUST include adjacent
text alternatives or DE-first/EN-second explanations at CEFR B2 readability.
- Accessibility evidence defaults to `docs/accessibility/` using
`a11y-checklist-template.md`, `a11y-evidence-template.md`,
`cli-a11y-review-template.md`, and `bilingual-content-check-template.md`
where applicable.
- Accessibility review is part of completion, not post-processing.

**Rationale**: Inclusive delivery improves quality for everyone, reduces retrofit work, and makes the repositories usable in real assistive-technology workflows from the start.
Expand Down Expand Up @@ -387,6 +435,12 @@ Mandatory security documentation (Principle XII extensions):
(`dependency-audit-template.md`) that is updated before each release and at
least monthly. The audit MUST cover CVE status, license compliance, registry
verification, lock-file status, and supply-chain risks.
- Every Level-2 project MUST maintain or cite a **Memory-Safe Language
Applicability** record (`msl-applicability-template.md`) when runtime or
language choice is part of the feature or project setup.
- Every Level-2 project MUST maintain language-specific secure-coding evidence
using `secure-coding-language-rules-template.md` or an equivalent checklist
when new language/runtime rules are introduced.
- Every Level-2 project SHOULD maintain **Security Quality Scenarios**
(`security-quality-scenarios-template.md`) following iSAQB CPSA-F quality
attribute scenario methodology to make security requirements testable and
Expand Down Expand Up @@ -503,6 +557,7 @@ MUST use this matrix to determine which standards apply.
| OWASP SAMM | SHOULD | Long-lived Level-1 and Level-2 workspaces/projects | Periodic self-assessment with prioritized improvement actions |
| CAPEC | SHOULD | Threat modeling of material attack paths | Reference relevant attack patterns for high-risk flows and abuse cases |
| NIST Zero Trust (SP 800-207) | Project-type-dependent | Distributed, service-based, cloud, remote-managed, or multi-device systems | Explicit applicability decision with controls or justified N/A |
| iSAQB / arc42 architecture governance | SHOULD | Structural, interface, quality-attribute, deployment, or long-term maintainability changes | Architecture evidence under `docs/architecture/` or justified N/A |
| OWASP Cheat Sheet Series / Proactive Controls | SHOULD | All developer-facing projects | Use as day-to-day implementation guidance below the constitution |
| OpenSSF Scorecard | Project-type-dependent | Public OSS repositories or high-impact external dependencies | Review repository/dependency security posture before adoption or release |

Expand Down Expand Up @@ -710,8 +765,8 @@ Mandatory rules:
secure-by-design, secure-by-default, vulnerability management, lifecycle
transparency, and SBOM availability.
- The CRA applicability decision MUST be recorded in `docs/security/` or
equivalent governance documentation (e.g., as a note in the supply-chain
evidence document or a dedicated S-ADR).
equivalent governance documentation using `cra-applicability-template.md`,
as a note in the supply-chain evidence document, or as a dedicated S-ADR.

**Rationale**: The EU Cyber Resilience Act (in force since December 2024,
with compliance deadlines phased through 2027) is the most significant
Expand All @@ -722,6 +777,47 @@ software placed on the EU market. Recording CRA applicability and aligning
practices proactively reduces legal and reputational risk and builds on the
security work already required by Principles XII–XVIII.

### XX. General iSAQB / arc42 Architecture Governance

Software architecture MUST be treated as explicit design evidence when a
change affects structure, interfaces, quality attributes, runtime behavior,
deployment, or long-term maintainability. Security-specific architecture stays
under Principle XIII; this principle covers general architecture reasoning.

Mandatory rules:
- Architecture work SHOULD follow iSAQB/CPSA-F method discipline and use
lightweight arc42-compatible documentation where useful.
- Architecturally significant decisions MUST be documented as ADRs or
architecture decision records.
- Quality attributes MUST be expressed as concrete scenarios with stimulus,
environment, response, and measurable response criteria. Generic words such
as "fast", "maintainable", or "scalable" are insufficient on their own.
- System context, building blocks, runtime behavior, and deployment constraints
MUST be documented when they materially affect the design or future change
decisions.
- Architecture risks and technical debt MUST be recorded with owner, impact,
mitigation, and review trigger when they affect delivery or operation.
- Architecture documentation MUST remain proportional: enough to support
review, onboarding, maintenance, and later change decisions without turning
every small implementation detail into a formal architecture artefact.

Evidence defaults:
- General architecture evidence lives in `docs/architecture/`.
- ADRs for general architecture default to `docs/architecture/adr/`.
- Use the 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`, and
`quality-scenarios-template.md` when the corresponding artefact applies.
- Security architecture evidence remains in `docs/security/`; if a decision is
both general and security-relevant, cross-link the records instead of
duplicating divergent content.

**Rationale**: iSAQB and arc42 provide a lightweight, reviewable way to keep
architecture decisions visible. Making general architecture evidence explicit
prevents structural drift while leaving security-specific controls in the
dedicated secure-architecture principles.

## Level-2 Project Environment Registry / Level-2-Projektumgebungsregister

This registry consolidates the constitution-relevant Level-2 project facts
Expand Down Expand Up @@ -812,7 +908,7 @@ allowed path.
`.github/copilot-instructions.md` for per-agent operational guidance. This
constitution is the authoritative policy layer above all agent-specific files.

**Version**: 1.12.0 | **Ratified**: 2026-03-31 | **Last Amended**: 2026-04-24
**Version**: 1.13.0 | **Ratified**: 2026-03-31 | **Last Amended**: 2026-05-05

<!-- EN: constitution.md placeholder
[DE-Zusammenfassung: constitution.md beschreibt die Prinzipien und Standards für alle home-baseline Workspaces.]
Expand Down
Loading
Loading