docs: add Risk Radar ADRs to arc42 documentation (#284)

raifdmueller · claude · web-flow · commit 7dca913b5dad · 2026-02-12T10:17:19.000+01:00
Created three Architecture Decision Records (Nygard format) documenting
the Risk Radar assessment and mitigation implementation:

- ADR-011: Risk Classification - dacli CLI (Tier 2)
- ADR-012: Risk Classification - dacli-mcp (Tier 2)
- ADR-013: Security Mitigations - Tier 2 Implementation

Key decisions documented:
- Tier 2 classification based on Code Type=2, Language=2, Blast Radius=2
- Repository-wide mitigation strategy (both modules share codebase)
- 100% Tier 1+2 measure implementation (9/9 measures complete)
- PR review policy with risk-based sampling (20-30%)
- Security fixes: cryptography 46.0.5, pip 26.0.1

Each ADR includes:
- Context with dimension scoring and evidence
- Decision rationale with tier requirements
- Pugh Matrix comparing alternatives
- Consequences (positive and negative)
- Implementation timeline with commit references

Updated CLAUDE.md with links to new ADRs.

Co-authored-by: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -313,3 +313,9 @@ _Updated by `/risk-mitigate` on 2026-02-11_
 **Security fixes applied**: cryptography>=46.0.5, pip 26.0.1 (commit 7766e90)
 
 **Note:** Both modules share the same codebase and mitigations. Entry points differ (`dacli.cli:cli` vs `dacli.main:main`), but risk profile and protection measures are identical.
+
+**Architecture Decision Records:**
+
+* link:src/docs/arc42/adr/ADR-011.adoc[ADR-011: Risk Classification - dacli CLI (Tier 2)]
+* link:src/docs/arc42/adr/ADR-012.adoc[ADR-012: Risk Classification - dacli-mcp (Tier 2)]
+* link:src/docs/arc42/adr/ADR-013.adoc[ADR-013: Security Mitigations - Tier 2 Implementation]
diff --git a/src/docs/arc42/adr/ADR-011.adoc b/src/docs/arc42/adr/ADR-011.adoc
@@ -0,0 +1,64 @@
+=== ADR-011: Risk Classification - dacli CLI (Tier 2)
+
+*Status:* Accepted (2026-02-11)
+
+*Deciders:* Development Team + Claude Code
+
+*Context:*
+
+The dacli CLI module requires risk classification according to the Risk Radar framework to determine appropriate security and quality assurance measures. The assessment evaluates five dimensions:
+
+| Dimension | Score | Level | Evidence |
+|-----------|-------|-------|----------|
+| Code Type | 2 | Business Logic | Click commands, service layer orchestration (`src/dacli/cli.py`, `src/dacli/services/`) |
+| Language | 2 | Dynamically typed | Python 3.12+ — 100% `.py` files |
+| Deployment | 1 | Internal tool | Command-line tool for documentation teams |
+| Data Sensitivity | 1 | Internal business data | Operates on internal documentation |
+| Blast Radius | 2 | Data loss (recoverable) | Could corrupt docs, recoverable from git |
+
+*Decision:*
+
+Classify **dacli CLI** as **Tier 2 — Extended Assurance** (determined by max(Code Type=2, Language=2, Blast Radius=2)).
+
+This tier requires:
+
+* **Tier 1 measures:** Linter & formatter, pre-commit hooks, dependency vulnerability scanning, CI with automated tests
+* **Tier 2 measures:** SAST (CodeQL), property-based testing (Hypothesis), code quality gates (SonarCloud), AI-assisted code review, PR review policy with sampling
+
+*Consequences:*
+
+**Positive:**
+
+* Clear security baseline established for the project
+* Comprehensive testing strategy (713 automated tests + property-based tests with 1,100+ generated cases)
+* Automated gates prevent common vulnerabilities (dependency CVEs, code quality issues)
+* SonarCloud integration provides continuous quality monitoring
+* PR review policy balances thoroughness with development velocity (20-30% sampling)
+
+**Negative:**
+
+* Additional CI pipeline duration (~2-3 minutes for SAST and quality gate checks)
+* Developer onboarding overhead (pre-commit hooks, review policy understanding)
+* Maintenance burden for Tier 2 tooling (CodeQL queries, SonarCloud configuration)
+
+==== Pugh Matrix: Risk Tier Selection
+
+[cols="3,1,1,1"]
+|===
+| Criterion | Tier 2 (Baseline) | Tier 1 (Lower) | Tier 3 (Higher)
+
+| Code Complexity Coverage | 0 | - | +
+| Language Risk Mitigation | 0 | - | +
+| Data Loss Prevention | 0 | - | +
+| Development Velocity | 0 | + | -
+| CI/CD Pipeline Complexity | 0 | + | -
+| **Total** | **0** | **-1** | **0**
+|===
+
+_Legend: + better than baseline, 0 same as baseline, - worse than baseline_
+
+**Tier 1 rejected:** Insufficient coverage for business logic complexity and blast radius (data loss risk). Missing SAST and property-based testing would leave gaps in quality assurance.
+
+**Tier 3 rejected:** Not cost-justified. The module is an internal tool without public-facing deployment or sensitive PII. Branch protection and fuzzing would be overkill for the current risk profile.
+
+**Tier 2 selected:** Balanced approach matching the actual risk profile (business logic + dynamic typing + recoverable data loss). Provides strong automated gates without excessive overhead.
diff --git a/src/docs/arc42/adr/ADR-012.adoc b/src/docs/arc42/adr/ADR-012.adoc
@@ -0,0 +1,66 @@
+=== ADR-012: Risk Classification - dacli-mcp (Tier 2)
+
+*Status:* Accepted (2026-02-11)
+
+*Deciders:* Development Team + Claude Code
+
+*Context:*
+
+The dacli-mcp MCP server module requires risk classification according to the Risk Radar framework to determine appropriate security and quality assurance measures. The assessment evaluates five dimensions:
+
+| Dimension | Score | Level | Evidence |
+|-----------|-------|-------|----------|
+| Code Type | 2 | Business Logic | MCP tools, service layer (`src/dacli/mcp_app.py`, `src/dacli/services/`) |
+| Language | 2 | Dynamically typed | Python 3.12+ — 100% `.py` files |
+| Deployment | 1 | Internal tool | MCP server for LLM integration in internal workflows |
+| Data Sensitivity | 1 | Internal business data | Operates on internal documentation |
+| Blast Radius | 2 | Data loss (recoverable) | Could corrupt docs, recoverable from git |
+
+**Note:** Initial consideration was given to Code Type score 3 (API/Database Queries) since the module exposes API endpoints (MCP tools). However, user confirmed score 2 as these are internal service APIs without public exposure or direct database access.
+
+*Decision:*
+
+Classify **dacli-mcp** as **Tier 2 — Extended Assurance** (determined by max(Code Type=2, Language=2, Blast Radius=2)).
+
+This tier requires the same mitigation measures as dacli CLI (both modules share the same codebase):
+
+* **Tier 1 measures:** Linter & formatter, pre-commit hooks, dependency vulnerability scanning, CI with automated tests
+* **Tier 2 measures:** SAST (CodeQL), property-based testing (Hypothesis), code quality gates (SonarCloud), AI-assisted code review, PR review policy with sampling
+
+*Consequences:*
+
+**Positive:**
+
+* Consistent risk management across both module entry points (CLI and MCP server)
+* Shared codebase benefits from unified quality gates and testing strategy
+* MCP tools benefit from the same 713 automated tests + property-based tests
+* FastMCP framework integration validated by comprehensive test suite
+
+**Negative:**
+
+* MCP-specific edge cases may need additional test coverage beyond shared tests
+* Tool invocation patterns (JSON-RPC) differ from CLI patterns, requiring careful validation
+
+==== Pugh Matrix: Risk Tier Selection
+
+[cols="3,1,1,1"]
+|===
+| Criterion | Tier 2 (Baseline) | Tier 1 (Lower) | Tier 3 (Higher)
+
+| API Exposure Risk | 0 | - | +
+| Language Risk Mitigation | 0 | - | +
+| Data Loss Prevention | 0 | - | +
+| Development Velocity | 0 | + | -
+| Tool Integration Complexity | 0 | + | -
+| **Total** | **0** | **-1** | **0**
+|===
+
+_Legend: + better than baseline, 0 same as baseline, - worse than baseline_
+
+**Tier 1 rejected:** Insufficient for an API-like interface (MCP tools). Missing SAST and property-based testing would leave gaps in tool invocation validation and edge case coverage.
+
+**Tier 3 rejected:** Not cost-justified. The MCP server is for internal LLM integration, not public-facing. The deployment context (internal tool) doesn't warrant branch protection, fuzzing, or penetration testing.
+
+**Tier 2 selected:** Appropriate for internal API-like interfaces with business logic. Provides SAST coverage for potential injection vulnerabilities and property-based tests for tool parameter validation without excessive overhead.
+
+**Shared codebase note:** Both dacli CLI and dacli-mcp modules share the same source code (`src/dacli/`). Entry points differ (`dacli.cli:cli` vs `dacli.main:main`), but risk profile and protection measures are identical. All mitigations are applied repository-wide.
diff --git a/src/docs/arc42/adr/ADR-013.adoc b/src/docs/arc42/adr/ADR-013.adoc
@@ -0,0 +1,140 @@
+=== ADR-013: Security Mitigations - Tier 2 Implementation
+
+*Status:* Accepted (2026-02-11)
+
+*Deciders:* Development Team + Claude Code
+
+*Context:*
+
+Following the Tier 2 risk classification for both dacli CLI and dacli-mcp modules (see ADR-011 and ADR-012), the project requires implementation of comprehensive security and quality assurance measures. The Risk Radar framework mandates cumulative mitigations: all Tier 1 measures plus all Tier 2 measures.
+
+Both modules share the same codebase (`src/dacli/`), so mitigations are applied repository-wide rather than per module.
+
+*Decision:*
+
+Implement **all required Tier 1 and Tier 2 mitigation measures** as repository-wide protections:
+
+**Tier 1 — Automated Gates:**
+
+. **Linter & Formatter:** Ruff configured in `pyproject.toml` with enforced rules (E, F, I, N, W, UP) and 100-character line length
+. **Pre-Commit Hooks:** Configured via `.pre-commit-config.yaml` (commit 68d6ae4) with Ruff checks
+. **Dependency Vulnerability Scanning:** `pip-audit` integrated in CI pipeline (commit fee56b6)
+. **CI Build & Unit Tests:** GitHub Actions workflow (`.github/workflows/test.yml`) running 713 automated tests with coverage reporting
+
+**Tier 2 — Extended Assurance:**
+
+. **SAST (Static Application Security Testing):** CodeQL workflow with `security-extended` query suite (commit fead47e), runs on upstream repository only
+. **AI-Assisted Code Review:** Claude Code review workflow (`.github/workflows/claude-code-review.yml`) for automated PR analysis
+. **Property-Based Testing:** Hypothesis framework (commit 87a965d) with 11 property-based tests generating 1,100+ test cases (`tests/test_property_based.py`)
+. **Code Quality Gate:** SonarCloud integration (commit fb4c8ad) via `.github/workflows/sonarcloud.yml` and `sonar-project.properties`
+. **PR Review Policy with Sampling:** Risk-based review policy documented in `.github/PR_REVIEW_POLICY.md` (commit efb868f):
+  * 100% review for security-sensitive changes, breaking changes, architecture changes
+  * 20-30% sampling for bug fixes, refactoring, tests, documentation
+  * Auto-merge eligible: non-security dependency updates, formatting fixes, PATCH version bumps
+
+**Security Fixes Applied:**
+
+* `cryptography` upgraded from 46.0.3 → 46.0.5 (CVE-2026-26007 mitigation)
+* `pip` upgraded from 24.0 → 26.0.1
+* Commit: 7766e90
+
+*Consequences:*
+
+**Positive:**
+
+* **100% mitigation coverage** for both Tier 1 (4/4 measures) and Tier 2 (5/5 measures)
+* **Zero known vulnerabilities** (pip-audit clean)
+* **Comprehensive test coverage:** 713 unit/integration tests + 11 property-based tests (1,100+ generated cases)
+* **Continuous quality monitoring:** SonarCloud provides ongoing code quality metrics and technical debt tracking
+* **Automated security scanning:** CodeQL runs on every push to main, catching potential vulnerabilities before production
+* **Efficient review process:** Sampling policy (20-30%) balances thoroughness with development velocity
+* **Developer experience:** Pre-commit hooks catch issues locally before CI, reducing feedback loop time
+
+**Negative:**
+
+* **CI pipeline duration increase:** ~2-3 minutes added for SAST (CodeQL) and quality gate (SonarCloud) checks
+* **Developer onboarding overhead:** New contributors must understand pre-commit hooks, review policy, and quality standards
+* **Maintenance burden:**
+  - CodeQL query suite updates needed for new Python versions
+  - SonarCloud project configuration requires manual setup and token management
+  - Hypothesis tests may need strategy refinement as edge cases are discovered
+* **External service dependencies:**
+  - SonarCloud outages block PRs (mitigated by making check non-blocking in fork workflow)
+  - CodeQL only runs on upstream repository (not on fork PRs)
+* **False positive handling:** SAST tools may flag intentional patterns (e.g., dynamic code in MCP server), requiring suppression annotations
+
+==== Pugh Matrix: Mitigation Strategy
+
+[cols="3,1,1,1"]
+|===
+| Criterion | Repository-wide (Baseline) | Module-specific | Tier 1 Only
+
+| Implementation Simplicity | 0 | - | +
+| Coverage Completeness | 0 | 0 | -
+| Maintenance Burden | 0 | - | +
+| Risk Mitigation Effectiveness | 0 | 0 | -
+| Compliance with Tier 2 | 0 | 0 | -
+| **Total** | **0** | **-2** | **-1**
+|===
+
+_Legend: + better than baseline, 0 same as baseline, - worse than baseline_
+
+**Module-specific approach rejected:** Both modules share the same codebase (`src/dacli/`). Applying mitigations per module would duplicate CI checks, complicate maintenance, and provide no additional risk reduction.
+
+**Tier 1 only rejected:** Insufficient coverage for Tier 2 classification. Missing SAST, property-based testing, and quality gates would leave critical gaps in security and quality assurance.
+
+**Repository-wide Tier 1+2 selected:** Simplest implementation, consistent protection across all entry points (CLI and MCP), compliant with Risk Radar tier requirements.
+
+==== Alternative Mitigation Measures Considered
+
+**Static Type Checking (mypy):**
+
+* **Rejected for Tier 1:** Python project without strict typing. Retrofitting type annotations to 64+ files would be high effort with moderate benefit. FastMCP framework uses dynamic features that complicate type checking.
+* **Future consideration:** May be added incrementally as codebase matures, but not required for current Tier 2 classification.
+
+**Fuzzing (AFL, cargo-fuzz):**
+
+* **Not required for Tier 2:** Fuzzing is a Tier 3 measure. The project's internal tool deployment context and recoverable data loss blast radius don't justify the complexity and CI time cost of continuous fuzzing.
+
+**Branch Protection:**
+
+* **Not required for Tier 2:** Branch protection (required status checks, mandatory reviews) is a Tier 3 measure. Current PR review policy with sampling (20-30%) provides adequate oversight for internal tool risk profile.
+
+==== Implementation Timeline
+
+All mitigations implemented between 2026-02-09 and 2026-02-11 as part of PR #279:
+
+. Pre-commit hooks: commit 68d6ae4
+. Dependency vulnerability scanning (pip-audit): commit fee56b6
+. Security fixes (cryptography, pip): commit 7766e90
+. CodeQL SAST workflow: commit fead47e
+. Property-based tests (Hypothesis): commit 87a965d
+. SonarCloud quality gate: commit fb4c8ad
+. PR review policy: commit efb868f
+
+**Verification:** All 713 tests passing, CI green, pip-audit clean, CodeQL and SonarCloud integrated.
+
+==== Module-Specific Notes
+
+**PR Review Policy - Differential Application:**
+
+While most mitigations are truly repository-wide, the PR review policy applies differentially based on change type (not module):
+
+* **100% mandatory review:**
+  - Security-sensitive changes (auth, crypto, file system ops with user paths)
+  - Breaking changes (public API, CLI interface, configuration format)
+  - Architecture changes (new components, core parsers, data model)
+  - Release preparation (MINOR/MAJOR version bumps)
+
+* **20-30% sampling review:**
+  - Bug fixes (prioritize critical bugs)
+  - Internal refactoring (prioritize complex changes)
+  - Test additions (prioritize property-based/integration tests)
+  - Documentation updates (prioritize user-facing docs)
+
+* **Auto-merge eligible:**
+  - Dependency updates (PATCH, non-security, passing CI)
+  - Formatting/linting fixes (no logic changes)
+  - PATCH version bumps (small fixes, no API changes)
+
+This differential approach ensures critical changes receive thorough review while maintaining development velocity for lower-risk changes.
diff --git a/src/docs/arc42/chapters/09_architecture_decisions.adoc b/src/docs/arc42/chapters/09_architecture_decisions.adoc
@@ -52,3 +52,15 @@ include::../adr/ADR-009.adoc[]
 ---
 
 include::../adr/ADR-010.adoc[]
+
+---
+
+include::../adr/ADR-011.adoc[]
+
+---
+
+include::../adr/ADR-012.adoc[]
+
+---
+
+include::../adr/ADR-013.adoc[]
