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
8 changes: 4 additions & 4 deletions CHECKSUMS.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@ c58492dd01b64460c5c9de4d2eb07e53590a688a97edf6ff7161c48542e9f652 *audit-prompts/
b3377cca11bf9f30bae20021e099b6f903fa6a1d2db341394ba5341ee8cd430e *audit-prompts/ai-llm-audit-master-prompt.md
e7231652a9b68dd7c2f2a300eeaa9967f049206eb99afb2d0203f90ae4f7dab0 *audit-prompts/api-audit-master-prompt.md
4e2315a6a0dcbc74b7eb115ee8234f2c1d52793f885347e5f6a24af99d51846f *audit-prompts/compliance-privacy-audit-master-prompt.md
cbb755bfbcbf6d10b19bf1e4d4e95aefbb6b7d417d0549f5ef241dd3623eb88c *audit-prompts/content-audit-master-prompt.md
ec8a4645bfca5686a0d4a024aef06f43b020bc2df5b41bbf0ef5bd57338e7540 *audit-prompts/content-audit-master-prompt.md
1d57a6b77e041844191e924d1c0c2e97db0437ce409fa3b1d5f661b9fe129d85 *audit-prompts/data-audit-master-prompt.md
afaad3168640d047af7082f93721ff6169f8c67ee0937f2a7a785fad21a0a798 *audit-prompts/documentation-audit-master-prompt.md
1c163b9bb26d4a8d56a60d4a3155f8719e735557c0830735b15709683de18380 *audit-prompts/frontend-audit-master-prompt.md
022cb41b8056e7c80bd23b1156302f6e138ebf497b3e027efac1e15b08936b96 *audit-prompts/full-audit-master-prompt.md
26ae6a7f36ee3cd7e44539238ab833026a585b38884c3334ab785c19e35ce440 *audit-prompts/infrastructure-audit-master-prompt.md
9322253707945af22ebb32104bb4657dff584869a23798091985f0226e336e58 *audit-prompts/lean-audit-master-prompt.md
cbb443387e4ecfc2425925af8c67552721fdec23207c4d47483792b2117f6670 *audit-prompts/lean-audit-master-prompt.md
eade468bffad5ee4143e0461502ccc8c607846fb4861c6b672b2a0af52031d4f *audit-prompts/performance-audit-master-prompt.md
ddee61e41e75d4b6d4a23d114f58eb5d1be7e13f29bbcf6ad37184076b14f872 *audit-prompts/repo-audit-master-prompt.md
435e1661ad34a4398d41715763c243cd4c76d9efb4d01b933f05768dca4ccc73 *audit-prompts/security-audit-master-prompt.md
6bcc77a3a95524cb58a189042ee579cd1172cc44ccc4fd1b7961387bfd899626 *ISSUE-OUTPUT-STANDARD.md
25417e9a606aeff7698e460f52befde8bcd725dc4449ef95458959d61dbc66c7 *ISSUE-OUTPUT-STANDARD.md
d5c630f94295b56fb451a53836c69f5815e5096f4a694347a40c1f09543afb78 *DOCUMENTATION-STANDARD.en.md
65463676dc3f20c23b4d1be66528f03753b50c632ef2e79a16bd9333f92d92f0 *DOCUMENTATION-STANDARD.md
73df04e730805068521bda76f3f8542cf6832cd60461f64033e000f40f07b472 *DOCUMENTATION-STANDARD.md
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Every Markdown file follows the [`DOCUMENTATION-STANDARD.md`](DOCUMENTATION-STAN
- Second person, present tense, active voice; short sentences; parallel lists.
- Notes as GitHub alerts (`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`) instead of emoji.
- No dead links; no doc–code drift.
- Use [`TERMINOLOGY.md`](TERMINOLOGY.md) as the German (de-CH)/English copy glossary — the content audit's `STYLE_REFERENCE` for binding and advisory term choices.

## Contributing a new audit template

Expand Down
12 changes: 6 additions & 6 deletions DOCUMENTATION-STANDARD.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Dokumentations-Standard (Google-Grade)

Ein normativer Standard für Repository-Dokumentation: messbar, profilabhängig und an den
aktuellen Google-Dokumentationsmustern ausgerichtet. Dieser Standard ist der Maßstab, gegen den
aktuellen Google-Dokumentationsmustern ausgerichtet. Dieser Standard ist der Massstab, gegen den
das [`documentation-audit`](audit-prompts/documentation-audit-master-prompt.md) beliebige Repos
prüft und konkrete Verbesserungs-Issues erzeugt.

Expand Down Expand Up @@ -39,7 +39,7 @@ Dieser Standard übernimmt **Googles Schreib- und Barrierefreiheits-Disziplin**
**Repo-Kopf**, den Googles eigene, minimalistische READMEs bewusst weglassen: Badges, ein
Management-Summary und ein Architektur-Diagramm. Diese Mischung ist gewollt:

- **Von Google:** Stimme, zweite Person, Präsens, Aktiv, satzweise Großschreibung der
- **Von Google:** Stimme, zweite Person, Präsens, Aktiv, satzweise Grossschreibung der
Überschriften, parallele Listen, Geltungsbereich + Zielgruppe zuerst nennen, strikte
Barrierefreiheit. (Quelle: Google developer documentation style guide, tech-writing.)
- **Von Best-in-Class-OSS:** Badge-Reihe (shields.io), Management-Summary/TL;DR, Mermaid-
Expand Down Expand Up @@ -95,7 +95,7 @@ Der Kopf entscheidet, ob ein Leser bleibt. Reihenfolge (verbindlich):
5. **Inhaltsverzeichnis.** Ab ~100 Zeilen README. Beschreibende Linktexte, funktionierende Anker.

> [!TIP]
> Das C4-Modell hilft beim Schichten von Architektur: **Context** (System + Außenwelt) →
> Das C4-Modell hilft beim Schichten von Architektur: **Context** (System + Aussenwelt) →
> **Container** (Apps, DBs, APIs) → **Component** (Inneres eines Containers). Im Repo-Kopf gehört
> in der Regel ein Context- oder schlankes Container-Diagramm.

Expand Down Expand Up @@ -195,7 +195,7 @@ tech-writing-Kursen. Sie gelten für jede Markdown-Datei im Repo.
- **Code-Blöcke.** Sprache am Fence angeben; Einrückung 2 Leerzeichen; Zeilen ~80 Zeichen;
ausgelassenen Code per sprachspezifischem Kommentar markieren, nicht per „…".
- **Caption-first bei Abbildungen.** Erst die Bildunterschrift/Aussage, dann das Bild; Callouts
statt langer Fließtext-Erklärungen.
statt langer Fliesstext-Erklärungen.

---

Expand All @@ -204,7 +204,7 @@ tech-writing-Kursen. Sie gelten für jede Markdown-Datei im Repo.
Barrierefreiheit ist nicht optional. Dokumentation muss mit Screenreader und Tastatur nutzbar sein.

- **Alt-Text** für jedes informative Bild; leerer Alt-Text nur für rein dekorative Bilder.
- **Keine Information ausschließlich über Bilder** vermitteln.
- **Keine Information ausschliesslich über Bilder** vermitteln.
- **Keine Richtungssprache.** „vorstehend/folgend/weiter oben im Text" statt „oben/unten/rechts" —
Layout variiert je nach Gerät und Screenreader.
- **Kontrast** mindestens 4.5:1 für Text.
Expand Down Expand Up @@ -266,7 +266,7 @@ ausgewiesen.
- **P1 — Hoch:** kein Management-Summary, kein Architektur-Diagramm wo Profil es verlangt,
undokumentiertes Kern-Feature, fehlende Pflicht-Health-Datei.
- **P2 — Mittel:** Drift, schwache Navigation, inkonsistente Terminologie, dünne Referenz.
- **P3 — Niedrig:** Stil, Tippfehler, Emoji-Politik-Verstöße ohne Informationsverlust.
- **P3 — Niedrig:** Stil, Tippfehler, Emoji-Politik-Verstösse ohne Informationsverlust.

Die Befunde werden nach dem [`ISSUE-OUTPUT-STANDARD.md`](ISSUE-OUTPUT-STANDARD.md) ausgegeben:
zuerst ein Tracking-Issue (priorisierter Index + Management-Summary + Roadmap), dann pro Befund
Expand Down
18 changes: 13 additions & 5 deletions ISSUE-OUTPUT-STANDARD.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,14 @@ Dieser Standard ist **verbindlich** und wird von jeder Vorlage in `audit-prompts

> [!NOTE]
> **Management-Summary.** Nach der adversariellen Verifikation überführt jedes Audit seine
> bestätigten Befunde in GitHub-Issues — **standardmäßig auf Deutsch**. Zuerst entsteht **ein
> bestätigten Befunde in GitHub-Issues — **standardmässig auf Deutsch**. Zuerst entsteht **ein
> Tracking-Issue** (der Index aller Sub-Aufgaben, nach Priorität sortiert, mit Management-Summary,
> Scorecard und Roadmap), danach **pro Befund ein eigenes Issue**, jedes mit eigener
> Management-Summary und konkreter Vorher/Nachher-Handlungsempfehlung. Das echte Anlegen erfolgt
> **erst nach Vorschau und ausdrücklicher Freigabe**.

Version 1.0.0 · Sprache der Issues: standardmäßig Deutsch (`OUTPUT_LANG` überschreibbar)
Version 1.1.0 · Sprache der Issues: standardmässig Deutsch (`OUTPUT_LANG` überschreibbar)
Neu in 1.1.0: de-CH-Orthografie (durchgehend ss) und der `dimension:`/`effort:`-Label-Kanon sind verbindlich.

---

Expand All @@ -20,6 +21,11 @@ Version 1.0.0 · Sprache der Issues: standardmäßig Deutsch (`OUTPUT_LANG` übe
- **Auslöser:** läuft nach Phase 3 (Verifikation) und der Synthese. Nur **bestätigte** Befunde
werden zu Issues; Hypothesen bleiben getrennt im Bericht.
- **Sprache:** Deutsch als Standard. Pro Lauf via `OUTPUT_LANG` änderbar (z. B. für englische Repos).
- **Locale & de-CH.** Die deutsche Issue-Ausgabe nutzt Schweizer Orthografie (durchgehend ss, kein
Eszett — Ausnahme nur unveränderliche Eigennamen, Code, Rechtstitel, wörtliche Zitate), deutsche
Anführungszeichen „…" (nie ein gerades ASCII-Schlusszeichen) und einheitliche Terminologie gemäss
Projekt-Glossar ([`TERMINOLOGY.md`](TERMINOLOGY.md)). Das gilt für **alle** Audits und ist pro Lauf
via `OUTPUT_LANG`/Locale überschreibbar.
- **Vorschau zuerst.** Immer ein Trockenlauf (vollständiger Issue-Text als Markdown im Bericht).
Echtes Anlegen nur bei **ausdrücklicher Freigabe** und vorhandenem Repo-Zugriff (`gh issue create`).
- **Idempotenz.** Vor dem Anlegen bestehende Audit-Issues per Label-Suche (`audit`, `<audit-typ>`)
Expand All @@ -35,7 +41,7 @@ Ein einzelnes „Epic"/Index-Issue, das alle Sub-Aufgaben bündelt.
- **Titel:** `[AUDIT] <Audit-Name> — Befund-Tracker & Roadmap`
- **Labels:** `audit`, `tracking`, `<audit-typ>` (z. B. `security`, `performance`, `docs`)
- **Body:**
1. **Management-Summary** (3–5 Sätze): Gesamturteil, Score/Note, größtes Risiko, realistisches
1. **Management-Summary** (3–5 Sätze): Gesamturteil, Score/Note, grösstes Risiko, realistisches
Ziel nach Behebung. Für Leitung lesbar.
2. **Scorecard** (Tabelle): Dimensionen × Note/Score × Befundzahl je Schweregrad.
3. **Priorisierte Aufgabenliste** als Checkboxen, sortiert **P0 → P3**, innerhalb gleicher
Expand All @@ -58,7 +64,9 @@ Jeder bestätigte Befund wird ein eigenständiges, erstklassig dokumentiertes Is

- **Titel:** `[<SEVERITY>][<Domäne/Dimension>] <prägnanter Befund>` — z. B.
`[P0][AuthZ] IDOR an GET /api/orders/{id}`
- **Labels:** `audit`, `sev:p0|p1|p2|p3`, `domäne:<x>`, `aufwand:S|M|L`
- **Labels:** `audit`, `sev:p0|p1|p2|p3`, `dimension:<x>`, `effort:S|M|L`, optional `locale:de-CH`.
Die Lokalisierungs-Dimension heisst `dimension:localisation`; `locale:de-CH` markiert Schweizer
Orthografie (optional).
- **Body (feste Reihenfolge):**
1. **Management-Summary** (2–3 Sätze): was, Auswirkung, Empfehlung in einem Satz.
2. **Schweregrad & Score:** P-Stufe + auditspezifischer Score (CVSS / ICE / Rubrik-Punkte).
Expand Down Expand Up @@ -96,7 +104,7 @@ Damit die Checklisten-Links im Tracker auflösen, in dieser Reihenfolge arbeiten
```markdown
> [!NOTE]
> **Management-Summary.** Das Security-Audit von `acme/shop` ergibt Note **Bronze (62/100)**.
> Größtes Risiko: ein nicht authentifizierter Endpunkt, der Kundendaten preisgibt (P0).
> Grösstes Risiko: ein nicht authentifizierter Endpunkt, der Kundendaten preisgibt (P0).
> Nach Behebung der 2 P0- und 3 P1-Befunde ist Silver erreichbar.

## Scorecard
Expand Down
105 changes: 105 additions & 0 deletions TERMINOLOGY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Terminology

This is the project glossary for German (de-CH) and English copy across the site
([`web/lib/i18n.ts`](web/lib/i18n.ts), [`web/lib/audit-details.ts`](web/lib/audit-details.ts),
[`web/lib/content.ts`](web/lib/content.ts)) and the German issue output of the 13 audit prompts in
[`audit-prompts/`](audit-prompts/). It is a reference doc, so the head-matter is English; the
canonical German forms live in the `de-CH` column. The content audit consumes this file as its
`STYLE_REFERENCE`.

Two tiers govern every entry:

- **BINDING** — a fixed decision. An audit may **not** override it. Use it verbatim (for
keep-as-code tokens) or in its single canonical form.
- **ADVISORY** — a preferred canonical form. An audit may **extend** the advisory tier with new
entries per run, but may never **demote** an advisory preference to a worse variant, and never
promote translationese over the listed form.

German copy follows Swiss orthography (de-CH): always `ss`, never the Eszett, except immutable
proper names, code, legal titles, or verbatim quotes. German quotation marks are „…", never an
ASCII straight-quote closer. See [`ISSUE-OUTPUT-STANDARD.md`](ISSUE-OUTPUT-STANDARD.md) for the
governing locale rule that all audits inherit.

The `keep-as-code?` column says whether the token stays a verbatim literal (`yes`) or is rendered
as prose in the target language (`no`).

## Binding — keep as code (stay English)

These tokens are acronyms, proper names, or literal identifiers. They are never translated, never
spelled out in running text, and keep their exact casing.

| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale |
|---|---|---|---|---|---|
| Continuous integration/delivery | CI/CD | CI/CD | yes | BINDING | Established pipeline acronym; recurs across the prompts. |
| Infrastructure as code | IaC | IaC | yes | BINDING | Standard acronym; do not spell out in German. |
| OWASP | OWASP | OWASP | yes | BINDING | Proper name of the standards body. |
| Common Weakness Enumeration | CWE | CWE | yes | BINDING | MITRE catalogue identifier (e.g. CWE-639). |
| CVSS | CVSS | CVSS | yes | BINDING | Scoring-system name; keep the score format too. |
| MITRE | MITRE | MITRE | yes | BINDING | Organisation / ATT&CK proper name. |
| CIS | CIS | CIS | yes | BINDING | Benchmark body name. |
| Software bill of materials | SBOM | SBOM | yes | BINDING | Supply-chain acronym; do not localise. |
| Retrieval-augmented generation | RAG | RAG | yes | BINDING | Established AI acronym. |
| SLSA | SLSA | SLSA | yes | BINDING | Supply-chain integrity framework name. |
| DORA | DORA | DORA | yes | BINDING | Delivery-metrics framework name. |
| WCAG | WCAG | WCAG | yes | BINDING | Accessibility standard; most-cited token in the corpus. |
| E-E-A-T | E-E-A-T | E-E-A-T | yes | BINDING | Google quality-rater acronym; keep the hyphenation. |
| Bottom line up front | BLUF | BLUF | yes | BINDING | Writing-discipline acronym. |
| Evidence citation | `file:line` | `file:line` | yes | BINDING | Fundort format; never translated or reformatted. |
| GitHub issue | GitHub-Issue | GitHub-Issue | yes | BINDING | Product name; German compound keeps „Issue". |
| Workflow trigger | `pull_request_target` | `pull_request_target` | yes | BINDING | Literal GitHub Actions identifier. |
| Insecure direct object reference | IDOR | IDOR | yes | BINDING | Vulnerability-class acronym. |
| Broken object-level authorization | BOLA | BOLA | yes | BINDING | OWASP API vulnerability-class acronym. |
| API | API | API | yes | BINDING | Universally known; never spelled out. |

## Binding — terms of art (keep English; one canonical German-inflected form where used as a verb)

These are established terms of art. The English noun is kept in German prose; where the corpus uses
the concept as a verb, exactly one German-inflected form is canonical.

| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale |
|---|---|---|---|---|---|
| Trust boundary | Trust Boundary | Trust Boundary | no | BINDING | Threat-modelling term of art; keep English noun. |
| Blast radius | Blast-Radius | Blast-Radius | no | BINDING | Established impact-scope term; keep the compound. |
| Prompt injection | Prompt-Injection | Prompt-Injection | no | BINDING | Security term of art; do not translate. |
| Supply chain | Supply Chain | Supply Chain | no | BINDING | Kept English in the prompts; not „Lieferkette". |
| Business logic | Business Logic | Business Logic | no | BINDING | Term of art; not „Geschäftslogik". |
| Human gate | Human-Gate | Human-Gate | no | BINDING | Agent-safety term; keep the English compound. |
| Output sink | Output-Sink | Output-Sink | no | BINDING | Dataflow term of art. |
| Cost cap | Cost-Cap | Cost-Cap | no | BINDING | Agent-budget term; keep English. |
| Untrusted input | untrusted Input | untrusted Input | no | BINDING | Kept as „untrusted Input" across the prompts. |
| Merge (git) | merge | mergen | no | BINDING | German verb „mergen" is the canonical inflected form; keep it. |
| Map (a system) | map | kartieren | no | BINDING | Canonical German verb is „kartieren", never „mappen". |

## Advisory — translate (prefer the German)

Where a clean German word exists, prefer it over an English loan. An audit may extend this list but
must not revert to the English form.

| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale |
|---|---|---|---|---|---|
| Finding | finding | Befund | no | ADVISORY | „Befund" is the established term in `i18n.ts` / `audit-details.ts`. |
| Output (result) | output | Ergebnis | no | ADVISORY | Prefer „Ergebnis" over „Output" in prose. |
| Run (a pass) | run | Durchlauf | no | ADVISORY | „Durchlauf" for one audit pass. |
| Lens | lens | Prüfbereich / Prüfdimension | no | ADVISORY | Translate; no English-loan need. |
| Sweep | sweep | Durchlauf | no | ADVISORY | Same German as „run". |
| Deduplicate | deduplicate | Doppelungen entfernen | no | ADVISORY | Avoid „deduplizieren"; use plain German. |
| Benchmark (verb) | benchmark | gegen Referenzen prüfen | no | ADVISORY | Avoid „benchmarken"; describe the action. |
| Remediation | remediation | Korrekturmassnahme | no | ADVISORY | de-CH spelling with ss, never the Eszett form. |
| Failure mode | failure mode | Fehlerbild | no | ADVISORY | Prefer „Fehlerbild". |
| Scope | scope | Umfang | no | ADVISORY | „Umfang" (already used in `i18n.ts`). |

## Advisory — rephrase (anchorless translationese to avoid)

These English phrasings produce calques in German. Rephrase to the listed German instead of
translating word for word.

| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale |
|---|---|---|---|---|---|
| Run/operate it | "laufen lassen" | einsetzen / ausführen | no | ADVISORY | „laufen lassen" is anchorless; use „einsetzen" or „ausführen". |
| Aim the agent | "Point your agent at" | „… nutzen" | no | ADVISORY | Rephrase to „… nutzen"; avoid the literal calque. |
| Self-test | "dogfooded" | „prüft sich selbst" | no | ADVISORY | Render the meaning: „prüft sich selbst". |
| Steelman | "steelmannen" | „den stärksten Gegenpunkt bilden" | no | ADVISORY | No German loan; describe the action. |

> [!NOTE]
> This glossary is a seed. Audits extend the ADVISORY tier per run, but never demote a BINDING
> decision.
Loading
Loading