Docs: health gating troubleshooting + calibration guide (#203 follow-up)

[mojoatomic]

Goal
Document how to enable, calibrate, and troubleshoot health gating so teams can safely adopt it.

Tasks

• Expand HEALTH-GATING.md
  • Troubleshooting: common failures, how to read failure messages, how to unblock
  • Calibration: choosing gateOn, setting minOverall, when to flip health.enabled
  • Failure message anatomy with examples (ratchet DX from feat: CI-safe init scripts + ratchet DX (examples, unlock hint) #212)
  • Bypass policy: env and commit token, recommended guardrails
• Link from CONTEXT-AWARE-LINTING.md and README
• Provide example .ai-coding-guide.json snippets (burn-in vs enforced)

Acceptance Criteria

• Clear step-by-step “Enable health gating” section
• Troubleshooting + calibration sections added with examples
• Cross-links in README/CONTEXT-AWARE-LINTING.md

References

• Health Gating Enforcement for Context-Aware Ratchet #203 Health gating enforcement
• feat: CI-safe init scripts + ratchet DX (examples, unlock hint) #212 Ratchet DX improvements (messages)
• feat(health): config-aware health gating (telemetry + optional gate) #208 Foundations

[mojoatomic]

Status: Opened PR #218 to implement init --ci and add a reusable workflow.

Included in PR:

• Generator: init --ci creates .github/workflows/ci-ratchet.yml (ratchet-and-tests job) if missing
• Reusable workflow: .github/workflows/ratchet-reusable.yml with workflow_call
• Keeps existing package.json scripts injection

Docs impact (to include here when we write #215):

• Two ways to enable: (A) run npx eslint-plugin-ai-code-snifftest init --ci or (B) reference the reusable workflow via:

  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 ratchet-and-tests (and optionally your test job)
• Health gating is controlled via .ai-coding-guide.json → ratchet.health (enabled=false by default)

After #218 merges, we can bake these instructions into HEALTH-GATING.md and README in a single pass.

[mojoatomic]

Opened PR #219 to document health gating enablement (init --ci, reusable workflow), branch protection, and calibration steps. Once merged, #215 can be closed.

[mojoatomic]

Docs merged via #219. Health gating enablement, branch protection, and calibration are documented. Proceeding to close this issue.