Ag Auditar Harness

ag-auditar-harness — Auditor do harness

> Equivalente local ao AgentShield do ECC, focado nos pontos fracos especificos > do sistema rAIz: drift de skills, hooks bloqueantes sem bypass documentado, > redundancia semantica entre skills, machines sem score, MCPs com baixo ROI.

Quando invocar

• Trimestral via ag-curador-skills
• Sob demanda: /ag-auditar-harness
• Como dimensao HARNESS de /ag-9-auditar --include-harness
• Apos qualquer adicao de >3 skills novas (gate manual)

Output

Relatorio em ~/Claude/docs/diagnosticos/harness-audit-YYYY-MM-DD.md com:

• HCS total (0-100) — media ponderada dos 5 sub-scores
• Sub-scores (cada um 0-100) — drift, injection, redundancy, dodviolation, mcpcost
• Findings P0/P1/P2 — path + linha + fix sugerido
• Quick wins (se --apply-quick-wins) — PR atomico com fixes triviais

HCS — formula

HCS = (
  HCS_drift      * 0.25 +
  HCS_injection  * 0.30 +    # peso maior — security first
  HCS_redundancy * 0.15 +
  HCS_dod        * 0.20 +
  HCS_mcp_cost   * 0.10
)

Convergencia: HCS >= 80 = passa. HCS 0.85 (candidatos a merge).

Metodo:

1. Embedding de cada description + primeiro paragrafo
2. Pairwise cosine
3. Para cada par > 0.85: P2 finding "considere merge ou delineacao mais clara"

Score: 100 - 5 * paresacimathreshold, floor 0.

Fallback sem embedding: Jaccard de tokens normalizados (stem + stopwords PT/EN).

4. HCS.dod_violation — Machines sem Definition of Done aplicada

Detecta em ~/Claude/.claude/skills/ag-N-*/SKILL.md:

• Machine sem metadata.scoring no frontmatter
• Machine sem score numerico mencionado no corpo (>= NN)
• Machine sem referencia a rule de DoD (quality-gate.md, fix-verification.md, etc.)
• Machine sem hook completion-gate.py mencionado (verificar via grep em corpo)
• Machine que cria PR mas sem checklist (- [ ] Typecheck, etc.)

Score: 100 - 10 * violacoespormachine, mean across ag-1..ag-13.

5. HCS.mcp_cost — MCPs com baixo ROI

Detecta em ~/.claude/plugins/installed_plugins.json:

| Sinal | Penalidade | |---|---| | Plugin instalado ha >30 dias sem invocacao registrada | -10 | | Plugin com >50 tools expostas (drain de context) | -15 | | Plugins duplicados (mesma capacidade) — ex: 2 playwrights | -20 | | Plugin com scope=project mas projeto nao-existe mais | -10 |

Cross-check: ~/.claude/projects/*/session-*.jsonl busca mcp____* tool calls.

Score: 100 - sum(penalidades), floor 0.

Implementacao

Agent({
  subagent_type: "general-purpose",
  model: "opus",
  description: "Audit local harness",
  prompt: """
Voce e o ag-auditar-harness. Execute as 5 sub-auditorias abaixo.

Paths:
  Skills: ~/Claude/.claude/skills/
  Hooks:  ~/Claude/.claude/hooks/
  Rules:  ~/Claude/.claude/rules/
  Plugins: ~/.claude/plugins/installed_plugins.json
  Sessoes: ~/.claude/projects/*/session-*.jsonl

Para cada sub-auditor:
  1. Execute o metodo descrito
  2. Calcule sub-score 0-100
  3. Liste top 5 findings P0/P1/P2

Depois:
  - HCS total = ponderada conforme formula
  - Escreva relatorio em docs/diagnosticos/harness-audit-YYYY-MM-DD.md
  - Se --apply-quick-wins: aplica fixes P2 triviais (typo em description, etc.)
    em PR atomico chamado chore: harness audit quick wins YYYY-MM-DD

Args recebidos: $ARGUMENTS
"""
})

Quick wins eligibility

Aplicaveis automaticamente com --apply-quick-wins:

• Typo em description do frontmatter
• Skill sem metadata.priority (default 50)
• Hook sem bypass env var documentado em comentario
• MCP duplicado: desinstala o mais antigo

NUNCA aplicar automaticamente:

• Merge de skills (decisao humana)
• Mudar model: de skill (custo)
• Remover hook bloqueante (security risk)
• Alterar score formula

Rule referenciada

Esta skill implementa o que ~/Claude/.claude/rules/harness-coverage.md exige.

Estado persistido

~/Claude/.claude/state/harness-audit-history.jsonl — uma linha por execucao:

{"date":"2026-05-18","hcs":82,"sub":{"drift":85,"injection":90,"redundancy":75,"dod":80,"mcp":85},"findings_p0":0,"findings_p1":3,"findings_p2":12}

Permite tracking de tendencia (ag-insights consome este arquivo).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andregusman-raiz
• Source: andregusman-raiz/a-gusman-claude
• License: MIT

Install and usage instructions live in the source repository linked above.