delivery-intel answers three questions — with evidence, not guesses:

1. Does this repo ship well? (deployment frequency, lead time, forensic signals)
2. Does it fail safely? (change fail rate, recovery time, vulnerabilities, flaky pipelines)
3. Is it getting better or worse? (30-day trend, verdict: exemplary / fast-but-fragile / unstable)

Every metric shows its source, sample size, and confidence level. No fake precision.

⚡ Quick Start

# Verdict mode — grade, confidence, forensics, policy (v2 engine)
npx delivery-intel facebook/react --v2

# Mode-specific analysis (implies --v2)
npx delivery-intel facebook/react --mode adopt

# Classic metrics dump (v1 engine)
npx delivery-intel facebook/react

┌──────────────────────────────────────────────────────────────┐
│  facebook/react                                              │
│  Grade A-   Score 91/100   Confidence high                  │
│  Trend ↑ +4 pts                                             │
└──────────────────────────────────────────────────────────────┘

✓   NO POLICY VIOLATIONS
──────────────────────────────────────────────────────────────
  ✓ All delivery health policies are passing.

METRICS  (source · sample · confidence)
──────────────────────────────────────────────────────────────
  ◆ Deploy Frequency       12.4/wk  [high]  deployment_statuses
  ◆ Change Lead Time       3.2h     [high]  commit_to_deploy (84 PRs)
  ● Recovery Time          0.8h     [med]   deployment_failures
  ◆ Change Fail Rate       4.8%     [high]  deployment_statuses
  ● Pipeline Failures      8.2%     [high]  workflow_runs (52 runs)

SIGNAL QUALITY
──────────────────────────────────────────────────────────────
  ◈ Production signal strength: high
  ✓ Scanned manifests: npm (package.json), Go (go.mod)

SECURITY
──────────────────────────────────────────────────────────────
  ✓ No known vulnerabilities found in scanned manifests

Works with full URLs too: npx delivery-intel https://github.com/vercel/next.js --v2

Why DORA metrics matter

Google's 2024 DORA Report (32,000+ respondents, 10 years of data):

Elite teams are 2× more likely to meet reliability targets and 1.8× more likely to meet business goals (DORA 2024).

Lead Time ★ Elite 3.2 hours median (0.1 days)

Change Failure Rate ● High 4.8% (2 failed / 42 total runs)

◈ Vulnerability Scan (OSV.dev) ──────────────────────────────────────────────────────── ✓ No known vulnerabilities found

◈ Suggestions ──────────────────────────────────────────────────────── ✓ Looking good, no critical issues detected

> Works with full URLs too: `npx delivery-intel https://github.com/vercel/next.js`

---

## What It Measures

| Metric | What it tells you | Source | Confidence |
|--------|-------------------|--------|------------|
| **Deploy Frequency** | How often code ships to production | Deployment statuses → deploys → Actions → PRs | Waterfall |
| **Change Lead Time** | Commit → production (PR flow as fallback) | Deployments + commits | High / Low |
| **Change Fail Rate** | % of deployments that failed or rolled back | Deployment statuses + heuristics | High / Low |
| **Recovery Time** | Time from failure to successful recovery | Deployment failures + workflow runs | High / Low |
| **Pipeline Failure Rate** | CI workflow run reliability (distinct from CFR) | Workflow Runs API | High |
| **Deployment Rework Rate** | Rollback/revert/hotfix rate (inferred) | PR titles + labels + deployment refs | Low (flagged) |
| **Vulnerabilities** | Known CVEs across 7 manifest ecosystems | [OSV.dev](https://osv.dev) batch API | — |
| **Delivery Score** | Confidence-weighted composite (0–100) | All of the above | Aggregate |

> Every metric exposes: data source · sample size · lookback window · confidence level.
> Low-confidence signals contribute less to the composite score — no fake precision.

Supported manifest ecosystems: **npm** · **pip** · **Go modules** · **Poetry** · **pnpm** · **Cargo** · **RubyGems**

---

## Usage

### CLI (zero install)

```bash
# Verdict: grade, confidence, policy violations, evidence chain (v2 engine)
npx delivery-intel facebook/react --v2

# Classic metrics output (v1 engine — backwards compatible)
npx delivery-intel facebook/react

# Compare last 30 days vs prior 30 days
npx delivery-intel vercel/next.js --trend

# Include workflow strain analysis
npx delivery-intel vercel/next.js --risk

# AI-powered executive narrative (requires LLM key — falls back to template)
npx delivery-intel vercel/next.js --narrative

# JSON output (v2 includes full evidence chain + policy result)
npx delivery-intel vercel/next.js --v2 --json

# Save report to file
npx delivery-intel vercel/next.js --v2 --json --output report.json

All flags

Web Dashboard

git clone https://github.com/ParthibanRajasekaran/delivery-intel.git
cd delivery-intel
npm install
npm run dev
# → http://localhost:3000

Paste a repo URL and get an animated dashboard with score ring, DORA cards, charts, vulnerability table, and suggestions.

Docker

# Dashboard
docker compose up dashboard

# CLI
REPO=facebook/react docker compose run --rm cli

📦 JSON Output Schema

Pass --json (or --json --output report.json) to get machine-readable output.

{
  "repo": { "owner": "vercel", "repo": "next.js" },
  "fetchedAt": "2026-04-17T12:00:00.000Z",
  "overallScore": 87,                          // 0–100
  "doraMetrics": {
    "deploymentFrequency": {
      "deploymentsPerWeek": 12.4,
      "rating": "Elite",                       // Elite | High | Medium | Low
      "source": "merged_prs_fallback"          // deployments_api | merged_prs_fallback
    },
    "leadTimeForChanges": {
      "medianHours": 3.2,
      "rating": "Elite"
    },
    "changeFailureRate": {
      "percentage": 4.8,
      "failedRuns": 2,
      "totalRuns": 42,
      "rating": "High"
    }
  },
  "vulnerabilities": [
    {
      "packageName": "lodash",
      "currentVersion": "4.17.15",
      "vulnId": "GHSA-xxxx-xxxx-xxxx",
      "summary": "Prototype pollution",
      "severity": "high",                      // critical | high | medium | low
      "aliases": ["CVE-2021-23337"],
      "fixedVersion": "4.17.21"
    }
  ],
  "suggestions": [
    {
      "category": "reliability",               // performance | reliability | security
      "severity": "high",                      // high | medium | low
      "title": "High Pipeline Failure Rate",
      "description": "...",
      "actionItems": ["..."]
    }
  ],
  "dailyDeployments": [0, 1, 2, 3, 1, 2, 3], // last 7 days, index 0 = 6 days ago
  // present only with --trend
  "trend": {
    "windowDays": 30,
    "current":  { "deploymentsPerWeek": 12.4, "leadTimeHours": 3.2, "changeFailureRate": 4.8, "score": 87 },
    "prior":    { "deploymentsPerWeek": 9.1,  "leadTimeHours": 5.6, "changeFailureRate": 6.2, "score": 78 },
    "deltas":   { "deploymentsPerWeek": 3.3,  "leadTimeHours": -2.4, "changeFailureRate": -1.4, "score": 9 }
  },
  // present only with --risk
  "riskScore": {
    "score": 42,
    "level": "moderate",                       // low | moderate | high | critical
    "cycleTimeDelta": 0.12,
    "failureRateDelta": -0.05,
    "sentimentMultiplier": 1.0,
    "summary": "..."
  }
}

🔐 Authentication

Token resolution order: --token flag → GITHUB_TOKEN env → gh auth token

Private repos require a token with repo scope. For CI, use ${{ secrets.GITHUB_TOKEN }}. It's auto-scoped and expires per job.

CI Integration

GitHub Actions Marketplace action

The easiest way — use the action directly:

# .github/workflows/delivery-intel.yml
name: Delivery Health Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: ParthibanRajasekaran/delivery-intel@v1.6.0
        with:
          fail-below: '40'   # fail the job if score drops below 40

Outputs available after the step: score, deploy-frequency, lead-time, change-failure-rate, mean-time-to-restore.

Evidence-backed PR guardrail (v2 engine)

Posts a policy-aware comment on every PR — no block unless a real threshold is breached:

    steps:
      - name: Delivery Health Check
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          npx delivery-intel@latest ${{ github.repository }} \
            --v2 \
            --pr-comment \
            --fail-below 40 \
            --no-spinner

      - name: Post PR Comment
        if: always() && github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file delivery-intel-pr-comment.md \
            --repo ${{ github.repository }}

The comment leads with a verdict (✅ No block / ⚠️ Warning / 🚫 BLOCKED), followed by a collapsible metrics table with source and confidence for every data point.

npx (custom pipeline)

    steps:
      - name: Run delivery-intel
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx delivery-intel@latest ${{ github.repository }} --v2 --json --output report.json

      - name: Check health score
        run: |
          SCORE=$(jq '.scores.delivery.score' report.json)
          echo "Health score: $SCORE / 100"
          if (( $(echo "$SCORE < 40" | bc -l) )); then
            echo "::error::Score $SCORE is below threshold (40)"
            exit 1
          fi

🏅 Badge

Once you have the dashboard deployed, you can show a live delivery score in any README:

[![Delivery Score](https://your-deployment-url/api/badge?repo=owner/repo)](https://github.com/ParthibanRajasekaran/delivery-intel)

The GET /api/badge?repo=owner/repo endpoint returns a Shields.io endpoint-badge payload. Score maps to color: < 20 red → < 40 orange → < 60 yellow → < 80 green → ≥ 80 bright green. Results cached 5 minutes.

Self-hosting: deploy the dashboard (npm run build && npm start or docker compose up dashboard) and replace your-deployment-url.

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                      delivery-intel                          │
├──────────────┬───────────────┬───────────────────────────────┤
│   CLI        │   Dashboard   │   CI Workflow / Action        │
│  (npx)       │  (Next.js)    │   (action.yml)                │
├──────────────┴───────────────┴───────────────────────────────┤
│              Renderers (terminal, JSON, PR comment)           │
├──────────────────────────────────────────────────────────────┤
│          Verdict Engine  ·  Forensic Signal Engine            │
├──────────┬────────────┬──────────────┬───────────────────────┤
│ Scoring  │ Policies   │  Fix Packs   │  Recommendations      │
│ (conf-   │ (gates,    │  (copy-paste │  (ranked actions)     │
│  weighted)│  blocking) │   artifacts) │                       │
├──────────┴────────────┴──────────────┴───────────────────────┤
│  DORA Metrics (6) · Confidence · Evidence Sources · Caveats  │
├──────────────────────────────────────────────────────────────┤
│       Normaliser (raw API → typed EvidenceEvent stream)       │
├──────────┬────────────┬──────────────────────────────────────┤
│ GitHub   │ OSV.dev    │  Extractors (7 ecosystems)           │
│ REST API │ Vuln API   │  npm·pip·Go·Poetry·pnpm·Cargo·Gems  │
└──────────┴────────────┴──────────────────────────────────────┘

🛠 Tech Stack

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for dev setup, coding standards, and workflow.

git clone https://github.com/ParthibanRajasekaran/delivery-intel.git
cd delivery-intel
npm install
npm run validate   # lint + typecheck + test in one shot

📄 License

MIT. Use it however you want.