feat: add governance roles to role taxonomy (#542)#659
Open
JensGrote wants to merge 5 commits into
Open
Conversation
Add three internal governance roles to :roles: vocabulary: - data-protection-officer (GDPR Art. 37-39) - legal-compliance (EU AI Act, ISO 9001/20000/27001, BSI-Grundschutz, NIS2) - ethics-officer (EU AI Act Art. 9, ISO/IEC 42001) Applied to 13 anchors relevant for audits, compliance, and governance. Regenerated roles.json, anchors.json, metadata.json via extract-metadata. Closes LLM-Coding#520
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (19)
✅ Files skipped from review due to trivial changes (18)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughNeue Rollenbezeichner und ihre Lesetexte werden ergänzt. Mehrere Anchor-Dokumente erweitern ihre Rollenmetadaten, die generierten Rollen- und Anchor-Daten werden angereichert, und Kategorien- sowie Statistikdateien werden aktualisiert. ChangesGovernance-Rollen und Metadatenaktualisierungen
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/anchors/twelve-factor-app.adoc (1)
5018-5049: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winKatalogeintrag für
twelve-factor-appergänzen.In
skill/semantic-anchor-translator/references/catalog.mdfehlt nochtwelve-factor-app; ohne den Eintrag erkennen AI-Agenten den neuen Anchor nicht.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/anchors/twelve-factor-app.adoc` around lines 5018 - 5049, The `catalog.md` reference list is missing the new `twelve-factor-app` anchor, so AI agents cannot discover it. Add a catalog entry for `twelve-factor-app` in `skill/semantic-anchor-translator/references/catalog.md`, matching the existing format used for other anchor entries and ensuring the new anchor name is included exactly so it can be resolved correctly.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/anchors/adr-according-to-nygard.adoc`:
- Around line 1-4: The metadata block in the ADR anchor is incomplete after the
roles change; update the same anchor entry to include the missing required
attributes. In `ADR according to Nygard`, add `:proponents:`, `:related:`, and
`:tags:` alongside the existing `:categories:` and `:roles:` metadata so the
document satisfies the `docs/anchors/**/*.adoc` requirements and the repo
guidelines for `related anchors` and tags.
In `@docs/anchors/adr-according-to-nygard.de.adoc`:
- Around line 1-4: The metadata block in this anchor AsciiDoc is incomplete;
update the document’s header metadata in the existing anchor file so it includes
the required attributes alongside the current title, categories, and roles. Add
the missing :proponents:, :related:, and :tags: metadata entries, and make sure
the file’s metadata follows the anchor-document conventions used by the
docs/anchors/*.adoc content.
In `@docs/anchors/arc42.adoc`:
- Around line 1-5: The arc42 anchor metadata block is incomplete because it
defines categories, roles, proponents, and tier but omits the required related
and tags attributes. Update the metadata in the arc42 anchor document so it
includes both :related: and :tags: alongside the existing anchor attributes,
keeping the block consistent with the required docs/anchors/*.adoc metadata
pattern.
In `@docs/anchors/arc42.de.adoc`:
- Around line 1-5: The metadata block in arc42.de.adoc is missing the required
related and tags attributes. Update the anchor metadata alongside categories,
roles, and proponents by adding :related: for the relevant linked anchors and
:tags: for the applicable tags, keeping the same metadata style used in the
other docs/anchors/*.adoc files.
In `@docs/anchors/testing-pyramid.de.adoc`:
- Around line 1-4: The metadata block in the anchor document is incomplete and
needs the missing required attributes added. Update the AsciiDoc header for the
testing anchor so it includes :proponents:, :related:, and :tags: alongside the
existing :categories: and :roles: entries, following the conventions used by
other anchor files and the repository guidelines. Use the document’s anchor
metadata section in testing-pyramid.de.adoc as the place to add these fields so
the file satisfies the required docs/anchors metadata contract.
In `@docs/anchors/twelve-factor-app.de.adoc`:
- Line 63: The “Aktueller Stand” passage in twelve-factor-app.de.adoc contains
an ungrounded speculation about LLM training data, so remove that claim or
replace it with a named, fetch-verified source. Update the anchor structure to
include both == Kritik and == Aktueller Stand sections in German and English,
and make the status statement traceable to a specific source such as
12factor.net or another cited publication/standard via the existing anchor
content.
---
Outside diff comments:
In `@docs/anchors/twelve-factor-app.adoc`:
- Around line 5018-5049: The `catalog.md` reference list is missing the new
`twelve-factor-app` anchor, so AI agents cannot discover it. Add a catalog entry
for `twelve-factor-app` in
`skill/semantic-anchor-translator/references/catalog.md`, matching the existing
format used for other anchor entries and ensuring the new anchor name is
included exactly so it can be resolved correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: b8f59feb-5543-4f8f-9a3b-9d5cdf9646fc
📒 Files selected for processing (31)
docs/anchors/adr-according-to-nygard.adocdocs/anchors/adr-according-to-nygard.de.adocdocs/anchors/arc42.adocdocs/anchors/arc42.de.adocdocs/anchors/c4-diagrams.adocdocs/anchors/c4-diagrams.de.adocdocs/anchors/iec-61508-sil-levels.adocdocs/anchors/iec-61508-sil-levels.de.adocdocs/anchors/linddun.adocdocs/anchors/linddun.de.adocdocs/anchors/meaningful-human-control.adocdocs/anchors/meaningful-human-control.de.adocdocs/anchors/owasp-top-10.adocdocs/anchors/owasp-top-10.de.adocdocs/anchors/quality-attribute-scenario.adocdocs/anchors/quality-attribute-scenario.de.adocdocs/anchors/regulated-environment.adocdocs/anchors/regulated-environment.de.adocdocs/anchors/site-reliability-engineering.adocdocs/anchors/site-reliability-engineering.de.adocdocs/anchors/stride.adocdocs/anchors/stride.de.adocdocs/anchors/testing-pyramid.adocdocs/anchors/testing-pyramid.de.adocdocs/anchors/twelve-factor-app.adocdocs/anchors/twelve-factor-app.de.adocscripts/extract-metadata.jswebsite/public/data/anchors.jsonwebsite/public/data/categories.jsonwebsite/public/data/metadata.jsonwebsite/public/data/roles.json
Comment on lines
1
to
5
| = arc42 Architecture Documentation | ||
| :categories: software-architecture | ||
| :roles: software-architect, technical-writer, team-lead | ||
| :roles: software-architect, technical-writer, team-lead, legal-compliance | ||
| :proponents: Gernot Starke, Peter Hruschka | ||
|
|
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
related und tags bitte im Metadatenblock ergänzen.
Der angefasste Anchor erfüllt die Repo-Vorgabe für categories/roles/proponents, aber :related: und :tags: fehlen weiterhin. As per coding guidelines, docs/anchors/*.adoc: "must use metadata attributes for categories, roles, related anchors, proponents, and tags."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/anchors/arc42.de.adoc` around lines 1 - 5, The metadata block in
arc42.de.adoc is missing the required related and tags attributes. Update the
anchor metadata alongside categories, roles, and proponents by adding :related:
for the relevant linked anchors and :tags: for the applicable tags, keeping the
same metadata style used in the other docs/anchors/*.adoc files.
Source: Coding guidelines
Collaborator
Author
There was a problem hiding this comment.
Pre-existing gap — same as EN version. Tracked in #668 (comprehensive metadata audit).
Contributor
There was a problem hiding this comment.
@JensGrote, understood — thanks for linking #668. I'll leave this as-is here since it's already tracked for the broader metadata audit.
🧠 Learnings used
Learnt from: raifdmueller
Repo: LLM-Coding/Semantic-Anchors PR: 379
File: docs/anchors/todotxt-flavoured-markdown.de.adoc:2-2
Timestamp: 2026-03-27T09:53:39.838Z
Learning: In this repository, `:categories:` in `docs/anchors/*.adoc` files is intentionally not restricted to a fixed whitelist. `extract-metadata.js` reads `:categories:` from all `.adoc` files to generate category data, so reviewers should allow new category slugs to be introduced via `:categories:`. After running `npm run build`, new categories should automatically appear in `website/public/data/categories.json`; do not flag new/unknown category slugs as invalid due to any hardcoded validation.
Collaborator
Author
|
Thanks for the thorough review, @coderabbitai! Regarding the metadata completeness comments ( These are pre-existing gaps — I verified against the merge base that all of these fields were already missing before my changes. My PR only adds I have created a separate cleanup issue (see below) to audit and fill the missing metadata across all 318 anchor files — the 5 files touched here will be fixed as part of that comprehensive effort, not in this PR. This keeps the scope of this PR focused on the governance roles addition. For reference, audit results across the catalog:
|
Contributor
|
Tip For best results, initiate chat on the files or code changes.
Good luck with the cleanup issue! (=^･ω･^)ﾉ ✏️ Learnings added
|
added 4 commits
July 1, 2026 22:59
…rrent Status (EN+DE)
…al-compliance role and fixed Current Status
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
(German version below)
Adds three internal governance roles to the
:roles:vocabulary, as agreed in #542. This implements Step 1 of the governance role taxonomy proposal, scoped down per maintainer recommendation.New roles
data-protection-officerlegal-complianceethics-officerAnchors tagged
regulated-environmentdata-protection-officer,legal-compliance,ethics-officermeaningful-human-controldata-protection-officer,ethics-officer,legal-compliancelinddundata-protection-officerstridedata-protection-officerowasp-top-10data-protection-officerquality-attribute-scenariodata-protection-officer,ethics-officerarc42legal-complianceadr-according-to-nygardlegal-compliancec4-diagramslegal-complianceiec-61508-sil-levelslegal-compliance,ethics-officersite-reliability-engineeringlegal-compliancetwelve-factor-applegal-compliancetesting-pyramidlegal-complianceScope rationale
The governance roles are not limited to IT security and data protection. They cover anchors relevant for:
Changes
:roles:extendedscripts/extract-metadata.js— three new entries inroleIdToName()roles.json,anchors.json,metadata.json,categories.jsonTests
All 16 unit tests pass (
scripts/vitest).Closes #520.
Addresses #542 (Step 1).
Deutsche Version
Zusammenfassung
Fügt drei interne Governance-Rollen zum
:roles:-Vokabular hinzu, wie in #542 vereinbart. Implementiert Schritt 1 des Governance-Rollen-Taxonomie-Vorschlags, auf Empfehlung der Maintainer reduziert.Neue Rollen
data-protection-officerlegal-complianceethics-officerGetaggte Anchors
regulated-environmentdata-protection-officer,legal-compliance,ethics-officermeaningful-human-controldata-protection-officer,ethics-officer,legal-compliancelinddundata-protection-officerstridedata-protection-officerowasp-top-10data-protection-officerquality-attribute-scenariodata-protection-officer,ethics-officerarc42legal-complianceadr-according-to-nygardlegal-compliancec4-diagramslegal-complianceiec-61508-sil-levelslegal-compliance,ethics-officersite-reliability-engineeringlegal-compliancetwelve-factor-applegal-compliancetesting-pyramidlegal-complianceScope-Begründung
Die Governance-Rollen sind nicht auf IT-Security und Datenschutz beschränkt. Sie umfassen Anchors relevant für:
Änderungen
:roles:erweitertscripts/extract-metadata.js— drei neue Einträge inroleIdToName()roles.json,anchors.json,metadata.json,categories.jsonregeneriertTests
Alle 16 Unit-Tests bestehen (
scripts/vitest).Schließt #520.
Adressiert #542 (Schritt 1).
Summary by CodeRabbit