Merge pull request #219 from mojoatomic/docs/health-gating-215

docs: health gating enablement and calibration (#215)

Author: mojoatomic

README.md

@@ -33,7 +33,7 @@ Running `init` creates:
 
 ### CI-safe setup (recommended)
 
-Add scripts to your package.json:
+Add scripts to your package.json (init will add these automatically):
 
 ```json
 {
@@ -47,15 +47,28 @@ Add scripts to your package.json:
 }
 ```
 
-GitHub Actions example:
+GitHub Actions options:
 
+A) Scaffold with the CLI
+```bash
+npx eslint-plugin-ai-code-snifftest init --ci
+```
+
+B) Reusable workflow
 ```yaml
-- name: Lint (non-blocking)
-  run: npm run lint:ci
-- name: Ratchet (blocks on regression)
-  run: npm run ci:ratchet
+name: ci-ratchet
+on: [push, pull_request]
+jobs:
+  ratchet-and-tests:
+    uses: mojoatomic/eslint-plugin-ai-code-snifftest/.github/workflows/ratchet-reusable.yml@main
+    with:
+      node-version: '20'
 ```
 
+Branch protection
+- Require status check: ratchet-and-tests
+- Optional: also require your primary test job (e.g., Test on Node.js 20.x)
+
 ### Requirements
 - Node.js 18+
 - ESLint 9+

docs/CONTEXT-AWARE-LINTING.md

@@ -30,9 +30,9 @@ Configuration (optional)
   }
 
 Promoting telemetry to a required PR check
-1) Burn‑in: keep telemetry job non‑blocking for a few PRs; review reported signals and health deltas in CI.
-2) Branch protection: mark the telemetry job (ratchet-context) as “required” in repository settings; optionally remove continue-on-error.
-3) (Optional) Health gating: after calibration, enable policy to block when overall health decreases. This can be added as a future enhancement (tracked in issue) and controlled via config (e.g., ratchet.health.gate with minDelta).
+- Prefer enabling health gating (see HEALTH-GATING.md) via the `ratchet-and-tests` job.
+- Burn‑in: keep `health.enabled=false`, review telemetry; then flip to true and require the job in branch protection.
+- Use `init --ci` or the reusable workflow to wire CI quickly.
 
 Notes
 - Support scripts under scripts/**/*.js are excluded from complexity/architecture and plugin-complexity rules, keeping product metrics accurate.

docs/HEALTH-GATING.md

@@ -17,16 +17,16 @@ Configuration (.ai-coding-guide.json)
 {
   "ratchet": {
     "health": {
-      "enabled": false,                 
-      "gateOn": "overall",            
-      "minOverall": 70,                
-      "intentOverrides": {             
+      "enabled": false,
+      "gateOn": "overall",
+      "minOverall": 70,
+      "intentOverrides": {
         "refactoring": { "minOverall": 65 }
       },
-      "bypass": {                       
-        "label": "health-bypass",     
+      "bypass": {
+        "label": "health-bypass",
         "commitToken": "[health-bypass]",
-        "maxBypassPerPR": 1            
+        "maxBypassPerPR": 1
       },
       "failureMessage": "Code health decreased below threshold. See telemetry output (intent, density, health)."
     }
@@ -38,14 +38,43 @@ Notes
 - intent detection: CLI accepts --refactoring or --intent=refactoring (best-effort; extend later).
 - bypass: commit messages containing the commitToken or env HEALTH_BYPASS=true will bypass; label reserved for future CI integration.
 
-CI recommendation
-- Keep the context-aware step non-blocking during burn-in; monitor health scores in PRs.
-- Once calibrated, flip health.enabled to true and remove continue-on-error; mark the job required in branch protection.
+## Enable in CI
+
+Option A: Scaffold workflow with the CLI
+```bash
+npx eslint-plugin-ai-code-snifftest init --ci
+```
+This creates `.github/workflows/ci-ratchet.yml` with a `ratchet-and-tests` job.
+
+Option B: Reusable workflow (no files needed)
+```yaml
+name: ci-ratchet
+on: [push, pull_request]
+jobs:
+  ratchet-and-tests:
+    uses: mojoatomic/eslint-plugin-ai-code-snifftest/.github/workflows/ratchet-reusable.yml@main
+    with:
+      node-version: '20'
+```
+
+Branch protection (GitHub → Settings → Branches → main)
+- Require status checks: `ratchet-and-tests`
+- Optional: also require your test matrix job (e.g., `Test on Node.js 20.x`)
+
+## Calibration (burn‑in → enforce)
+1) Burn‑in: keep `health.enabled=false` and watch the reported scores in PRs.
+2) Choose thresholds: set `gateOn` and `minOverall` based on observed ranges.
+3) Flip the switch: set `health.enabled=true` to enforce. The CI job will fail if score < threshold.
 
 Troubleshooting
 - No lines.executable in analysis: health falls back to physical lines; check analyzer wiring.
 - Unexpected gate failures: confirm thresholds, gateOn, and any intent override are set as intended; use a one-time bypass with the commit token for urgent fixes.
 
+Failure message anatomy
+- HEALTH-GATE FAIL: <message>
+- gateOn, threshold, actual, intent printed for quick diagnosis
+- Example suggestions printed by the ratchet script for common rules
+
 ## Health Score Calculation
 
 ### Formula
@@ -69,12 +98,12 @@ overall:    3   // Balanced (all categories)
 // Good code
 executableLOC = 5000
 violations.structural = 10
-// density = 10 / 5 = 2.0; score (structural) = 100 - (2.0 * 5) = 90 ✅
+// density = 10 / 5 = 2.0; score (structural) = 90 ✅
 
 // Poor code
 executableLOC = 5000
 violations.structural = 50
-// density = 50 / 5 = 10.0; score (structural) = 100 - (10.0 * 5) = 50 ❌
+// density = 50 / 5 = 10.0; score (structural) = 50 ❌
 
 // Refactoring intent (relaxed overall)
 executableLOC = 5000