@lhi/tdd-audit 1.14.0 → 1.16.0

package/README.md

@@ -1,7 +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.14.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
 

package/index.js

@@ -12,7 +12,7 @@ const {
   printFindings,
 } = require('./lib/scanner');
 const { toJson, toSarif, toText } = require('./lib/reporter');
-const { writeInitConfig } = require('./lib/config');
+const { writeInitConfig, loadConfig, parseCliOverrides } = require('./lib/config');
 const { badgeLine, injectBadge } = require('./lib/badge');
 
 const args = process.argv.slice(2);
@@ -35,6 +35,7 @@ const outputFormat = args.includes('--json') ? 'json'
 const agentBaseDir = isLocal ? process.cwd() : os.homedir();
 const agentDirName = isClaude ? '.claude' : '.agents';
 const projectDir = process.cwd();
+const config = loadConfig(projectDir, parseCliOverrides(args));
 
 const targetSkillDir = path.join(agentBaseDir, agentDirName, 'skills', 'tdd-remediation');
 const targetWorkflowDir = isClaude
@@ -88,7 +89,7 @@ if (scanOnly) {
     process.stdout.write('\n');
     printFindings(findings, exempted);
   }
-  injectBadge(projectDir, badgeLine(findings));
+  injectBadge(projectDir, badgeLine(findings, config.tdd_site));
   process.exit(0);
 }
 
@@ -245,7 +246,7 @@ if (!skipScan) {
   const findings = quickScan(projectDir);
   process.stdout.write('\n');
   printFindings(findings);
-  const badge = badgeLine(findings);
+  const badge = badgeLine(findings, config.tdd_site);
   injectBadge(projectDir, badge);
   console.log('✅ README badge updated');
 }

package/lib/badge.js

@@ -17,10 +17,16 @@ const NPM_URL = 'https://www.npmjs.com/package/@lhi/tdd-audit';
  *
  * 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
+ * The badge links to `siteUrl` when provided (set via `tdd_site` in
+ * .tdd-audit.json). When absent — including all skill-mode invocations where
+ * no config file exists — the link falls back to the @lhi/tdd-audit npm page
+ * so readers always know where the security tooling came from.
+ *
+ * @param {Array}  findings  - findings array returned by quickScan()
+ * @param {string} [siteUrl] - optional override link (from config.tdd_site)
+ * @returns {string}         - single-line markdown badge ending with \n
  */
-function badgeLine(findings) {
+function badgeLine(findings, siteUrl) {
   // 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;
@@ -38,10 +44,11 @@ function badgeLine(findings) {
     color   = 'brightgreen';
   }
 
-  const badgeUrl = `https://img.shields.io/badge/tdd--audit-${message}-${color}`;
+  const badgeUrl  = `https://img.shields.io/badge/tdd--audit-${message}-${color}`;
+  const targetUrl = (siteUrl && siteUrl.trim()) ? siteUrl.trim() : NPM_URL;
   // 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`;
+  return `[![tdd-audit](${badgeUrl})](${targetUrl}) <!-- ${BADGE_MARKER} -->\n`;
 }
 
 /**

package/lib/config.js

@@ -17,6 +17,7 @@ const DEFAULTS = {
   apiKeyEnv:         null,      // env var name to read the key from
   serverApiKey:      null,      // key required on REST API calls
   trustProxy:        false,     // trust X-Forwarded-For for rate limiting
+  tdd_site:          null,      // custom URL for the README badge link; falls back to npm page
 };
 
 // Provider-specific defaults for `tdd-audit init --provider <name>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lhi/tdd-audit",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Security skill installer for Claude Code, Gemini CLI, Cursor, Codex, and OpenCode. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol.",
   "main": "index.js",
   "bin": {

package/prompts/auto-audit.md

@@ -400,6 +400,115 @@ After all vulnerabilities are addressed, output a final **Remediation Summary**:
 
 ---
 
+## Phase 4: Coverage Gate (≥ 95%)
+
+After all vulnerabilities are patched and the hardening checklist is complete, measure test coverage and drive it to **≥ 95% line and branch coverage**.
+
+```bash
+# Node.js / Jest
+npx jest --coverage --coverageReporters=text
+
+# Python
+pytest --cov=. --cov-report=term-missing
+
+# Go
+go test ./... -coverprofile=coverage.out && go tool cover -func=coverage.out
+```
+
+1. Run the coverage report.
+2. Identify every uncovered line or branch.
+3. For each gap: write a test (Red — must fail without the code path), confirm it passes (Green), re-run coverage.
+4. Repeat until the overall line **and** branch coverage both reach ≥ 95%.
+5. If a file is intentionally excluded (e.g., generated code, migration stubs), add it to the coverage exclusion config and note the reason.
+
+Do **not** write empty or trivially-true tests to inflate numbers. Every test must assert real behavior.
+
+---
+
+## Phase 5: Badge README
+
+Once coverage is ≥ 95%, add a coverage badge to `README.md`.
+
+- If `README.md` does not exist, create a minimal one with the project name and badge.
+- The badge must appear at the **top of the file**, before any other content.
+- Use a static Shields.io badge that reflects the actual measured value:
+
+```markdown
+![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
+```
+
+**Colour tiers:**
+
+| Coverage | Colour |
+|---|---|
+| ≥ 90% | `brightgreen` |
+| 75–89% | `yellow` |
+| < 75% | `red` |
+
+Adjust the percentage in the badge URL to match the real number (e.g., `97%25` for 97%).
+
+---
+
+## Phase 6: SECURITY.md
+
+Check whether a `SECURITY.md` exists at the repo root.
+
+- **If it exists** — do not overwrite it. Read it and confirm it has a vulnerability reporting contact. If missing, append one.
+- **If it does not exist** — create it following the GitHub Security Advisory format:
+
+```markdown
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---|---|
+| latest | ✅ |
+| < latest | ❌ |
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Report vulnerabilities privately via:
+- **GitHub**: Use [GitHub's private vulnerability reporting](../../security/advisories/new)
+- **Email**: security@example.com *(replace with project contact)*
+
+Expect acknowledgement within **48 hours** and a patch or mitigation plan within **14 days** for verified HIGH/CRITICAL issues. Reporters are credited in release notes unless anonymity is requested.
+
+## Security Hardening
+
+This repository is maintained with the following controls:
+
+- HTTP security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options)
+- Rate limiting on all state-mutating and authentication routes
+- Dependencies audited on every CI run (`npm audit --audit-level=high`)
+- No secrets committed to git history (verified with gitleaks / trufflehog)
+- ≥ 95% test coverage enforced via CI coverage gate
+- Vulnerabilities remediated using a Red-Green-Refactor exploit-test protocol
+```
+
+Replace placeholder email and version table with the project's real information.
+
+---
+
+## Final Report
+
+After Phases 4–6 complete, append to the Remediation Summary:
+
+```
+## Coverage & Documentation
+
+| Item | Status | Detail |
+|---|---|---|
+| Line coverage   | ✅ | 96.4% |
+| Branch coverage | ✅ | 95.1% |
+| README badge    | ✅ | Updated to 96% (brightgreen) |
+| SECURITY.md     | ✅ | Created at repo root |
+```
+
+---
+
 ## Agentic AI Security (ASI01–ASI10)
 
 When the project contains AI agent code, MCP configurations, CLAUDE.md files, or tool-calling patterns, also scan for agentic-specific vulnerabilities. These can be harder to spot than traditional web vulns but carry severe consequences (data exfiltration via tool abuse, agent hijacking, supply chain via MCP).

package/prompts/hardening-phase.md

@@ -321,6 +321,94 @@ If this project contains AI agent code, MCP configurations, or CLAUDE.md files,
 
 ---
 
+## 4l. Coverage Gate (≥ 95%)
+
+After hardening is complete, measure test coverage and drive it to **≥ 95% line and branch coverage** before closing the audit.
+
+```bash
+# Node.js / Jest
+npx jest --coverage --coverageReporters=text
+
+# Python
+pytest --cov=. --cov-report=term-missing
+
+# Go
+go test ./... -coverprofile=coverage.out && go tool cover -func=coverage.out
+```
+
+1. Run the coverage report and note every uncovered line or branch.
+2. For each gap: write a failing test (Red), make it pass (Green), re-run coverage.
+3. Repeat until line **and** branch coverage both reach ≥ 95%.
+4. Files that are intentionally excluded (generated code, migration stubs) must be listed in the coverage config with a reason.
+
+Do **not** write trivially-true tests to inflate numbers — every test must assert real behavior.
+
+---
+
+## 4m. Badge README
+
+Once coverage is ≥ 95%, add (or update) a coverage badge in `README.md`. If no `README.md` exists, create a minimal one.
+
+The badge must appear at the **top of the file**, before any other content:
+
+```markdown
+![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
+```
+
+**Colour tiers:**
+
+| Coverage | Colour |
+|---|---|
+| ≥ 90% | `brightgreen` |
+| 75–89% | `yellow` |
+| < 75% | `red` |
+
+Adjust the percentage to match the actual measured value (e.g., `97%25` for 97%). Do not overwrite other existing badges — add the coverage badge as the first badge on the line.
+
+---
+
+## 4n. SECURITY.md
+
+Check whether a `SECURITY.md` exists at the repo root. **Do not overwrite an existing file.**
+
+If absent, create one following the GitHub Security Advisory format:
+
+```markdown
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---|---|
+| latest | ✅ |
+| < latest | ❌ |
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Report privately via:
+- **GitHub**: Use [GitHub's private vulnerability reporting](../../security/advisories/new)
+- **Email**: security@example.com *(replace with project contact)*
+
+Expect acknowledgement within **48 hours** and a patch or mitigation plan within **14 days** for verified HIGH/CRITICAL issues. Reporters are credited in release notes unless anonymity is requested.
+
+## Security Hardening
+
+This repository is maintained with the following controls:
+
+- HTTP security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options)
+- Rate limiting on all state-mutating and authentication routes
+- Dependencies audited on every CI run (`npm audit --audit-level=high`)
+- No secrets committed to git history (verified with gitleaks / trufflehog)
+- ≥ 95% test coverage enforced via CI coverage gate
+- Vulnerabilities remediated using a Red-Green-Refactor exploit-test protocol
+```
+
+Replace placeholder email and version table with the project's real information.
+
+---
+
 ## 4k. Hardening Verification Checklist
 
 After Phase 4, confirm all of the following:
@@ -341,3 +429,6 @@ After Phase 4, confirm all of the following:
 - [ ] `CLAUDE.md` in version control and reviewed; no user-supplied content
 - [ ] MCP servers pinned to exact versions or local installs
 - [ ] Agent tool permissions scoped to minimum required
+- [ ] Test coverage ≥ 95% line and branch (4l)
+- [ ] `README.md` has a coverage badge at the top reflecting the actual % (4m)
+- [ ] `SECURITY.md` exists at repo root with a private vulnerability reporting contact (4n)