Code Quality Scoring

Code Quality Scoring

A vendor-neutral framework for quantifying and communicating software quality at the application and portfolio level. Most quality skills tell you how to fix one finding; this skill tells you how to score an entire codebase, estimate the cost of its debt, and explain both to people who do not read code.

Source note: The scoring frameworks below are derived from CAST Highlight's code

quality indicators and methodology (https://doc.casthighlight.com/). They are

paraphrased and re-expressed as a vendor-neutral model. Threshold bands and

debt-density figures are CAST's proprietary calibration from their AppMarq benchmark

dataset; they are presented here as attributed reference ranges, not as universal

standards. Where CAST defers to open standards (COCOMO II for effort, SPDX/choosealicense

for licenses, CWE/CVE for security), cite those primary sources.

When to Use This Skill

Use it when the question is "how healthy is this codebase, and what should we do first?" — for example:

• Onboarding to an unfamiliar codebase and needing a health baseline.
• Deciding whether to refactor, rewrite, or retire an application.
• Prioritizing remediation across many applications (a portfolio).
• Estimating the effort/cost a backlog of quality defects represents.
• Presenting a quality/debt position to a manager, product owner, or executive.

Do not reach for it to fix a single defect — for that, use the language-specific quality skills (Python/Java/PHP/TS quality anti-patterns) and code-review-standards.

Core Concept 1 — Software Health is a composite

Treat overall code health as the straight average of three independent dimensions, each scored 0–100. This decomposition (derived from CAST Highlight) is useful because each dimension maps to a different class of fix and a different stakeholder concern:

Software Health = avg(Resiliency, Agility, Elegance)

Threshold bands (attributed to CAST's calibration — use as guidance, not gospel):

The key insight is not the exact numbers — it is that each dimension has its own distribution and its own remediation strategy, so a single blended grade hides the story. A codebase can be green on Resiliency (rarely crashes) yet red on Agility (nobody can change it safely). See [software-health-framework.md](references/software-health-framework.md).

Core Concept 2 — Technical debt is an effort-to-fix estimate

Express debt as estimated remediation effort, derived from violation density scaled by a per-line-of-code debt factor that varies by language. Higher-level / verbose languages (Java, JavaScript, PHP) tend to carry more debt per LOC than concise scripting languages (Python, shell). Always present these as attributed ranges ("Java's median debt density is roughly 3–4× Python's per industry benchmarks") rather than copied exact figures, and convert to money/time only with explicit assumptions stated. CAST's maintenance-effort model itself builds on COCOMO II. See [technical-debt-estimation.md](references/technical-debt-estimation.md).

Core Concept 3 — Cloud readiness is scan + survey

Cloud maturity is the average of a code-scan score (blockers and boosters detected in source — e.g. hard-coded file paths and host names are blockers; statelessness and externalized config are boosters) and a survey score (team/operational factors the code cannot reveal). See [cloud-maturity.md](references/cloud-maturity.md).

Core Concept 4 — Open-source safety is a three-part index

Third-party risk is the average of Security (CVE count weighted by criticality), License Compliance (share of low- vs medium- vs high-risk licenses), and Obsolescence (version gap to latest). This cross-references the Phase 1 OSS Safety work — do not duplicate it. See [open-source-safety.md](references/open-source-safety.md), and for remediation mechanics use universal/security/security-scanning and toolchains/universal/dependency/dependency-audit, which already carry the license-risk tiers and CVE-weighting framing.

Core Concept 5 — Prioritize by business impact

A defect-dense application nobody depends on is lower priority than a moderately-flawed revenue-critical one. Blend a technical risk score with a business impact score (failure consequences, audience size, release/maintenance effort) so remediation is ranked by risk to the business, not by raw defect count. CAST formalizes this as a ROAR-style index (risk weighted by business impact). See [quality-communication-guide.md](references/quality-communication-guide.md).

How to Apply (quick workflow)

1. Score the three health dimensions from your existing linters/scanners — map each tool's findings into Resiliency / Agility / Elegance, average to a Health score, place on the red/orange/green band. 2. Estimate debt — multiply violation density by the language's debt factor (as an attributed range), express as effort (hours/FTE) with assumptions stated. 3. Score OSS safety and cloud readiness if relevant to the decision. 4. Weight by business impact to rank applications/modules. 5. Communicate using the stakeholder framing — lead with risk and money, not rule names.

Anti-Patterns

• Reporting a single blended grade and hiding the dimension that is actually red.
• Quoting debt in exact dollars without stating the LOC, hourly rate, and density

assumptions — present ranges and assumptions.

• Treating CAST's threshold numbers as universal law — they are one vendor's

calibration; cite them as reference context.

• Ranking remediation by defect count instead of by business-weighted risk.
• Duplicating the OSS license tiers here — cross-reference the Phase 1 references.

Navigation

• [Software Health Framework](references/software-health-framework.md) — the

Resiliency/Agility/Elegance decomposition, bands, and how to map linter output onto it.

• [Technical Debt Estimation](references/technical-debt-estimation.md) — effort-to-fix

model, per-language debt-density ranges (attributed), COCOMO II linkage, worked example.

• [Cloud Maturity](references/cloud-maturity.md) — scan vs survey, code blockers and

boosters, how to read a cloud-readiness score.

• [Open Source Safety](references/open-source-safety.md) — the Security/License/

Obsolescence index; cross-references to the dependency-audit and security-scanning skills.

• [Quality Communication Guide](references/quality-communication-guide.md) — business-

impact framing, ROAR-style prioritization, presenting scores to non-technical stakeholders.

Related Skills

• code-review-standards — per-finding checklist with Efficiency + Transferability

dimensions (Phase 1); this skill aggregates those families into scores.

• security-scanning / dependency-audit — OSS safety remediation mechanics.
• software-patterns — architectural signals that low Elegance/Agility scores point to.

Cloud Maturity / Cloud Readiness

Overview

Cloud Maturity measures how well an application is suited to run in (or move to) a cloud environment. Score it 0 (low maturity) to 100 (high maturity) as the average of two independent parts:

Cloud Maturity = avg(Cloud Scan, Cloud Survey)

Source note: This model is derived from CAST Highlight's Cloud Maturity indicator

(https://doc.casthighlight.com/). It is paraphrased and re-expressed vendor-neutrally;

the blocker/booster examples below are original, illustrating the concept rather than

reproducing CAST's catalog.

---

Cloud Scan — what the code reveals (0–100)

Computed from blockers (patterns that resist cloud deployment) and boosters (patterns that ease it) detected in source code. The principle: cloud-native code is stateless, externally configured, and makes no assumptions about the host.

Common blockers (lower the score):

Common boosters (raise the score):

---

Cloud Survey — what the code cannot reveal (0–100)

A questionnaire covering team and operational factors that static analysis cannot see: CI/CD maturity, observability, deployment automation, team cloud experience, licensing/compliance constraints, data-residency requirements. Even perfectly cloud-native code scores low overall if the surrounding organization cannot operate it in the cloud.

---

How to read and act on the score

1. Low Cloud Scan, adequate Survey → the code is the bottleneck. Prioritize removing blockers (externalize config, remove local-disk persistence, add health endpoints). 2. Adequate Cloud Scan, low Survey → the organization is the bottleneck. Invest in CI/CD, observability, and team enablement before migrating. 3. Both low → re-platforming is a multi-quarter effort; sequence code remediation and org enablement deliberately.

Use Cloud Maturity as a migration-readiness gate, not a code-quality grade: a clean, well-tested monolith can still score low if it assumes a fixed host.

References

• CAST Highlight Cloud Maturity indicator — https://doc.casthighlight.com/
• The Twelve-Factor App (open standard for cloud-native config/state) —

https://12factor.net/

Open Source Safety Index (scoring view)

Overview

Open Source Safety expresses third-party / dependency risk as a single 0 (low safety) to 100 (high safety) index — the average of three independent sub-scores. This reference covers the scoring and aggregation angle. The detailed remediation mechanics (license tier definitions, CVE-weighting math, audit commands) already live in the Phase 1 references — cross-reference them, do not duplicate.

Open Source Safety = avg(Security, License Compliance, Obsolescence)

Source note: Derived from CAST Highlight's Open Source Safety methodology

(https://doc.casthighlight.com/). License tiers follow CAST's out-of-the-box profile,

aligned with https://choosealicense.com/appendix/; CVE weighting follows CVSS/NVD

severity. Presented as reference guidance, not proprietary calibration.

---

The three sub-scores

Aggregation rule: average for the headline number, but gate on the worst sub-score. A component can be CVE-clean yet a license liability, or permissively licensed yet dangerously stale. A high blended score hides a single fatal dimension.

---

Where the detail lives (do not re-document here)

---

Using the index in a portfolio scorecard

1. Compute the three sub-scores per application from your SCA tooling. 2. Average for the headline OSS Safety number; record the worst sub-score alongside it. 3. Feed the OSS Safety number into the overall application scorecard next to Software Health and Cloud Maturity (see quality-communication-guide.md). 4. For prioritization, weight by business impact: a stale, CVE-heavy dependency in a revenue-critical app outranks the same in an internal tool.

References

• CAST Highlight Open Source Safety — https://doc.casthighlight.com/
• License summary — https://choosealicense.com/appendix/
• CVE severity — https://nvd.nist.gov/ (CVSS)

Quality Communication Guide

Overview

A health score nobody acts on is wasted work. This reference covers two things: how to prioritize remediation by business impact, and how to present quality and debt to people who do not read code.

Source note: The business-impact weighting and ROAR-style prioritization are derived

from CAST Highlight's Business Impact and ROAR (Ranking of Application Risks) indicators

(https://doc.casthighlight.com/). The exact ROAR weighting formula is CAST's proprietary

calibration and is described here as reference context, not reproduced as a normative

standard.

---

1. Prioritize by business-weighted risk, not defect count

The mistake teams make is fixing the application with the most findings. The right target is the application where technical risk × business importance is highest.

Business Impact captures how much the organization depends on an application. Score it from factors the code cannot reveal (a short survey):

• Would failure cause service disruption, revenue loss, or reputational harm?
• Would failure erode customer confidence?
• Internal users, external users, or both? How many?
• How many major releases and how much maintenance effort in the last 12 months?
• Is the app aligned with the company's future technology direction?

Combine the answers into a single 0–100 Business Impact score (weighted average).

Risk ranking (ROAR-style). CAST blends the three health factors — weighting Resiliency most heavily, then Elegance, then Agility — and multiplies by Business Impact. The vendor-neutral takeaway you can carry without copying the formula:

Priority ≈ (technical_risk, weighted toward Resiliency) × business_impact

• High risk + high impact → urgent; investigate now.
• High risk + low impact → schedule; not urgent.
• Low risk + high impact → monitor; keep it healthy.
• Low risk + low impact → leave it; possibly a retirement candidate.

This is why Resiliency is weighted heaviest: a reliability defect in a revenue-critical app is the worst combination — likely to fail and expensive when it does.

---

2. Present scores to non-technical stakeholders

Lead with risk and money, not rule names

Use the traffic-light bands

Red/orange/green maps cleanly to executive dashboards. Pair each color with one sentence of consequence and one recommended action. Never present a number without a "so what."

Always state assumptions for money figures

When you convert debt to dollars, show the inputs: LOC, debt-density range (attributed), hourly cost, and a confidence band (±50% at low fidelity). Unqualified dollar figures invite false precision and erode trust.

Frame paying down debt as reducing run-cost

The strongest business case: higher Agility/Elegance scores reduce the steady-state maintenance effort (the COCOMO II linkage — see technical-debt-estimation.md). "Fixing this lowers what it costs us to own this app every quarter" lands better than "the code is cleaner."

---

3. A one-page application scorecard template

Application: <name>          Business Impact: <0-100>  🟢/🟠/🔴
------------------------------------------------------------------
Software Health:  <0-100> 🟠   (Resiliency <n> / Agility <n> / Elegance <n>)
Open Source Safety: <0-100> 🔴  (worst sub-score: License Compliance)
Cloud Maturity:   <0-100> 🟠   (Scan <n> / Survey <n>)
------------------------------------------------------------------
Top risk:     <one sentence, business framed>
Recommended:  <one action> — est. <effort range, ±band>
Priority:     <urgent / scheduled / monitor / retire>

Map scores to team actions consistently across the portfolio so two reviewers reach the same recommendation from the same numbers.

References

• CAST Highlight Business Impact & ROAR indicators — https://doc.casthighlight.com/
• COCOMO II (maintenance-effort basis) — https://en.wikipedia.org/wiki/COCOMO

Software Health Framework

Overview

Software Health is a composite score that answers a single question: how well does this codebase comply with the practices that keep it reliable, changeable, and lean? It is the straight average of three independent 0–100 sub-scores.

Software Health = avg(Resiliency, Agility, Elegance)

Source note: This decomposition and the threshold bands are derived from CAST

Highlight's Software Health, Software Resiliency, Software Agility, and Software Elegance

indicators (https://doc.casthighlight.com/). The numeric cutoffs are CAST's proprietary

calibration from their AppMarq benchmark dataset and are reproduced here as **attributed

reference ranges**, not as a universal standard.

---

The three dimensions

1. Resiliency / Robustness — "will it break?"

Searches for defensive-coding and reliability practices: error handling that does not swallow failures, no raw exceptions thrown across boundaries, no fall-through in switch, no missing default/else, no risky catches. A low Resiliency score predicts production incidents.

Maps to: the Robustness and Security families in code-review-standards, and the per-language quality-anti-pattern references (Python riskycatches/illegalexception, Java genericcatches/nestedtrycatches, PHP empty-catch, JS errormanagement/eval).

Remediation owner: engineers fixing error-handling and edge-case defects.

2. Agility / Changeability — "can we change it quickly?"

Searches for the presence of embedded documentation and readability practices: consistent naming, commented closings, no over-long if/else if chains that should be a switch, no useless overriding methods, no functions used before declaration. A low Agility score predicts slow, error-prone changes and onboarding pain.

Agility uses different band cutoffs than Health overall (red below ~54, green above

~69 per CAST's calibration) because its score distribution differs. Do not assume one

set of cutoffs applies to every dimension.

Maps to: the Transferability and Changeability families (naming consistency, dead code, switch nesting in code-review-standards's criteria-transferability.md).

Remediation owner: engineers improving readability, documentation, structure.

3. Elegance / Efficiency — "is it lean?"

Searches for complexity and waste: nested loops, large switch statements, repetitive deep-member access, dead code, over-fetching. A low Elegance score predicts performance problems and a code model that resists simplification.

Maps to: the Efficiency family in code-review-standards's criteria-efficiency.md.

Remediation owner: engineers reducing complexity and algorithmic/data-access waste.

---

Threshold bands (attributed to CAST calibration)

The bands matter less than the per-dimension breakdown. Two applications can share a Health score of 64 (orange) for opposite reasons: one is green on Resiliency but red on Agility (stable but unmaintainable), the other red on Resiliency but green on Agility (easy to read, prone to crash). Their remediation plans are completely different.

---

Mapping your existing tooling onto the dimensions

You do not need CAST to compute a Health-style score. Map the findings your existing linters already produce:

Compute each sub-score as 100 * (1 - weighted_violations / opportunities) or simply as a normalized rank against a baseline — the exact formula is less important than applying it consistently across the applications you compare.

---

Worked example (illustrative)

A service with 50k LOC:

• Resiliency: 81 🟢 (good error handling; a few missing defaults)
• Agility: 49 🔴 (sparse docs, inconsistent naming, several god-functions)
• Elegance: 70 🟠 (some nested loops and dead code)

Health = (81 + 49 + 70) / 3 = 66.7  → 🟠 Orange

Reading: the blended grade is "orange," but the actionable story is Agility is red. The remediation plan should prioritize documentation, naming, and decomposition — not error handling (already green) or performance (acceptable). A single grade would have buried this.

---

References

• CAST Highlight Software Health / Resiliency / Agility / Elegance indicators —

https://doc.casthighlight.com/

• For per-finding criteria feeding each dimension, see the

universal/process/code-review-standards references criteria-efficiency.md and criteria-transferability.md.

Technical Debt Estimation

Overview

Technical debt is most useful when expressed as estimated remediation effort — the hours (or FTE-days, or money) it would take to bring code up to standard. This turns an abstract "the code is bad" into a number a manager can act on.

Estimated debt ≈ violation_count × avg_effort_per_violation
                ≈ LOC × debt_density(language)

Source note: The effort-to-fix model and per-language debt-density concept are

derived from CAST Highlight's Technical Debt and Software Maintenance methodology

(https://doc.casthighlight.com/), which itself builds on the COCOMO II cost model

(Constructive Cost Model — Post Architecture, https://en.wikipedia.org/wiki/COCOMO).

The specific debt-density figures are CAST-proprietary, drawn from their AppMarq

benchmark dataset. Do not copy CAST's exact per-LOC values. Use the relative

ranges below and always state your own assumptions.

---

Per-language debt density — as attributed relative ranges

CAST's benchmark data shows debt-per-LOC varies substantially by technology. The pattern worth carrying forward is the relative ordering, not the absolute numbers:

How to phrase this honestly: "Per industry benchmarks (CAST AppMarq), Java's median technical-debt density is on the order of 3–4× Python's. We applied the upper end as a conservative estimate." Never state a precise dollars-per-line figure as if it were a law of nature.

Why the ordering holds: more verbose, boilerplate-heavy languages accumulate more remediable patterns per line; concise scripting languages pack more intent per line and have fewer ceremonial constructs to get wrong. Treat this as a directional prior, not a precise multiplier.

---

Building a back-of-envelope estimate

1. Count violations by severity from your scanners (or estimate violation density per kLOC if you only have a sample). 2. Assign an average fix-effort per severity. A defensible default set:

• Critical/security: ~2–8 h each
• High: ~1–4 h each
• Medium: ~0.25–1 h each
• Low/cosmetic: ~0.1 h each (often batch-fixable, so cap the total)

3. Sum to total hours; divide by working hours/FTE-day to get FTE effort. 4. Apply the language prior as a sanity check: if your bottom-up estimate for a Java service comes out far below the Python prior, re-examine — you likely under-counted. 5. State assumptions inline: LOC, density source, hourly cost, and that estimates are ±50% at this fidelity.

Worked example (illustrative)

A 50k-LOC Java service, scanner reports: 12 high, 140 medium, 600 low violations.

high:    12 × 3 h   =   36 h
medium: 140 × 0.5 h =   70 h
low:    600 × 0.1 h =   60 h (cap if batch-fixable)
                       --------
total  ≈ 166 h ≈ ~1 FTE-month

Sanity check against language prior: Java is in the higher debt tier, so ~3 h/kLOC of remediable debt is plausible (166 h / 50 kLOC ≈ 3.3 h/kLOC). The estimate is internally consistent.

Present it as: "Roughly one FTE-month (±50%) to clear the current backlog, assuming $X/hour and the violation effort defaults stated above."

---

Maintenance effort (COCOMO II linkage)

For ongoing maintenance rather than one-time remediation, CAST's model derives a recommended maintenance FTE from COCOMO II cost drivers plus the quality scores: higher Agility/Elegance scores → lower recommended maintenance effort. The actionable takeaway: improving Agility and Elegance scores reduces the steady-state cost of owning the code, which is the business case for paying down debt. Cite COCOMO II as the primary source for any effort math, not CAST's calibration.

---

Caveats

• Estimates are directional, not precise — communicate confidence bands.
• Violation counts depend on scanner configuration; hold it constant across comparisons.
• Debt density is a prior, not a measurement — a clean Java service can beat a messy

Python one. Use bottom-up counts as the primary estimate and the prior as a check.

• Never present CAST's exact per-LOC dollar figures verbatim; they are proprietary.

References

• CAST Highlight Technical Debt & Software Maintenance methodology —

https://doc.casthighlight.com/

• COCOMO II — https://en.wikipedia.org/wiki/COCOMO
• For OSS-component debt (obsolescence), see open-source-safety.md.