---
name: codacy-guardrails-enforcer
description: Install, configure, audit, and troubleshoot Codacy Guardrails while keeping local scans, repository rules, Codacy Cloud, MCP, and CI gates consistent. Use for Guardrails setup, rule drift, Windows or WSL limits, MCP startup failures, and safe AI-assisted remediation.
---

# Codacy Guardrails Enforcer

Use Guardrails as an early local feedback layer, never as a replacement for repository tests or CI.

## Required sequence

1. Guardrails catches local issues during editing or agent generation.
2. Native lint, compile, tests, coverage, and security checks verify the working tree.
3. GitHub Actions or repository CI remains the merge authority.
4. Codacy Cloud provides centralized findings and policy.
5. An agent interprets and repairs findings within explicit approval boundaries.

## Workflow

### 1. Check support

Verify current Codacy documentation and record OS, WSL status, IDE version, Git, Node.js, `npx`, curl, repository language, supported scanners, Codacy connection, and any organization policy blocking MCP.

Do not claim support for an IDE, OS, language, or scanner not listed in current documentation.

### 2. Choose authentication

- Without an account token, use the documented recommended local rules where available.
- With an account token, expect Guardrails to retrieve connected repository rules.
- Keep `CODACY_ACCOUNT_TOKEN` outside repository files.
- Pin `CODACY_CLI_VERSION` where supported.
- Do not place tokens in shared IDE configuration.

### 3. Configure MCP

The current documented server uses `@codacy/codacy-mcp`.

Before adding it:

1. review the package and version;
2. choose direct local MCP or the read-only `meyer-mcp` broker;
3. separate reads from ignore, reanalysis, repository, and rule writes;
4. verify IDE discovery and startup;
5. run one read-only call;
6. confirm no token appears in logs.

Global installation is only a fallback when desktop clients cannot resolve `npx` through NVM. Record absolute Node and package paths.

### 4. Configure rules

Prefer version-controlled scanner configuration when supported and when local, CI, and Cloud behavior should match. Current examples include ESLint files, PMD rulesets, Pylint configuration, `.semgrep.yaml`, and Dart `analysis_options.yaml`.

Use Codacy UI or coding standards for centralized policy when the plan and governance model justify it.

After rule changes:

- identify the canonical source;
- compare local and Cloud configuration;
- refresh local configuration using the current documented procedure;
- run the smallest relevant scan;
- request reanalysis only with approval;
- record historical-finding behavior.

### 5. Remediate safely

For each finding, capture tool, rule, severity, location, and evidence; reproduce locally; classify validity or probable false positive; fix safely; run native tests and the scanner; and never ignore automatically. Suppressions require owner, reason, scope, and expiry.

## Troubleshooting

Read [references/troubleshooting.md](references/troubleshooting.md). Check Node and `npx` paths, IDE agent mode, Copilot MCP policy, package and CLI versions, WSL, proxy access, token environment, local configuration freshness, generated agent instructions, scanner support, and Cloud/repository rule drift.

## Report format

Return:

1. environment and limitations;
2. authentication and MCP mode;
3. canonical rule source and drift result;
4. scanner and finding results;
5. fixes, suppressions proposed, and approvals required;
6. CI verification;
7. unresolved platform, plan, proxy, IDE, or Windows constraints.