@trohde/earos 1.0.0

package/assets/init/overlays/data-governance.yaml

@@ -0,0 +1,94 @@
+rubric_id: EAROS-OVR-DATA-001
+version: 2.0.0
+kind: overlay
+title: Data Governance Overlay
+status: approved
+artifact_type: any
+purpose:
+  - data_assurance_review
+  - information_architecture_review
+stakeholders:
+  - data_architect
+  - data_governance
+  - risk
+  - privacy
+dimensions:
+  - id: DAT1
+    name: Information treatment and accountability
+    description: >
+      Data flows through architectures like electricity through circuits — present everywhere
+      but invisible unless explicitly documented. This dimension checks whether the artifact
+      treats information as a first-class design concern with explicit ownership, lifecycle
+      treatment, and privacy or quality implications. Data without accountability is a
+      governance liability.
+    criteria:
+      - id: DAT-01
+        question: Does the artifact define key information objects, accountability, lifecycle concerns, and material data quality or privacy implications?
+        description: >
+          Data governance requires more than listing data entities in passing. The artifact must
+          define who owns each key information object, how it flows through the system, how long
+          it lives, and what privacy or quality risks it carries. Without this, data architecture
+          decisions are made implicitly, often incorrectly, and cannot be verified at review time.
+          This criterion applies whenever the artifact describes data flows, storage, retention,
+          or classification.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate: false
+        required_evidence:
+          - key information objects named and described
+          - ownership assignments
+          - lifecycle view (create, store, use, archive, delete)
+          - quality or privacy considerations
+        scoring_guide:
+          "0": No material data treatment anywhere in the artifact
+          "1": Data mentioned only in passing (e.g. 'stores user data in a database')
+          "2": Some data objects defined but ownership and lifecycle are absent or superficial
+          "3": Most material information concerns covered with ownership and some lifecycle treatment
+          "4": Complete information accountability including ownership, classification, lifecycle, retention policy, privacy implications, and quality thresholds
+        anti_patterns:
+          - Data flows shown in diagrams without ownership at each hop
+          - No lifecycle or retention treatment for personal or financial data
+          - Classification missing from information objects
+          - Privacy implications absent for PII-touching designs
+        examples:
+          good:
+            - >
+              "Key information objects: CustomerProfile (owner: Customer Domain, classification:
+              PII/Confidential, retention: account lifetime + 7 years, GDPR lawful basis: contract,
+              quality threshold: < 0.1% field error rate). TransactionRecord (owner: Payments Domain,
+              classification: Financial/Sensitive, retention: 10 years, quality threshold: < 0.01%
+              error rate). Data flows: Section 4 diagram shows numbered steps with ownership at
+              each hop."
+          bad:
+            - >
+              "The system stores customer data and transaction records in a PostgreSQL database.
+              [No ownership, no classification, no lifecycle, no privacy treatment]"
+        decision_tree: >
+          IF no data treatment at all THEN score 0.
+          IF data mentioned but only incidentally THEN score 1.
+          IF some data objects defined but ownership and lifecycle absent THEN score 2.
+          IF most material data concerns covered with ownership and some lifecycle treatment THEN score 3.
+          IF complete information accountability including ownership, classification, lifecycle,
+          retention, privacy, and quality requirements THEN score 4.
+        remediation_hints:
+          - Add an information object table with owner, classification, retention policy
+          - Map data flows with ownership at each hop
+          - Address GDPR lawful basis and right-to-erasure implications for PII
+          - Define data quality thresholds for critical information objects
+
+scoring:
+  scale: 0-4 ordinal plus N/A
+  method: append_to_base_rubric
+  thresholds:
+    escalation: Escalate when material regulated data is present and DAT-01 < 3
+
+outputs:
+  require_evidence_refs: true
+  require_confidence: true
+  require_actions: true
+  require_evidence_class: true
+  require_evidence_anchors: true
+  formats:
+    - yaml
+    - json
+    - markdown-report

package/assets/init/overlays/regulatory.yaml

@@ -0,0 +1,154 @@
+rubric_id: EAROS-OVR-REG-001
+version: 2.0.0
+kind: overlay
+title: Regulatory Compliance Overlay
+status: draft
+artifact_type: any
+purpose:
+  - regulatory_compliance_review
+  - governance_assurance_review
+stakeholders:
+  - compliance
+  - legal
+  - risk
+  - architecture_board
+dimensions:
+  - id: REG1
+    name: Regulatory identification
+    description: >
+      Regulatory compliance begins with identifying which rules apply. An artifact operating
+      in a regulated domain that does not name the applicable regulations cannot be reviewed
+      for compliance — the reviewer has no baseline to measure against. Applicability
+      assessment is a precondition for all downstream compliance evidence.
+    weight: 1.0
+    criteria:
+      - id: REG-ID-01
+        question: Are applicable regulations and compliance requirements explicitly identified?
+        description: >
+          Different regulations apply differently depending on jurisdiction, data type, business
+          activity, and customer segment. An artifact that asserts general regulatory compliance
+          without naming specific regulations, jurisdictions, and applicability rationale provides
+          no basis for governance review. Applicability assessment must be explicit and specific
+          to this artifact's scope.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate:
+          enabled: true
+          severity: critical
+          failure_effect: reject when regulatory applicability cannot be determined
+        required_evidence:
+          - named regulation references (e.g. GDPR, DORA, PSD2)
+          - applicability assessment for each regulation
+          - jurisdiction identification
+        scoring_guide:
+          "0": No regulatory consideration — regulations not mentioned or assessed
+          "1": Vague mention of compliance — 'we will comply with applicable regulations' with no specifics
+          "2": Some regulations named but no applicability assessment — which rules apply and why is unclear
+          "3": Material regulations identified with applicability rationale — specific to this context
+          "4": Complete regulatory mapping with jurisdictional analysis and formal applicability assessment for all relevant regulations
+        anti_patterns:
+          - Compliance assumed without identifying which regulations apply
+          - No jurisdiction specified for data protection regulations
+          - Generic regulatory references without applicability assessment for this specific solution
+        examples:
+          good:
+            - >
+              "Applicable regulations: GDPR (EU) — applies because solution processes EU citizen
+              personal data. PSD2 (EU) — applies because solution initiates payment transactions.
+              DORA (EU) — applies because this is a critical ICT system at a regulated financial
+              entity (classification: Tier 1 critical function). UK GDPR — applies for UK data
+              subjects post-Brexit. Assessed and not applicable: CCPA — no California customers
+              in current scope."
+          bad:
+            - >
+              "The solution will comply with all relevant data protection and financial services
+              regulations. [No specific regulations named, no jurisdiction, no applicability
+              assessment]"
+        decision_tree: >
+          IF no regulatory consideration anywhere THEN score 0.
+          IF compliance mentioned generically without naming specific regulations THEN score 1.
+          IF some regulations named but no applicability assessment THEN score 2.
+          IF material regulations named with applicability rationale for this specific context THEN score 3.
+          IF complete regulatory mapping with jurisdiction analysis and formal applicability assessment THEN score 4.
+        remediation_hints:
+          - List all regulations by jurisdiction and assess applicability with rationale for each
+          - Identify regulations reviewed and found not applicable — document the rationale
+          - Perform a formal applicability assessment if none exists
+
+  - id: REG2
+    name: Compliance evidence
+    description: >
+      Identifying regulations is necessary but insufficient. The artifact must demonstrate
+      how the design satisfies each applicable regulation through specific design controls,
+      audit mechanisms, and documented exceptions with owners and remediation timelines.
+      Compliance by assertion is not compliance.
+    weight: 1.0
+    criteria:
+      - id: REG-EV-01
+        question: Is compliance with identified regulations demonstrated with evidence?
+        description: >
+          Compliance must be demonstrated through specific design controls that can be inspected
+          and verified — not asserted through generic statements. Each applicable regulation
+          requires a mapping to architectural elements that implement the relevant controls.
+          Exceptions must be logged with owner, approval, and remediation plan. Without this,
+          governance boards cannot discharge their compliance oversight responsibility.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate:
+          enabled: true
+          severity: critical
+          failure_effect: reject when compliance evidence is absent for mandatory regulations
+        required_evidence:
+          - regulation-to-control mappings (which design elements satisfy which rules)
+          - compliance statements with specific evidence references
+          - audit trail references
+        scoring_guide:
+          "0": No compliance evidence — regulations identified but no design controls shown
+          "1": Compliance asserted without evidence — 'the system is GDPR compliant'
+          "2": Partial evidence for some regulations — key regulations have partial control mappings
+          "3": Evidence provided for most material regulations — control mappings with design references
+          "4": Complete evidence trail with control-to-regulation mapping, exception log with owners, and verification approach
+        anti_patterns:
+          - Compliance by assertion only — 'we comply with X' without showing how
+          - No exception log for items that do not yet comply
+          - Control mappings exist in a separate document not referenced by this artifact
+        examples:
+          good:
+            - >
+              "GDPR Article 17 (Right to Erasure): implemented via async deletion event propagated
+              to all downstream stores (Section 5.2, see data flow diagram step 8). DORA Article 8
+              (ICT risk management): risk assessment in Section 7; incident classification in
+              Section 8. PSD2 SCA: Strong Customer Authentication via FIDO2 hardware key (Section
+              4.1). Exception: DORA RTS on threat-led penetration testing — not yet completed;
+              planned Q3 2026, Owner: CISO, approved by Risk Committee 2026-01-15."
+          bad:
+            - >
+              "The solution is GDPR and PSD2 compliant. [No control mappings, no design
+              references, no exceptions]"
+        decision_tree: >
+          IF no compliance evidence beyond identifying regulations THEN score 0.
+          IF compliance asserted without showing how design meets requirements THEN score 1.
+          IF evidence provided for some regulations but material regulations have gaps THEN score 2.
+          IF evidence provided for most material regulations with control-to-design mappings THEN score 3.
+          IF complete evidence trail with control mapping, exception log, owners, and verification approach THEN score 4.
+        remediation_hints:
+          - Map each regulation to specific design controls using a compliance matrix
+          - Record exceptions with approver, approval date, and remediation timeline
+          - Reference specific sections and design elements, not generic compliance statements
+
+scoring:
+  scale: 0-4 ordinal plus N/A
+  method: append_to_base_rubric
+  thresholds:
+    critical_regulatory_failure: Reject or escalate when mandatory regulations are unaddressed
+
+outputs:
+  require_evidence_refs: true
+  require_confidence: true
+  require_actions: true
+  require_evidence_class: true
+  require_evidence_anchors: true
+  formats:
+    - yaml
+    - json
+    - markdown-report

package/assets/init/overlays/security.yaml

@@ -0,0 +1,92 @@
+rubric_id: EAROS-OVR-SEC-001
+version: 2.0.0
+kind: overlay
+title: Security Overlay
+status: approved
+artifact_type: any
+purpose:
+  - security_assurance
+  - control_alignment_review
+stakeholders:
+  - security
+  - risk
+  - architecture_board
+dimensions:
+  - id: SEC1
+    name: Threat, control, and ownership treatment
+    description: >
+      Security concerns that are absent from the architecture document will be absent from
+      the architecture. This dimension checks whether the artifact treats security as a
+      first-class design concern — with identified threats, mapped controls, and named
+      ownership — rather than delegating security to delivery as an afterthought.
+    criteria:
+      - id: SEC-01
+        question: Does the artifact show material threats, required controls, and control ownership at a level suitable for the review?
+        description: >
+          A security overlay is applied when an artifact touches authentication, authorization,
+          personal data, privileged access, external integrations, or sensitive processing.
+          The criterion checks whether the artifact identifies material threats, maps required
+          controls to design elements, and assigns ownership — the three minimum elements
+          for a reviewable security treatment. Designs that assert compliance without
+          demonstrating it cannot be approved at governance level.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate:
+          enabled: true
+          severity: critical
+          failure_effect: Reject or escalate when mandatory controls are unaddressed
+        required_evidence:
+          - threat view or risk list
+          - control mapping to design elements
+          - ownership assignments
+        scoring_guide:
+          "0": No material security treatment anywhere in the artifact
+          "1": Security assertions only (e.g. 'the system will be secure') with no specifics
+          "2": Partial threat or control view — some threats identified or some controls mapped but ownership absent
+          "3": Material controls and their owners addressed for key threat areas
+          "4": Threats, controls, residual risk, exceptions, and ownership are all explicit and decision-useful
+        anti_patterns:
+          - Security delegated to delivery without any design response
+          - No exception handling for non-compliant elements
+          - Security section absent from artifact touching personal data
+          - Controls copied from a policy document without mapping to this design
+        examples:
+          good:
+            - >
+              "Threat: Unauthorized access to customer PII. Control: Role-based access control,
+              OAuth 2.0/OIDC, audit logging to SIEM. Owner: Security Architecture. Residual risk:
+              Medium — pending MFA enforcement (planned Q3). Exception: Legacy admin portal —
+              temporary exemption granted by CISO 2026-01-15, expires 2026-07-15."
+          bad:
+            - >
+              "Security will be handled according to enterprise security standards. The delivery
+              team will ensure security requirements are met. [No threats identified, no controls
+              mapped to this design, no ownership]"
+        decision_tree: >
+          IF no security section and no security-related content THEN score 0.
+          IF security mentioned only as assertion or intention THEN score 1.
+          IF partial threat or control view exists but material gaps remain THEN score 2.
+          IF material controls addressed with owners for key threat areas THEN score 3.
+          IF threats, controls, residual risk, exceptions, and ownership are all explicit THEN score 4.
+        remediation_hints:
+          - Map controls explicitly to architecture decisions and components
+          - Record residual risk, exception approvals, and named owners
+          - Produce a threat model or risk register, even if lightweight
+          - Distinguish between controls in the design vs. controls in the platform/infrastructure
+
+scoring:
+  scale: 0-4 ordinal plus N/A
+  method: append_to_base_rubric
+  thresholds:
+    critical_security_failure: Escalate or reject according to control policy when SEC-01 < 2 or gate fails
+
+outputs:
+  require_evidence_refs: true
+  require_confidence: true
+  require_actions: true
+  require_evidence_class: true
+  require_evidence_anchors: true
+  formats:
+    - yaml
+    - json
+    - markdown-report

package/assets/init/profiles/adr.yaml

@@ -0,0 +1,225 @@
+rubric_id: EAROS-ADR-001
+version: 2.0.0
+kind: profile
+title: Architecture Decision Record Profile
+status: approved
+artifact_type: architecture_decision_record
+inherits:
+  - EAROS-CORE-002
+design_method: decision_centred
+purpose:
+  - decision_review
+  - decision_quality_review
+  - knowledge_retention_review
+stakeholders:
+  - architect
+  - engineering_lead
+  - maintainers
+  - governance
+viewpoints:
+  - decision
+  - context
+  - consequence
+
+dimensions:
+  - id: AD1
+    name: Decision clarity
+    description: >
+      An ADR that is unclear about what decision was actually made is worse than no ADR —
+      it creates false confidence that a decision was documented while leaving room for
+      misinterpretation. The decision statement is the most critical element of the record.
+    weight: 1.0
+    criteria:
+      - id: ADR-01
+        question: Is the decision stated as a clear, testable, singular decision rather than a vague discussion topic?
+        description: >
+          The core value of an ADR is capturing a specific decision for future reference.
+          Vague language like 'we will investigate microservices' or 'consider adopting
+          event-driven architecture' is a study plan, not a decision. A testable decision
+          can be verified objectively: either the codebase uses Kafka or it does not. A
+          singular decision means one ADR documents one choice; compound ADRs mixing
+          multiple decisions are ambiguous and hard to supersede.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate:
+          enabled: true
+          severity: major
+          failure_effect: Cannot pass above conditional_pass
+        required_evidence:
+          - decision statement
+          - status (accepted/proposed/superseded)
+          - date or trigger context
+        scoring_guide:
+          "0": No decision — document is meeting notes, discussion, or study results only
+          "1": Topic only — subject area identified but no decision reached or stated
+          "2": Partly clear decision — stated but ambiguous, compound, or untestable
+          "3": Clear decision with explicit scope — singular and understandable
+          "4": Clear, bounded, and testable decision — verifiable, scoped, and dated with trigger context
+        anti_patterns:
+          - ADR as meeting notes with multiple unrelated items
+          - Multiple unrelated decisions in one record
+          - Vague outcome language ('we will look into', 'consider using')
+          - Decision scope undefined (which service, which context?)
+        examples:
+          good:
+            - >
+              "Decision: We will use PostgreSQL as the primary datastore for the Order Service,
+              effective Q2 2026. Status: Accepted. This decision applies only to the Order Service
+              domain; other services may choose different stores with separate justification."
+          bad:
+            - >
+              "The team discussed various database options. After reviewing the pros and cons, the
+              team agreed to proceed with the investigation and revisit next sprint. [No decision
+              reached, no scope, no date]"
+        decision_tree: >
+          IF no decision section exists THEN score 0.
+          IF document is meeting notes or discussion summary with no clear decision THEN score 1.
+          IF decision stated but ambiguous, compound, or untestable THEN score 2.
+          IF single, clear decision with stated scope THEN score 3.
+          IF single, clear, bounded, and testable decision with explicit date and trigger context THEN score 4.
+        remediation_hints:
+          - Rewrite the decision in one declarative sentence in the form 'We will use X for Y'
+          - Split compound ADRs into separate records
+          - Add explicit scope (which service, which domain, which timeframe)
+
+  - id: AD2
+    name: Option space and consequences
+    description: >
+      The option space captures the intellectual work behind the decision. Future maintainers
+      must be able to understand why the chosen option was selected and why alternatives were
+      rejected — without needing to reconstruct the original thinking from memory or oral history.
+    weight: 1.0
+    criteria:
+      - id: ADR-02
+        question: Does the ADR capture meaningful alternatives and the consequences of the chosen decision?
+        description: >
+          An ADR that only documents the chosen option is only half an ADR. The value for
+          future readers lies in understanding the rejected alternatives and the consequences
+          of the chosen path — including the negative consequences accepted as an explicit
+          trade-off. Without this, future maintainers cannot judge whether the original
+          decision still applies in a changed context.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate: false
+        required_evidence:
+          - alternatives considered
+          - pros and cons of alternatives
+          - consequences of the chosen option (including negative)
+          - reversibility assessment
+        scoring_guide:
+          "0": No alternatives or consequences documented
+          "1": Superficial mention — 'we considered X but chose Y' with no reasoning
+          "2": Partial treatment — alternatives listed or consequences noted but not both
+          "3": Meaningful alternatives with pros/cons and genuine consequences stated
+          "4": Strong rationale with explicit trade-offs, reversibility conditions, and downstream effects on other decisions
+        anti_patterns:
+          - Only positive consequences documented
+          - Rejected options listed without explanation
+          - No reversibility or exit conditions
+          - Consequences omit known downsides
+        examples:
+          good:
+            - >
+              "Alternatives: (A) MongoDB — rejected: no ACID guarantees for financial data.
+              (B) MySQL — rejected: licensing cost at expected volume exceeds budget. Consequences:
+              PostgreSQL requires managed RDS service (adds £1,200/month opex). Trade-off: higher
+              cost accepted for stronger consistency guarantees. Reversible: yes, with data migration;
+              trigger: if managed PostgreSQL cost exceeds £5,000/month for 2 consecutive quarters."
+          bad:
+            - >
+              "We considered other options but PostgreSQL was the best fit for our needs.
+              [No alternatives named, no consequences, no reversibility]"
+        decision_tree: >
+          IF no alternatives or consequences THEN score 0.
+          IF one-sentence mention of alternatives with no reasoning THEN score 1.
+          IF alternatives listed without meaningful comparison OR consequences superficial THEN score 2.
+          IF meaningful alternatives with pros/cons AND genuine consequences including negatives THEN score 3.
+          IF explicit trade-offs, reversibility conditions, and downstream effects on other decisions THEN score 4.
+        remediation_hints:
+          - Add a named alternatives table with rejection reasoning for each
+          - Document negative consequences alongside positive ones
+          - Define explicit reversibility conditions and triggers
+
+  - id: AD3
+    name: Decision durability and traceability
+    description: >
+      An ADR is an investment in institutional memory. For that investment to pay off, the
+      decision must remain interpretable years later by people who were not in the room.
+      This requires the context that made the decision necessary, the conditions under which
+      it should be revisited, and links to the artifacts and processes it affects.
+    weight: 1.0
+    criteria:
+      - id: ADR-03
+        question: Can a future reader understand why the decision was made and when it should be revisited?
+        description: >
+          Architecture decisions made today will be revisited, challenged, or overridden by
+          teams years from now. An ADR with no review triggers assumes the world is static.
+          Specifying when to revisit — and making the decision interpretable to future readers
+          who lack the original context — turns an ADR from a historical artifact into an
+          active governance tool that signals when the decision has been invalidated.
+        metric_type: ordinal
+        scale: [0, 1, 2, 3, 4, "N/A"]
+        gate: false
+        required_evidence:
+          - business or technical context that motivated the decision
+          - drivers that made this the right choice at the time
+          - review triggers or conditions for revisiting
+          - links to related artifacts or superseded decisions
+        scoring_guide:
+          "0": No durable context — only the decision itself with no surrounding information
+          "1": Weak historical trace — vague context or no review triggers
+          "2": Some future usefulness — context provided but incomplete or generic
+          "3": Mostly durable and traceable — sufficient context for future reader, review triggers defined
+          "4": Durable, traceable, and reviewable — complete context, specific triggers, links to related artifacts, and supersession chain
+        anti_patterns:
+          - Decision depends entirely on oral history for interpretation
+          - No revisit conditions or triggers defined
+          - Context so generic it applies to any decision
+          - Links to superseded decisions or related ADRs absent
+        examples:
+          good:
+            - >
+              "Context: Q1 2026 cost optimization initiative required switching from managed cloud
+              database to self-managed. Business driver: reduce infrastructure spend by 20% (OKR).
+              Review triggers: (1) team size drops below 3 DBAs, (2) managed PostgreSQL pricing
+              drops below self-managed TCO, (3) each major PostgreSQL version upgrade requires
+              assessment. Supersedes: ADR-007 (MySQL selection 2023). Related: RFC-022
+              (infrastructure cost policy), ADR-012 (backup strategy)."
+          bad:
+            - >
+              "This decision was made because the current approach was not working well.
+              [No specific context, no drivers, no review triggers, no links]"
+        decision_tree: >
+          IF no context or durable information beyond the decision itself THEN score 0.
+          IF minimal context with no links or review triggers THEN score 1.
+          IF some context provided but incomplete or generic, or triggers missing THEN score 2.
+          IF sufficient context for future reader AND review triggers defined THEN score 3.
+          IF complete context, specific triggers, links to related artifacts, and supersession chain THEN score 4.
+        remediation_hints:
+          - Add the business or technical context that made this decision necessary
+          - Define at least two specific review triggers
+          - Link to superseded decisions and related ADRs, RFCs, or policy documents
+
+scoring:
+  scale: 0-4 ordinal plus N/A
+  method: gates_first_then_weighted_average
+  thresholds:
+    pass: No critical gate failure, overall >= 3.2, and no dimension < 2.0
+    conditional_pass: No critical gate failure and overall 2.4-3.19 or one weak dimension
+    rework_required: Overall < 2.4 or repeated weak dimensions
+    reject: Critical gate failure or mandatory control breach
+    not_reviewable: Evidence insufficient for core gate criteria
+    profile_specific_escalation: Escalate when ADR-01 < 3 for strategic or cross-team decisions
+  na_policy: Exclude N/A criteria from denominator; evaluator must justify N/A
+  confidence_policy: Confidence reported separately, must not modify score
+
+outputs:
+  require_evidence_refs: true
+  require_confidence: true
+  require_actions: true
+  require_evidence_class: true
+  require_evidence_anchors: true
+  formats:
+    - yaml
+    - json
+    - markdown-report