configure-budget

name	configure-budget
description	Use this skill when the user wants to install, change, or inspect the claude-code-complexity-guard config (`.cogcomp.yml`); pick a preset (off/advisory/default/strict); override CCS/HSI thresholds; or stop the hook from blocking certain metrics. Triggers on "configure complexity guard", "change preset to strict", "stop blocking on HSI", "set up cogcomp", "make complexity guard advisory only".

Configure Budget

.cogcomp.yml is read by the PostToolUse hook from the closest ancestor of the file being edited. Place it at your repo root unless you have a reason for finer-grained scoping.

Quick options

Pick a preset and write the file. The four presets are:

Preset	CCS per_function	CCS new_function	CCS block	HSI threshold	HSI block
off	—	—	—	—	—
advisory	30	20	false	0.01	false
default	30	20	true	0.01	true
strict	20	15	true	0.005	true

V1 release default: advisory (warning-only). When you're ready to have the hook block AI edits on threshold breach, switch to default. For a tighter SonarSource-consensus enforcement, switch to strict.

Minimum config (V1 release default — warning only)

preset: advisory

This matches what configure-budget writes for first-time users — the hook surfaces violations but does not block edits. Suitable while you're tuning thresholds against your codebase or before the V1 latency gates close.

Minimum blocking config

When you want the hook to actually fail AI edits on threshold breach:

preset: default

Use default once you've validated that the latency and accuracy are acceptable on your codebase (typically after running advisory for a few sessions). For tighter SonarSource-consensus thresholds, use preset: strict.

Override examples

Loosen CCS for legacy files:

preset: default
overrides:
  ccs:
    per_function: 50

Make CCS advisory but keep HSI blocking:

preset: default
overrides:
  ccs:
    block: false

Disable HSI entirely (you don't care about helper sprawl):

preset: default
overrides:
  hsi:
    enabled: false

Schema reference

preset: <off | advisory | default | strict>     # required
overrides:                                        # optional
  ccs:
    enabled: <bool>          # default: per preset
    per_function: <int>      # default: per preset
    new_function: <int>      # default: per preset
    block: <bool>            # default: per preset
  hsi:
    enabled: <bool>
    threshold: <number>
    block: <bool>

Strict-schema notes

• Unknown top-level keys are rejected (e.g. refactor_mode_until — that field is reserved for Phase 2.5 / DR).
• Unknown keys under overrides are rejected (e.g. overrides.dr — also Phase 2.5).
• block: "false" (string) is rejected; use block: false (YAML boolean).
• per_function: "30" (string) is rejected; use per_function: 30.
• The off preset name is parsed as a string even though YAML 1.1 would normally collapse it to false — the loader is configured to preserve it as a string token.

Workflow

1. Decide preset.
2. Write .cogcomp.yml at your repo root with at minimum preset: <name>.
3. Trigger any edit on a supported file (.rs, .py).
4. Observe whether the hook blocks or warns.
5. Add overrides if needed.

If the parser rejects your file, the hook exits 2 with the parser's error message on stderr. Fix the file and retry.