@trohde/earos 1.0.0

package/assets/init/docs/consistency-report.md

@@ -0,0 +1,325 @@
+# EaROS Consistency Report
+
+**Date:** 2026-03-19
+**Performed by:** Claude Sonnet 4.6 (automated + manual review)
+**Scope:** Full project — YAML rubrics, JSON schemas, Markdown docs, templates
+**Validation tool:** `tools/validate.py` (jsonschema Draft 2020-12)
+
+---
+
+## Executive Summary
+
+| Category | Before | After |
+|----------|--------|-------|
+| Schema errors | 10 | 0 |
+| Duplicate criterion IDs | 0 | 0 |
+| Duplicate dimension IDs | 0 | 0 |
+| Cross-reference errors | 3 | 0 |
+| Documentation inaccuracies | 5 | 0 |
+| Quality warnings (missing optional fields) | 97 | 89 |
+
+All schema errors and documentation inaccuracies have been fixed. Quality warnings represent missing CLAUDE.md-recommended fields (`description`, `decision_tree`, `examples.good/bad`) in older criteria — these require content authoring, not structural fixes, and are tracked as technical debt below.
+
+---
+
+## Check 1 — Schema Validation
+
+**Tool:** Python `jsonschema` v4.x, Draft 2020-12 validator against `standard/schemas/rubric.schema.json`
+**Required top-level fields per schema:** `rubric_id`, `version`, `kind`, `title`, `artifact_type`, `dimensions`, `scoring`, `outputs`
+
+### Violations Found and Fixed
+
+| File | Violation | Fix Applied |
+|------|-----------|-------------|
+| `profiles/roadmap.yaml` | Missing required `outputs` section | Added `outputs` block with all v2 fields |
+| `overlays/regulatory.yaml` | Missing required `scoring` section | Added `scoring` with `append_to_base_rubric` method |
+| `overlays/regulatory.yaml` | Missing required `outputs` section | Added `outputs` block with all v2 fields |
+
+### Post-fix Status
+
+All 9 rubric files now pass schema validation with 0 errors.
+
+---
+
+## Check 2 — Criterion ID Uniqueness
+
+**Method:** Programmatic scan of all `criteria[*].id` fields across all 9 rubric files.
+**Result: PASS — no duplicates.**
+
+35 unique criterion IDs found:
+
+| ID | File |
+|----|------|
+| ACT-01 | core/core-meta-rubric.yaml |
+| ADR-01, ADR-02, ADR-03 | profiles/adr.yaml |
+| CAP-01, CAP-02, CAP-03 | profiles/capability-map.yaml |
+| CMP-01, CON-01, CVP-01, MNT-01, RAT-01, SCP-01, STK-01, STK-02, TRC-01 | core/core-meta-rubric.yaml |
+| DAT-01 | overlays/data-governance.yaml |
+| RA-DEC-01, RA-DEC-02, RA-IMP-01, RA-IMP-02, RA-OPS-01, RA-QA-01, RA-REU-01, RA-VIEW-01, RA-VIEW-02 | profiles/reference-architecture.yaml |
+| RD-DEP-01, RD-OWN-01, RD-TRN-01 | profiles/roadmap.yaml |
+| REG-EV-01, REG-ID-01 | overlays/regulatory.yaml |
+| SEC-01 | overlays/security.yaml |
+| SOL-01, SOL-02, SOL-03 | profiles/solution-architecture.yaml |
+
+---
+
+## Check 3 — Dimension ID Uniqueness
+
+**Method:** Programmatic scan of all `dimensions[*].id` fields across all 9 rubric files.
+**Result: PASS — no duplicates.**
+
+31 unique dimension IDs found across: `D1–D9` (core), `RA-D1–RA-D6` (reference architecture), `SD1–SD3` (solution architecture), `AD1–AD3` (ADR), `CP1–CP3` (capability map), `RD1–RD3` (roadmap), `SEC1` (security), `DAT1` (data governance), `REG1–REG2` (regulatory).
+
+---
+
+## Check 4 — Cross-Reference Integrity
+
+### Violations Found and Fixed
+
+| File | Violation | Fix Applied |
+|------|-----------|-------------|
+| `profiles/solution-architecture.yaml` | `inherits: [EAROS-CORE-001@1.0.0]` — referenced rubric_id does not exist in the v2 repository | Changed to `inherits: [EAROS-CORE-002]` |
+| `profiles/adr.yaml` | Same — inherits non-existent `EAROS-CORE-001@1.0.0` | Changed to `inherits: [EAROS-CORE-002]` |
+| `profiles/capability-map.yaml` | Same — inherits non-existent `EAROS-CORE-001@1.0.0` | Changed to `inherits: [EAROS-CORE-002]` |
+| `overlays/regulatory.yaml` | Had `inherits: [EAROS-CORE-002]` — overlays must NOT have an `inherits` field; they append, not inherit | Removed `inherits` field entirely |
+
+### Post-fix Status
+
+All profiles inherit `EAROS-CORE-002`. No overlays have `inherits` fields. All referenced rubric IDs resolve to existing files.
+
+---
+
+## Check 5 — Scoring Consistency
+
+### Scale definition
+
+All 9 files use `scale: 0-4 ordinal plus N/A` ✓
+
+### Scoring guide completeness (keys "0"–"4" for ordinal criteria)
+
+All ordinal criteria have all five keys in `scoring_guide`. ✓
+
+### Status threshold consistency
+
+| File | Method | Thresholds |
+|------|--------|------------|
+| `core-meta-rubric.yaml` | `gates_first_then_weighted_average` | Full set incl. floor check ✓ |
+| `reference-architecture.yaml` | `gates_first_then_weighted_average` | Full set ✓ |
+| `roadmap.yaml` | `gates_first_then_weighted_average` | **Fixed** — was missing floor check `no dimension < 2.0` |
+| `solution-architecture.yaml` | `merge_with_inherited_and_apply_core_thresholds` | Profile-specific escalation only (by design) |
+| `adr.yaml` | `merge_with_inherited_and_apply_core_thresholds` | Profile-specific escalation only (by design) |
+| `capability-map.yaml` | `merge_with_inherited_and_apply_core_thresholds` | Profile-specific escalation only (by design) |
+| `security.yaml` | `append_to_base_rubric` | Overlay-specific ✓ |
+| `data-governance.yaml` | `append_to_base_rubric` | Overlay-specific ✓ |
+| `regulatory.yaml` | `append_to_base_rubric` | **Fixed** — was missing `scoring` section |
+
+**Note on `merge_with_inherited_and_apply_core_thresholds`:** This method name is non-standard (not defined in the schema's method enum). It is nonetheless consistent across the three older profiles (SOL, ADR, CAP) and is a valid string per the schema (which does not restrict method values). Future authoring guidance should address whether these profiles should adopt `gates_first_then_weighted_average`.
+
+---
+
+## Check 6 — Gate Type Consistency
+
+**Valid gate severity values per schema:** `advisory`, `major`, `critical`
+**Valid disabled form:** `gate: false`
+
+All gate configurations across all 35 criteria use valid severity values. No invalid gate types found. ✓
+
+Gate inventory:
+
+| Criterion | File | Severity |
+|-----------|------|----------|
+| STK-01, TRC-01 | core | major |
+| SCP-01, CMP-01 | core | critical |
+| RA-VIEW-01, RA-DEC-01, RA-OPS-01, RA-QA-01 | reference-architecture | major |
+| SOL-01 | solution-architecture | major |
+| SOL-02 | solution-architecture | critical |
+| ADR-01 | adr | major |
+| CAP-01 | capability-map | major |
+| RD-DEP-01 | roadmap | major |
+| SEC-01 | security | critical |
+| REG-ID-01, REG-EV-01 | regulatory | critical |
+| All others | — | `gate: false` |
+
+---
+
+## Check 7 — File Naming Consistency
+
+**Convention (CLAUDE.md §8):** `<artifact-type>.v<major>.yaml` where `<major>` must match the major version number inside the file.
+
+### Violations Found
+
+| File | Filename Major | Internal Version | Status |
+|------|---------------|-----------------|--------|
+| `core-meta-rubric.yaml` | 2 | 2.0.0 | ✓ |
+| `reference-architecture.yaml` | 2 | 2.0.0 | ✓ |
+| `roadmap.yaml` | 2 | 2.0.0 | ✓ |
+| `regulatory.yaml` | 2 | 2.0.0 | ✓ |
+| `solution-architecture.yaml` | 2 | **1.0.0 → fixed to 2.0.0** | ✓ (after fix) |
+| `adr.yaml` | 2 | **1.0.0 → fixed to 2.0.0** | ✓ (after fix) |
+| `capability-map.yaml` | 2 | **1.0.0 → fixed to 2.0.0** | ✓ (after fix) |
+| `security.yaml` | 2 | 1.0.0 | ⚠ mismatch |
+| `data-governance.yaml` | 2 | 1.0.0 | ⚠ mismatch |
+
+**Remaining mismatch — `security.yaml` and `data-governance.yaml`:** These overlays have `version: 1.0.0` internally but are named `.yaml`. The `v2` in the filename appears to denote EaROS framework era rather than the file's own major version — a deliberate ambiguity in the original design. These have NOT been changed because: (1) bumping to 2.0.0 would imply a breaking change that did not occur, and (2) the `v2` naming may be intentional to signal EaROS v2 compatibility. This should be resolved by a governance decision, documented below under Judgment Calls.
+
+All filenames use kebab-case ✓. No spaces in filenames ✓.
+
+---
+
+## Check 8 — Missing Required Fields
+
+### Schema-required criterion fields (`id`, `question`, `metric_type`, `scale`, `required_evidence`, `scoring_guide`)
+
+**Result: PASS — all 35 criteria have all 6 schema-required fields.** ✓
+
+### CLAUDE.md-required criterion fields (`description`, `gate`, `anti_patterns`, `examples.good`, `examples.bad`, `decision_tree`, `remediation_hints`)
+
+This is a quality standard beyond the JSON schema. 89 warnings remain after fixes. The `reference-architecture.yaml` profile is the most complete; older profiles (SOL, ADR, CAP, Roadmap) and the two simple overlays (SEC, DAT) are missing these fields on most criteria.
+
+**Breakdown by file:**
+
+| File | Criteria | Missing `description` | Missing `decision_tree` | Missing `examples` |
+|------|----------|-----------------------|------------------------|-------------------|
+| `core-meta-rubric.yaml` | 10 | 9 | 8 | 7 |
+| `reference-architecture.yaml` | 9 | 0 | 5 | 3 |
+| `solution-architecture.yaml` | 3 | 3 | 3 | 3 |
+| `adr.yaml` | 3 | 3 | 3 | 3 |
+| `capability-map.yaml` | 3 | 3 | 3 | 3 |
+| `roadmap.yaml` | 3 | 3 | 3 | 3 |
+| `security.yaml` | 1 | 1 | 1 | 1 |
+| `data-governance.yaml` | 1 | 1 | 1 | 1 |
+| `regulatory.yaml` | 2 | 2 | 2 | 2 |
+
+**Action required:** The missing fields in each criterion need domain-expert authoring. They cannot be safely auto-filled — they require knowledge of the review context. This is tracked as a backlog item below.
+
+---
+
+## Check 9 — README/Docs Consistency
+
+### Violations Found and Fixed
+
+| File | Issue | Fix Applied |
+|------|-------|-------------|
+| `README.md` | Score labels used `Exemplary`, `Adequate`, `Insufficient` instead of the canonical `Strong`, `Good`, `Weak` from CLAUDE.md §2.1 and the core rubric | Fixed to match canonical labels |
+| `README.md` | DAG step names `challenge_pass_check` and `calibration_anchor` do not match YAML (`challenge_pass`, `calibration`) | Fixed |
+| `docs/getting-started.md` | Referenced `level_descriptors` (field does not exist) — correct field name is `scoring_guide` | Fixed |
+| `docs/getting-started.md` | Referenced `evidence_requirement` (field does not exist) — correct field name is `required_evidence` | Fixed |
+| `docs/getting-started.md` | Gate description stated "any gate criterion scores 0 → Reject" — incorrect; only `critical` gates reject; `major` gates cap at Conditional Pass | Fixed to accurately describe gate severity model |
+| `CHANGELOG.md` | DAG step names `challenge_pass_check` and `calibration_anchor` | Fixed |
+| `CHANGELOG.md` | Reference architecture profile listed as "11 criteria" — actual count is 9 | Fixed |
+| `profiles/reference-architecture.yaml` | Internal comment stated "11 criteria … 21 criteria total" | Fixed to 9 / 19 |
+| `CLAUDE.md` | Section 10 stated "11 criteria … 21 criteria total" | Fixed to 9 / 19 |
+
+### File reference integrity (README → actual files)
+
+All files referenced in README.md were verified to exist:
+- `core/core-meta-rubric.yaml` ✓
+- All 5 profiles ✓
+- All 3 overlays ✓
+- Both JSON schemas ✓
+- Both template files ✓
+- `templates/reference-architecture/Reference_Architecture_Template_v2.docx` ✓
+- Both scoring sheets ✓
+- `examples/example-solution-architecture.evaluation.yaml` ✓
+- `calibration/gold-set/`, `calibration/results/` ✓
+- All 3 research files ✓
+- All 3 presentation files ✓
+- `docs/getting-started.md`, `docs/profile-authoring-guide.md` ✓
+
+---
+
+## Check 10 — Duplicate Files
+
+**Method:** Compared files by purpose and content type.
+
+`tools/scoring-sheets/EAROS_Scoring_Sheet.xlsx` (v1) and `tools/scoring-sheets/EAROS_Scoring_Sheet_v2.xlsx` (v2) coexist intentionally — the v1 sheet is the original tooling from EaROS v1.0, kept for reference. The README correctly lists both. Not a duplicate.
+
+No other duplicate files found. ✓
+
+---
+
+## Check 11 — CHANGELOG Completeness
+
+### Violations Found and Fixed
+
+| Issue | Fix Applied |
+|-------|-------------|
+| DAG step names `challenge_pass_check` / `calibration_anchor` | Fixed to `challenge_pass` / `calibration` |
+| Reference architecture profile listed with "11 criteria" | Fixed to 9 |
+
+### Coverage gaps (not fixed — judgment calls)
+
+- The CHANGELOG v1.0.0 entry references `solution-architecture.yaml` and `adr.yaml`, but the repository contains `solution-architecture.yaml` and `adr.yaml`. The v1.x files no longer exist in the repository. The v2.0.0 changelog does not mention these profiles were ported/revised for v2. **Recommendation:** Add a changelog entry noting the v2 updates to `solution-architecture.yaml`, `adr.yaml`, and `capability-map.yaml` — or annotate that they were renamed from v1 originals.
+
+---
+
+## Check 12 — CLAUDE.md Accuracy
+
+The CLAUDE.md accurately describes the project structure, scoring model, gate types, evaluation modes, and conventions, with the single fix applied above (criterion count 11→9). All file paths in the Quick Reference table were verified to exist. ✓
+
+---
+
+## Judgment Calls (Not Auto-Fixed)
+
+These items require deliberate decisions by the project owner:
+
+### JC-1: Overlays `security.yaml` and `data-governance.yaml` — version mismatch
+
+Both have `version: 1.0.0` internally but are named `.yaml`. Two interpretations:
+- **Interpretation A:** The `v2` in the filename means EaROS-v2-era compatibility, not the file's own major version. Under this interpretation, `version: 1.0.0` is correct.
+- **Interpretation B:** Per CLAUDE.md §8 convention, `v<major>` in the filename must match the internal major. Under this interpretation, the internal version should be `2.0.0`.
+
+**Recommendation:** Adopt Interpretation B for consistency. Bump both overlays to `version: 2.0.0` and document in CHANGELOG. This is a non-breaking change (no scoring model change).
+
+### JC-2: `merge_with_inherited_and_apply_core_thresholds` scoring method
+
+Three profiles (SOL, ADR, CAP) use this non-standard method name. It is not defined in the schema's `method` property (which accepts any string, so no schema violation), but it differs from the primary method `gates_first_then_weighted_average` used by newer files.
+
+**Recommendation:** Decide whether these profiles should use `gates_first_then_weighted_average` (requiring full threshold definitions) or whether `merge_with_inherited_and_apply_core_thresholds` should be formally documented as a valid method name in the schema.
+
+### JC-3: Missing recommended criterion fields across 27 criteria
+
+89 quality warnings remain for missing `description`, `decision_tree`, and `examples.good/bad` fields. The reference architecture profile is the model of completeness; all other files fall short of the CLAUDE.md §8 standard.
+
+**Recommendation:** Create a sprint/backlog item to enrich each criterion with:
+1. A `description` field (what does this criterion assess and why does it matter?)
+2. A `decision_tree` with IF/THEN logic for AI agent disambiguation
+3. `examples.good` and `examples.bad` for concrete illustrations
+
+Priority order: core criteria first (most frequently used), then SOL/ADR/CAP profiles, then overlays.
+
+### JC-4: CHANGELOG v1.0.0 entry references non-existent file names
+
+The v1.0.0 section mentions `solution-architecture.yaml` and `adr.yaml`, which are not in the repository. Either the files were renamed without a changelog entry, or the v1 files were replaced wholesale.
+
+**Recommendation:** Add a note to CHANGELOG v2.0.0 explaining that `solution-architecture.yaml` and `adr.yaml` are updated versions of the v1.0 originals, now inheriting EAROS-CORE-002.
+
+---
+
+## Files Modified by This Consistency Check
+
+| File | Change |
+|------|--------|
+| `profiles/solution-architecture.yaml` | Fixed `inherits` (CORE-001→CORE-002), added `design_method: decision_centred`, bumped `version` to 2.0.0, added `require_evidence_class` and `require_evidence_anchors` to outputs |
+| `profiles/adr.yaml` | Fixed `inherits`, added `design_method: decision_centred`, bumped `version` to 2.0.0, added v2 output fields |
+| `profiles/capability-map.yaml` | Fixed `inherits`, added `design_method: viewpoint_centred`, bumped `version` to 2.0.0, added v2 output fields |
+| `profiles/roadmap.yaml` | Added missing `outputs` section, fixed `thresholds` to include floor check and `not_reviewable` status |
+| `overlays/regulatory.yaml` | Removed erroneous `inherits` field, added `scoring` section, added `outputs` section, fixed `rubric_id` from `EAROS-OVL-REG-001` to `EAROS-OVR-REG-001`, added `anti_patterns` and `remediation_hints` to both criteria |
+| `README.md` | Fixed score labels (Exemplary→Strong, Adequate→Good, Insufficient→Weak), fixed DAG step names |
+| `docs/getting-started.md` | Fixed `level_descriptors`→`scoring_guide`, `evidence_requirement`→`required_evidence`, rewrote gate description to accurately reflect severity model |
+| `CHANGELOG.md` | Fixed DAG step names, fixed reference architecture criterion count (11→9) |
+| `profiles/reference-architecture.yaml` | Fixed internal comment (11 criteria→9, 21 total→19) |
+| `CLAUDE.md` | Fixed Section 10 criterion count (11→9, 21→19) |
+| `tools/validate.py` | New file — validation script for ongoing use |
+
+---
+
+## Validation Script
+
+`tools/validate.py` can be run at any time to re-check all rubric files:
+
+```bash
+py -3 tools/validate.py
+```
+
+It checks: schema compliance, cross-reference integrity, duplicate IDs, gate severities, scoring guide completeness, filename/version alignment, and quality field coverage. Add new rubric files to the `RUBRIC_FILES` list at the top of the script.

package/assets/init/docs/getting-started.md

@@ -0,0 +1,194 @@
+# Getting Started with EaROS
+
+This guide walks you through your first architecture artifact assessment using EaROS. By the end, you will have scored an artifact, produced a structured evaluation record, and know how to interpret the results.
+
+---
+
+## Before You Start
+
+**What you need:**
+- The artifact you want to assess (document, YAML, or structured text)
+- About 30–60 minutes for a first assessment (subsequent assessments take 15–20 minutes once you know the rubric)
+
+**What EaROS provides:**
+- A rubric specifying exactly what to look for and how to score it
+- A scoring sheet to record your evidence and scores
+- Clear pass/fail thresholds
+
+---
+
+## Step 1: Identify the Artifact Type
+
+EaROS has profiles for the most common enterprise architecture artifact types:
+
+| Artifact Type | Profile to Use |
+|--------------|----------------|
+| Solution architecture document | `profiles/solution-architecture.yaml` |
+| Reference architecture | `profiles/reference-architecture.yaml` |
+| Architecture Decision Record (ADR) | `profiles/adr.yaml` |
+| Capability map | `profiles/capability-map.yaml` |
+| Architecture roadmap | `profiles/roadmap.yaml` |
+| Other / unknown | Core only: `core/core-meta-rubric.yaml` |
+
+If your artifact does not match any profile, apply only the core rubric. The core dimensions are universal.
+
+---
+
+## Step 2: Select Your Rubric Set
+
+Every assessment starts with the core and adds a profile, plus any applicable overlays.
+
+**Minimum (core only):**
+```
+core/core-meta-rubric.yaml
+```
+
+**Typical (core + profile):**
+```
+core/core-meta-rubric.yaml
+profiles/solution-architecture.yaml
+```
+
+**Full (core + profile + overlay):**
+```
+core/core-meta-rubric.yaml
+profiles/solution-architecture.yaml
+overlays/security.yaml         ← if the design touches auth, secrets, or data handling
+overlays/data-governance.yaml  ← if the design involves data flows or storage
+overlays/regulatory.yaml       ← if the design is subject to compliance requirements
+```
+
+Apply overlays selectively. Not every artifact needs every overlay.
+
+---
+
+## Step 3: Open the Scoring Sheet
+
+Open the appropriate Excel scoring sheet from `tools/scoring-sheets/`:
+
+- **`EAROS_Scoring_Sheet_v2.xlsx`** — use for most artifact types
+- **`EAROS_RefArch_Scoring_Sheet.xlsx`** — use specifically for reference architectures
+
+The scoring sheet has:
+- One tab per rubric section (core dimensions + profile dimensions)
+- Dropdown menus for scores (0, 1, 2, 3, 4, N/A)
+- Evidence fields for recording your cited text or reference
+- An automatic aggregation tab that calculates the weighted score and indicates the pass threshold
+
+---
+
+## Step 4: Read the Rubric, Then Read the Artifact
+
+Open the relevant YAML rubric files. For each criterion, familiarise yourself with:
+- The `description` — what the criterion is asking
+- The `scoring_guide` — what each score level (0–4) means for this specific criterion
+- The `required_evidence` — what kind of evidence counts
+- The `gate` field — if enabled with severity `critical`, a failure triggers a Reject; severity `major` caps the status at Conditional Pass
+
+**Then read the artifact end-to-end** before scoring. Do not score as you read on the first pass. Form an overall impression first, then return to score criterion by criterion.
+
+---
+
+## Step 5: Score Each Criterion
+
+For each criterion:
+
+1. **Find the evidence.** Locate the section, statement, diagram, or table in the artifact that addresses this criterion. If you cannot find any evidence, that is a 0 (Absent) or N/A, not a 1.
+
+2. **Match the level descriptor.** Compare what you found to the descriptor for each score level. The score is the *highest level where the artifact fully satisfies the descriptor*. If it partially meets level 3 but not fully, score 2.
+
+3. **Record the evidence.** In the scoring sheet evidence field, write a brief reference: section number, page, or a short direct quote. This is mandatory — unsubstantiated scores are not valid under EaROS.
+
+4. **Flag uncertainty.** If you genuinely cannot assess the criterion (for example, the artifact references external documents you do not have access to), mark it N/A and note the reason.
+
+### Example Scoring Decision
+
+**Criterion:** Scope and boundary clarity
+**Descriptor for score 3:** "Scope is defined with boundaries; assumptions are stated but some exclusions are implicit rather than explicit."
+**Descriptor for score 4:** "Scope is precisely defined with explicit boundaries, exclusions, assumptions, and constraints; no ambiguity about what is in or out."
+
+You read the artifact and find a scope statement that defines what is in scope but does not list explicit exclusions. → **Score: 3** → Record: "Section 1.2: scope statement defines in-scope components but exclusions are not listed."
+
+---
+
+## Step 6: Check the Gates
+
+Before calculating the aggregate, check every criterion with a `gate` object (not `gate: false`) in the rubric files. Gate behaviour depends on severity:
+
+- **`critical`** — Any score below the threshold triggers an immediate **Reject**, regardless of the aggregate score.
+- **`major`** — A weak score (typically < 2) caps the status at **Conditional Pass** at best; cannot achieve a Pass.
+- **`advisory`** — Triggers a recommendation but does not cap the status.
+
+Gate criteria represent non-negotiable minimums on their respective concern. A critical gate failure means the artifact has a fundamental deficiency that makes it unsuitable for its purpose.
+
+---
+
+## Step 7: Determine the Status
+
+The scoring sheet calculates the weighted dimension average automatically. Read the status from the aggregation tab:
+
+| Weighted Average | Status |
+|-----------------|--------|
+| ≥ 3.2 | **Pass** |
+| 2.4 – 3.19 | **Conditional Pass** |
+| < 2.4 | **Rework Required** |
+| Any gate at 0 | **Reject** |
+
+**Conditional Pass** means the artifact is acceptable for use but has identified remediation items that must be addressed before the next formal review. Document each item with the criterion ID, the score, and the specific improvement needed.
+
+---
+
+## Step 8: Write the Evaluation Record
+
+Use `templates/evaluation-record.template.yaml` to produce a structured evaluation record. See `examples/example-solution-architecture.evaluation.yaml` for a completed example.
+
+The evaluation record captures:
+- Artifact metadata (name, version, type, author)
+- Assessor identity and date
+- Rubric set used (core + profile + overlays, with versions)
+- Per-criterion scores and evidence references
+- Dimension averages and weights
+- Gate check results
+- Overall status
+- Remediation items (for Conditional Pass) or rejection reason (for Reject)
+
+Store completed evaluation records with the artifact or in your architecture governance system.
+
+---
+
+## Interpreting Results
+
+### Pass
+The artifact meets the standard. It may still have minor improvement opportunities noted in the assessment — these are recommended, not required.
+
+### Conditional Pass
+The artifact is usable but has specific gaps that must be addressed. List each remediation item with the criterion ID and a concrete improvement. Schedule a re-review after remediation.
+
+### Rework Required
+The artifact has pervasive or significant gaps. Return it to the author with the full evaluation record. A new assessment is required after rework — do not re-score the same version.
+
+### Reject
+The artifact has failed one or more gate criteria, indicating a fundamental deficiency. Reject means the artifact should not be used or progressed until the gate issue is fully resolved. A gate failure is not about quality level — it is about something that makes the artifact unsuitable for its purpose.
+
+---
+
+## Calibrating Your Assessments
+
+If you are introducing EaROS to a team or beginning to use it for formal governance, calibrate before going live:
+
+1. Select 3–5 artifacts of the same type with a range of quality levels
+2. Have two or more assessors score them independently using the same rubric set
+3. Compare scores criterion by criterion
+4. For any criterion where scores differ by more than 1 point, re-read the level descriptors together and reach consensus
+5. Document the agreed interpretation in a calibration note stored in `calibration/gold-set/`
+
+Target inter-rater reliability: Cohen's κ > 0.70 for well-defined criteria.
+
+---
+
+## Next Steps
+
+- **Create a profile** for an artifact type not yet covered → [`docs/profile-authoring-guide.md`](profile-authoring-guide.md)
+- **Set up AI-agent assessment** → [`README.md`](../README.md#ai-agent-assessment) and [`standard/EAROS.md`](../standard/EAROS.md)
+- **Review the research behind EaROS** → [`research/`](../research/)
+- **Run a team calibration session** → [`calibration/`](../calibration/)

package/assets/init/docs/profile-authoring-guide.md

@@ -0,0 +1,51 @@
+# EaROS v2.0 Profile Authoring Guide
+
+## Overview
+
+Profiles extend the Core Meta-Rubric for specific artifact types. This guide explains how to create, validate, and publish a new profile.
+
+## Before You Start
+
+1. Confirm the artifact type recurs enough to justify standardisation
+2. Verify the Core Meta-Rubric alone is insufficient
+3. Choose a design method (A-E) from EaROS v2.0 Section 15
+4. Gather 3-5 representative artifacts for calibration
+
+## Profile Design Methods
+
+| Method | Best For |
+|--------|----------|
+| A: Decision-Centred | ADRs, investment reviews, exception requests |
+| B: Viewpoint-Centred | Capability maps, reference architectures |
+| C: Lifecycle-Centred | Transition designs, roadmaps, handover docs |
+| D: Risk-Centred | Security, regulatory, resilience architecture |
+| E: Pattern-Library | Recurring reference patterns, platform services |
+
+## Profile Rules
+
+- Inherit the core scale (0-4) and status model unless approved exception
+- Add no more than 5-12 specific criteria
+- Map every criterion to a dimension
+- Define evidence anchors, gate types, and applicability rules
+- Include examples, anti-patterns, and remediation hints
+- Include at least one calibration artifact before approval
+
+## v2.0 Additions
+
+- Include `examples.good` and `examples.bad` for AI disambiguation
+- Add `decision_tree` for ambiguous criteria
+- Specify `design_method` in metadata
+- Set `reliability_targets` for agent evaluation
+- Document `agent_scale` if collapsing to 0-3 for agent mode
+
+## Workflow
+
+1. Create proposal (see EaROS Section 16)
+2. Classify as profile or overlay
+3. Choose design method (A-E)
+4. Draft using `templates/new-profile.template.yaml`
+5. Build calibration pack (1 strong, 1 weak, 1 ambiguous, 1 incomplete)
+6. Run calibration with 2+ reviewers
+7. Revise until agreement stabilises
+8. Approve, publish, and assign owner
+9. Monitor in production