Habilidades e ganchos do CodeMender para o Antigravity

1. Introdução

Neste codelab, você vai configurar um agente de programação de IA (Antigravity) para que a segurança faça parte do ciclo de desenvolvimento normal, em vez de ser uma etapa de revisão separada. Você vai instalar um conjunto de habilidades de agente que orientam o agente em um ciclo de Planejar → Vermelho → Verde → Refatorar e um hook PreToolUse que intercepta git push, verifica os arquivos alterados com o CodeMender e entrega as descobertas ao agente com instruções para corrigi-las priorizando os testes.

As habilidades e o hook vêm do Secure TDD Agent Framework de código aberto. Você vai instalar as ferramentas no mesmo espaço de trabalho do ~/codemender-lab que criou em Noções básicas da CLI do CodeMender.

Dica: no momento, o CodeMender está disponível para um grupo limitado de clientes no Acesso antecipado. Entre em contato com sua equipe de vendas para ter acesso.

O que você vai aprender

• Como o Antigravity descobre regras, habilidades e hooks do espaço de trabalho em .agents/.
• O que as seis habilidades do TDD seguro fazem e qual fase do loop cada uma delas possui.
• Como um hook PreToolUse recebe a chamada de ferramenta do agente em stdin e retorna uma decisão de permissão/negação.
• Como o hook do portão de segurança (security_gate_hook.sh) executa o cm find, classifica as descobertas por gravidade, rastreia as tentativas de correção e encaminha com o cm verify.
• Como verificar todo o pipeline de hook off-line com scanners simulados antes de apontá-lo para o cm real.

Pré-requisitos

• Conclusão do curso Noções básicas da CLI do CodeMender. Este laboratório continua no diretório ~/codemender-lab e reutiliza sample_app/, CONTEXT.md, o histórico do Git e ~/.codemender/config.yaml.
• Antigravity instalado, com a capacidade de abrir uma pasta local como um espaço de trabalho.
• git, jq e bash instalados. Os scripts de hook são bash simples e são executados no bash 3.2 padrão do macOS, bem como em versões mais recentes.
• O ambiente virtual do Python de Noções básicas da CLI do CodeMender (~/codemender-lab/.venv) com o Flask instalado.
• Conhecimento básico de scripting de shell.

2. Configuração do Workspace

Etapa 1: voltar ao diretório do laboratório

Todos os comandos neste laboratório são executados em ~/codemender-lab com o ambiente virtual ativo:

cd ~/codemender-lab && source .venv/bin/activate

Confirme se o espaço de trabalho do laboratório anterior está intacto e se a árvore de trabalho está limpa:

ls sample_app/data_service.py CONTEXT.md .gitignore
git status --short

git status --short não deve mostrar nada. Se ele listar arquivos, faça o commit deles antes de continuar.

Etapa 2: nomeie a ramificação main

O portão de segurança compara sua árvore de trabalho com origin/main para decidir quais arquivos verificar. Se essa referência não existir, ela vai usar HEAD~1, que abrange apenas o commit mais recente. Verifique se o nome da ramificação é main:

git branch -M main

Etapa 3: adicionar um ponto de entrada do pacote de testes

O loop de TDD seguro pede que o agente execute python3 -m unittest discover -s tests após cada correção. Por isso, o espaço de trabalho precisa de um diretório tests/. Comece com um teste de caracterização para que o pacote tenha algo real para executar:

mkdir -p tests && touch tests/__init__.py
cat << 'EOF' > tests/test_data_service.py
import unittest

from sample_app.data_service import hash_password


class HashPasswordTests(unittest.TestCase):
    def test_returns_hex_digest(self):
        digest = hash_password("hunter2")
        self.assertIsInstance(digest, str)
        int(digest, 16)  # raises ValueError if not hexadecimal


if __name__ == "__main__":
    unittest.main()
EOF
python3 -m unittest discover -s tests

Você vai ver Ran 1 test e OK.

Observação: esse teste documenta o que o código faz hoje, não o que ele deveria fazer. O hash_password ainda usa MD5, e um ciclo posterior de TDD seguro pode substituí-lo. Como o teste só afirma que o resultado é uma string hexadecimal, ele continua sendo aprovado quando isso acontece. O README do framework chama isso de teste de caracterização e o recomenda como a primeira etapa antes de tocar no código legado.

Etapa 4: estender .gitignore e confirmar

Adicione os arquivos de ambiente de execução produzidos por este laboratório a .gitignore e confirme o valor de referência:

printf '.security-gate/\nusers.db\n*.bak\n' >> .gitignore
git add -A && git commit -m "Add test suite entry point for Secure TDD"

3. Como instalar os arquivos do framework

As habilidades, a regra, o hook e o arcabouço de testes off-line ficam em um único diretório .agents/. Em vez de digitar cerca de 800 linhas de bash manualmente, clone o framework e copie esse diretório para seu espaço de trabalho:

git clone --depth 1 https://github.com/h3xar0n/secure-tdd-agent-framework.git /tmp/secure-tdd
cp -R /tmp/secure-tdd/.agents ./.agents
rm -rf /tmp/secure-tdd

Confirme o layout:

find .agents -type f | sort

.agents/hooks.json
.agents/lib/README.md
.agents/lib/engine_codemender.sh
.agents/lib/engine_semgrep.sh
.agents/lib/gate_common.sh
.agents/rules/secure_tdd_workflow.md
.agents/security_gate_hook.sh
.agents/skills/defensive-developer/SKILL.md
.agents/skills/history-context-seeder/SKILL.md
.agents/skills/local-refactor-scanner/SKILL.md
.agents/skills/security-test-writer/SKILL.md
.agents/skills/skill-evolution-updater/SKILL.md
.agents/skills/threat-model-assessor/SKILL.md
.agents/tests/mocks/cm
.agents/tests/mocks/semgrep
.agents/tests/run_tests.sh

Verifique se o ponto de entrada do hook é executável:

chmod +x .agents/security_gate_hook.sh
ls -l .agents/security_gate_hook.sh

Observação: o Antigravity descobre as personalizações do espaço de trabalho ao percorrer o diretório .agents/ na raiz da pasta aberta: rules/*.md para instruções sempre ativas ou condicionais, skills//SKILL.md para procedimentos sob demanda e hooks.json para hooks de ciclo de vida. Não é necessário registrar mais nada. Se o Antigravity já estiver aberto nessa pasta, feche e reabra depois de copiar os arquivos para que ele use o hooks.json.

O restante deste laboratório mostra o que você acabou de instalar, uma parte de cada vez.

4. Regra de fluxo de trabalho sempre ativa

As habilidades são carregadas sob demanda, quando o agente decide que a descrição de uma habilidade corresponde à tarefa. Algo precisa dizer ao agente para alcançá-los na ordem certa. Esse é o trabalho do .agents/rules/secure_tdd_workflow.md. O frontmatter define trigger: always_on, então a regra é injetada em cada turno:

---
trigger: always_on
---

# Test-Driven Development with Integrated Security (Secure TDD) Workflow Rule

You MUST strictly follow this 4-phase cyclical workflow for all feature implementations, refactors, and bug fixes:

1. **Phase A (Plan, Scope & Threat Model)**:
   - Ingest `CONTEXT.md` to review established project conventions, approved helpers, and trust zones.
   - Decompose feature requirements, user stories, and acceptance criteria.
   - Invoke the **Threat Model Assessor Skill** to perform a STRIDE evaluation and generate/update `threat_model.md`.

2. **Phase B (Functional & Security Test-First - RED)**:
   - Invoke the **Security Test Writer Skill**.
   - Author unit and integration tests asserting functional behavior (happy paths, business logic), edge cases, AND security boundaries (rejecting invalid inputs, unauthenticated requests, unauthorized role access).
   - Execute the tests and confirm they FAIL for the expected assertion reason (RED).

3. **Phase C (Feature Implementation & Defensive Code - GREEN)**:
   - Invoke the **Defensive Developer Skill**.
   - Author clean, modular production code strictly required to satisfy the functional tests and security assertions.
   - Apply input validation allow-lists, parameterized queries, and least-privilege payload returns.
   - Run the tests to confirm they are GREEN.

4. **Phase D (Refactor, Quality & Scan)**:
   - Invoke the **Local Refactor & Scanner Skill**.
   - Clean up code, eliminate duplication, and verify 100% passing test regressions.
   - Run fast deterministic checks (secrets, dependencies, local SAST).
   - Conduct a guided AI review to verify architectural boundaries and eliminate logic bypasses.
   - Ensure diffs remain small, surgical, and preserve baseline stability.

5. **Continuous Evolution**:
   - If a new pattern, helper function, or architectural convention was introduced, invoke the **Skill Evolution Updater Skill** to document the lesson into `CONTEXT.md` or the appropriate `SKILL.md`.

6. **Multi-Finding Remediation Protocol**:
   - When resolving multiple findings from a scan or security gate rejection, iterate sequentially one finding at a time:
     1. Author one discrete boundary test for the finding (RED).
     2. Implement the minimal defensive fix (GREEN).
     3. Verify local tests pass before moving to the next finding.
   - Avoid applying multi-finding changes in a single unverified edit. Run the full regression test suite only after all individual findings have passed their discrete TDD cycle.

A regra faz referência a CONTEXT.md, que você criou em Noções básicas da CLI do CodeMender. O mesmo arquivo que direcionou o cm fix para sua convenção de consulta parametrizada agora direciona o planejamento do agente. O item 6 é o mais importante para este laboratório: é o que o agente segue quando o portão de segurança rejeita um push com várias descobertas de uma só vez.

Dica: as regras aceitam outros acionadores além de always_on: model_decision (o agente lê um description e decide se carrega a regra), glob (ativa quando arquivos correspondentes estão abertos) e manual (somente quando você o menciona com @). always_on custa tokens em cada turno. Por isso, mantenha as regras curtas e coloque os detalhes nas habilidades.

5. As seis habilidades do agente

Cada habilidade é um diretório que contém um SKILL.md com frontmatter YAML. Dois campos são obrigatórios:

• name: um identificador em letras minúsculas e com hifens.
• description: o que a habilidade faz e quando usá-la. O agente lê apenas esse campo ao decidir se deve carregar a habilidade completa. Por isso, cada descrição abaixo também diz o que a habilidade não faz.

Habilidade	Fase	Finalidade
threat-model-assessor	A: Plano	Defina o escopo do recurso, execute o STRIDE e escreva threat_model.md.
security-test-writer	B: Vermelho	Escrever testes funcionais e de limite que falham pelo motivo certo.
defensive-developer	C: Verde	Escreva o mínimo de código que torne os testes verdes, usando padrões seguros.
local-refactor-scanner	D: Refatorar	Limpar, executar o pacote completo, executar scanners locais, revisar a diferença.
skill-evolution-updater	Contínuo	Registre novas convenções nos arquivos CONTEXT.md e SKILL.md.
history-context-seeder	Integração	Minere o histórico do Git para propagar CONTEXT.md em um repositório atual.

O conteúdo completo segue abaixo para que você possa ver como o frontmatter e as instruções se encaixam.

1. threat-model-assessor (Fase A)

.agents/skills/threat-model-assessor/SKILL.md:

---
name: threat-model-assessor
description: Plans feature architecture, functional requirements, and evaluates STRIDE security boundaries in Phase A Plan. Use when scoping new features or bug fixes, defining user stories and acceptance criteria, identifying trust boundaries, and generating or updating threat_model.md. Do not use for writing test assertions, implementing production code, or running local scanners.
---

# Planning, Requirements & Threat Model Assessor Skill (Phase A: Plan Phase)

## Overview
Decompose feature requirements, establish functional acceptance criteria, and map trust boundaries before any production code is authored. This skill pairs functional engineering scoping with STRIDE threat modeling at the planning stage, establishing the functional and security acceptance criteria consumed by downstream test writers.

## System Sequence
1. **Ingest Context**: Read `CONTEXT.md` to identify existing architecture, trust boundaries, approved libraries, and conventions.
2. **Decompose Requirements**:
   - Define user stories, input/output data contracts, and functional acceptance criteria.
   - Break complex tasks into bite-sized, testable implementation stages.
3. **Apply STRIDE Threat Modeling**:
   - **Spoofing**: Authentication boundaries, session validation, caller identity checks.
   - **Tampering**: Input payload validation, integrity checks, parameter tampering.
   - **Repudiation**: Audit logging of critical state transitions.
   - **Information Disclosure**: Restrict error responses, prevent stack trace leaks, mask PII/secrets.
   - **Denial of Service**: Resource limits, payload size constraints, timeout limits.
   - **Elevation of Privilege**: Role-Based Access Control (RBAC), caller authorization checks.
4. **Generate/Update `threat_model.md`**:
   - Store or update `threat_model.md` at the workspace root with both Functional & Security Acceptance Criteria.

## Target Output Artifact (`threat_model.md`)
```markdown
# Feature Plan & Threat Model: [Feature Name]

## 1. Functional Scope & Requirements
- **Goal**: [Description of feature or bug fix]
- **Deliverables**: [Endpoints, functions, or modules to create/modify]
- **Functional Acceptance Criteria**: [Expected behaviors and outputs]

## 2. Entry Points & Data Inputs
- Endpoint / Input: [Path / Name]
- Format & Constraints: [Schema / Type]

## 3. Trust Boundaries & Access Controls
- Authentication: [Required / Public]
- Authorization Role: [User / Admin]

## 4. STRIDE Threat Matrix & Security Acceptance Criteria
- [STRIDE Category]: [Threat Description] -> [Required Mitigation & Test Assertion]
```

2. security-test-writer (fase B)

.agents/skills/security-test-writer/SKILL.md:

---
name: security-test-writer
description: Authors test-first unit and integration tests covering functional behavior, edge cases, and security boundaries in Phase B RED. Use when creating failing automated tests before writing production code, asserting HTTP status codes and contract responses, establishing boundary limits, or asserting that exploit payloads are rejected cleanly. Do not use for threat modeling during initial planning, writing production feature code, or running refactor sweeps.
---

# QA & Security Test Writer Skill (Phase B: RED Phase)

## Overview
Translate functional requirements and security criteria from `threat_model.md` and `CONTEXT.md` into executable test cases that fail initially (RED), asserting expected business logic, edge-case handling, and security boundaries before production code is authored.

## Three Verification Pillars
1. **Behavior-Driven Outcomes**:
   - Assert strictly on API/HTTP outcomes (status codes 200/302 for valid requests, 400/401/403 for invalid/unauthorized, expected JSON responses) rather than mocking internal private methods.
2. **Strict Test Isolation**:
   - Ensure test setup and teardown cleanly isolate state (e.g., transaction rollbacks, fresh test contexts) so state never bleeds between test runs.
3. **Integration Over Fragile Mocking**:
   - Utilize local test databases or real server contexts rather than fragile fake mocks to verify realistic functional and security behavior.

## Execution Sequence
1. **Consume Requirements & Threat Model**: Read the task scope, `threat_model.md`, and `CONTEXT.md` for functional requirements and security acceptance criteria.
2. **Author Test Cases**:
   - **Functional Happy Path**: Test validating standard user workflows and expected output payloads.
   - **Functional Edge Cases**: Test missing optional/required parameters, boundary limits, and unexpected data types.
   - **Authentication Boundary**: Assert requests without valid credentials return `401 Unauthorized`.
   - **Authorization Boundary**: Assert requests with insufficient role/scope return `403 Forbidden`.
   - **Input Validation**: Assert malformed, oversized, or un-whitelisted data returns `400 Bad Request`.
   - **Exploit Payloads**: Assert dangerous inputs (SQLi, path traversal `../../`, XSS) are rejected cleanly.
3. **Execute & Verify RED**:
   - Run the project's test command (e.g., `pytest`, `python3 -m unittest discover -s tests`).
   - **Requirement**: Confirm the tests fail due to the expected missing feature logic/boundary assertion and not due to a syntax or import error.
4. **Multi-Finding Handling**:
   - When remediating multiple scanner findings, write and verify one boundary test for one finding at a time before proceeding to defensive implementation.

3. defensive-developer (fase C)

.agents/skills/defensive-developer/SKILL.md:

---
name: defensive-developer
description: Implements clean, maintainable production code to deliver features and satisfy functional and security test assertions in Phase C GREEN. Use when writing minimal, modular production code to turn failing RED tests GREEN, applying input validation allow-lists, enforcing explicit caller authorization, and using parameterized sinks and least-privilege payloads. Do not use for authoring initial tests, performing initial threat modeling, or running post-implementation security scans.
---

# Feature Implementation & Defensive Developer Skill (Phase C: GREEN Phase)

## Overview
Implement clean, modular production code that delivers the requested feature or bug fix and satisfies all functional, edge-case, and security assertions from Phase B while adhering to defensive design principles and project conventions in `CONTEXT.md`.

## Three Defensive Pillars
1. **Simple Input Validation**:
   - Enforce type, size, and strict allow-list validation on all incoming data.
   - Prefer structured parsing libraries (`pydantic`, `urllib.parse`) over complex regex which may be vulnerable to ReDoS.
2. **Explicit Authorization**:
   - Validate caller identity and match required permissions before invoking business logic.
3. **Least Privilege & Safe Operations**:
   - Parameterize all SQL/database queries.
   - Use canonical path checks (`os.path.realpath`) with prefix boundary validation.
   - Return only the minimal data payload required by the client.
   - Mask credentials, PII, and omit internal stack traces in error messages.

## Execution Sequence
1. **Inspect Failing Tests & Rules**: Review the functional requirements, failing tests from Phase B, and conventions in `CONTEXT.md`.
2. **Author Clean Production Code**:
   - Implement the business logic and algorithms required to satisfy the functional feature requirements.
   - Apply defensive patterns (e.g. `utils.security.resolve_safe_path`, parameterized SQL statements, `pydantic` schemas).
3. **Confirm GREEN State**:
   - Run the project test suite.
   - Verify that all functional and security tests pass cleanly without errors.
4. **Multi-Finding Handling**:
   - When remediating multiple scanner findings, apply the minimal fix for the current failing boundary test, confirm GREEN, then proceed to the next finding's test-fix cycle.

Observação: a habilidade menciona utils.security.resolve_safe_path como um exemplo de assistente. Esse módulo é fornecido com o app de exemplo do framework, não com o sample_app/data_service.py do módulo Noções básicas da CLI do CodeMender. O agente vai usar os padrões no seu CONTEXT.md (por exemplo, os.path.realpath mais uma verificação de prefixo). Se você quiser usar auxiliares compartilhados, adicione-os ao projeto e liste-os na seção 2 de CONTEXT.md.

4. local-refactor-scanner (Fase D)

.agents/skills/local-refactor-scanner/SKILL.md:

---
name: local-refactor-scanner
description: Refactors code for quality and maintainability, executes full test suite regression passes, and runs local deterministic security and lint scans in Phase D REFACTOR. Use when cleaning up code structure and eliminating duplication after tests pass, running local linters and fast offline scanners for secrets or dependencies, executing full regression test suites, and performing guided code reviews. Do not use for implementing initial feature logic, writing failing test-first suites, or modifying architectural threat models.
---

# Code Refactoring, Quality & Local Scanner Skill (Phase D: REFACTOR Phase)

## Overview
Refactor implementation for clean code structure, modularity, and maintainability while ensuring 100% passing test regressions and blocking pattern-based security flaws locally prior to commit.

## Verification Guardrails
1. **Code Quality & Refactoring**:
   - Clean up boilerplate, eliminate dead code, and centralize common utilities.
   - Improve variable naming, modularity, and type annotations without altering verified behavior.
2. **Deterministic Scans (Fast & Offline)**:
   - **Secrets**: Check diffs for plaintext credentials, tokens, or private keys.
   - **Dependencies**: Flag unpinned dependencies or known CVEs in new packages.
   - **Rules-Based SAST**: Run local SAST rules on modified files (`semgrep scan --config auto --json` or `cm find`).
3. **Guided AI Review**:
   - Audit architecture and design issues that static tools miss.
   - Review business logic and edge cases for bypasses or regression risks.
4. **Small Diffs & Regression QA**:
   - Run the complete project test suite to verify zero regressions across existing and new tests.
   - Ensure the diff contains only surgical changes directly related to the task scope.

## Execution Sequence
1. Review the git diff of modified files (`git diff`).
2. Refactor code for clarity, maintainability, and helper reuse.
3. Run local linters and security scanners on changed files.
4. Run the full test suite to guarantee 100% passing tests.
5. **Continuous Evolution**: Capture new conventions in `CONTEXT.md` and suggest/apply updates to `SKILL.md` instructions via `skill-evolution-updater` to permanently prevent recurrence of issues.

5. skill-evolution-updater (evolução contínua)

.agents/skills/skill-evolution-updater/SKILL.md:

---
name: skill-evolution-updater
description: Extracts systemic conventions from resolved bugs, patterns, and refactors to update CONTEXT.md and agent skills for continuous evolution. Use when capturing durable coding rules, architectural conventions, or recurring fix patterns into CONTEXT.md after a task or bug fix, updating skill instructions to prevent recurrence of errors, and logging gate findings to findings-log.ndjson. Do not use for writing feature code, authoring unit tests, or running pre-push scanner pipelines.
---

# Skill & Conventions Evolution Updater (Continuous Evolution)

## Overview
Ensure the development team and agent fleet continuously learn from local fixes, architecture decisions, and refactoring patterns so that systemic quality and security standards are retained permanently.

## Continuous Feedback Mechanism
```
+-----------------------------------------------------------------+
|                    CONTINUOUS FEEDBACK LOOP                     |
|                                                                 |
|   1. Local Fix / Feature Verified (Refactor Phase)              |
|                               v                                 |
|   2. Systemic Lesson Extracted (Best practices & conventions)   |
|                               v                                 |
|   3. Feed Back to Shared Specs (Update SKILL.md/CONTEXT.md)     |
|                               v                                 |
|   4. Context Seeding (All future agents inherit rules upfront)  |
+-----------------------------------------------------------------+
```

## Execution Sequence
1. **Analyze Remediation Diff**: Review the code change or bug fix just completed.
2. **Extract the Systemic Rule**:
   - Formulate an actionable, project-specific rule.
   - Example: *"When implementing redirects, always use `utils.security.safe_redirect()` with allow-listed domains."*
   - Example: *"All JSON endpoints must validate request body using Pydantic schemas."*
3. **Update Shared Specifications**:
   - **Update `CONTEXT.md`**: Append the rule under `## 4. Continuous Evolution: Auto-Evolved Conventions`.
   - **Update Skills (if applicable)**: If a general coding anti-pattern or QA procedure was refined, update the relevant `SKILL.md`.
4. **Persist Insight**: Append the raw structured event to `.security-gate/findings-log.ndjson` for audit traceability.

Aviso: essa habilidade permite que o agente edite as próprias instruções. Isso é conveniente para um desenvolvedor independente que trabalha em um sandbox como este laboratório. Em um ambiente de equipe, o README do framework recomenda que os agentes proponham mudanças de habilidades (como uma solicitação de envio ou um tíquete) em vez de aplicá-las diretamente a um registro de habilidades compartilhado.

6. history-context-seeder (Integração)

.agents/skills/history-context-seeder/SKILL.md:

---
name: history-context-seeder
description: Analyzes repository Git history for past bug fixes, architectural conventions, and security patterns to seed CONTEXT.md on onboarding. Use when first adopting the framework in an existing repository, mining historical commits and bug fixes for recurring risk areas, or populating the initial CONTEXT.md baseline with established conventions and helpers. Do not use for routine feature development, authoring test suites, or running the inner TDD loop on active tasks.
---

# History & Architectural Context Seeder Skill (Repository Onboarding)

## Overview
Analyzes the repository's Git history and past fix commits to extract recurring bug patterns, architectural conventions, and security patterns, seeding `CONTEXT.md` during initial repository onboarding.

## Execution Sequence
1. **Analyze Git Log**:
   - Inspect commits touching bug fixes, refactors, and sensitive modules:
     `git log --grep="fix\|bug\|refactor\|vuln\|security\|patch" -n 50 --oneline`
2. **Extract Historical Lessons**:
   - Identify which files and modules have historically been prone to bugs or regressions.
   - Extract past patterns and architectural conventions established by maintainers.
3. **Seed `CONTEXT.md`**:
   - Populate `CONTEXT.md` with known architectural risk areas, sensitive directories, approved helpers, and custom project conventions.

Você não vai usar essa habilidade nos laboratórios porque o CONTEXT.md já existe, mas ela é útil quando você leva o framework para um repositório que tem anos de histórico e nenhuma convenção escrita.

6. Como configurar o hook do Antigravity

.agents/hooks.json instrui o Antigravity a executar o portão de segurança antes de qualquer comando de terminal que o agente execute:

{
  "security-gate": {
    "PreToolUse": [
      {
        "matcher": "run_command|.*:run_command|run_shell_command|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [ -x ./security_gate_hook.sh ]; then exec ./security_gate_hook.sh; else exec ./.agents/security_gate_hook.sh; fi'",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Alguns detalhes sobre esse arquivo explicam o design do script que ele inicia:

• matcher é uma regex sobre nomes de ferramentas, não texto de comando. PreToolUse é acionado antes da execução de uma ferramenta, e o matcher decide quais ferramentas. run_command é a ferramenta de terminal do Antigravity. As outras alternativas abrangem variantes com namespace de plug-in e outras plataformas de agente que compartilham esses arquivos. Um matcher como git push* nunca seria acionado porque nenhuma ferramenta tem esse nome. A filtragem no comando real acontece dentro do script.
• O hook recebe a chamada de ferramenta em stdin. O Antigravity canaliza um payload JSON, como {"toolCall": {"name": "run_command", "args": {"CommandLine": "git push origin main"}}, ...}. O script lê .toolCall.args.CommandLine e sai imediatamente com uma decisão de permissão para tudo que não seja um git push.
• O diretório de trabalho é o diretório que contém hooks.json, então o hook começa dentro de .agents/. O wrapper bash -c 'if [ -x ./security_gate_hook.sh ] ...' lida com esse caso e com o lançamento a partir da raiz do repositório. Em seguida, o script faz cd para git rev-parse --show-toplevel antes de realizar qualquer trabalho.
• O script responde em stdout com JSON. {"decision": "allow"} permite que o comando original seja executado. {"decision": "deny", "reason": "..."} bloqueia a mensagem e mostra o motivo ao agente. O framework também emite um booleano allow_tool para compatibilidade com contratos de hook mais antigos.
• Os hooks são executados de forma síncrona e bloqueiam o loop do agente até que sejam concluídos ou atinjam timeout (em segundos; o padrão é 30 se omitido).

Aviso: 120 segundos é um tempo muito curto para uma execução real do CodeMender. No laboratório Noções básicas da CLI do CodeMender, o comando cm find em um único arquivo levou cerca de um minuto, e o comando cm verify levou cerca de três. O portão executa cm find uma vez por arquivo alterado e, após falhas repetidas, executa cm verify. Aumente o tempo limite antes de conectar o hook ao cm real.

O formato -i.bak funciona com GNU e BSD (macOS) sed:

sed -i.bak 's/"timeout": 120/"timeout": 900/' .agents/hooks.json && rm .agents/hooks.json.bak

Dica: o hook só intercepta os pushes que o agente faz pela ferramenta de terminal. Executar o git push em um shell ignora totalmente o hook, o que é útil quando você precisa enviar os arquivos de hook pela primeira vez. Para um portão que também abrange pushes humanos, instale o mesmo script como um gancho pre-push do git.

7. Como funciona o gancho do portão de segurança

security_gate_hook.sh é um ponto de entrada simples que usa três módulos de .agents/lib/:

Módulo	Papel
gate_common.sh	Padrões de configuração, saída allow/deny, classificação de gravidade, registro de auditoria NDJSON, contagem de tentativas, auxiliares de commit e CONTEXT.md.
engine_semgrep.sh	Etapa 1. Verificação determinista opcional com o Semgrep. Ignorado se semgrep não estiver em PATH.
engine_codemender.sh	Etapa 2. Verificação semântica com cm find, classificação, rastreamento de tentativas e escalonamento de cm verify.

Etapa 1: decidir se é um push

O ponto de entrada extrai o comando do payload stdin e o testa em relação a uma regex que reconhece git push em suas formas comuns (git -C /repo push, cd x && git push, sudo git push) enquanto ignora o texto entre aspas, como git commit -m "before git push". Tudo o que não for um push é permitido imediatamente:

CMD_TO_CHECK=$(printf '%s\n' "$STDIN_INPUT" | jq -r '
  .toolCall?.args?.CommandLine? //
  .toolCall?.args?.command? //
  .tool_input?.command? //
  .CommandLine? //
  .command? //
  empty
')
...
if ! is_git_push_command "$CMD_TO_CHECK"; then
  allow
fi

Etapa 2: escolher os verificadores

SECURITY_GATE_SCANNER seleciona o pipeline. O padrão, auto, executa o Semgrep e o CodeMender que estiverem instalados, nessa ordem:

case "$SCANNER" in
  codemender|cm) run_codemender_gate false ;;
  semgrep)       run_semgrep_gate false ;;
  auto|pipeline|"")
    command -v semgrep >/dev/null && run_semgrep_gate true
    command -v cm      >/dev/null && run_codemender_gate true
    allow ;;
esac

Quando o Estágio 1 encontra problemas de bloqueio no modo de pipeline, ele não os nega por conta própria. Ele os grava em um arquivo temporário que o Estágio 2 coleta, para que o CodeMender tenha a palavra final.

Etapa 3: estágio do CodeMender

run_codemender_gate em engine_codemender.sh faz o seguinte, em ordem:

1. Encontrar arquivos alterados com git diff --name-only origin/main (revertendo para HEAD~1). Nenhuma mudança significa que o acesso é permitido.
2. Verifique cada arquivo com cm find "$file" -y --bypass-warning e, em seguida, extraia tudo com cm report --format json. Se cm report falhar ou retornar um JSON inválido, isso será um erro de verificação, não um resultado limpo.
3. Filtre as descobertas com o status OPEN ou REOPENED e em que o file_path termina com um dos arquivos alterados. As descobertas que você já corrigiu ou dispensou no módulo Noções básicas da CLI do CodeMender são ignoradas.
4. Classifique cada descoberta. A gravidade em SECURITY_GATE_BLOCK_SEVERITY ou acima (padrão HIGH) é de bloqueio. Qualquer valor menor é de aviso, registrado e impresso, mas não interrompe o push.
5. Permitir se nada bloquear. Se uma descoberta que bloqueou um push anterior não estiver mais presente, o portão a registrará como FIXED, anexará uma convenção a CONTEXT.md em ## 4. Continuous Evolution e confirmará essa mudança.
6. Contar as tentativas por descoberta de bloqueio lendo o próprio registro de auditoria. Cada negação é uma tentativa. Nas tentativas de 1 a SECURITY_GATE_MAX_RETRIES (padrão 3), o portão registra DENIED_TO_AGENT e adiciona a descoberta a uma mensagem de rejeição.
7. Escalar depois que o orçamento for gasto. Na quarta tentativa para a mesma descoberta, o portão executa cm verify. Se a descoberta não for explorável (código de saída 1 ou status DISMISSED), ela será rebaixada para aviso. Se for confirmado ou se o cm verify falhar, o gate vai registrar BLOCKED e negar com um pedido de revisão humana.
8. Negar com instruções. Se alguma descoberta ainda for relevante, o portão vai retornar este motivo ao agente:

Security Gate blocked push (1 unresolved finding(s)).

Action Required: Execute the Secure TDD Loop sequentially for each finding:
For each finding below (one at a time):
  1. Invoke 'security-test-writer' to author one failing boundary test in tests/ (assert RED).
  2. Invoke 'defensive-developer' to apply the minimal defensive fix (assert GREEN).
  3. Run the local test to confirm it passes before moving to the next finding.
Once all findings are resolved, run the full regression test suite (python3 -m unittest discover -s tests) and retry 'git push'.

Open Findings:
- [80bdddd6-...] (CRITICAL) in /home/you/codemender-lab/sample_app/data_service.py (Attempt 1/3): OS Command Injection in ping_host endpoint

Essa é a transição entre o gancho e as habilidades. O hook não chama cm fix. Ele nomeia as habilidades que o agente deve usar, o agente faz a correção de teste primeiro e o próximo git push executa novamente o portão.

Observação: o portão reutiliza o banco de dados global do CodeMender em ~/.codemender/state.db, o mesmo que cm report lê. Como ele filtra por caminho de arquivo e status OPEN, as descobertas antigas em relação a sample_app/data_service.py do módulo "Noções básicas da CLI do CodeMender" que você nunca corrigiu (por exemplo, a injeção de comando do SO em /ping) vão bloquear o primeiro push que tocar nesse arquivo. Isso é intencional: o portão não tem noção de "pré-existente", apenas de "aberto em um arquivo que você está enviando".

Referência de configuração

Todas as configurações são variáveis de ambiente com padrões definidos em gate_common.sh:

Variável	Padrão	Efeito
SECURITY_GATE_SCANNER	auto	auto, codemender (ou cm) ou semgrep.
SECURITY_GATE_BLOCK_SEVERITY	HIGH	Gravidade mais baixa que bloqueia. CRITICAL, HIGH, MEDIUM ou LOW.
SECURITY_GATE_MAX_RETRIES	3	Negações por descoberta antes de cm verify ser consultado.
SECURITY_GATE_ALLOW_ON_ERROR	false	true permite um push quando um scanner não é executado, marcando o commit unverified-scan-.
SECURITY_GATE_TEST_CMD	python3 -m unittest discover -s tests	Comando de teste citado em solicitações de rejeição e mensagens de commit.
SECURITY_GATE_EVOLVE_CONTEXT	true	Anexe as convenções verificadas a CONTEXT.md.
SECURITY_GATE_LOG	.security-gate/findings-log.ndjson	Registro de auditoria somente para anexar.
SECURITY_GATE_NOTIFY_CMD	(vazio)	Comando opcional que recebe cada evento de portão como JSON em stdin.

Dica: os hooks herdam o ambiente do Antigravity, que é difícil de mudar por espaço de trabalho. Para fixar uma configuração, coloque-a na string command em hooks.json, por exemplo, "command": "SECURITY_GATE_SCANNER=codemender bash -c '...'". Forçar o codemender é uma boa opção para este laboratório se você tiver o Semgrep instalado e quiser um único scanner previsível.

8. Como verificar o hook off-line

Antes que o portão toque no cm real, confirme se ele se comporta corretamente com simulações. O framework inclui um arcabouço de testes com binários cm e semgrep falsos que abrangem os caminhos de permissão, aviso, negação, erro e encaminhamento para um supervisor:

bash .agents/tests/run_tests.sh

A execução leva alguns segundos e termina com:

-- test_pipeline_tools_missing_passes_smoothly
-- test_skills_frontmatter_valid
60 passed, 0 failed

O último teste também valida o frontmatter de cada habilidade em .agents/skills/. Portanto, esse é o comando que deve ser executado novamente após a edição de um SKILL.md.

Em seguida, simule o que o Antigravity envia para um comando que não é um push. O script precisa responder allow sem tocar em nenhum scanner:

echo '{"toolCall":{"name":"run_command","args":{"CommandLine":"git status"}}}' \
  | bash .agents/security_gate_hook.sh

{"allow_tool": true, "decision": "allow"}

Agora simule um push sem mudanças locais em origin/main. Como ainda não há um controle remoto, o portão volta para HEAD~1 e verifica os arquivos do último commit. Para manter essa etapa off-line, aponte-a para o cm e o semgrep simulados:

echo '{"toolCall":{"name":"run_command","args":{"CommandLine":"git push origin main"}}}' \
  | PATH="$PWD/.agents/tests/mocks:$PATH" bash .agents/security_gate_hook.sh

Stage 1: Running Deterministic AST Scan (semgrep) on: sample_app/data_service.py ...
Deterministic scan clean. No AST vulnerabilities found.
Stage 2: Running Semantic Analysis & Verification (CodeMender)...
No blocking vulnerabilities detected. Code verified clean.
{"allow_tool": true, "decision": "allow"}

Os dois estágios foram executados porque o diretório simulado contém um semgrep e um cm falsos. As mensagens de progresso vão para stderr, e apenas a decisão JSON vai para stdout, o que permite que o Antigravity analise o resultado.

Aviso: executar o mesmo payload de push sem o prefixo simulado PATH chama os cm find e cm report reais no seu espaço de trabalho. Essa é uma maneira legítima de testar o portão de ponta a ponta em um terminal, mas leva vários minutos e relata todas as descobertas abertas nos arquivos do seu último commit. Guarde-o para o próximo codelab, em que esse comportamento é o foco.

Por fim, confirme os arquivos do framework para que eles sejam enviados com o repositório:

git add -A && git commit -m "Add Secure TDD skills, rule, and security gate hook"

9. Como abrir o espaço de trabalho no Antigravity

Abra ~/codemender-lab como uma pasta no Antigravity. Depois de carregado, o agente tem:

• A regra secure_tdd_workflow em cada turno.
• As seis habilidades disponíveis sob demanda.
• O hook security-gate registrado em run_command.

Uma maneira rápida de confirmar se as habilidades estão visíveis é perguntar ao agente, em uma nova conversa: "Quais habilidades do Workspace você tem disponíveis e o que cada uma faz?" Ele deve listar os seis por nome.

Permissões

O hook em si é iniciado pelo Antigravity, não pelo agente, então ele não passa pelas solicitações de permissão de ferramenta. Os comandos do próprio agente sim. No próximo codelab, você vai receber solicitações de aprovação para o comando de teste, as operações de git e qualquer comando cm que o agente decida executar diretamente. Aprove-as quando solicitado. Se o Antigravity oferecer a opção de lembrar a decisão para um prefixo de comando, aceite para evitar novas solicitações durante o loop.

O que acontece em git push

1. O agente chama a ferramenta de terminal com git push origin main.
2. O Antigravity compara run_command com hooks.json e executa security_gate_hook.sh com a chamada de ferramenta em stdin.
3. O script reconhece um push, encontra arquivos alterados, os verifica com cm find e lê cm report.
4. Se nada bloquear, ele vai mostrar {"decision": "allow"} e o push vai continuar.
5. Se o bloqueio de descobertas, ele vai mostrar {"decision": "deny", "reason": "..."}. O push não é executado, o agente vê o motivo, e a regra sempre ativa, além das habilidades nomeadas, dizem o que fazer em seguida: um teste com falha, uma correção mínima, executar novamente o pacote, fazer o push de novo.

Parabéns! Você concluiu o codelab "Habilidades e hooks do CodeMender para Antigravity". No próximo codelab, você vai dar ao agente uma solicitação de recurso e assistir a esse loop ser executado de ponta a ponta, desde o modelo de ameaças até um push que passa pelo portão.