project_maturity_audit v1.0.0

name: "project_maturity_audit" description: "Audit a project or repo for maturity: score eight dimensions (code health, documentation, testing, release practice, security, governance, community, sustainability) from real evidence, then sort fixes by return on effort. Use when asked to assess project health, repo maturity, readiness for adoption, graduation, or investment, or to produce a maturity scorecard."

Project Maturity Audit

Purpose

Give a project a maturity verdict a skeptical reader can check. The audit scores eight dimensions from 0 to 5, weights them into a score out of 100, and names the level: Fragile, Early, Developing, Solid, or Established. Every score rests on evidence you opened or measured. Claims alone cap a score at 2. The method draws on three public frameworks and does not copy any one of them: OpenSSF Scorecard and the OpenSSF Best Practices Badge for security and release checks, CHAOSS metrics for community and concentration measures, and the Apache Project Maturity Model for governance, quality, and release process tests.

Workflow

1. Scope the audit first. Record the repo or project, the commit or date you audited, who asked, and what the verdict will decide (adoption, funding, graduation, internal investment). A score without a decision context invites misuse.

1. Gather evidence before scoring. Open, at minimum: the README and docs, CONTRIBUTING, LICENSE, SECURITY.md, the changelog, the last three release tags and notes, CI configuration and a recent CI run, branch protection or its closest equivalent, the last 30 merged pull requests, issue response samples from the last 90 days, and the contributor list for the last year. Run OpenSSF Scorecard if the project is public and record the date and aggregate score as one input, never as the audit itself.

1. Classify every piece of evidence by tier. Tier A is a direct artifact you opened. Tier B is a measured metric with a stated window and method, such as median time to first response over the last 90 days. Tier C is a claim from an interview, a README, or a maintainer. Write the tier next to each score.

1. Score the eight dimensions with the anchors in references/rubric.md: code health (weight 15), documentation (12), testing (15), release practice (13), security and supply chain (15), governance (10), community and responsiveness (10), sustainability and dependency risk (10). Apply the cap: a dimension backed only by tier C evidence scores at most 2, even if the claim sounds strong.

1. Mark what you could not inspect as unknown, not zero. Private CI, a closed chat, or a missing analytics export is a coverage gap. Report coverage with the score, for example: 46/100, Developing, 100 percent coverage, or 46/100 with two dimensions unknown.

1. Test two claims by doing, not reading. Follow the install or quickstart steps cold and time the result for the documentation score. Then check that the written release process would let a newcomer cut a release, the test the Apache model calls RE50. If either test fails, the related dimension cannot score above 2.

1. Check community health with CHAOSS style measures, always with a window: time to first response, change request review duration, new contributors, release frequency, and contributor concentration (the Elephant Factor idea: how much of the work the top one or two contributors carry). Raw counts without a window do not count as evidence.

1. Check release practice against practice, not policy. Compare the last five version numbers against semantic versioning rules, read the changelog for Keep a Changelog groups (Added, Changed, Deprecated, Removed, Fixed, Security), and confirm whether releases are built in CI and signed or carry provenance.

1. Build the fix list. For each weak dimension, write one to three fixes. Rate impact 1 to 5 and effort 1 to 5, where effort 1 is under a day and effort 5 is a quarter or more. Sort by impact divided by effort. Any fix that removes an active security risk goes first regardless of ratio, with the reason stated.

1. Score with the worksheet. Put dimension scores, tiers, and fixes in a JSON file and run python3 scripts/maturity_score.py worksheet.json. Run python3 scripts/maturity_score.py --example first to see the format and the tier C cap working. The script returns the weighted score, the level, coverage, and the sorted fix list. Do the math with the script, not by hand.

1. Write the report in the Output Contract format. Lead with the level and the two or three facts that decide it. Keep praise and blame tied to artifacts a reader can open.

Output Contract

• Header: project, commit or date audited, auditor, coverage percentage, weighted score out of 100, and maturity level.
• Scorecard: all eight dimensions with score, evidence tier, and a one line evidence note naming the artifact or metric window.
• Deciding facts: the three strongest and three weakest pieces of evidence, each with a link, file path, or measured value.
• Fix list sorted by return on effort: title, dimension, impact, effort, ratio, and what done looks like in one verifiable sentence.
• Unknowns section: what could not be inspected, why, and what evidence would close the gap.
• No dimension score without evidence, and no total without coverage stated beside it.

Operating Rules

• Never score from a README claim, a badge image, or a project website alone. Badges are claims until you open the underlying record, for example the project entry on bestpractices.dev or a dated Scorecard run.
• Never invent a metric. If you did not measure response time, coverage, or concentration, say unmeasured and score on the artifacts you do have.
• Separate unknown from zero in every report. Zero means you looked and it was absent or broken. Unknown means you could not look.
• Date every measurement. Community and activity numbers rot fast, so a score from last year is history, not a current verdict. Re-audit after a major maintainer change or a six month gap.
• Keep the audit fair to small projects. A solo project can score well on documentation, testing, and release practice. It will score low on sustainability and governance concentration, and the report should say that plainly without treating it as a character flaw.
• Do not publish or share the report outside the audience the audit was scoped for without the project owner seeing it first when the scores are low. A maturity audit is a working tool, not a public ranking.
• Write plainly. No em dashes. Short sentences, concrete nouns, no motivational filler.