@praneeth_54/agentdoctor 0.1.4-beta → 0.2.0-beta

package/CHANGELOG.md

@@ -9,8 +9,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Planned
 
-- Deterministic readiness scoring
 - Safe automatic fixes
+- Terminal readiness line and GitHub Action score-gate inputs (deferred; see scoring.md v2+)
+
+## [0.2.0-beta] — 2026-08-02
+
+Minor beta: deterministic readiness scoring and CLI `--min-score` enforcement.
+
+### Added
+
+- Deterministic readiness scoring (v1): `scan()` populates `scoringAvailable: true` and
+  `scores` (`overall`, `categories`, `agents`) from post-dedupe findings
+  ([docs/scoring.md](docs/scoring.md))
+- CLI `--min-score N` enforcement: exit code `1` when `scores.overall < N`
+- `--ci` without `--min-score` remains report-only (exit `0` on successful scan)
+- Scoring specification and compatibility / exit-code docs updated for shipped behavior
+
+### Compatibility
+
+- No new JSON top-level fields (`scoringModel` / `scoreExplanation` deferred)
+- Findings, rule IDs, and agent detection unchanged
+- GitHub Action remains `--ci --json` report-only (no score-gate inputs)
+- Default Action `version` input is `0.2.0-beta`
 
 ## [0.1.4-beta] — 2026-08-02
 
@@ -123,7 +143,8 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
 
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.1.4-beta...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.2.0-beta...HEAD
+[0.2.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.2.0-beta
 [0.1.4-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.4-beta
 [0.1.3-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.3-beta
 [0.1.2-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.2-beta

package/README.md

@@ -16,7 +16,7 @@ AgentDoctor is a local CLI that inspects project-level AI coding agent setup —
 npx @praneeth_54/agentdoctor
 ```
 
-Public beta (`0.1.x-beta`). Readiness scoring and automatic fixes are not available yet.
+Public beta (`0.1.x-beta`). Deterministic readiness scores ship in JSON; automatic fixes are not available yet.
 
 ---
 
@@ -24,12 +24,12 @@ Public beta (`0.1.x-beta`). Readiness scoring and automatic fixes are not availa
 
 ![AgentDoctor scanning a repository and reporting coding-agent security findings](docs/images/cli-scan.png)
 
-_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v0.1.4-beta._
+_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v0.2.0-beta._
 
 ```text
 $ npx @praneeth_54/agentdoctor
 
-🩺 AgentDoctor v0.1.4-beta
+🩺 AgentDoctor v0.2.0-beta
 
 Scanning repository...
 
@@ -155,7 +155,7 @@ npx @praneeth_54/agentdoctor
 Pin a beta version when you need a fixed install:
 
 ```bash
-npx @praneeth_54/agentdoctor@0.1.4-beta
+npx @praneeth_54/agentdoctor@0.2.0-beta
 ```
 
 ### Global (optional)
@@ -259,7 +259,7 @@ steps:
 
   - name: Audit coding-agent configuration
     id: agentdoctor
-    uses: pranee54/AgentDoctor@v0.1.4-beta
+    uses: pranee54/AgentDoctor@v0.2.0-beta
     with:
       path: .
       output-file: agentdoctor-report.json
@@ -271,7 +271,7 @@ steps:
       path: ${{ steps.agentdoctor.outputs.report-path }}
 ```
 
-The action installs the published `@praneeth_54/agentdoctor@0.1.4-beta` package, runs it with
+The action installs the published `@praneeth_54/agentdoctor@0.2.0-beta` package, runs it with
 `--ci --json`, and writes the report inside the checked-out workspace. It sets up Node.js 20
 for the CLI. The optional `version` input accepts an exact npm version or the `latest` / `beta`
 dist-tag.
@@ -281,13 +281,28 @@ dist-tag.
 Use JSON directly in other CI systems:
 
 ```bash
+# Report-only (exit 0 even when findings exist; scores still in JSON)
 npx @praneeth_54/agentdoctor --ci --json
+
+# Fail CI when overall readiness is below 70
+npx @praneeth_54/agentdoctor --ci --json --min-score 70
 ```
 
-`--ci` runs non-interactively. Until readiness scoring ships, successful scans exit `0` even when findings exist, and `--min-score` is accepted but ignored.
+`--ci` runs non-interactively and does **not** apply an implicit score threshold.
+Use `--min-score N` (with or without `--ci`) to fail with exit code `1` when
+`scores.overall < N`.
 
 Exit codes: [docs/exit-codes.md](docs/exit-codes.md). Compatibility promises: [docs/compatibility.md](docs/compatibility.md).
 
+### Readiness scoring
+
+Scans populate `scoringAvailable: true` and a deterministic `scores` object
+(overall, categories, agents). The terminal report does not render a readiness line yet;
+scores are available in JSON (`--json`).
+
+`--min-score N` is enforced by the CLI. Details (weights, security caps, threshold rules,
+and deferred v2 items): [docs/scoring.md](docs/scoring.md).
+
 ---
 
 ## Beta limitations
@@ -296,21 +311,21 @@ Honest limits of the current public beta:
 
 | Limitation                          | Status                                                          |
 | ----------------------------------- | --------------------------------------------------------------- |
-| Readiness scoring                   | Not available (`scores` is `null`, `scoringAvailable: false`)   |
-| `--min-score`                       | Accepted, ignored until scoring ships                           |
+| Terminal readiness line             | Scores ship in JSON only; terminal does not print N/100 yet     |
+| GitHub Action score gates           | Action remains `--ci --json` report-only (no `min-score` input) |
 | Automatic fixes (`agentdoctor fix`) | Stub only — does not modify files                               |
 | Secret-content scanning             | Filename / config heuristics only                               |
 | Detection style                     | Intentionally conservative; false security findings are avoided |
 | Agent coverage                      | Cursor, Claude Code, Codex project configs                      |
 
-See [CHANGELOG.md](CHANGELOG.md) and [docs/release-notes-v0.1.4-beta.md](docs/release-notes-v0.1.4-beta.md).
+See [CHANGELOG.md](CHANGELOG.md) and [docs/release-notes-v0.2.0-beta.md](docs/release-notes-v0.2.0-beta.md).
 
 ---
 
 ## Architecture
 
 ```text
-Discovery → Project detect → Agent adapters → Rule engine → Findings → Terminal / JSON
+Discovery → Project detect → Agent adapters → Rule engine → Findings → Scores → Terminal / JSON
 ```
 
 Details: [docs/architecture.md](docs/architecture.md)
@@ -319,17 +334,18 @@ Details: [docs/architecture.md](docs/architecture.md)
 
 ## Documentation
 
-| Doc                                                                | Contents                       |
-| ------------------------------------------------------------------ | ------------------------------ |
-| [docs/README.md](docs/README.md)                                   | Documentation index            |
-| [docs/architecture.md](docs/architecture.md)                       | Scan pipeline                  |
-| [docs/rules.md](docs/rules.md)                                     | Stable rule IDs                |
-| [docs/exit-codes.md](docs/exit-codes.md)                           | Process exit codes             |
-| [docs/compatibility.md](docs/compatibility.md)                     | Beta compatibility promises    |
-| [docs/development.md](docs/development.md)                         | Local development              |
-| [docs/github-launch-checklist.md](docs/github-launch-checklist.md) | GitHub About / topics / launch |
-| [ROADMAP.md](ROADMAP.md)                                           | Near- and medium-term plans    |
-| [CHANGELOG.md](CHANGELOG.md)                                       | Release history                |
+| Doc                                                                | Contents                        |
+| ------------------------------------------------------------------ | ------------------------------- |
+| [docs/README.md](docs/README.md)                                   | Documentation index             |
+| [docs/architecture.md](docs/architecture.md)                       | Scan pipeline                   |
+| [docs/rules.md](docs/rules.md)                                     | Stable rule IDs                 |
+| [docs/exit-codes.md](docs/exit-codes.md)                           | Process exit codes              |
+| [docs/scoring.md](docs/scoring.md)                                 | Readiness scoring specification |
+| [docs/compatibility.md](docs/compatibility.md)                     | Beta compatibility promises     |
+| [docs/development.md](docs/development.md)                         | Local development               |
+| [docs/github-launch-checklist.md](docs/github-launch-checklist.md) | GitHub About / topics / launch  |
+| [ROADMAP.md](ROADMAP.md)                                           | Near- and medium-term plans     |
+| [CHANGELOG.md](CHANGELOG.md)                                       | Release history                 |
 
 ---
 

package/dist/cli/commands/doctor.js

@@ -15,7 +15,7 @@ export async function runDoctorCommand() {
     lines.push(`  ${symbolOk()} Core scan API available`);
     lines.push("");
     lines.push(colors.dim("Environment looks ready."));
-    lines.push(colors.dim("Readiness scoring and automatic fixes are not available yet."));
+    lines.push(colors.dim("Automatic fixes are not available yet."));
     lines.push("");
     process.stdout.write(lines.join("\n"));
     return EXIT_CODES.SUCCESS;

package/dist/cli/commands/scan.js

@@ -24,20 +24,12 @@ export async function runScanCommand(options) {
                 verbose: options.verbose === true,
             }));
         }
-        if (options.ci || options.minScore !== undefined) {
-            if (!result.scoringAvailable || result.scores === null) {
+        if (options.minScore !== undefined && result.scores !== null) {
+            if (result.scores.overall < options.minScore) {
                 if (!options.json) {
-                    console.error("Note: readiness scoring is not available in this release; --min-score was ignored.");
-                }
-            }
-            else {
-                const threshold = options.minScore ?? 0;
-                if (result.scores.overall < threshold) {
-                    if (!options.json) {
-                        console.error(`\nCI check failed: overall score ${result.scores.overall} is below --min-score ${threshold}`);
-                    }
-                    return EXIT_CODES.ISSUES_OR_THRESHOLD;
+                    console.error(`\nCI check failed: overall score ${result.scores.overall} is below --min-score ${options.minScore}`);
                 }
+                return EXIT_CODES.ISSUES_OR_THRESHOLD;
             }
         }
         return EXIT_CODES.SUCCESS;

package/dist/cli/program.js

@@ -29,9 +29,9 @@ export function createProgram() {
         .version(PACKAGE_VERSION, "-V, --version", "Print AgentDoctor version")
         .argument("[path]", "Repository path to scan (default: current directory)")
         .option("--json", "Emit machine-readable JSON (no decorative output)", false)
-        .option("--ci", "CI mode (non-interactive; --min-score is ignored until scoring ships)", false)
+        .option("--ci", "CI mode (non-interactive; report-only unless --min-score is set)", false)
         .option("--verbose", "Show timing and extra diagnostics", false)
-        .option("--min-score <number>", "Fail when overall score is below this (no-op until scoring ships)", parseMinScore)
+        .option("--min-score <number>", "Exit 1 when overall readiness score is below this (0-100)", parseMinScore)
         .action(async (pathArg, options) => {
         const minScore = readMinScore(options);
         const code = await runScanCommand({
@@ -48,9 +48,9 @@ export function createProgram() {
         .description("Scan a repository for AI coding agent configuration issues (default command)")
         .argument("[path]", "Repository path to scan")
         .option("--json", "Emit machine-readable JSON", false)
-        .option("--ci", "CI mode (--min-score ignored until scoring ships)", false)
+        .option("--ci", "CI mode (non-interactive; report-only unless --min-score is set)", false)
         .option("--verbose", "Show timing and extra diagnostics", false)
-        .option("--min-score <number>", "Fail when overall score is below this (no-op until scoring ships)", parseMinScore)
+        .option("--min-score <number>", "Exit 1 when overall readiness score is below this (0-100)", parseMinScore)
         .action(async (pathArg, options) => {
         const minScore = readMinScore(options);
         const code = await runScanCommand({

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const PACKAGE_VERSION = "0.1.4-beta";
+export declare const PACKAGE_VERSION = "0.2.0-beta";
 export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export declare const DEFAULT_IGNORE_DIRECTORIES: Set<string>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "0.1.4-beta";
+export const PACKAGE_VERSION = "0.2.0-beta";
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export const DEFAULT_IGNORE_DIRECTORIES = new Set([

package/dist/core/scanner/scan.d.ts

@@ -1,7 +1,6 @@
 import type { ScanOptions, ScanResult } from "../../types/index.js";
 /**
  * Public scan entry point.
- * Pipeline: discovery → project detection → agent adapters → rule engine → findings.
- * Readiness scoring is reserved for a later release (`scores` remains null for now).
+ * Pipeline: discovery → project detection → agent adapters → rule engine → findings → scores.
  */
 export declare function scan(options?: ScanOptions): Promise<ScanResult>;

package/dist/core/scanner/scan.js

@@ -4,10 +4,10 @@ import { detectProject } from "../../detectors/project.js";
 import { sanitizeTerminalText } from "../../security/redaction.js";
 import { buildRuleContext } from "../rules/build-context.js";
 import { runRules } from "../rules/run-rules.js";
+import { computeReadinessScores } from "../scoring/compute-scores.js";
 /**
  * Public scan entry point.
- * Pipeline: discovery → project detection → agent adapters → rule engine → findings.
- * Readiness scoring is reserved for a later release (`scores` remains null for now).
+ * Pipeline: discovery → project detection → agent adapters → rule engine → findings → scores.
  */
 export async function scan(options = {}) {
     const totalStarted = performance.now();
@@ -51,21 +51,24 @@ export async function scan(options = {}) {
     if (agentSecurityAnalysis === "limited") {
         warnings.push("No supported coding-agent configuration detected; agent-specific security exposure checks are limited.");
     }
+    const scoringStarted = performance.now();
+    const scores = computeReadinessScores(findings);
+    const scoringMs = Math.round(performance.now() - scoringStarted);
     return {
         version: PACKAGE_VERSION,
         repository,
         agents,
         findings,
         summary,
-        scores: null,
-        scoringAvailable: false,
+        scores,
+        scoringAvailable: true,
         agentSecurityAnalysis,
         timing: {
             discoveryMs: discovery.elapsedMs,
             detectionMs,
             agentsMs,
             rulesMs,
-            scoringMs: 0,
+            scoringMs,
             totalMs: Math.round(performance.now() - totalStarted),
         },
         diagnostics: {

package/dist/core/scoring/compute-scores.d.ts

@@ -0,0 +1,6 @@
+import type { Finding, Scores } from "../../types/index.js";
+/**
+ * v1 readiness scores from post-dedupe findings.
+ * Spec: docs/scoring.md
+ */
+export declare function computeReadinessScores(findings: readonly Finding[]): Scores;

package/dist/core/scoring/compute-scores.js

@@ -0,0 +1,90 @@
+const SEVERITY_BASE = {
+    critical: 35,
+    warning: 10,
+    info: 2,
+};
+const SEVERITY_SORT_RANK = {
+    critical: 0,
+    warning: 1,
+    info: 2,
+};
+/**
+ * v1 readiness scores from post-dedupe findings.
+ * Spec: docs/scoring.md
+ */
+export function computeReadinessScores(findings) {
+    const overallRaw = 100 - sumDeductions(findings);
+    const overall = clampScore(applySecurityCaps(overallRaw, findings));
+    return {
+        overall,
+        categories: {
+            security: scoreSubset(findings.filter((f) => f.category === "security")),
+            context: scoreSubset(findings.filter((f) => f.category === "context")),
+            instructions: scoreSubset(findings.filter((f) => f.category === "instructions")),
+            mcp: scoreSubset(findings.filter((f) => f.category === "mcp")),
+            compatibility: scoreSubset(findings.filter((f) => f.category === "compatibility")),
+            performance: scoreSubset(findings.filter((f) => f.category === "performance")),
+        },
+        agents: {
+            cursor: scoreSubset(findings.filter((f) => f.affectedAgents.includes("cursor"))),
+            "claude-code": scoreSubset(findings.filter((f) => f.affectedAgents.includes("claude-code"))),
+            codex: scoreSubset(findings.filter((f) => f.affectedAgents.includes("codex"))),
+        },
+    };
+}
+function scoreSubset(findings) {
+    return clampScore(100 - sumDeductions(findings));
+}
+function sumDeductions(findings) {
+    const sorted = sortFindings(findings);
+    const severityIndex = {
+        critical: 0,
+        warning: 0,
+        info: 0,
+    };
+    let total = 0;
+    for (const finding of sorted) {
+        const occurrence = severityIndex[finding.severity];
+        severityIndex[finding.severity] = occurrence + 1;
+        total += SEVERITY_BASE[finding.severity] * diminishingMultiplier(occurrence);
+    }
+    return total;
+}
+function diminishingMultiplier(zeroBasedIndex) {
+    if (zeroBasedIndex === 0)
+        return 1;
+    if (zeroBasedIndex === 1)
+        return 0.7;
+    if (zeroBasedIndex === 2)
+        return 0.5;
+    return 0.35;
+}
+function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const sev = SEVERITY_SORT_RANK[a.severity] - SEVERITY_SORT_RANK[b.severity];
+        if (sev !== 0)
+            return sev;
+        const rule = a.ruleId.localeCompare(b.ruleId);
+        if (rule !== 0)
+            return rule;
+        const pathA = a.evidence?.path ?? "";
+        const pathB = b.evidence?.path ?? "";
+        const pathCmp = pathA.localeCompare(pathB);
+        if (pathCmp !== 0)
+            return pathCmp;
+        return a.id.localeCompare(b.id);
+    });
+}
+function applySecurityCaps(overall, findings) {
+    const securityCriticals = findings.filter((f) => f.category === "security" && f.severity === "critical").length;
+    if (securityCriticals >= 2) {
+        return Math.min(overall, 49);
+    }
+    if (securityCriticals >= 1) {
+        return Math.min(overall, 69);
+    }
+    return overall;
+}
+function clampScore(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}

package/dist/core/scoring/placeholder.d.ts

@@ -1,7 +1,7 @@
 import type { Scores } from "../../types/index.js";
 /**
- * Internal scoring stub retained for upcoming readiness scores.
- * Production scans currently return `scores: null`.
- * A clean undetected-agent repo stays below 100 by design.
+ * Historical filesScanned-based stub. Kept for unit tests that document the
+ * pre-v1 placeholder behavior. Production scans use computeReadinessScores
+ * (docs/scoring.md) — do not call this from scan().
  */
 export declare function computePlaceholderScores(filesScanned: number): Scores;

package/dist/core/scoring/placeholder.js

@@ -1,7 +1,7 @@
 /**
- * Internal scoring stub retained for upcoming readiness scores.
- * Production scans currently return `scores: null`.
- * A clean undetected-agent repo stays below 100 by design.
+ * Historical filesScanned-based stub. Kept for unit tests that document the
+ * pre-v1 placeholder behavior. Production scans use computeReadinessScores
+ * (docs/scoring.md) — do not call this from scan().
  */
 export function computePlaceholderScores(filesScanned) {
     const base = 72;

package/dist/types/index.d.ts

@@ -106,11 +106,11 @@ export interface ScanResult {
     findings: Finding[];
     summary: FindingsSummary;
     /**
-     * Readiness scores when scoring is available.
-     * Null while scoring is unavailable — do not treat as readiness.
+     * Readiness scores (v1). Always populated when `scoringAvailable` is true.
+     * Remains typed as nullable for older consumers / transitional tooling.
      */
     scores: Scores | null;
-    /** False until the readiness scoring model ships. */
+    /** True when the readiness scoring model is active and `scores` is populated. */
     scoringAvailable: boolean;
     /**
      * `limited` when no supported coding agent is detected/configured.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praneeth_54/agentdoctor",
-  "version": "0.1.4-beta",
+  "version": "0.2.0-beta",
   "description": "Audit AI coding agent configuration in a repository — local, deterministic, no API key.",
   "type": "module",
   "bin": {