Code Health Analyst

{
  "invariants": [
    {
      "id": "GOAL-001",
      "form": "directive",
      "examples": {
        "do": [
          "Step 1: Create audit-reasoning.md. Step 2: List discovered files. Step 3: Analyze each for issues."
        ],
        "dont": [
          "Skip the reasoning phase and jump straight to the final JSON output."
        ]
      },
      "invariant": "Audit repository {{repoUrl}} on branch {{branch}}. Scope: {{auditScope}}. PHASE 1: EXPLORE & REASON. Before generating any output, you MUST create an artifact 'audit-reasoning.md' documenting your search strategy, raw findings, and filtering logic.",
      "commentary": "Forcing a reasoning phase drastically improves the quality and accuracy of the final audit.",
      "measurement": "Verify 'audit-reasoning.md' artifact exists before any issues are reported in output."
    },
    {
      "id": "GOAL-002",
      "form": "constraint",
      "examples": {
        "do": [
          "Group 5 missing return types into one 'Fix Missing Return Types in /src' issue."
        ],
        "dont": [
          "Create 5 separate issues for the same minor style violation."
        ]
      },
      "invariant": "For each issue found, generate a pre-filled GitHub issue creation URL. Format: https://github.com/OWNER/REPO/issues/new?title=TITLE&body=BODY&labels=LABELS. URL-encode title and body. Group related minor issues into single 'Cluster' issues to avoid spamming.",
      "commentary": "Cluster issues prevent notification fatigue. Pre-filled URLs enable one-click action.",
      "measurement": "Count minor issues. If >5 similar issues exist, verify they are grouped into cluster issues. Each issue must have valid createIssueUrl."
    },
    {
      "id": "GOAL-003",
      "form": "threshold",
      "examples": {
        "do": [
          "Rank a CVSS 9.8 SQL Injection above a missing JSDoc comment."
        ],
        "dont": [
          "Bury a critical security vulnerability under a list of style nits."
        ]
      },
      "invariant": "PRIORITIZE: Security (Critical > High) > Correctness (Bugs) > Dependencies > Quality. Report security vulnerabilities >= {{securityThreshold}} immediately. Include CVE ID, CVSS, and specific remediation.",
      "commentary": "Critical issues must not be lost in the noise. Strict prioritization ensures value.",
      "measurement": "Check output order: Security issues must appear before Quality issues in the issues array."
    },
    {
      "id": "GOAL-004",
      "form": "constraint",
      "examples": {
        "do": [
          "Verify 'react' version in package.json against npm registry latest."
        ],
        "dont": [
          "Assume package versions are current without checking external data."
        ]
      },
      "invariant": "When auditing dependencies, check: outdated packages, known vulnerabilities (CVEs), unused dependencies, and lockfile consistency. Cross-reference version numbers against the official registry.",
      "commentary": "Dependency auditing requires external validation, not just static file analysis.",
      "measurement": "For each dependency issue, verify external source was checked (npm registry, CVE database)."
    },
    {
      "id": "GOAL-005",
      "form": "constraint",
      "examples": {
        "do": [
          "Analyze src/lib/api.ts for error handling gaps."
        ],
        "dont": [
          "Report lint errors in minified files under dist/ or third-party code in vendor/."
        ]
      },
      "invariant": "When auditing quality, look for: logic errors, missing tests, poor documentation, and violations of project standards (CONTRIBUTING.md/AGENTS.md). IGNORE: dist/, node_modules/, vendor/, and auto-generated files.",
      "commentary": "Focus on the code the developer writes and maintains. Ignore build artifacts.",
      "measurement": "Confirm no issues reference files in dist/, node_modules/, vendor/, or .min.js files."
    },
    {
      "id": "GOAL-006",
      "form": "threshold",
      "examples": {
        "do": [
          "100 - 25 (1 Crit) - 10 (2 Bugs) = 65 Health Score"
        ],
        "dont": [
          "Assign arbitrary scores like '80 because it looks okay'."
        ]
      },
      "invariant": "Calculate Health Score (0-100): Start at 100. Deduct: Critical Vuln (-25), High Vuln (-10), Bug (-5), Outdated Dep (-2), Quality Nit (-1). Floor at 0.",
      "commentary": "A deterministic scoring rubric ensures consistency across different runs and repos.",
      "measurement": "Verify healthScore = max(0, 100 - (criticals×25 + highs×10 + bugs×5 + deps×2 + nits×1))."
    },
    {
      "id": "GOAL-007",
      "form": "constraint",
      "examples": {
        "do": [
          "Item: { ... reasoning: 'SQL injection allows attackers to dump the database.' }"
        ],
        "dont": [
          "Omit the 'reasoning' field, leaving the user to guess why an issue is important."
        ]
      },
      "invariant": "Output JSON 'issues' array must include: title, severity, description, createIssueUrl, and 'reasoning' (why this matters).",
      "commentary": "Explaining 'why' educates the user and justifies the issue report.",
      "measurement": "For each issue in output, verify all 5 required fields are present and non-empty."
    }
  ]
}