2600Hz/kazoo

What it measures: Over-large classes that try to do too much ("god classes").

Method: God-class detection by line and method-count thresholds per logical type (partial classes unified), filtered for generated code and registration/contract false positives. Deterministic.

Maturity: Documented → Verified → Prevented · effective 6.1 / 10 · rule-coverage 100% · ceiling Prevented

378 god class(es) detected.

What to do

1. Resolve the 262 TooManyMethods finding(s) in God Classes — start with kapps_call_command.erl, kzd_accounts.erl, kzd_devices.erl. — One of this dimension's main actionable groups (262 warning-level).
2. Resolve the 116 FileTooLong finding(s) in God Classes — start with kapps_call_command.erl, kapi_dialplan.erl, kapi_notifications.erl. — One of this dimension's main actionable groups (116 warning-level).
3. Enforce God Classes in CI to reach Verified (currently Documented). — Hardens enforcement from Documented toward Prevented — provenance only; does not change the score.

Detailed fixes: d3_recommendation.md · top locations in Appendix A, every location in findings.md.

What it measures: Copy-pasted code that should be shared instead.

Method: Code duplication via token-stream sliding windows with type-aware normalization (locals masked, type names preserved), density-scored per KLoC of production code. Deterministic.

Maturity: Documented → Verified → Prevented · effective 10.0 / 10 · rule-coverage 100% · ceiling Verified

0 duplicated block group(s) detected.

✓ On the Gold path — maintain.

Detailed fixes: d4_recommendation.md.

What it measures: Whether any secrets (keys, tokens, passwords) have leaked into the code.

Method: In-process native secret scanner (entropy plus signature patterns) across all tracked files; no external tool. A clean result is a measured 10, not no-data zero. Deterministic.

Maturity: Documented → Verified → Prevented · effective 10.0 / 10 · rule-coverage 100% · ceiling Prevented

Secret scan ran and found no leaked secrets.

✓ On the Gold path — maintain.

Detailed fixes: d13_recommendation.md.

What it measures: Whether the project's documentation is clear, complete, and useful.

Method: Judged by language model at low temperature (0.0-0.1) on a deterministic doc sample (READMEs plus first 25 architecture docs), with two-pass stability filtering. Advisory, sampled.

Maturity: Documented → Verified → Prevented · effective Strong / 10 · rule-coverage 100% · ceiling Documented

Kazoo's documentation is comprehensive and well-organized across READMEs, architecture markdowns, scripts, and per-module docs. The main strengths are the clear project-wide announcements link (to a dedicated doc/announcements.md), an excellent Getting Started section that invites contributors to submit notes, and detailed runnable script examples for each tool in the scripts directory. There is strong coverage of the core Kazoo modules: the AST library parsing Erlang modules, the amqp_cron distributed scheduler, SUP command-line interface, and voicemail migration process. The documentation is complete per the outline (announcements, Welcome!, Scripts, Getting Started, Developer, Integrator, Operator, Cloud-Based Telecommunications For Everyone, What is Kazoo?, Who is 2600Hz?, Who Can Contribute?; Not a coder?; I know me some Erlang! How can I contribute?; Do you know other languages?), and the quality is high. The Kazoo project's documentation is comprehensive and well-structured across READMEs, architecture/Docs markdown files, and XML-doc coverage. It starts with a short README for each core module (Transactions, Token Buckets, Telemetry, Stats, Speech, SIP, Services, OAuth, Numbers, ModB) that states the purpose of the library plus an overview table or two. The telemetry and numbers modules are particularly rich: the former has a configuration table mapping keys to descriptions, while the latter gives a concrete JSON example for a number document and explains how ownership changes affect account databases. The Services module's README is the longest at 3768 words and covers the plan object structure, quantities, applications, ratedecks, overrides, merge, quotes, invoices, the Account Is Born, service-plan assignments, the Account Grows, accepting charges, manual quantities, audit logs, reconciliation, and synchronization. The document outline for each module is fully present in the visible text (e.g., 'In the beginning' for Services), so missing sections are not flagged by truncation.

What to do

1. Resolve the 1 The plan object's flat_rates, rates, and cascade parameters are… finding(s) in Documentation Quality — start with README.md. — One of this dimension's main actionable groups (1 recommendation-level).

Detailed fixes: d19_recommendation.md · top locations in Appendix A, every location in findings.md.

What it measures: Whether names — types, methods, variables — are clear and consistent.

Method: Judged by language model at low temperature (0.0-0.1) on a deterministic random symbol sample (fixed size, not exhaustive), with disclosed confidence band. Advisory, sampled.

Maturity: Documented → Verified → Prevented · effective Exemplary / 10 · rule-coverage 100% · ceiling Verified

0 naming inconsistencies across 0 sampled symbols.

✓ On the Gold path — maintain.

Detailed fixes: d21_recommendation.md.

What it measures: Whether any secrets were ever committed — scanned across the full git history, not just now.

Method: Git-history secret scan via gitleaks detect over full history in an isolated checkout; each match flagged High. Exhaustive; degrades cleanly when tool absent.

Maturity: Documented → Verified → Prevented · effective 0.0 / 10 · rule-coverage 100% · ceiling Documented

73 finding(s): 0 critical, 73 high, 0 medium, 0 low. Remediation for historically-committed secrets is credential rotation — they remain in history regardless of later deletion.

What to do

1. Resolve the 33 Secret finding(s) in Secrets (history) — start with user.json (4), %2B12014370855.json (2), %2B12014370857.json (2). — One of this dimension's main actionable groups (33 issue-level).
2. Resolve the 1 Rotate the exposed credentials finding(s) in Secrets (history). — One of this dimension's main actionable groups (1 recommendation-level).

Detailed fixes: d28_recommendation.md · top locations in Appendix A, every location in findings.md.

What it measures: Real static-analysis (SAST) findings — likely security bugs in the code, any language.

Method: Polyglot static analysis via semgrep across the repo using the pinned, image-baked p/security-audit + p/owasp-top-ten rulesets (no scan-time registry fetch); severity rules (ERROR/WARNING/INFO) map to a full-band severity-weighted score. Exhaustive, deterministic; degrades on parse failure.

Coverage: semgrep pattern rules over all files — exhaustive for the rule set, blind to classes of bug without a rule (clean = no rule matched).

Maturity: Documented → Verified → Prevented · effective 9.0 / 10 · rule-coverage 100% · ceiling Documented

2 finding(s): 0 critical, 0 high, 2 medium, 0 low.

✓ On the Gold path — maintain.

Detailed fixes: d29_recommendation.md · top locations in Appendix A, every location in findings.md.

What it measures: Whether anyone still has living knowledge of each file, or it has been orphaned — last understood long ago by someone now gone quiet. The sibling of the bus factor: D16 asks who owns it, D34 asks whether anyone still knows it.

Method: File orphaning as total living-knowledge decay below one focused-commit's worth within a year, computed per-file from the D16 decay model. Exhaustive, deterministic over fixed history.

Maturity: Documented → Verified → Prevented · effective 0.0 / 10 · rule-coverage 100% · ceiling Documented

1151 of 1151 significant source file(s) are orphaned — their living knowledge has decayed to nothing, so no one currently understands them. The largest is core/kazoo_call/src/kapps_call_command.erl.

What to do

1. Resolve the 3 Largest orphaned file finding(s) in Knowledge Freshness — start with kapps_call_command.erl, kapi_notifications.erl, kapi_dialplan.erl. — One of this dimension's main actionable groups (3 recommendation-level).
2. Resolve the 1 Dormant codebase finding(s) in Knowledge Freshness. — One of this dimension's main actionable groups (1 recommendation-level).

Detailed fixes: d34_recommendation.md · top locations in Appendix A, every location in findings.md.

What it measures: Whether files that change together actually belong together — pairs that repeatedly co-change in git history despite having no explicit code dependency, surfacing the hidden/logical coupling (and boundaries in the wrong place) a static scan can't see.

Method: Pairwise co-occurrence over the per-commit file sets in git history (production source only — tests and generated dropped): Degree-of-Coupling = shared ÷ min individual revisions, reported above noise floors (each file ≥10 revisions, ≥5 shared commits, ≥50% strength); sweeping commits excluded. Deterministic over fixed history.

Coverage: Population: PRODUCTION source files only — test and generated files are dropped before pairing, so a class co-changing with its own test (trivially ~100%) can't drown the real production↔production coupling. Pairs ranked by Degree-of-Coupling; coupling through a build step, config, or non-source file isn't seen.

Maturity: Documented → Verified → Prevented · effective 10.0 / 10 · rule-coverage 100% · ceiling Documented

No strong hidden change-coupling between production files.

✓ On the Gold path — maintain.

Detailed fixes: d35_recommendation.md.

What it measures: Whether the build pipeline provides supply-chain integrity — generated provenance/attestation, signed artifacts (cosign/sigstore), an SBOM, and pinned build actions. Presence of the configuration, not a runtime guarantee.

Method: Supply-chain provenance/signing read deterministically from CI/build config (.github/workflows, .gitlab-ci.yml, azure-pipelines, Jenkinsfile, .circleci) + the release surface: four signals — generated provenance/attestation (SLSA/in-toto/actions-attest), artifact signing (cosign/sigstore/gitsign), an SBOM (syft/sbom-action/*.spdx.json/*.cdx.json), and SHA-pinned build actions — scored 10·present/denom. NotApplicable without a build pipeline. Detects configuration presence, not runtime enforcement.

Maturity: Documented → Verified → Prevented · effective 0.0 / 10 · rule-coverage 100% · ceiling Documented

0/3 supply-chain integrity signals present (provenance, signing, SBOM).

What to do

1. Resolve the 1 No build provenance finding(s) in Supply-chain Provenance & Signing. — One of this dimension's main actionable groups (1 recommendation-level).
2. Resolve the 1 No artifact signing finding(s) in Supply-chain Provenance & Signing. — One of this dimension's main actionable groups (1 recommendation-level).
3. Resolve the 1 No SBOM finding(s) in Supply-chain Provenance & Signing. — One of this dimension's main actionable groups (1 recommendation-level).

Detailed fixes: d36_recommendation.md · top locations in Appendix A, every location in findings.md.

Other · Accessibility — Whether form controls have a programmatic label (an associated label, aria-label or aria-labelledby), buttons have text, links have an accessible name, fieldsets have a non-empty legend, known UI-library field components carry a label prop, and a placeholder isn't used as the only label. Static markup readiness, not a WCAG conformance claim.

Method: Static markup-model scan: inputs/selects/textareas checked for an associated label[for]/wrapping label/aria-label/aria-labelledby (per document), buttons for accessible text, fieldsets for a legend; placeholder-only labelling flagged. Deterministic, hard fact per control.

Other · Accessibility — Whether pages declare a language (well-formed BCP-47) and a non-empty title, expose exactly one main landmark and a sane heading order with non-empty headings, keep zoom enabled, title their iframes, give data tables header cells, and avoid meta-refresh. Static markup readiness, not a WCAG conformance claim.

Method: Static markup-model scan: html lang, document <title>, a main landmark and heading order on full documents only, plus zoom-disabling viewports, untitled iframes and meta-refresh anywhere. Deterministic, per structural checkpoint.

• Skipping heading levels breaks the document outline assistive tech relies on. Don't jump levels — increase by at most one. (×14) — customer_update.html:47, low_balance.html:59, port_cancel.html:63, …

What to do

• Declare <html lang>, a document <title> and a <main> landmark, keep headings in order, leave zoom enabled, title iframes and drop meta-refresh.

Other · Accessibility — Whether ARIA is used correctly — valid non-abstract roles, the ARIA state a role requires, valid (non-misspelled) aria-* attribute names, in-enum values for token-typed aria-* attributes, and no aria-hidden on (or wrapping) a focusable element. Static markup readiness, not a WCAG conformance claim.

Method: Static markup-model scan: role values checked against the WAI-ARIA role set (abstract/invalid flagged), required ARIA state for a role, and aria-hidden on a focusable element. Deterministic, role/attribute level.

Other · Accessibility — Whether focus outlines aren't removed without a replacement, motion respects prefers-reduced-motion, and literal CSS colour pairs meet contrast — PARTIAL: inline styles, in-repo <style> blocks, in-repo .css files, var() tokens, Tailwind neutral utilities and CSS-in-JS literals are read (hex/rgb/hsl/named), never computed/runtime/external-CDN colour. Static markup readiness, not a WCAG conformance claim.

Method: Static markup/CSS scan: inline outline:none/0, literal inline colour/background contrast against the 4.5:1 AA floor, and <style>-block animation without a prefers-reduced-motion guard. Deterministic but PARTIAL — only inline styles and in-repo CSS literals are visible.

• The inline foreground/background colours fall below the 4.5:1 WCAG AA minimum for normal text. Darken/lighten one of them. (×2) — bill_reminder.html:77, service_added.html:58

What to do

• Keep a visible focus style (don't remove the outline without a replacement), guard animation with prefers-reduced-motion, and raise low-contrast colour pairs to at least 4.5:1.

Other · Accessibility — Whether accessibility is ENFORCED in the toolchain — an accessibility checker configured over the markup (an a11y lint rule set, e.g. eslint-plugin-jsx-a11y or vuejs-accessibility where the project lints JavaScript) and an automated accessibility assertion wired into tests or CI (axe/pa11y/Lighthouse or an equivalent) — on the Documented→Verified→Prevented ladder.

Method: Repo config/CI scan: an accessibility checker configured over the markup (an a11y lint rule set such as eslint-plugin-jsx-a11y / vuejs-accessibility where JavaScript is linted) and an automated accessibility assertion in tests or CI (axe/pa11y/Lighthouse or equivalent), graded on the Documented→Verified→Prevented rungs. Deterministic, presence/rung detection.

• No accessibility enforcement found — no automated accessibility check runs over your pages. Add an accessibility checker (axe-core, pa11y or Lighthouse) over your HTML in CI and fail the build on new violations.

What to do

• Enforce accessibility over your pages: run an accessibility checker (axe-core, pa11y or Lighthouse) against your HTML in CI and fail the build on new violations — these run as standalone tools without adding a package manifest.

Other · Architecture — Whether read (query) handlers stay side-effect-free — a query that writes persistent state or raises events breaks CQS and makes reads unsafe to retry, cache, or route to a read replica.

Method: Roslyn scan: CQRS handlers classified query-vs-command by interface (IQueryHandler/ICommandHandler/IRequestHandler<TQuery,TResult>) and name convention (*Query/Get*/Find* vs *Command); each query handler's body checked for persistent-state writes (SaveChanges/repository Add-Update) or event publishes by resolved invocation. Deterministic, type-level, exhaustive over the detected handlers.

Coverage: Population: CQRS handlers identified by IQueryHandler/ICommandHandler/IRequestHandler interface + *Query/Get*/Find*/*Command NAME convention; query purity then checked exhaustively within that set — a query handler using neither convention is invisible, and mutation is a resolved persistence/publish CALL, not full dataflow.

Other · Event-Driven — Whether event handlers stay asynchronous (no blocking remote HTTP/gRPC calls awaited inside a handler).

Method: Roslyn semantic scan (event-driven gated): event-handler bodies scanned for HTTP/gRPC invocations by resolved symbol type, not substring. Deterministic, semantic-resolved.

• `waveguide_responder` clause `activating/3#146` blocks the process on a synchronous outbound I/O client call (a remote HTTP request, a socket receive, or a blocking pool checkout) awaited inline while handling a message — the process is blocked (holding its mailbox) until a peer replies or the sleep elapses. That couples this handler in real time to another process being up and fast, and a mutual call can DEADLOCK. To decouple, issue the request off the hot path — reply asynchronously and do the I/O in a throwaway spawned worker (or use the async client API), so the process keeps serving its mailbox. — waveguide_responder.erl:148
• `waveguide_responder` clause `handshaking/3#168` blocks the process on a synchronous outbound I/O client call (a remote HTTP request, a socket receive, or a blocking pool checkout) awaited inline while handling a message — the process is blocked (holding its mailbox) until a peer replies or the sleep elapses. That couples this handler in real time to another process being up and fast, and a mutual call can DEADLOCK. To decouple, issue the request off the hot path — reply asynchronously and do the I/O in a throwaway spawned worker (or use the async client API), so the process keeps serving its mailbox. — waveguide_responder.erl:170
• `waveguide_responder` clause `submitting/3#190` blocks the process on a synchronous outbound I/O client call (a remote HTTP request, a socket receive, or a blocking pool checkout) awaited inline while handling a message — the process is blocked (holding its mailbox) until a peer replies or the sleep elapses. That couples this handler in real time to another process being up and fast, and a mutual call can DEADLOCK. To decouple, issue the request off the hot path — reply asynchronously and do the I/O in a throwaway spawned worker (or use the async client API), so the process keeps serving its mailbox. — waveguide_responder.erl:192

What to do

• Remove synchronous peer round-trips (gen_server:call / hand-rolled receive) and blocking sleeps from OTP message handlers — cast a follow-up or resolve state locally, so processes stay temporally decoupled and deadlock-free.

Other · Event Sourcing — Whether the event-sourcing replay fold reconstructs state purely from the event (no wall clock, UUID or randomness) so replay is reproducible.

Method: Roslyn syntax scan (event-sourcing gated): Apply/When folds checked for forbidden tokens (DateTime.Now, Guid.NewGuid, Random, IO), stripped of comments/strings. Deterministic, hard fact per fold.

Other · Event Sourcing — Whether persisted events stay immutable (never rewritten in place).

Method: Roslyn scan (event-sourcing gated): persisted events checked for public setters; immutability verified per property/field. Deterministic, hard fact.

Maturity · Maturity — Whether the repo and its projects have a README, and whether it's substantive and current.

Method: Filesystem scan: README presence, word count, and headings for depth; git history for staleness. Exhaustive across root and project dirs, deterministic.

What to do

• Add a 'Testing' section to the root README — how to run the test suite.
• Add an 'Architecture' / 'How it works' section to the root README — the high-level shape.
• Add a README to the 2 of 2 project(s) that lack one — worth up to 2 pts.

Maturity · Maturity — Whether key decisions (ADRs) and the high-level shape (C4/diagrams) are written down.

Method: Filesystem scan: ADR folder/naming conventions or content, plus Mermaid/PlantUML/C4/architecture.md discovery. Exhaustive, deterministic.

• No Architecture Decision Records found — no conventional ADR directory, no `NNNN-title.md` documents and nothing ADR-shaped by content. Design rationale recorded elsewhere (a design-notes tree, a mailing list, pull-request discussion) is not visible to this check and is not re-findable per decision, so a future maintainer cannot ask why one choice was made and get an answer.

What to do

• Record significant decisions one document per decision — dated, stating the context, the decision and its consequences — and keep them together wherever your design docs already live (a conventional `docs/adr/` tree with `NNNN-title.md` names is the most discoverable form).

Maturity · Maturity — Whether the repo is organised deliberately — src/test separation and consistent project naming.

Method: Filesystem scan: src/test folder separation and namespace-prefix consistency (majority RootNamespace agreement). Exhaustive across projects, deterministic.

• Production code isn't grouped under a src/ folder — it's spread across several top-level directories, so there's no one place that says 'this is the product'.

What to do

• Group production code under src/ (or split deliberately, e.g. backend/ + frontend/) so production and tooling code aren't mixed at the root.

Maturity · Maturity — Whether the README actually describes the code that exists (LLM-judged, advisory).

Method: Judged by language model at low temperature: README accuracy versus actual projects, within a disclosed tolerance. Advisory, not a measured number.

Readiness · Readiness — Whether an automated pipeline builds and tests every change.

Method: Filesystem scan: CI workflow files (.github/workflows, .gitlab-ci.yml, etc.) for build and test stages. Exhaustive, deterministic.

Readiness · Readiness — Whether SAST, secret/dependency scanning and performance benchmarking are wired in (presence, not runtime).

Method: Filesystem scan: SAST configuration, dependency-update automation, secret scanning, and a benchmark harness or benchmark step — in this repository's own ecosystem. Exhaustive, deterministic.

What to do

• Enable Dependabot/Renovate or a dependency-review gate.
• Add gitleaks/trufflehog in CI to block PRs that introduce committed secrets.

Readiness · Readiness — Whether releases are automated and safely reversible (probes, rolling updates, approval gates) — from manifests/pipeline files, not the live environment.

Method: Filesystem scan: deployment manifests/IaC (K8s YAML, Helm, Terraform) for rolling updates, probes, approval gates, migration hooks. Exhaustive, deterministic.

What to do

• Nothing pauses a release for a human: publish as a draft release (or gate the release job on a protected tag/manual dispatch) so a bad build can be stopped before users can download it.

Readiness · Readiness — Whether releases are traceable — a maintained changelog and explicit version stamping.

Method: Filesystem scan: changelog file presence and version tags in csproj or git tags. Exhaustive, deterministic.

• A changelog exists but has few versioned entries — keep it current with each release.

What to do

• Keep the changelog current — add a versioned entry (Keep-a-Changelog ## [x.y.z]) for each release so the history isn't a stub.