Severity Vocabulary Canonical Mapping

Severity Vocabulary Canonical Mapping

Last updated: 2026-06-05 Pillars: P2 (primary), P4 (supporting). Canonical for: agents/hatch3r-reviewer.md, agents/hatch3r-fixer.md, the 9 CQ quality-vector specialists (agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md), checks/*.md.

Purpose

Single source of truth for severity vocabulary alignment across all hatch3r content artifacts. Audit findings (the canonical audit severity taxonomy) use 5 buckets: Critical, High, Medium, Low, Info. Other artifacts (reviewer agent, security auditor, check criteria) use their own vocabularies. This file maps them so the fixer agent can consume any source's output and map to the canonical bucket.

6-Column Canonical Map

Audit Severity (canonical)	Reviewer Verdict	Reviewer Level	Security-Auditor Severity	Check Criteria Tag	Specialist Status
Critical	DESIGN_OBJECTION	Critical	Critical	[CRITICAL]	CRITICAL
High	REQUEST CHANGES	Critical	High	[CRITICAL]	FINDINGS
Medium	REQUEST CHANGES	Warning	Medium	[RECOMMENDED]	FINDINGS
Low	APPROVE	Suggestion	Low	[RECOMMENDED]	PASS
Info	APPROVE	Suggestion	(n/a)	(n/a)	PASS

Mapping Rationale

• Critical (canonical) maps to DESIGN_OBJECTION because both express a fundamental, unfixable-by-iteration problem requiring architectural intervention. Reviewer Level Critical also maps when paired with REQUEST CHANGES and the issue is a security or correctness blocker.
• High (canonical) maps to REQUEST CHANGES + Reviewer Level Critical. The reviewer's Critical level covers both canonical Critical and High; disambiguation uses verdict (DESIGN_OBJECTION → Critical, REQUEST CHANGES → High) and finding nature (architectural vs. quality gap).
• Medium (canonical) maps to REQUEST CHANGES + Reviewer Level Warning and Security-Auditor Medium. These are quality gaps that block the current cycle but not the release.
• Low (canonical) maps to APPROVE + Reviewer Level Suggestion. The reviewer approves but flags improvements. Security-Auditor Low is the equivalent severity for security-domain findings.
• Info (canonical) has no Security-Auditor or Check-Criteria equivalent because those vocabularies do not enumerate a no-action observation tier.
• Specialist Status (PASS | FINDINGS | CRITICAL) is the 3-value vocabulary emitted by the 9 CQ quality-vector specialists (agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md). CRITICAL maps to canonical Critical (any item shows a Critical-severity finding → DESIGN_OBJECTION-equivalent block). FINDINGS covers the canonical High + Medium band (Medium/High findings present, no Critical → REQUEST CHANGES). PASS maps to canonical Low + Info (every checklist item green or advisory-only → APPROVE). The collapse of two canonical buckets into one specialist value is intentional: specialists gate merge readiness, not finding-by-finding triage, so they emit a coarser status that the fixer re-expands via this row.

Consumer Contract

• hatch3r-fixer: When ingesting findings from any source, MUST map source vocabulary to the canonical Audit Severity column before applying its action policy. Critical → blocking fix; High → blocking fix; Medium → fix in current cycle; Low → fix or defer per scope; Info → log, no action.
• hatch3r-reviewer: Output uses Reviewer Verdict + Reviewer Level columns. Map to canonical via this table when escalating to fixer or audit.
• hatch3r-security (CQ3 specialist): Output uses Security-Auditor Severity column. Map to canonical via this table when emitting findings.
• check criteria authors (checks/*.md): Use Check Criteria Tag column. Map to canonical for severity-rollup reports.
• CQ quality-vector specialists (agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md): Output uses the Specialist Status column (PASS | FINDINGS | CRITICAL). Map to canonical via this table when escalating to fixer or feeding the release decision.
• canonical audit severity taxonomy: Defines the canonical Audit Severity column. This mapping table is the cross-vocabulary reference.
• audit-execute regression gate: The "Severity Vocab" gate enforces that every modified .md content file either uses canonical buckets or references this file.

Edge Cases

• Reviewer Critical overlaps two canonical buckets. Disambiguation rule: use DESIGN_OBJECTION verdict for canonical Critical, REQUEST CHANGES + Critical level for canonical High. When unclear, default to Critical (conservative for fixer blocking-action policy).
• Check Criteria has only two tags. [CRITICAL] covers canonical Critical + High; [RECOMMENDED] covers canonical Medium + Low. Severity-rollup reports must use the worst-case canonical mapping for [CRITICAL] tags (treat as canonical Critical until disambiguated by file/line context).
• Security-Auditor has no Info tier. Security findings of observation-only nature must be either omitted from audit output or flagged as Low with a confidence: low qualifier per the Confidence Expression section of agents/hatch3r-security.md.
• A11y-Auditor WCAG vocabulary. Critical/Major/Minor maps to canonical Critical/Medium/Low (WCAG A blockers → Critical; AA violations → Medium; advisory AA/AAA → Low). No direct High equivalent — escalate Major to High when the violation blocks a critical user journey.
• Dependency-Auditor CVSS vocabulary. CVSS-derived Critical (≥9.0) / High (7.0–8.9) / Medium (4.0–6.9) / Low (<4.0) aligns 1:1 with canonical audit severity. No mapping translation required.

2.0.0 Domain Vocabulary Extensions (Decision 19)

D22 / D23 / D24 admission (per the canonical audit domain map) adds three domain-specific severity vocabularies. Each row maps to the canonical Audit Severity column above.

Domain	Source vocabulary	Bucket meaning	Canonical map
D22 Content Architecture	obsolete	Artifact serves no current pillar AND has zero cross-references	Critical (remove via D16-SA16.3 threshold)
D22 Content Architecture	merge_candidate	≥80% conceptual overlap with another artifact AND removal threshold not met	High (merge the overlapping artifacts)
D22 Content Architecture	drift	Artifact frontmatter or body diverges from current pillar definitions	Medium
D22 Content Architecture	gap	Pillar is under-represented in the content corpus (per web-comparison findings)	Medium (CL-2 candidate)
D22 Content Architecture	coverage_low	Pillar served by <2 artifacts but pillar surface area expects ≥2	Low
D23 Agentic Engineering Trends	lagging	hatch3r lacks a pattern adopted by ≥2 reputable comparables in ≤6 months	High
D23 Agentic Engineering Trends	trailing	hatch3r implements a pattern but ≥1 sub-element behind comparable	Medium
D23 Agentic Engineering Trends	leading	hatch3r ahead of all comparables on a pattern	Info (record as Strength)
D24 Governance Self-Audit	invariant_violation	A constitution invariant (e.g., lean threshold, anti-slop, pillar coverage) is broken	Critical
D24 Governance Self-Audit	process_drift	Audit cycle deviated from the audit-execute Phase contract	High
D24 Governance Self-Audit	traceability_gap	A change landed without a finding-registry entry or §8 amendment trail	Medium
D24 Governance Self-Audit	cadence_miss	Required cadence (re-envision ≥14 days, audit cycle, evolve) overdue	Low

The Specialist Status column from the 6-Column Canonical Map applies to D22/D23/D24 SAs (PASS | FINDINGS | CRITICAL coarse status) — the bucket-level mapping above is the per-finding-row resolution within each SA's output. Consumers (fixer, reviewer) map the source bucket to canonical Audit Severity before applying action policy, identical to the Consumer Contract for existing domains.

Cross-Domain Severity Escalation Rules

A finding's source bucket maps to canonical Audit Severity per the table above. Two escalation rules then re-evaluate the row before it ships to the finding registry:

1. Multi-domain compound rule. A finding cited by ≥2 domain SAs (cross-domain dependency per the compound-system audit domain) escalates one canonical band (Medium → High, High → Critical). Rationale: cross-domain surface area indicates systemic driver, not symptom. The escalation is recorded in the finding's cross_domain_citations registry field; bands cap at Critical.
2. CQ pillar regression rule. A finding that introduces a measurable regression on a CQ1-CQ9 pillar threshold (per the content-quality (CQ) pillars and their specialist agents) escalates one canonical band regardless of source bucket. The CQ specialist's Specialist Status column already collapses to PASS | FINDINGS | CRITICAL — the escalation re-expands to the canonical band the regression actually represents per the regression evidence file path + line cited in the finding body.

Escalations chain: a CQ regression cited by ≥2 domain SAs receives two single-band escalations (capped at Critical). De-escalation is not permitted via these rules — a Critical never falls to High through this protocol; only the bias-check downgrade in the rigor contract (agents/shared/rigor-contract.md §Scientific Rigor Contract item 5) can reduce a severity band.

Verification

This file lives at agents/shared/severity-mapping.md. Enforcement is the inverse of a citation-count floor: scripts/validate-severity-vocabulary.ts (run via npm run validate:severity-vocabulary, wired into npm run validate) scans .md files under agents/, checks/, commands/, rules/, skills/, hooks/, and governance/ for off-canonical severity terms (Moderate, Major, Minor, Blocker, etc.) in a structured severity context (frontmatter severity:, severity-labeled table cells, Severity:/Level: pairs, bracket tags). A file that emits any such term MUST reference this file (basename severity-mapping.md) as the documented opt-out, or the scan emits a SEVERITY-MAPPING-MISS plus per-occurrence SEVERITY-OFF-CANONICAL error (exit 1). The set of referencing files is therefore demand-driven — it grows only when an artifact actually emits an off-canonical term — not a fixed minimum. The mapping doc's own absence at the canonical path makes the scan exit clean on a default-root run (the opt-out can no longer be relied on), so this file's presence is itself the enabling precondition.

Pillar Service

• P2 Scientific Quality (primary): Canonical mapping eliminates ambiguity in fixer bucketing — finder output is round-trippable through the fix pipeline without information loss.
• P4 Lean Coverage (supporting): Single source of truth replaces 5 partial vocabularies (reviewer, security-auditor, check-criteria, CVSS/WCAG auditors, CQ-specialist status); consumers reference instead of restating.