Repo Readiness Engine

The Repo Readiness Engine is ReformCode's front-door product wedge: a 100-point check that tells you what a repository really is, what is missing, what is risky, and what to do next.

Use it before you trust a dependency, fork a starter, white-label a project, inherit a client codebase, buy a repo, generate on top of an existing app, or ship a release.

The Claim

Lovable, Bolt, Cursor, and similar tools help teams create code faster. ReformCode's stronger job is to tell teams whether the code is ready to trust.

The Repo Readiness Engine turns a repository into:

• Evidence: files, routes, APIs, schemas, dependencies, workflows, and launch surfaces checked.
• Findings: blockers, risks, missing functionality, weak patterns, and competitive opportunities.
• Score: a 0-100 readiness number with factor-level deductions.
• Plan: prioritized work to move the repo from its current state to launch-grade.
• Proof: reports, CODE handoffs, PR evidence, deploy certification, and enterprise evidence rooms.

100-Point Score Model

Score Bands

Implementation Contract

The shared score contract lives in lib/repo-readiness/score-contract.ts and is exported through lib/repo-readiness.

The contract defines:

• REPO_READINESS_DIMENSIONS: the canonical 10-dimension, 100-point weight model.
• RepoReadinessInput: target, dimension signals, evidence, findings, and unavailable-signal reasons.
• RepoReadinessReport: score, verdict, confidence, dimension reports, evidence coverage, blockers, top findings, and next actions.
• calculateRepoReadinessScore(): deterministic report generation with blocker caps and missing-evidence penalties.
• validateRepoReadinessWeights(): a guard that confirms dimensions still sum to 100.

Important scoring rule: missing evidence does not redistribute weight into available dimensions. If a repo only has architecture and security evidence, the remaining dimensions stay missing and reduce confidence instead of making the score look better than it is.

The ingestion evidence map lives in lib/repo-readiness/evidence-map.ts.

It turns a file snapshot into:

• route inventory for app/**/page.*, pages/**, dynamic segments, and route groups.
• API inventory for app/api/**/route.* and pages/api/**, including exported HTTP methods when content is available.
• schema and migration evidence for Prisma, Drizzle, SQL, and database folders.
• dependency manifest evidence for Node, Python, Go, Rust, Maven, Gradle, Ruby, PHP, and .NET indicators.
• workflow, test, docs, config, environment, observability, deploy, security, and product-surface evidence areas.
• dimension input objects that can feed calculateRepoReadinessScore().

Static ingestion is conservative. If no database dependency or schema is detected, data-model evidence is marked unavailable. If database dependencies exist but schema files are absent, schema evidence is marked missing.

The product-completeness scanner lives in lib/repo-readiness/product-completeness.ts.

It checks product files for:

• placeholder-style product copy and unfinished implementation markers.
• inert links such as empty destinations or hash-only anchors.
• buttons without detected click, submit, form action, or intentional disabled state.
• forms without a submit handler or action target.
• dynamic/data-backed pages without visible loading, error, or empty-state evidence.
• internal links that do not match detected page routes in the snapshot.
• REFORM decision surfaces that lack a visible CODE handoff when both surfaces exist.

The scanner returns ProductCompletenessScanReport with score, status, findings, evidence, signals, stats, and a product_completeness dimension input for calculateRepoReadinessScore().

The readiness findings engine lives in lib/repo-readiness/findings-engine.ts.

It turns fragmented scan output into one launch-risk register:

• evidence-map gaps from missing routes, schemas, workflows, tests, docs, config, environment, deploy, security, and observability signals.
• product-completeness findings from placeholder-style copy, inert links, inactive controls, incomplete forms, missing states, navigation gaps, and missing CODE handoffs.
• external AST, security, license, dependency, test, DX, performance, data-model, observability, launch-readiness, and manual findings.
• deterministic severity ranking, launch blocker extraction, dimension summaries, score-impact signals, merged dimension inputs, and score-driven next actions.

The public entrypoint is buildRepoReadinessFindings(). It accepts a target, optional file snapshots, optional prebuilt evidence/product reports, and optional external findings. The return value includes ranked findings, launch blockers, dimension summaries, merged RepoReadinessDimensionInput objects, a full RepoReadinessReport, and recommended next actions for CODE, REFORM, test generation, security repair, data review, deploy proof, or report export.

The score-to-action planner lives in lib/repo-readiness/action-planner.ts.

It converts a findings report into:

• phased execution: stabilize blockers, recover score, prove release, and package evidence.
• concrete work items for CODE, REFORM, tester agent, security agent, deploy proof, and Evidence Studio.
• priority, estimated score gain, source finding IDs, acceptance criteria, and score-driven action metadata.
• recommended reform recipes such as Security Hardening Sprint, Product Flow Completion, Test Proof Pack, Data Model Hardening, Launch Proof Certification, Observability Proof Pack, Performance Budget Pass, DX Pack, and Reliability Hardening Pass.

The public entrypoint is planRepoReadinessActions(). It accepts a ReadinessFindingsReport, target score, and optional item cap. Clean launch-grade reports produce evidence packaging only; risky reports produce a phased fix-and-proof plan.

The first public UX foundation is /repo-readiness.

It provides:

• a branded explanation of the 100-point repo check.
• a live JSON snapshot runner backed by /api/repo-readiness/check.
• visible score, status, target score, top findings, and phased action-plan output.
• a safe deterministic API path with file-count and payload-size limits.
• a homepage CTA so users can move from marketing claim to working repo-readiness proof.

The API does not call AI models and does not write to the database. It is designed as the first productized preflight loop before persisted history, repo-detail integration, dashboard recent checks, deeper CODE execution, and report packaging are layered in.

The fix-forward package builder lives in lib/repo-readiness/fix-forward.ts.

It converts selected findings and the action plan into:

• deterministic CODE branch names such as reformcode/readiness-demo-next-dashboard-20260604.
• a CODE handoff URL with target, branch, evidence, and repo metadata.
• /REPO_READINESS_FIX_FORWARD.md for the human-readable repair brief.
• /.reformcode/repo-readiness-fix-forward.json for machine-readable task, evidence, validation, and rerun metadata.
• /REPO_READINESS_ACTION_PLAN.md for the score-to-action plan.
• a workspace seed with source files, open tabs, active file, selected panel, validation commands, rerun checklist, and status.

The /api/repo-readiness/check response now includes fixForward alongside findingsReport and actionPlan. Callers may pass selectedFindingIds, baseBranch, and repoUrl; if no findings are selected, the API selects launch blockers first and then the highest-ranked findings. Launch-grade repos produce an evidence-only package rather than fake repair work.

The CODE handoff helper lives in lib/repo-readiness/code-handoff.ts. The public page stores the full fix-forward package in browser session storage before navigating to /code; CODE then hydrates the workspace with the Markdown brief, JSON manifest, action plan, source files, open tabs, active file, and Problems panel. If session storage is unavailable, CODE falls back to a minimal URL-derived placeholder that tells the user to rerun the repo check for full evidence.

The current fix-forward contract prepares the CODE proof loop. It does not yet claim that autonomous edits, Git commits, PR creation, deploy certification, or score updates have already run.

Workflow

1. Ingest

Start from Universal Search, a GitHub repository, an uploaded project snapshot, a package, a trust-network page, or a REFORM-to-CODE handoff.

2. Analyze

ReformCode combines static code intelligence, dependency and license evidence, security scans, Code Genome signals, workspace validation, route/workflow inventory, and launch proof.

3. Explain

The score is only useful if it is explainable. Each deduction should point to a route, file, dependency, missing workflow, test gap, schema issue, or deployment signal.

4. Act

Findings can become:

• A REFORM plan for repo remixing, white-labeling, migration, or starter extraction.
• A CODE workspace with files, problems, Git proof, validation proof, and deploy proof.
• A pull request review with score diff, blockers, and remediation notes.
• An Evidence Studio report or Enterprise Evidence Room.
• A team portfolio signal for risk, readiness, and policy decisions.

Why This Matters

AI builders can make new software feel fast. The harder problem is knowing whether a repo is actually safe, complete, maintainable, and worth building on.

ReformCode should become the standard preflight for:

• Adopting dependencies: compare quality beyond stars and downloads.
• Starting from templates: know which starter is closest to launch-grade.
• White-labeling apps: find brand, package, domain, metadata, license, and attribution surfaces.
• Client audits: produce a professional gap report with evidence and next steps.
• M&A and repo purchases: review code risk before committing time or money.
• AI-generated code: validate what the builder produced before users depend on it.

Product Surfaces

• Universal Search: ranks software discovery with score and trust signals.
• Repo Readiness Page: runs capped JSON snapshot checks and renders score, findings, and action plan output.
• Repo Detail: shows readiness context, health, graph, recommendations, and handoff actions.
• REFORM: turns findings into remix, migration, and white-label plans.
• CODE: fixes gaps inside a VS Code-like workspace with preview, validation, Git, and deploy proof.
• GitHub App: checks pull requests and comments with score diffs and policy blockers.
• Evidence Studio: exports Markdown, JSON, PDF-ready, executive, and white-label reports.
• Enterprise Evidence Rooms: packages buyer-safe proof for stakeholders.

Differentiation

ReformCode is not trying to win only by generating the first draft. The durable wedge is repo truth:

Before you build on it, ship it, buy it, clone it, or trust it, ReformCode scores it.

That position makes ReformCode complementary to AI builders and stronger for professional software decisions. A builder creates code. ReformCode proves what the code is ready for.

Next Best Actions

After a repo check, the recommended path should be explicit:

Success Metric

The Repo Readiness Engine succeeds when users can answer three questions in minutes:

1. Is this repo worth trusting?
2. What exactly is wrong or missing?
3. What should I do next to get it to launch-grade?