Skip to content

Commit 3dcbf7d

Browse files
hindermathCopilot
andcommitted
docs: amend constitution to v1.13.0 for preset governance
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent d4049ae commit 3dcbf7d

33 files changed

Lines changed: 1314 additions & 42 deletions

.github/copilot-instructions.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,13 @@ Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifisc
228228
- Ä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`.
229229

230230
*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.*
231+
## Allgemeine Architektur-Governance / General Architecture Governance
232+
233+
- Struktur-, Schnittstellen-, Qualitätsattribut-, Laufzeit-, Deployment- oder Wartbarkeitsänderungen müssen iSAQB/arc42-Architekturevidenz prüfen.
234+
- Standardpfad: `docs/architecture/`; ADRs fuer allgemeine Architekturentscheidungen liegen unter `docs/architecture/adr/`.
235+
- 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`.
236+
237+
*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.*
231238
## Sicherheitsdokumentation / Security Documentation (XII–XVIII Extensions)
232239

233240
- Jedes Level-2-Projekt MUSS die folgenden Sicherheitsdokumente pflegen, basierend auf den Templates in `.specify/templates/`:
@@ -236,14 +243,17 @@ Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifisc
236243
- **arc42 Section 8 Sicherheits-Querschnittskonzepte** (`arc42-security-template.md`) — Authentifizierung, Autorisierung, Verschlüsselung, Eingabevalidierung, Fehlerbehandlung, Logging, Abhängigkeiten, Deployment (Prinzip XIII)
237244
- **Sicherheits-Checkliste / Security Checklist** (`security-checklist-template.md`) — sprachspezifische Code-Review-Checkliste (Prinzip XII)
238245
- **Abhängigkeits-Audit / Dependency Audit** (`dependency-audit-template.md`) — CVE-Tracking, Lizenz-Compliance, Supply-Chain-Sicherheit (Prinzip XII)
246+
- **MSL-Anwendbarkeit / MSL Applicability** (`msl-applicability-template.md`) — Laufzeit-/Sprachwahl und Begründung (Prinzip XI)
247+
- **Sichere Sprachregeln / Secure Coding Language Rules** (`secure-coding-language-rules-template.md`) — sprachspezifische Sicherheitsregeln (Prinzip XII)
239248
- **Sicherheits-Qualitätsszenarien / Security Quality Scenarios** (`security-quality-scenarios-template.md`) — iSAQB CPSA-F Qualitätsszenario-Methodik (Prinzip XII + XIII, SHOULD)
240249
- **ASVS-Verifikation / ASVS Verification** (`asvs-verification-template.md`) — OWASP ASVS Level, Scope und Evidenz (Prinzip XV, Web-/API-Projekte MUST)
241250
- **Supply-Chain-Evidenz / Supply Chain Evidence** (`supply-chain-evidence-template.md`) — SBOM, VEX, SLSA, OpenSSF Scorecard (Prinzip XVI, releasefähige Projekte MUST)
242251
- **Zero-Trust-Anwendbarkeit / Zero Trust Applicability** (`zero-trust-applicability-template.md`) — NIST SP 800-207-Bewertung (Prinzip XVIII, verteilte Systeme SHOULD)
243252
- **SAMM-Bewertung / SAMM Assessment** (`samm-assessment-template.md`) — OWASP SAMM Reifegrad und Verbesserungsplan (Prinzip XVIII, langlebige Projekte SHOULD)
253+
- **CRA-Anwendbarkeit / CRA Applicability** (`cra-applicability-template.md`) — EU Cyber Resilience Act Scope und Nachweise (Prinzip XIX)
244254
- Projektspezifische Instanzen werden in `docs/security/` gepflegt; S-ADRs als einzelne Dateien in `docs/security/adr/`.
245255

246-
*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.*
256+
*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.*
247257

248258
## Gemeinsame Governance-Ergaenzung / Shared Governance Addendum
249259

@@ -272,9 +282,11 @@ Diese Regeln gelten für alle Repositories in diesem Workspace. Projektspezifisc
272282
- Bei Web/API-Features den `ASVS`-Level und den Verifikationsumfang in `docs/security/` oder gleichwertiger Projektdokumentation ablegen.
273283
- Bei Release-/Artefakt-Arbeit `SBOM`, `VEX`, Provenance/SLSA-Nachweise und gegebenenfalls `OpenSSF Scorecard` in Release- oder Sicherheitsdokumentation einplanen.
274284
- Bei Architekturänderungen `Zero Trust`-Anwendbarkeit und bei langlebigen Projekten `SAMM`-Folgeaktionen prüfen.
285+
- Bei allgemeinen Architekturänderungen iSAQB/arc42-Evidenz unter `docs/architecture/` prüfen.
286+
- Bei A11Y-relevanten Artefakten `docs/accessibility/`-Evidenz und Sprach-Tags fuer Markdown-Codebloecke pruefen.
275287
- 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.
276288

277-
*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.*
289+
*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.*
278290

279291
<!-- SPECKIT START -->
280292
For additional context about technologies to be used, project structure,

.specify/memory/constitution.md

Lines changed: 106 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,40 @@
11
<!--
22
Sync Impact Report
3-
Version change: 1.11.0 -> 1.12.0
3+
Version change: 1.12.0 -> 1.13.0
44
Modified principles:
5-
- None (purely additive)
5+
- II. Cross-Platform Parity & Documentation (aligned with preset-specific Bash/PowerShell rules)
6+
- VII. Programmierung #include<everyone> — Inclusion & Accessibility By Default (added evidence and code-block tagging)
7+
- XII. Secure Code Generation (added MSL and CRA evidence templates)
8+
- XIV. Secure Development Standards & Applicability Matrix (added general architecture evidence routing)
9+
- XVI. Supply-Chain Transparency & Build Integrity (kept CRA-linked all-level SBOM scope)
10+
- XIX. EU Cyber Resilience Act (CRA) Compliance Awareness (linked dedicated CRA template)
611
Added sections:
7-
- None
12+
- XX. General iSAQB / arc42 Architecture Governance
813
Removed sections:
914
- None
1015
Templates requiring updates:
1116
- ✅ .specify/templates/plan-template.md
1217
- ✅ .specify/templates/spec-template.md
1318
- ✅ .specify/templates/tasks-template.md
19+
- ✅ .specify/templates/a11y-checklist-template.md
20+
- ✅ .specify/templates/a11y-evidence-template.md
21+
- ✅ .specify/templates/bilingual-content-check-template.md
22+
- ✅ .specify/templates/cli-a11y-review-template.md
23+
- ✅ .specify/templates/agent-parity-checklist-template.md
24+
- ✅ .specify/templates/man-page-template.md
25+
- ✅ .specify/templates/powershell-help-template.md
26+
- ✅ .specify/templates/script-parity-checklist-template.md
27+
- ✅ .specify/templates/architecture-vision-template.md
28+
- ✅ .specify/templates/context-view-template.md
29+
- ✅ .specify/templates/building-block-view-template.md
30+
- ✅ .specify/templates/runtime-view-template.md
31+
- ✅ .specify/templates/deployment-view-template.md
32+
- ✅ .specify/templates/architecture-decision-template.md
33+
- ✅ .specify/templates/architecture-risks-template.md
34+
- ✅ .specify/templates/quality-scenarios-template.md
35+
- ✅ .specify/templates/msl-applicability-template.md
36+
- ✅ .specify/templates/secure-coding-language-rules-template.md
37+
- ✅ .specify/templates/cra-applicability-template.md
1438
- ✅ .specify/templates/asvs-verification-template.md
1539
- ✅ .specify/templates/supply-chain-evidence-template.md
1640
- ✅ .specify/templates/zero-trust-applicability-template.md
@@ -21,12 +45,13 @@ Runtime guidance requiring updates:
2145
- ✅ CLAUDE.md
2246
- ✅ GEMINI.md
2347
- ✅ .github/copilot-instructions.md
48+
- ✅ docs/project-statistics.md
2449
- ✅ .specify/memory/constitution.md (mirror)
2550
Follow-up TODOs:
2651
- None
2752
-->
2853

29-
# Constitution v1.12.0
54+
# Constitution v1.13.0
3055

3156
# home-baseline Constitution
3257

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

81106
### II. Cross-Platform Parity & Documentation
82107

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

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

95122
All files MUST be committed together in the same commit.
96123

124+
Implementation discipline:
125+
- Bash scripts SHOULD use `set -euo pipefail` or document the exception.
126+
- Bash scripts MUST quote variable expansions and MUST NOT use `eval` on
127+
untrusted input.
128+
- PowerShell scripts MUST use `Set-StrictMode -Version Latest` and SHOULD use
129+
`-NoProfile` for non-interactive subprocess calls.
130+
- Both variants MUST behave equivalently in dry-run mode (`--dry-run` /
131+
`-WhatIf`) where the tool mutates state.
132+
- Script-parity evidence SHOULD use `script-parity-checklist-template.md`;
133+
Bash man pages and PowerShell help SHOULD use the matching templates in
134+
`.specify/templates/`.
135+
97136
**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.
98137

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

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

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

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

780+
### XX. General iSAQB / arc42 Architecture Governance
781+
782+
Software architecture MUST be treated as explicit design evidence when a
783+
change affects structure, interfaces, quality attributes, runtime behavior,
784+
deployment, or long-term maintainability. Security-specific architecture stays
785+
under Principle XIII; this principle covers general architecture reasoning.
786+
787+
Mandatory rules:
788+
- Architecture work SHOULD follow iSAQB/CPSA-F method discipline and use
789+
lightweight arc42-compatible documentation where useful.
790+
- Architecturally significant decisions MUST be documented as ADRs or
791+
architecture decision records.
792+
- Quality attributes MUST be expressed as concrete scenarios with stimulus,
793+
environment, response, and measurable response criteria. Generic words such
794+
as "fast", "maintainable", or "scalable" are insufficient on their own.
795+
- System context, building blocks, runtime behavior, and deployment constraints
796+
MUST be documented when they materially affect the design or future change
797+
decisions.
798+
- Architecture risks and technical debt MUST be recorded with owner, impact,
799+
mitigation, and review trigger when they affect delivery or operation.
800+
- Architecture documentation MUST remain proportional: enough to support
801+
review, onboarding, maintenance, and later change decisions without turning
802+
every small implementation detail into a formal architecture artefact.
803+
804+
Evidence defaults:
805+
- General architecture evidence lives in `docs/architecture/`.
806+
- ADRs for general architecture default to `docs/architecture/adr/`.
807+
- Use the templates `architecture-vision-template.md`,
808+
`context-view-template.md`, `building-block-view-template.md`,
809+
`runtime-view-template.md`, `deployment-view-template.md`,
810+
`architecture-decision-template.md`, `architecture-risks-template.md`, and
811+
`quality-scenarios-template.md` when the corresponding artefact applies.
812+
- Security architecture evidence remains in `docs/security/`; if a decision is
813+
both general and security-relevant, cross-link the records instead of
814+
duplicating divergent content.
815+
816+
**Rationale**: iSAQB and arc42 provide a lightweight, reviewable way to keep
817+
architecture decisions visible. Making general architecture evidence explicit
818+
prevents structural drift while leaving security-specific controls in the
819+
dedicated secure-architecture principles.
820+
725821
## Level-2 Project Environment Registry / Level-2-Projektumgebungsregister
726822

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

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

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

0 commit comments

Comments
 (0)