@lhi/tdd-audit 1.12.0 → 1.15.0

package/README.md

@@ -1,6 +1,7 @@
 # @lhi/tdd-audit
+[![tdd-audit](https://img.shields.io/badge/tdd--audit-passing-brightgreen)](https://www.npmjs.com/package/@lhi/tdd-audit) <!-- tdd-audit-badge -->
 
-> **v1.12.0** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — prove the hole exists, apply the fix, prove it's closed.
+> **v1.15.0** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — prove the hole exists, apply the fix, prove it's closed. Enforces ≥ 95% test coverage, README badge, and SECURITY.md on every audit.
 
 ## Install
 
@@ -80,7 +81,7 @@ npx @lhi/tdd-audit serve --config ~/configs/prod-audit.json
 ## REST API + AI remediation
 
 ```bash
-# Start the API server
+# Start the API server (now powered by Fastify)
 npx @lhi/tdd-audit serve --port 3000 --api-key YOUR_SECRET
 
 # Scan any path → JSON
@@ -88,6 +89,19 @@ curl -X POST http://localhost:3000/scan \
   -H "Authorization: Bearer YOUR_SECRET" \
   -d '{"path": "."}' | jq '.summary'
 
+# Full automated pipeline: scan + remediate in one shot
+curl -X POST http://localhost:3000/audit \
+  -H "Authorization: Bearer YOUR_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{"path": ".", "provider": "anthropic", "apiKey": "sk-ant-..."}' \
+  | jq '.jobId'
+
+# Poll job status
+curl http://localhost:3000/jobs/<jobId>
+
+# Or stream real-time updates via SSE
+curl -N http://localhost:3000/jobs/<jobId>/stream
+
 # Use any OpenAI-compatible service (Groq, OpenRouter, Together AI, etc.)
 npx @lhi/tdd-audit serve \
   --provider openai \
@@ -98,6 +112,17 @@ npx @lhi/tdd-audit serve \
 
 Supported providers: `anthropic` · `openai` · `gemini` · `ollama` (local) · **any OpenAI-compatible endpoint via `--base-url`**
 
+### Endpoints
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/health` | No | Version + liveness check |
+| `POST` | `/scan` | Yes | Scan a path, return findings |
+| `POST` | `/remediate` | Yes | AI-fix a findings list; returns `jobId` |
+| `POST` | `/audit` | Yes | Full scan+remediate pipeline; returns `jobId` |
+| `GET` | `/jobs/:id` | Yes | Poll job status |
+| `GET` | `/jobs/:id/stream` | Yes | SSE stream — real-time job progress |
+
 ## Output formats
 
 ```bash
@@ -108,11 +133,11 @@ npx @lhi/tdd-audit --scan                 # human-readable text (default)
 
 ## Testing
 
-463 tests across unit, E2E, and security suites:
+586 tests across unit, E2E, and security suites:
 
 ```bash
 npm test                  # full suite
-npm run test:unit         # unit tests with coverage (91.6% branch coverage)
+npm run test:unit         # unit tests with coverage (96.6% branch coverage)
 npm run test:security     # security regression tests only
 npm run test:e2e          # end-to-end REST API tests
 ```
@@ -126,7 +151,7 @@ Security tests cover prompt injection, path traversal, rate limiting, timing-saf
 | [REST API](docs/rest-api.md) | Endpoints, auth, rate limiting, trust-proxy, request/response schema |
 | [AI Remediation](docs/ai-remediation.md) | Provider setup, `--base-url` for compatible APIs, config file |
 | [Scanner](docs/scanner.md) | Architecture, detection logic, false-positive handling |
-| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 34 patterns — descriptions, grep signatures, fix pointers |
+| [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 57 patterns — descriptions, grep signatures, fix pointers |
 | [TDD Protocol](docs/tdd-protocol.md) | Red-Green-Refactor in full, with framework templates for all 6 stacks |
 | [Agentic AI Security](docs/agentic-ai-security.md) | ASI01–ASI10 — prompt injection, MCP supply chain, Actions injection |
 | [Hardening](docs/hardening.md) | Phase 4 controls — Helmet, CSP, CSRF, rate limiting, gitleaks, SRI |

package/docs/rest-api.md

@@ -1,6 +1,6 @@
 # REST API
 
-`tdd-audit serve` turns the scanner into an authenticated HTTP API. Use it to integrate vulnerability scanning into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
+`tdd-audit serve` turns the scanner into an authenticated HTTP API built on **Fastify**. Use it to integrate vulnerability scanning and AI remediation into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
 
 ---
 
@@ -29,7 +29,7 @@ npx @lhi/tdd-audit serve --config ~/configs/prod.json
 }
 ```
 
-If `--api-key` / `serverApiKey` is omitted the server starts unauthenticated with a warning. Always set one in production.
+If `--api-key` / `serverApiKey` is omitted the server starts unauthenticated with a stderr warning. Always set one in production.
 
 ---
 
@@ -45,13 +45,13 @@ Authorization: Bearer YOUR_SECRET
 
 Missing or wrong key → `401 Unauthorized`.
 
-Tokens are compared using **HMAC + `crypto.timingSafeEqual`** to prevent timing-oracle attacks.
+Tokens are compared using **HMAC + `crypto.timingSafeEqual`** to prevent timing-oracle attacks (both values are HMAC-normalised before comparison so lengths are always equal).
 
 ### Rate limiting
 
-All endpoints are rate-limited to **60 requests / IP / minute** (default). Exceeding the limit returns `429 Too Many Requests`.
+All endpoints are rate-limited to **60 requests / IP / minute**. Exceeding the limit returns `429 Too Many Requests`.
 
-By default the rate limiter keys on the **socket IP**, not `X-Forwarded-For`, to prevent header-spoofing bypasses. Enable proxy-forwarded IPs only if you are behind a trusted reverse proxy:
+By default the rate limiter keys on the **socket IP**, not `X-Forwarded-For`, to prevent header-spoofing bypasses. Enable proxy-forwarded IPs only when you are behind a trusted reverse proxy:
 
 ```json
 { "trustProxy": true }
@@ -59,15 +59,16 @@ By default the rate limiter keys on the **socket IP**, not `X-Forwarded-For`, to
 
 ### Path validation
 
-`POST /scan` validates that the requested path is inside the server's working directory (normalised with a trailing separator to prevent sibling-directory prefix bypasses). Paths outside cwd return `400`.
+`POST /scan` and `POST /audit` validate that the requested path is inside the server's working directory. The check is normalised with a trailing path separator to prevent sibling-directory prefix bypasses (e.g. `/app-evil` cannot escape via `/app`). Paths outside cwd return `400`.
 
 ### Security headers
 
 Every response includes:
 
 ```
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
+Content-Security-Policy: default-src 'none'
+X-Content-Type-Options:  nosniff
+X-Frame-Options:         DENY
 ```
 
 ---
@@ -79,14 +80,14 @@ X-Frame-Options: DENY
 No auth required. Returns server status and version.
 
 ```json
-{ "status": "ok", "version": "1.9.0" }
+{ "status": "ok", "version": "1.13.0" }
 ```
 
 ---
 
 ### `POST /scan`
 
-Scan a local path and return structured findings.
+Scan a local path and return structured findings synchronously.
 
 **Request**
 ```json
@@ -104,13 +105,13 @@ Scan a local path and return structured findings.
 **Response — JSON**
 ```json
 {
-  "version":             "1.9.0",
-  "summary":             { "CRITICAL": 1, "HIGH": 3, "MEDIUM": 1, "LOW": 0 },
-  "findings":            [ ... ],
+  "version":              "1.13.0",
+  "summary":              { "CRITICAL": 1, "HIGH": 3, "MEDIUM": 1, "LOW": 0 },
+  "findings":             [ ... ],
   "likelyFalsePositives": [ ... ],
-  "exempted":            [],
-  "scannedAt":           "2026-03-25T12:00:00.000Z",
-  "duration":            42
+  "exempted":             [],
+  "scannedAt":            "2026-03-25T12:00:00.000Z",
+  "duration":             42
 }
 ```
 
@@ -122,7 +123,7 @@ Returns a SARIF 2.1.0 object ready to upload to GitHub code scanning.
 
 | Status | Reason |
 |---|---|
-| 400 | Path traversal attempt, sibling-directory bypass, oversized body (> 512 KB), or invalid JSON |
+| 400 | Path traversal attempt, oversized body (> 512 KB), or invalid JSON |
 | 401 | Missing or invalid API key |
 | 429 | Rate limit exceeded |
 
@@ -130,18 +131,18 @@ Returns a SARIF 2.1.0 object ready to upload to GitHub code scanning.
 
 ### `POST /remediate`
 
-Queue an AI-powered remediation job. Returns immediately with a `jobId`; poll `/jobs/:id` for results.
+Queue an AI-powered remediation job for a **provided findings list**. Returns immediately with a `jobId`; poll `GET /jobs/:id` (or stream `GET /jobs/:id/stream`) for results.
 
-The server stores up to **1 000 jobs** in memory (TTL: 1 hour). Oldest jobs are evicted when the cap is reached.
+Use `POST /audit` instead if you want the server to run the scan itself.
 
 **Request**
 ```json
 {
   "findings": [ ... ],
-  "provider": "openai",
-  "apiKey":   "sk-...",
-  "model":    "gpt-4o",
-  "baseUrl":  "https://api.groq.com/openai/v1",
+  "provider": "anthropic",
+  "apiKey":   "sk-ant-...",
+  "model":    "claude-opus-4-6",
+  "baseUrl":  null,
   "severity": "HIGH"
 }
 ```
@@ -155,23 +156,69 @@ The server stores up to **1 000 jobs** in memory (TTL: 1 hour). Oldest jobs are
 | `baseUrl` | no | Override base URL for any OpenAI-compatible service |
 | `severity` | no | Minimum severity to fix. Default: `LOW` (fix all) |
 
-**Response**
+**Response — 202 Accepted**
 ```json
 { "jobId": "job_1_1711363200000" }
 ```
 
+Job lifecycle: `pending → running → done | error`
+
 ---
 
-### `GET /jobs/:id`
+### `POST /audit`
+
+Full automated pipeline: **scan + AI remediation in one shot**. No interaction needed. Returns immediately with a `jobId`.
 
-Poll for remediation job status.
+If no `provider`/`apiKey` are supplied, the server runs the scan only (no remediation) and the job transitions to `done` with just the `findings` array.
 
-**Response — pending / running**
+**Request**
 ```json
-{ "id": "job_1_...", "status": "pending", "createdAt": "..." }
+{
+  "path":     ".",
+  "provider": "anthropic",
+  "apiKey":   "sk-ant-...",
+  "model":    "claude-opus-4-6",
+  "baseUrl":  null,
+  "webhook":  "https://your-server.example.com/webhook"
+}
 ```
 
-**Response — done**
+| Field | Required | Description |
+|---|---|---|
+| `path` | no | Path to scan. Defaults to cwd. Must be inside server cwd. |
+| `provider` | no | If supplied with `apiKey`, AI remediation runs after the scan |
+| `apiKey` | no | Provider API key |
+| `model` | no | Defaults per provider |
+| `baseUrl` | no | Override base URL for OpenAI-compatible providers |
+| `webhook` | no | URL to POST the final job payload to when complete (fire-and-forget) |
+
+**Response — 202 Accepted**
+
+```
+HTTP/1.1 202 Accepted
+Location: /jobs/job_1_1711363200000
+Retry-After: 2
+```
+```json
+{ "jobId": "job_1_1711363200000" }
+```
+
+Job lifecycle: `pending → scanning → scanned → remediating → done | error`
+
+Poll `GET /jobs/:id` or stream `GET /jobs/:id/stream` for progress.
+
+**Job object during remediation**
+```json
+{
+  "id":        "job_1_...",
+  "status":    "remediating",
+  "total":     8,
+  "completed": 3,
+  "current":   "SQL Injection"
+}
+```
+
+**Job object when done**
 ```json
 {
   "id":          "job_1_...",
@@ -179,6 +226,7 @@ Poll for remediation job status.
   "createdAt":   "...",
   "startedAt":   "...",
   "completedAt": "...",
+  "findings":    [ ... ],
   "results": [
     {
       "finding":        { ... },
@@ -193,28 +241,130 @@ Poll for remediation job status.
 
 ---
 
-## Examples
+### `GET /jobs/:id`
+
+Poll for job status. Works for jobs created by both `POST /remediate` and `POST /audit`.
+
+**Response — pending / scanning**
+```json
+{ "id": "job_1_...", "status": "scanning", "createdAt": "..." }
+```
+
+**Response — remediating (with progress)**
+```json
+{
+  "id":        "job_1_...",
+  "status":    "remediating",
+  "total":     8,
+  "completed": 3,
+  "current":   "SQL Injection"
+}
+```
+
+**Response — done**
+```json
+{
+  "id":          "job_1_...",
+  "status":      "done",
+  "createdAt":   "...",
+  "startedAt":   "...",
+  "completedAt": "...",
+  "results":     [ ... ]
+}
+```
+
+**Response — error**
+```json
+{ "id": "job_1_...", "status": "error", "error": "Provider returned 401: ..." }
+```
+
+The job store keeps up to **1 000 jobs** in memory (TTL: 1 hour). Oldest jobs are evicted when the cap is reached.
+
+---
+
+### `GET /jobs/:id/stream`
 
-### curl
+Real-time job progress via **Server-Sent Events (SSE)**. The server pushes an event each time the job state changes, and closes the connection when the job reaches `done` or `error`.
+
+```bash
+curl -N http://localhost:3000/jobs/job_1_.../stream \
+  -H "Authorization: Bearer YOUR_SECRET"
+```
+
+**Event format**
+```
+data: {"id":"job_1_...","status":"scanning","createdAt":"..."}
+
+data: {"id":"job_1_...","status":"scanned","findings":[...]}
+
+data: {"id":"job_1_...","status":"remediating","total":8,"completed":1,"current":"SQL Injection"}
+
+data: {"id":"job_1_...","status":"done","completedAt":"...","results":[...]}
+```
+
+The connection is closed automatically after the terminal state (`done` / `error`). If you connect to an already-completed job, the server pushes the current state and closes immediately.
+
+**Node.js example using EventSource**
+```javascript
+const es = new EventSource(
+  'http://localhost:3000/jobs/job_1_.../stream',
+  { headers: { Authorization: 'Bearer YOUR_SECRET' } }
+);
+es.onmessage = (e) => {
+  const job = JSON.parse(e.data);
+  if (job.status === 'done') { console.log(job.results); es.close(); }
+  if (job.status === 'error') { console.error(job.error); es.close(); }
+};
+```
+
+---
+
+## Full workflow examples
+
+### curl — scan only
 
 ```bash
-# Start server
 npx @lhi/tdd-audit serve --port 3000 --api-key mysecret &
 
-# Scan current directory
 curl -s -X POST http://localhost:3000/scan \
   -H "Authorization: Bearer mysecret" \
   -H "Content-Type: application/json" \
   -d '{"path": "."}' | jq '.summary'
+```
+
+### curl — full pipeline with polling
 
-# SARIF output for GitHub upload
+```bash
+# Kick off audit
+JOB=$(curl -s -X POST http://localhost:3000/audit \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "path":     ".",
+    "provider": "anthropic",
+    "apiKey":   "sk-ant-..."
+  }' | jq -r '.jobId')
+
+# Poll until done
+while true; do
+  STATUS=$(curl -s http://localhost:3000/jobs/$JOB \
+    -H "Authorization: Bearer mysecret" | jq -r '.status')
+  echo "Status: $STATUS"
+  [ "$STATUS" = "done" ] || [ "$STATUS" = "error" ] && break
+  sleep 2
+done
+```
+
+### curl — SARIF output for GitHub code scanning
+
+```bash
 curl -s -X POST http://localhost:3000/scan \
   -H "Authorization: Bearer mysecret" \
   -H "Content-Type: application/json" \
   -d '{"path": ".", "format": "sarif"}' > results.sarif
 ```
 
-### Node.js
+### Node.js — scan
 
 ```javascript
 const res = await fetch('http://localhost:3000/scan', {

package/docs/scanner.md

@@ -8,10 +8,12 @@
 
 | Export | Purpose |
 |---|---|
-| `quickScan(projectDir)` | Walk all source files and return a findings array |
+| `quickScan(projectDir)` | Walk all source files and return a merged findings array |
 | `scanPromptFiles(projectDir)` | Walk all `.md` prompt/skill files and check for prompt-specific patterns |
 | `scanAppConfig(projectDir)` | Check `app.json` / `app.config.*` for embedded secrets |
 | `scanAndroidManifest(projectDir)` | Check `AndroidManifest.xml` for `android:debuggable="true"` |
+| `scanPackageJson(projectDir)` | Check `package.json` lifecycle scripts for supply-chain exfiltration (postinstall curl/wget) |
+| `scanEnvFiles(projectDir)` | Check `.env*` files for `NEXT_PUBLIC_*SECRET/KEY/TOKEN` leaking secrets to the browser |
 | `printFindings(findings, exempted)` | Format and print a findings report to stdout |
 | `detectFramework(dir)` | Detect the test framework (`jest`, `vitest`, `mocha`, `pytest`, `go`, `flutter`) |
 | `detectAppFramework(dir)` | Detect the UI framework (`nextjs`, `expo`, `react-native`, `react`, `flutter`) |
@@ -23,7 +25,7 @@
 
 ```
 projectDir
-  └─ walkFiles()          — yields .js/.ts/.jsx/.tsx/.mjs/.py/.go/.dart files
+  └─ walkFiles()           — yields source files (see Scanned extensions below)
        └─ for each file:
             1. Read file content (read-first, check length after — no TOCTOU)
             2. Skip if content.length > 512 KB
@@ -32,12 +34,14 @@ projectDir
                  – If pattern matches, push finding with severity / name / file / line / snippet
                  – inTestFile: true if path is under a test directory
                  – likelyFalsePositive: true if inTestFile && pattern.skipInTests
-  └─ scanAppConfig()      — checks app.json / app.config.* for secret patterns
-  └─ scanAndroidManifest() — checks android:debuggable
-  └─ scanPromptFiles()    — walks .md files in prompt directories
+  └─ scanAppConfig()       — checks app.json / app.config.* for embedded secret patterns
+  └─ scanAndroidManifest() — checks android:debuggable="true"
+  └─ scanPromptFiles()     — walks .md files in agent config directories for prompt-specific patterns
+  └─ scanPackageJson()     — checks postinstall/preinstall lifecycle scripts for curl/wget exfiltration
+  └─ scanEnvFiles()        — checks .env* files for NEXT_PUBLIC_* keys with secret-sounding names
 ```
 
-All four result sets are merged into one array and returned to the caller.
+All six result sets are merged into one array and returned to the caller.
 
 ---
 
@@ -47,7 +51,7 @@ All four result sets are merged into one array and returned to the caller.
 
 Yields scannable source files (`SCAN_EXTENSIONS`). Skips:
 
-- **`SKIP_DIRS`**: `node_modules`, `.git`, `dist`, `build`, `.next`, `out`, `__pycache__`, `venv`, `.venv`, `vendor`, `.expo`, `.dart_tool`, `.pub-cache`
+- **`SKIP_DIRS`**: `node_modules`, `.git`, `dist`, `build`, `coverage`, `.next`, `out`, `__pycache__`, `venv`, `.venv`, `vendor`, `.expo`, `.dart_tool`, `.pub-cache`
 - **Symlinks** — never followed, preventing escape from the project root on shared/M-series filesystems
 
 ### `walkMdFiles(dir)`
@@ -58,9 +62,9 @@ Same skip rules, yields `.md` files only. Used by `scanPromptFiles`.
 
 ## Scanned extensions
 
-`.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.dart`
+`.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.dart` `.yml` `.yaml`
 
-YAML, JSON, XML, and shell files are not scanned by the code scanner. CI workflow files (`.yml`) are scanned separately when explicitly passed to the ASI08/ASI09 grep patterns during an agent-driven audit.
+JSON and XML files are not walked by the code scanner. `package.json` is handled by `scanPackageJson()` and `.env*` files by `scanEnvFiles()` — both run as separate targeted checks. CI workflow files (`.yml`/`.yaml`) **are** now scanned by `walkFiles()` for GitHub Actions expression injection and similar patterns.
 
 ---
 

package/index.js

@@ -13,6 +13,7 @@ const {
 } = require('./lib/scanner');
 const { toJson, toSarif, toText } = require('./lib/reporter');
 const { writeInitConfig } = require('./lib/config');
+const { badgeLine, injectBadge } = require('./lib/badge');
 
 const args = process.argv.slice(2);
 const isLocal   = args.includes('--local');
@@ -87,6 +88,7 @@ if (scanOnly) {
     process.stdout.write('\n');
     printFindings(findings, exempted);
   }
+  injectBadge(projectDir, badgeLine(findings));
   process.exit(0);
 }
 
@@ -243,6 +245,9 @@ if (!skipScan) {
   const findings = quickScan(projectDir);
   process.stdout.write('\n');
   printFindings(findings);
+  const badge = badgeLine(findings);
+  injectBadge(projectDir, badge);
+  console.log('✅ README badge updated');
 }
 
 console.log(`\nSkill installed to ${path.relative(os.homedir(), targetSkillDir)}`);

package/lib/badge.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// Marker embedded in the badge line — used to find and replace it on re-scan.
+const BADGE_MARKER = 'tdd-audit-badge';
+
+const NPM_URL = 'https://www.npmjs.com/package/@lhi/tdd-audit';
+
+/**
+ * Build a shields.io badge markdown line reflecting actual scan results.
+ *
+ * - 0 critical/high (real) findings → "passing" · brightgreen
+ * - ≥1 high (no critical)           → "{n} high"  · orange
+ * - ≥1 critical                     → "{n} critical" · red
+ *
+ * likelyFalsePositive findings (test fixtures) are excluded from the count.
+ *
+ * @param {Array} findings  - findings array returned by quickScan()
+ * @returns {string}        - single-line markdown badge ending with \n
+ */
+function badgeLine(findings) {
+  // Exclude test-file findings and likely false positives — badge reflects production code only
+  const real     = (findings || []).filter(f => !f.likelyFalsePositive && !f.inTestFile);
+  const criticals = real.filter(f => f.severity === 'CRITICAL').length;
+  const highs     = real.filter(f => f.severity === 'HIGH').length;
+
+  let message, color;
+  if (criticals > 0) {
+    message = `${criticals}%20critical`;
+    color   = 'red';
+  } else if (highs > 0) {
+    message = `${highs}%20high`;
+    color   = 'orange';
+  } else {
+    message = 'passing';
+    color   = 'brightgreen';
+  }
+
+  const badgeUrl = `https://img.shields.io/badge/tdd--audit-${message}-${color}`;
+  // Embed the marker as a hidden HTML comment after the badge so injectBadge()
+  // can locate and replace the line on subsequent runs.
+  return `[![tdd-audit](${badgeUrl})](${NPM_URL}) <!-- ${BADGE_MARKER} -->\n`;
+}
+
+/**
+ * Inject or update the tdd-audit badge in the project's README.md.
+ *
+ * Behaviour:
+ *  - Searches for README.md / readme.md / README in the project root.
+ *  - If a badge line (identified by BADGE_MARKER) already exists, replaces it.
+ *  - Otherwise inserts the badge immediately after the first `# Heading` line.
+ *    If no heading exists, prepends to the file.
+ *  - No-ops silently when no README is found.
+ *  - Idempotent: running twice with the same inputs produces the same output.
+ *
+ * @param {string} projectDir  - absolute path to the project root
+ * @param {string} badge       - badge markdown line from badgeLine()
+ */
+function injectBadge(projectDir, badge) {
+  const candidates = ['README.md', 'readme.md', 'Readme.md', 'README'];
+  let readmePath = null;
+  for (const name of candidates) {
+    const p = path.join(projectDir, name);
+    if (fs.existsSync(p)) { readmePath = p; break; }
+  }
+  if (!readmePath) return;
+
+  const original = fs.readFileSync(readmePath, 'utf8');
+
+  // Replace existing badge (idempotent + allows re-scan update)
+  if (original.includes(BADGE_MARKER)) {
+    const updated = original.replace(/^.*tdd-audit-badge.*$/m, badge.trimEnd());
+    fs.writeFileSync(readmePath, updated);
+    return;
+  }
+
+  // Insert after the first h1 line, or prepend if no h1 exists
+  const lines = original.split('\n');
+  const h1Idx = lines.findIndex(l => /^#\s/.test(l));
+
+  let updated;
+  if (h1Idx !== -1) {
+    lines.splice(h1Idx + 1, 0, badge.trimEnd());
+    updated = lines.join('\n');
+  } else {
+    updated = badge.trimEnd() + '\n' + original;
+  }
+
+  fs.writeFileSync(readmePath, updated);
+}
+
+module.exports = { badgeLine, injectBadge, BADGE_MARKER };

package/lib/jobs.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+
+// ─── Job store (singleton, in-memory) ────────────────────────────────────────
+
+const MAX_JOBS   = 1_000;
+const JOB_TTL_MS = 60 * 60 * 1_000; // 1 hour
+
+const jobs   = new Map();
+let   jobSeq = 0;
+
+// EventEmitter used to push job updates to SSE subscribers
+const _emitter = new EventEmitter();
+_emitter.setMaxListeners(500);
+
+function evictJobs() {
+  const cutoff = Date.now() - JOB_TTL_MS;
+  for (const [id, job] of jobs) {
+    if (new Date(job.createdAt).getTime() < cutoff) jobs.delete(id);
+  }
+  while (jobs.size >= MAX_JOBS) {
+    jobs.delete(jobs.keys().next().value);
+  }
+}
+
+function createJob() {
+  evictJobs();
+  const id = `job_${++jobSeq}_${Date.now()}`;
+  jobs.set(id, { id, status: 'pending', createdAt: new Date().toISOString() });
+  return id;
+}
+
+function updateJob(id, patch) {
+  const job = jobs.get(id);
+  if (!job) return;
+  const updated = { ...job, ...patch };
+  jobs.set(id, updated);
+  _emitter.emit(id, updated);
+}
+
+/**
+ * Subscribe to live updates for a job.
+ * @param {string}   id  - job id
+ * @param {Function} fn  - called with the updated job object on every change
+ * @returns {Function}   - call to unsubscribe
+ */
+function subscribe(id, fn) {
+  _emitter.on(id, fn);
+  return () => _emitter.off(id, fn);
+}
+
+module.exports = { jobs, createJob, updateJob, subscribe, evictJobs, MAX_JOBS, JOB_TTL_MS };