Hook & Skill CodeMender untuk Antigravity

1. Pengantar

Dalam codelab ini, Anda akan mengonfigurasi agen coding AI (Antigravity) sehingga keamanan menjadi bagian dari loop pengembangan normalnya, bukan langkah peninjauan terpisah. Anda akan menginstal serangkaian keterampilan agen yang memandu agen melalui siklus Rencana → Merah → Hijau → Refaktorisasi, dan hook PreToolUse yang menangkap git push, memindai file yang diubah dengan CodeMender, dan menyerahkan temuan apa pun kembali ke agen dengan petunjuk untuk memperbaikinya dengan mengutamakan pengujian.

Keterampilan dan hook berasal dari Secure TDD Agent Framework open source. Anda akan menginstalnya ke ruang kerja ~/codemender-lab yang sama dengan yang Anda buat di Dasar-Dasar CodeMender CLI.

Tips: CodeMender saat ini tersedia untuk sejumlah pelanggan tertentu dalam Pratinjau Publik. Hubungi tim penjualan Anda untuk mendapatkan akses.

Yang akan Anda pelajari

• Cara Antigravity menemukan aturan, keahlian, dan hook ruang kerja di bagian .agents/.
• Fungsi enam keterampilan TDD Aman dan fase loop yang dimiliki masing-masing keterampilan.
• Cara hook PreToolUse menerima panggilan alat agen di stdin dan menampilkan keputusan izinkan/tolak.
• Cara hook gerbang keamanan (security_gate_hook.sh) menjalankan cm find, mengklasifikasikan temuan berdasarkan tingkat keparahan, melacak upaya perbaikan, dan mengeskalasi dengan cm verify.
• Cara memverifikasi seluruh pipeline hook secara offline dengan pemindai tiruan sebelum mengarahkannya ke cm yang sebenarnya.

Prasyarat

• Penyelesaian CodeMender CLI Basics. Lab ini berlanjut di direktori ~/codemender-lab dan menggunakan kembali sample_app/, CONTEXT.md, histori git, dan ~/.codemender/config.yaml.
• Antigravity terinstal, dengan kemampuan untuk membuka folder lokal sebagai ruang kerja.
• git, jq, dan bash diinstal. Skrip hook adalah bash biasa dan berjalan di bash 3.2 bawaan macOS serta versi yang lebih baru.
• Lingkungan virtual Python dari Dasar-Dasar CodeMender CLI (~/codemender-lab/.venv) dengan Flask yang sudah terinstal.
• Pengetahuan dasar tentang pembuatan skrip shell.

2. Penyiapan Workspace

Langkah 1: Kembali ke direktori lab

Semua perintah di lab ini dijalankan dari ~/codemender-lab dengan lingkungan virtual yang aktif:

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

Pastikan ruang kerja dari lab sebelumnya masih utuh dan hierarki kerja Anda bersih:

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

git status --short tidak akan mencetak apa pun. Jika ada file yang tercantum, commit file tersebut sebelum melanjutkan.

Langkah 2: Beri nama cabang main

Gerbang keamanan membedakan hierarki kerja Anda dengan origin/main untuk memutuskan file mana yang akan dipindai. Jika ref tersebut tidak ada, tindakan akan kembali ke HEAD~1, yang hanya mencakup commit terbaru. Pastikan cabang Anda bernama main:

git branch -M main

Langkah 3: Tambahkan titik entri suite pengujian

Loop Secure TDD meminta agen untuk menjalankan python3 -m unittest discover -s tests setelah setiap perbaikan, sehingga ruang kerja memerlukan direktori tests/. Mulailah dengan satu pengujian karakterisasi agar suite memiliki sesuatu yang nyata untuk dijalankan:

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

Anda akan melihat Ran 1 test dan OK.

Catatan: Pengujian ini mendokumentasikan fungsi kode saat ini, bukan fungsi yang seharusnya. hash_password masih menggunakan MD5, dan siklus TDD Aman berikutnya mungkin akan menggantikannya. Karena pengujian hanya menyatakan bahwa hasilnya adalah string hex, pengujian akan terus lulus saat hal itu terjadi. README framework menyebutnya sebagai pengujian karakterisasi dan merekomendasikannya sebagai langkah pertama sebelum menyentuh kode lama.

Langkah 4: Perpanjang .gitignore dan lakukan commit

Tambahkan file runtime yang dihasilkan lab ini ke .gitignore, lalu commit baseline:

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

3. Menginstal File Framework

Keterampilan, aturan, hook, dan tes otomatis offline semuanya berada di satu direktori .agents/. Daripada mengetik sekitar 800 baris bash secara manual, clone framework dan salin direktori tersebut ke ruang kerja Anda:

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

Konfirmasi tata letak:

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

Pastikan titik entri hook dapat dieksekusi:

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

Catatan: Antigravity menemukan penyesuaian ruang kerja dengan menelusuri direktori .agents/ di root folder yang terbuka: rules/*.md untuk petunjuk selalu aktif atau bersyarat, skills//SKILL.md untuk prosedur on-demand, dan hooks.json untuk hook siklus proses. Tidak ada hal lain yang perlu didaftarkan. Jika Antigravity sudah terbuka di folder ini, tutup dan buka kembali setelah menyalin file agar Antigravity mengambil hooks.json.

Bagian selanjutnya dari lab ini akan membahas apa yang baru saja Anda instal, satu per satu.

4. Aturan Alur Kerja Selalu Aktif

Keterampilan dimuat sesuai permintaan, saat agen memutuskan bahwa deskripsi keterampilan cocok dengan tugas. Sesuatu harus memberi tahu agen untuk menjangkaunya dalam urutan yang benar. Itulah tugas .agents/rules/secure_tdd_workflow.md. Frontmatter-nya menetapkan trigger: always_on, sehingga aturan dimasukkan ke dalam setiap giliran:

---
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.

Aturan ini merujuk ke CONTEXT.md, yang Anda buat di Dasar-Dasar CodeMender CLI. File yang sama yang mengarahkan cm fix ke konvensi kueri berparameter Anda kini mengarahkan perencanaan agen. Item 6 adalah yang paling penting untuk lab ini: item ini adalah yang diikuti agen saat gerbang keamanan menolak push dengan beberapa temuan sekaligus.

Tips: Aturan mendukung pemicu lain selain always_on: model_decision (agen membaca description dan memutuskan apakah akan memuat aturan), glob (diaktifkan saat file yang cocok terbuka), dan manual (hanya saat Anda @-menyebutnya). always_on menggunakan token di setiap giliran, jadi buat aturan tersebut singkat dan pindahkan detail ke keterampilan.

5. Enam Keahlian Agen

Setiap keterampilan adalah direktori yang berisi SKILL.md dengan frontmatter YAML. Dua kolom wajib diisi:

• name: ID dengan tanda hubung dan huruf kecil.
• description: fungsi keahlian dan kapan harus menggunakannya. Agen hanya membaca kolom ini saat memutuskan apakah akan memuat keahlian lengkap, sehingga setiap deskripsi di bawah juga menyatakan apa yang tidak dapat dilakukan oleh keahlian tersebut.

Badge	Fase	Tujuan
threat-model-assessor	A: Perencanaan	Tentukan cakupan fitur, jalankan STRIDE, tulis threat_model.md.
security-test-writer	B: Merah	Menulis pengujian fungsional dan batas yang gagal karena alasan yang tepat.
defensive-developer	C: Hijau	Tulis kode minimal yang membuat pengujian berhasil, menggunakan pola yang aman.
local-refactor-scanner	D: Melakukan refaktorisasi	Bersihkan, jalankan rangkaian lengkap, jalankan pemindai lokal, tinjau perbedaannya.
skill-evolution-updater	Berkelanjutan	Catat konvensi baru dalam file CONTEXT.md dan SKILL.md.
history-context-seeder	Orientasi	Menambang histori git untuk menyisipkan CONTEXT.md di repositori yang ada.

Konten lengkapnya akan ditampilkan agar Anda dapat melihat bagaimana frontmatter dan petunjuknya saling melengkapi.

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.

Catatan: Skill ini menyebutkan utils.security.resolve_safe_path sebagai contoh helper. Modul tersebut dikirimkan dengan aplikasi contoh framework itu sendiri, bukan dengan sample_app/data_service.py dari CodeMender CLI Basics. Agen akan beralih ke pola di CONTEXT.md Anda (misalnya, os.path.realpath ditambah pemeriksaan awalan). Jika Anda menginginkan helper bersama, tambahkan helper tersebut ke project Anda dan cantumkan di CONTEXT.md bagian 2.

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 (Evolusi Berkelanjutan)

.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.

Peringatan: Keterampilan ini memungkinkan agen mengedit petunjuknya sendiri. Hal ini memudahkan developer perseorangan yang bekerja di sandbox seperti lab ini. Dalam setelan tim, README framework merekomendasikan agar agen mengusulkan perubahan keterampilan (sebagai PR atau tiket), bukan menerapkannya langsung ke registry keterampilan bersama.

6. history-context-seeder (Orientasi)

.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.

Anda tidak akan menggunakan keterampilan ini di lab karena CONTEXT.md sudah ada, tetapi keterampilan ini adalah yang harus digunakan saat Anda membawa framework ke repositori yang memiliki histori bertahun-tahun dan tidak memiliki konvensi tertulis.

6. Mengonfigurasi Hook Antigravity

.agents/hooks.json memberi tahu Antigravity untuk menjalankan gerbang keamanan sebelum perintah terminal apa pun yang dijalankan agen:

{
  "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
          }
        ]
      }
    ]
  }
}

Beberapa detail tentang file ini menjelaskan desain skrip yang diluncurkannya:

• matcher adalah ekspresi reguler untuk nama alat, bukan teks perintah. PreToolUse diaktifkan sebelum alat berjalan, dan matcher memutuskan alat mana yang akan digunakan. run_command adalah alat terminal Antigravity; alternatif lainnya mencakup varian dengan namespace plugin dan platform agen lain yang membagikan file ini. Pencocok seperti git push* tidak akan pernah diaktifkan karena tidak ada alat yang diberi nama tersebut. Pemfilteran pada perintah yang sebenarnya terjadi di dalam skrip.
• Hook menerima panggilan alat di stdin. Antigravity menyalurkan payload JSON seperti {"toolCall": {"name": "run_command", "args": {"CommandLine": "git push origin main"}}, ...}. Skrip membaca .toolCall.args.CommandLine dan langsung keluar dengan keputusan mengizinkan untuk apa pun yang bukan git push.
• Direktori kerja adalah direktori yang berisi hooks.json, sehingga hook dimulai di dalam .agents/. Wrapper bash -c 'if [ -x ./security_gate_hook.sh ] ...' menangani kasus tersebut dan diluncurkan dari root repositori. Skrip kemudian cd ke git rev-parse --show-toplevel sebelum melakukan pekerjaan apa pun.
• Skrip menjawab di stdout dengan JSON. {"decision": "allow"} memungkinkan perintah asli dijalankan. {"decision": "deny", "reason": "..."} akan memblokirnya dan menampilkan alasannya kepada agen. Framework ini juga memunculkan boolean allow_tool untuk kompatibilitas dengan kontrak hook yang lebih lama.
• Hook berjalan secara sinkron dan memblokir loop agen hingga selesai atau mencapai timeout (dalam detik; defaultnya adalah 30 jika dihilangkan).

Peringatan: 120 detik terlalu singkat untuk menjalankan CodeMender yang sebenarnya. Di CodeMender CLI Basics, cm find pada satu file memerlukan waktu sekitar satu menit dan cm verify sekitar tiga menit. Gate menjalankan cm find sekali per file yang diubah, dan setelah kegagalan berulang, gate akan menjalankan cm verify. Tingkatkan waktu tunggu sebelum Anda menghubungkan hook ke cm yang sebenarnya.

Formulir -i.bak berfungsi dengan GNU dan BSD (macOS) sed:

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

Tips: Hook hanya mencegat push yang dilakukan agen melalui alat terminalnya. Menjalankan git push sendiri di shell akan mengabaikannya sepenuhnya, yang berguna saat Anda perlu mengirim file hook untuk pertama kalinya. Untuk gate yang juga mencakup push manusia, instal skrip yang sama sebagai hook pre-push git.

7. Cara Kerja Pengait Gerbang Keamanan

security_gate_hook.sh adalah titik entri tipis yang mengambil tiga modul dari .agents/lib/:

Modul	Peran
gate_common.sh	Default konfigurasi, output allow/deny, peringkat tingkat keparahan, log audit NDJSON, penghitungan upaya, helper commit dan CONTEXT.md.
engine_semgrep.sh	Tahap 1. Pemindaian deterministik opsional dengan Semgrep. Dilewati jika semgrep tidak ada di PATH.
engine_codemender.sh	Tahap 2. Pemindaian semantik dengan cm find, klasifikasi, pelacakan upaya, dan eskalasi cm verify.

Langkah 1: Tentukan apakah ini adalah push

Titik entri mengekstrak perintah dari payload stdin dan mengujinya terhadap ekspresi reguler yang mengenali git push dalam bentuk umumnya (git -C /repo push, cd x && git push, sudo git push) sambil mengabaikan teks yang dikutip seperti git commit -m "before git push". Apa pun yang bukan push akan langsung diizinkan:

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

Langkah 2: Pilih pemindai

SECURITY_GATE_SCANNER memilih pipeline. Defaultnya, auto, menjalankan Semgrep dan CodeMender yang diinstal, dalam urutan tersebut:

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

Saat Tahap 1 menemukan masalah pemblokiran dalam mode pipeline, tahap ini tidak akan menolak dengan sendirinya; tahap ini akan menulisnya ke file sementara yang diambil oleh Tahap 2, sehingga CodeMender yang akan menentukan keputusan akhir.

Langkah 3: Tahap CodeMender

run_codemender_gate di engine_codemender.sh melakukan hal berikut, secara berurutan:

1. Temukan file yang diubah dengan git diff --name-only origin/main (kembali ke HEAD~1). Tidak ada perubahan berarti diizinkan.
2. Pindai setiap file dengan cm find "$file" -y --bypass-warning, lalu tarik semuanya kembali dengan cm report --format json. Jika cm report gagal atau menampilkan JSON yang tidak valid, hal itu merupakan error pemindaian, bukan hasil yang bersih.
3. Filter ke temuan yang statusnya OPEN atau REOPENED dan yang file_path-nya diakhiri dengan salah satu file yang diubah. Temuan yang telah Anda perbaiki atau tutup di CodeMender CLI Basics akan diabaikan.
4. Klasifikasikan setiap temuan. Tingkat keparahan pada atau di atas SECURITY_GATE_BLOCK_SEVERITY (default HIGH) akan memblokir; apa pun yang lebih rendah akan bersifat saran, dicatat dalam log, dan dicetak, tetapi tidak menghentikan push.
5. Izinkan jika tidak ada yang memblokir. Jika temuan yang memblokir push sebelumnya kini hilang, gate akan mencatatnya sebagai FIXED, menambahkan konvensi ke CONTEXT.md di bagian ## 4. Continuous Evolution, dan meng-commit perubahan tersebut.
6. Menghitung upaya per temuan pemblokiran dengan membaca log auditnya sendiri. Setiap penolakan dihitung sebagai satu upaya. Pada upaya 1 hingga SECURITY_GATE_MAX_RETRIES (default 3), gerbang akan mencatat DENIED_TO_AGENT ke dalam log dan menambahkan temuan ke pesan penolakan.
7. Eskalasikan setelah anggaran dibelanjakan. Pada upaya keempat untuk temuan yang sama, gerbang akan menjalankan cm verify. Jika temuan tidak dapat dieksploitasi (kode keluar 1 atau status DISMISSED), temuan tersebut akan diturunkan ke saran. Jika dikonfirmasi, atau cm verify error, gate akan mencatat BLOCKED dan menolak dengan permintaan peninjauan manual.
8. Tolak dengan petunjuk. Jika ada temuan yang masih dapat ditindaklanjuti, gate akan menampilkan alasan ini kepada agen:

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

Ini adalah transisi antara hook dan keterampilan. Hook tidak memanggil cm fix. Agen akan menyebutkan keterampilan yang harus digunakan, melakukan perbaikan test-first, dan git push berikutnya akan menjalankan ulang gate.

Catatan: Gate menggunakan kembali database CodeMender global di ~/.codemender/state.db, yang sama dengan yang dibaca cm report. Karena memfilter berdasarkan jalur file dan status OPEN, temuan lama terhadap sample_app/data_service.py dari CodeMender CLI Basics yang tidak pernah Anda perbaiki (misalnya, injeksi perintah OS di /ping) akan memblokir push pertama yang menyentuh file tersebut. Hal ini memang disengaja: gate tidak memiliki konsep "sudah ada", hanya "terbuka dalam file yang Anda kirim".

Referensi konfigurasi

Semua setelan adalah variabel lingkungan dengan setelan default di gate_common.sh:

Variabel	Default	Efek
SECURITY_GATE_SCANNER	auto	auto, codemender (atau cm), atau semgrep.
SECURITY_GATE_BLOCK_SEVERITY	HIGH	Tingkat keparahan terendah yang memblokir. CRITICAL, HIGH, MEDIUM, atau LOW.
SECURITY_GATE_MAX_RETRIES	3	Penolakan per temuan sebelum cm verify dikonsultasikan.
SECURITY_GATE_ALLOW_ON_ERROR	false	true memungkinkan push dilakukan saat pemindai gagal dijalankan, dengan memberi tag pada commit unverified-scan-.
SECURITY_GATE_TEST_CMD	python3 -m unittest discover -s tests	Perintah pengujian yang dikutip dalam perintah penolakan dan pesan commit.
SECURITY_GATE_EVOLVE_CONTEXT	true	Tambahkan konvensi yang diverifikasi ke CONTEXT.md.
SECURITY_GATE_LOG	.security-gate/findings-log.ndjson	Log audit hanya-tambah.
SECURITY_GATE_NOTIFY_CMD	(kosong)	Perintah opsional yang menerima setiap peristiwa gate sebagai JSON di stdin.

Tips: Hook mewarisi lingkungan Antigravity, yang sulit diubah per ruang kerja. Untuk menyematkan setelan, masukkan setelan tersebut ke dalam string command di hooks.json, misalnya "command": "SECURITY_GATE_SCANNER=codemender bash -c '...'". Memaksakan codemender adalah pilihan yang baik untuk lab ini jika Anda menginstal Semgrep dan menginginkan pemindai tunggal yang dapat diprediksi.

8. Memverifikasi Hook Secara Offline

Sebelum gate menyentuh cm yang sebenarnya, pastikan gate berperilaku dengan benar menggunakan tiruan. Framework ini mengirimkan tes otomatis dengan biner cm dan semgrep palsu yang mencakup jalur izinkan, saran, tolak, error, dan eskalasi:

bash .agents/tests/run_tests.sh

Proses ini memerlukan waktu beberapa detik dan diakhiri dengan:

-- test_pipeline_tools_missing_passes_smoothly
-- test_skills_frontmatter_valid
60 passed, 0 failed

Pengujian terakhir juga memvalidasi frontmatter setiap skill di bagian .agents/skills/, jadi ini adalah perintah yang harus dijalankan ulang setelah mengedit SKILL.md.

Selanjutnya, simulasikan apa yang dikirim Antigravity untuk perintah yang bukan push. Skrip harus menjawab allow tanpa menyentuh pemindai apa pun:

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

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

Sekarang, simulasikan push tanpa perubahan lokal terhadap origin/main. Karena belum ada remote, gate akan kembali ke HEAD~1 dan memindai file dari commit terakhir Anda. Agar langkah ini tetap offline, arahkan ke tiruan cm dan semgrep:

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"}

Kedua tahap dijalankan karena direktori tiruan berisi semgrep palsu serta cm palsu. Pesan progres akan dikirim ke stderr dan hanya keputusan JSON yang dikirim ke stdout, sehingga Antigravity dapat mengurai hasilnya.

Peringatan: Menjalankan payload push yang sama tanpa awalan PATH tiruan akan memanggil cm find dan cm report yang sebenarnya terhadap ruang kerja Anda. Ini adalah cara yang sah untuk menguji gate secara menyeluruh dari terminal, tetapi memerlukan waktu beberapa menit dan akan melaporkan temuan terbuka dalam file dari commit terakhir Anda. Simpan untuk codelab berikutnya, yang akan membahas perilaku tersebut.

Terakhir, commit file framework agar file tersebut disertakan dalam repositori:

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

9. Membuka Ruang Kerja di Antigravity

Buka ~/codemender-lab sebagai folder di Antigravity. Setelah dimuat, agen tersebut:

• Aturan secure_tdd_workflow di setiap giliran.
• Enam keterampilan yang tersedia on-demand.
• Hook security-gate terdaftar di run_command.

Cara cepat untuk mengonfirmasi bahwa keterampilan terlihat adalah dengan bertanya kepada agen, dalam percakapan baru, "Keterampilan Workspace apa yang Anda miliki, dan apa fungsi masing-masing keterampilan tersebut?" Sebutkan keenamnya berdasarkan nama.

Izin

Hook itu sendiri diluncurkan oleh Antigravity, bukan oleh agen, sehingga tidak melalui perintah izin alat. Perintah agen itu sendiri yang melakukannya. Selama codelab berikutnya, nantikan perintah persetujuan untuk perintah pengujian, operasi git, dan perintah cm apa pun yang diputuskan agen untuk dijalankan secara langsung. Setujui saat diminta; jika Antigravity menawarkan untuk mengingat keputusan untuk awalan perintah, menyetujuinya akan menghindari permintaan ulang di seluruh loop.

Yang terjadi pada git push

1. Agen memanggil alat terminalnya dengan git push origin main.
2. Antigravity mencocokkan run_command dengan hooks.json dan menjalankan security_gate_hook.sh dengan panggilan alat di stdin.
3. Skrip mengenali push, menemukan file yang diubah, memindainya dengan cm find, dan membaca cm report.
4. Jika tidak ada yang memblokir, {"decision": "allow"} akan dicetak dan push akan dilanjutkan.
5. Jika temuan memblokir, temuan tersebut akan mencetak {"decision": "deny", "reason": "..."}. Push tidak berjalan, agen melihat alasannya, dan aturan selalu aktif serta keterampilan yang disebutkan memberi tahu agen apa yang harus dilakukan selanjutnya: satu pengujian yang gagal, satu perbaikan minimal, jalankan kembali suite, push lagi.

Selamat! Anda telah menyelesaikan codelab CodeMender Skills & Hooks for Antigravity. Dalam codelab berikutnya, Anda akan memberikan permintaan fitur kepada agen dan melihat loop ini berjalan secara menyeluruh, mulai dari model ancaman hingga push yang melewati gerbang.