Health Gating Enforcement for Context-Aware Ratchet

[mojoatomic]

Overview

Implement health gating enforcement based on the context-aware ratchet telemetry that was introduced in issue #198. This builds on the successful telemetry burn-in phase to add actual enforcement.

Background

The context-aware ratchet now provides:

• Composite Code Health score (0-100)
• Intent classification (refactor/suspect/neutral)
• Weighted violation analysis
• Violation density metrics

Currently running as non-blocking telemetry for burn-in. Need to add enforcement mechanisms.

Implementation Tasks

Core Health Gating

• Add configurable health score thresholds in .ai-coding-guide.json
• Implement health score enforcement in ratchet script
• Add bypass mechanisms for emergency fixes
• Configure different thresholds for different change types (refactor vs normal)

CI Integration

• Remove continue-on-error from context-aware telemetry job
• Add health gating as required branch protection rule
• Configure appropriate failure modes and messaging

Configuration Schema

• Extend .ai-coding-guide.json with health gating config:
  • Minimum health scores by intent type
  • Bypass keywords/patterns
  • Enforcement modes (strict/lenient/disabled)
  • Threshold adjustments for file types

Documentation

• Update CONTEXT-AWARE-LINTING.md with gating details
• Add troubleshooting guide for health gate failures
• Document bypass procedures for urgent fixes
• Add calibration guidance for teams

Testing & Validation

• Test enforcement with various code changes
• Validate bypass mechanisms work correctly
• Ensure emergency override procedures
• Add tests for health gating logic

Success Criteria

• Health gating prevents merging of code that degrades quality metrics significantly
• Emergency bypass mechanisms work when needed
• Clear feedback helps developers understand and fix issues
• Configuration is flexible enough for different project needs

Dependencies

• Successful telemetry burn-in from issue Ratchet 2.0: context-aware code health, critical vs minor policy, weighted/density metrics, heuristics (Phase 2 next) #198
• Stable context-aware ratchet implementation
• Team agreement on enforcement thresholds

Related Issues

• Ratchet 2.0: context-aware code health, critical vs minor policy, weighted/density metrics, heuristics (Phase 2 next) #198 - Context-aware ratchet telemetry (predecessor)
• Health gating builds on the telemetry foundation established there

[mojoatomic]

Minimal config proposal for health gating (to add in .ai-coding-guide.json)

{
  "ratchet": {
    "mode": "context-aware",
    "health": {
      "enabled": false,                 // set true after burn-in
      "gateOn": "overall",            // overall | structural | semantic | maintainability | style
      "minOverall": 70,                  // default floor when gating is enabled
      "intentOverrides": {               // optional relaxations per intent
        "refactoring": { "minOverall": 65 }
      },
      "bypass": {                        // controlled escape hatches
        "label": "health-bypass",        // PR label to allow one-off bypass
        "commitToken": "[health-bypass]", // token allowed in a single commit message
        "maxBypassPerPR": 1
      },
      "failureMessage": "Code health decreased below threshold. See telemetry output (intent, density, weighted, health)."
    },
    "weights": {                         // existing weights used by telemetry
      "complexity": 10,
      "architecture": 8,
      "domainTerms": 2,
      "magicNumbers": 1
    },
    "critical": ["complexity", "architecture"],
    "minor": ["domainTerms", "magicNumbers"]
  }
}

Notes

• Keep health.enabled: false during burn-in. After a few PRs, flip to true and adjust minOverall based on observed telemetry.
• intentOverrides allows a slightly lower floor for refactoring PRs if needed.
• bypass provides a controlled escape hatch for urgent fixes (label or single commit token).

Acceptance for this issue (#203)

• Schema accepted and documented in CONTEXT-AWARE-LINTING.md
• Ratchet script enforces health gate when enabled: true
• CI marks the context job as required (post burn-in)
• Clear failure message points to telemetry details
• Bypass honored and limited per PR

[mojoatomic]

Opened PR #208 (health gating foundations): config-aware health telemetry + optional gate, docs added. Default remains disabled; prints health scores for calibration. Follow-up: add tests for computeHealth and gate/bypass flows.

[mojoatomic]

Status update (2025-11-11)

Merged:

• feat(health): config-aware health gating (telemetry + optional gate) #208 feat(health): config-aware health gating (telemetry + optional gate)
• feat: CI-safe init scripts + ratchet DX (examples, unlock hint) #212 ratchet DX: clearer failure messages (benefits health gate UX)
• feat: permissive-start + progressive ratchet scaffolding #211 permissive-start + CI-safe scripts (enables safe adoption; orthogonal but related)

Delivered so far:

• Configurable health thresholds via .ai-coding-guide.json (minOverall, gateOn, intentOverrides) ✓
• Enforcement in ratchet when health.enabled=true ✓
• Bypass mechanisms (env HEALTH_BYPASS, commit token) ✓
• Docs: HEALTH-GATING.md + link from CONTEXT-AWARE-LINTING.md ✓
• Failure messaging improved ✓

Pending to complete acceptance in #203:

• CI integration: make the context/health job required; remove continue-on-error
• Tests: unit for computeHealth, integration for gate pass/fail and bypass
• Schema: optional threshold adjustments by file type (if still desired)
• Bypass policy: enforce max bypass per PR (if we keep it in schema)
• Documentation: troubleshooting guide and calibration guidance (expand docs)

Proposed next steps:

1. Add tests for computeHealth and gating/bypass flows
2. Update workflow + branch protection to gate on health when enabled
3. Either implement per-file-type thresholds or drop from acceptance
4. Expand docs with troubleshooting and calibration guidance

Question: keep #203 to track all of the above, or split tests/CI/docs into follow-ups? Once CI wiring and tests land, we can close this.

[mojoatomic]

Opened #213 to enable health gating in CI (no continue-on-error; normal exit codes). Pending: require ratchet-and-tests as a protected branch check for main. If you prefer, I can also add Node 20.x test as required.

[mojoatomic]

Configured branch protection on main to require ratchet-and-tests (strict). This makes the health-gate job enforceable once health.enabled=true. PR #213 remains to be merged to remove continue-on-error in the workflow (already done in that branch).

[mojoatomic]

Branch protection updated: now requires ratchet-and-tests AND Test on Node.js 20.x. Once #213 merges and we flip health.enabled=true, health gating will block merges alongside Node 20 tests.