Antigravity için CodeMender Becerileri ve Kancaları

1. Giriş

Bu codelab'de, güvenliğin ayrı bir inceleme adımı yerine normal geliştirme döngüsünün bir parçası olması için bir yapay zeka kodlama temsilcisini (Antigravity) yapılandıracaksınız. Temsilciye Plan → Kırmızı → Yeşil → Yeniden Düzenleme döngüsünde rehberlik eden bir dizi temsilci becerisi yükleyeceksiniz. Ayrıca git push işlemini kesintiye uğratan, değiştirilen dosyaları CodeMender ile tarayan ve bulguları önce test etme talimatlarıyla birlikte temsilciye geri ileten bir PreToolUse kancası da yükleyeceksiniz.

Beceriler ve kanca, açık kaynaklı Secure TDD Agent Framework'ten alınmıştır. Bunları, CodeMender CLI Basics'te oluşturduğunuz ~/codemender-lab çalışma alanına yükleyeceksiniz.

İpucu: CodeMender şu anda sınırlı sayıda müşteri için genel önizleme aşamasındadır. Erişim için satış ekibinizle iletişime geçin.

Öğrenecekleriniz

• Antigravity, .agents/ altındaki çalışma alanı kurallarını, becerilerini ve kancalarını nasıl keşfeder?
• Altı güvenli TDD becerisinin ne işe yaradığı ve her birinin döngünün hangi aşamasına ait olduğu
• PreToolUse kancası, temsilcinin araç çağrısını stdin'de nasıl alır ve izin verme/reddetme kararı döndürür.
• Güvenlik kapısı kancasının (security_gate_hook.sh) cm find aracını nasıl çalıştırdığı, bulguları önem derecesine göre nasıl sınıflandırdığı, düzeltme girişimlerini nasıl izlediği ve cm verify ile nasıl üst birime ilettiği.
• Gerçek cm'e yönlendirmeden önce tüm kanca ardışık düzenini sahte tarayıcılarla çevrimdışı olarak doğrulama.

Ön koşullar

• CodeMender CLI Basics'i tamamlama Bu laboratuvar ~/codemender-lab dizininde devam eder ve sample_app/, CONTEXT.md, git geçmişi ve ~/.codemender/config.yaml öğelerini yeniden kullanır.
• Yerel bir klasörü çalışma alanı olarak açma özelliğine sahip Antigravity yüklü olmalıdır.
• git, jq ve bash yüklendi. Kanca komut dosyaları düz bash'tir ve macOS'un stok bash 3.2 sürümünün yanı sıra daha yeni sürümlerinde de çalışır.
• CodeMender CLI Basics (~/codemender-lab/.venv) bölümündeki, Flask'ın yüklü olduğu Python sanal ortamı.
• Temel kabuk komut dosyası oluşturma bilgisi

2. Workspace Kurulumu

1. adım: Laboratuvar dizinine dönün

Bu laboratuvardaki tüm komutlar, sanal ortam etkinleştirilmiş şekilde ~/codemender-lab dizininden çalıştırılır:

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

Önceki laboratuvardaki çalışma alanının bozulmadığını ve çalışma ağacınızın temiz olduğunu onaylayın:

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

git status --short hiçbir şey yazdırmamalıdır. Dosyalar listeleniyorsa devam etmeden önce bunları kaydedin.

2. adım: Dalı adlandırın main

Güvenlik kapısı, hangi dosyaların taranacağına karar vermek için çalışma ağacınızı origin/main ile karşılaştırır. Bu referans yoksa yalnızca en son kaydı kapsayan HEAD~1 değerine geri döner. Dalınızın adının main olduğundan emin olun:

git branch -M main

3. adım: Test paketi giriş noktası ekleyin

Güvenli TDD döngüsü, her düzeltmeden sonra temsilcinin python3 -m unittest discover -s tests komutunu çalıştırmasını ister. Bu nedenle, çalışma alanında bir tests/ dizini bulunmalıdır. Paketin çalıştırabileceği gerçek bir test olması için bir karakterizasyon testiyle başlayın:

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

Ran 1 test ve OK seçeneklerini görürsünüz.

Not: Bu test, kodun ne yapması gerektiğini değil, şu anda ne yaptığını belgeler. hash_password hâlâ MD5 kullanıyor ve daha sonraki bir Güvenli TDD döngüsü bunu değiştirebilir. Test yalnızca sonucun onaltılık bir dize olduğunu iddia ettiğinden, bu gerçekleştiğinde başarılı olmaya devam eder. Çerçevenin README dosyasında bu test, karakterizasyon testi olarak adlandırılır ve eski koda dokunmadan önce ilk adım olarak önerilir.

4. adım: .gitignore uzantısını genişletme ve kaydetme

Bu laboratuvarın oluşturduğu çalışma zamanı dosyalarını .gitignore dizinine ekleyin, ardından temel çizgiyi uygulayın:

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

3. Çerçeve dosyalarını yükleme

Beceriler, kural, kanca ve çevrimdışı test bandı tek bir .agents/ dizininde bulunur. Yaklaşık 800 satırlık bash kodunu elle yazmak yerine çerçeveyi klonlayın ve bu dizini çalışma alanınıza kopyalayın:

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

Düzeni onaylayın:

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

Kanca giriş noktasının yürütülebilir olduğundan emin olun:

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

Not: Antigravity, açık klasörün kökündeki .agents/ dizinini inceleyerek çalışma alanı özelleştirmelerini bulur: Her zaman açık veya koşullu talimatlar için rules/*.md, seç-izle prosedürler için skills//SKILL.md ve yaşam döngüsü kancaları için hooks.json. Başka bir şey kaydetmeniz gerekmez. Antigravity bu klasörde zaten açıksa dosyaları kopyaladıktan sonra kapatıp yeniden açın. Böylece hooks.json dosyasını algılar.

Bu laboratuvarın geri kalanında, yüklediğiniz her bir bileşen ayrı ayrı incelenir.

4. Her Zaman Açık İş Akışı Kuralı

Beceriler, temsilci bir becerinin açıklamasının görevle eşleştiğine karar verdiğinde isteğe bağlı olarak yüklenir. Temsilciye, bu nesnelere doğru sırayla ulaşmasını söyleyen bir şey olmalıdır. Bu, .agents/rules/secure_tdd_workflow.md'nin görevidir. Frontmatter'ı trigger: always_on değerini ayarlar. Bu nedenle kural her sıraya eklenir:

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

Kural, CodeMender CLI Basics'te oluşturduğunuz CONTEXT.md kuralına referans veriyor. cm fix aracını parametreleştirilmiş sorgu kuralınıza yönlendiren dosya, artık temsilcinin planlamasını yönlendiriyor. Bu laboratuvar için en önemli madde 6. maddedir: Güvenlik kapısı, aynı anda birden fazla bulgu içeren bir push işlemini reddettiğinde temsilcinin izlediği madde budur.

İpucu: Kurallar, always_on dışında başka tetikleyicileri de destekler: model_decision (temsilci bir description okur ve kuralı yükleyip yüklemeyeceğine karar verir), glob (eşleşen dosyalar açıkken etkinleşir) ve manual (yalnızca @ ile bahsettiğinizde). always_on, her adımda jeton harcar. Bu nedenle, bu tür kuralları kısa tutun ve ayrıntıları becerilere taşıyın.

5. Altı Temsilci Becerisi

Her beceri, YAML frontmatter içeren bir SKILL.md dosyası barındıran bir dizindir. İki alanın doldurulması zorunludur:

• name: Küçük harfli, kısa çizgili bir tanımlayıcı.
• description: Becerinin ne işe yaradığı ve ne zaman kullanılması gerektiği. Temsilci, becerinin tamamını yükleyip yüklemeyeceğine karar verirken yalnızca bu alanı okur. Bu nedenle, aşağıdaki her açıklamada becerinin ne için kullanılmadığı da belirtilir.

Beceri	Faz	Amaç
threat-model-assessor	A: Plan	Özelliğin kapsamını belirleyin, STRIDE'ı çalıştırın, threat_model.md yazın.
security-test-writer	B: Kırmızı	Doğru nedenle başarısız olan işlevsel ve sınır testleri yazma
defensive-developer	C: Yeşil	Güvenli kalıplar kullanarak testleri başarılı kılan minimum kodu yazın.
local-refactor-scanner	D: Yeniden düzenleme	Temizleme, tam paketi çalıştırma, yerel tarayıcıları çalıştırma, farkı inceleme.
skill-evolution-updater	Sürekli	CONTEXT.md ve SKILL.md dosyalarına yeni kuralları kaydedin.
history-context-seeder	Oryantasyon	Mevcut bir depoda CONTEXT.md için Git geçmişini inceleyin.

Ön bilgi ve talimatların nasıl bir araya geldiğini görebilmeniz için içeriğin tamamı aşağıda verilmiştir.

1. threat-model-assessor (A aşaması)

.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 (B aşaması)

.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 (C aşaması)

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

Not: Beceri, örnek yardımcı olarak utils.security.resolve_safe_path'dan bahseder. Bu modül, CodeMender CLI Basics'teki sample_app/data_service.py ile değil, çerçevenin kendi örnek uygulamasıyla birlikte gelir. Temsilci, CONTEXT.md içindeki kalıplara (örneğin, os.path.realpath ve bir ön ek kontrolü) geri döner. Paylaşılan yardımcılar kullanmak istiyorsanız bunları projenize ekleyin ve CONTEXT.md 2. bölümde listeleyin.

4. local-refactor-scanner (D aşaması)

.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 (Sürekli Gelişim)

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

Uyarı: Bu beceri, temsilcinin kendi talimatlarını düzenlemesine olanak tanır. Bu, bu laboratuvar gibi bir korumalı alanda tek başına çalışan geliştiriciler için kullanışlıdır. Ekip ortamında, çerçevenin README dosyası, temsilcilerin beceri değişikliklerini doğrudan paylaşılan bir beceri kayıt defterine uygulamak yerine (PR veya destek kaydı olarak) önermesini önerir.

6. history-context-seeder (İlk katılım)

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

CONTEXT.md zaten mevcut olduğundan bu beceriyi laboratuvarlarda kullanmayacaksınız. Ancak çerçeveyi, yıllarca geçmişi olan ve yazılı kuralları olmayan bir depoya getirdiğinizde bu beceriyi kullanmanız gerekir.

6. Antigravity kancasını yapılandırma

.agents/hooks.json, Antigravity'ye, temsilcinin yürüttüğü tüm terminal komutlarından önce güvenlik denetimini çalıştırmasını söyler:

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

Bu dosyayla ilgili birkaç ayrıntı, başlattığı komut dosyasının tasarımını açıklar:

• matcher, komut metni değil, araç adları üzerinde bir normal ifadedir. PreToolUse, bir araç çalıştırılmadan önce tetiklenir ve eşleştirici hangi araçların çalıştırılacağına karar verir. run_command, Antigravity'nin terminal aracıdır. Diğer alternatifler, eklenti ad alanına sahip varyantları ve bu dosyaları paylaşan diğer aracı platformlarını kapsar. git push* gibi bir eşleştirici, bu ada sahip bir araç olmadığı için hiçbir zaman tetiklenmez. Asıl komutun filtrelenmesi komut dosyasında gerçekleşir.
• Kanca, araç çağrısını stdin üzerinden alır. Antigravity, {"toolCall": {"name": "run_command", "args": {"CommandLine": "git push origin main"}}, ...} gibi bir JSON yükünü aktarır. Komut dosyası .toolCall.args.CommandLine değerini okur ve git push olmayan her şey için izin verme kararı vererek hemen çıkar.
• Çalışma dizini, hooks.json dosyasını içeren dizindir. Bu nedenle, kanca .agents/ içinde başlar. bash -c 'if [ -x ./security_gate_hook.sh ] ...' sarmalayıcısı hem bu durumu hem de depo kökünden başlatılma durumunu işler. Komut dosyası, herhangi bir işlem yapmadan önce git rev-parse --show-toplevel için cd.
• Komut dosyası, stdout'ta JSON ile yanıt verir. {"decision": "allow"}, orijinal komutun çalıştırılmasına izin verir. {"decision": "deny", "reason": "..."}, bu mesajı engeller ve temsilciye nedenini gösterir. Çerçeve, eski kanca sözleşmeleriyle uyumluluk için bir allow_tool boole değeri de yayınlar.
• Kancalar eşzamanlı olarak çalışır ve tamamlanana veya timeout değerine ulaşana kadar (saniye cinsinden; atlanırsa varsayılan değer 30'dur) aracı döngüsünü engeller.

Uyarı: 120 saniye, gerçek bir CodeMender çalıştırması için çok kısa. CodeMender CLI Basics'te, tek bir dosyada cm find yaklaşık bir dakika, cm verify ise yaklaşık üç dakika sürdü. Kapı, değiştirilen her dosya için bir kez cm find çalıştırılır ve tekrarlanan hatalardan sonra cm verify çalıştırılır. Kancayı gerçek cm hizmetine bağlamadan önce zaman aşımı süresini artırın.

-i.bak biçimi hem GNU hem de BSD (macOS) sed ile çalışır:

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

İpucu: Kanca, yalnızca temsilcinin terminal aracı üzerinden yaptığı push işlemlerini yakalar. git push komutunu bir kabukta kendiniz çalıştırmak bu işlemi tamamen atlar. Bu, kanca dosyalarını ilk kez göndermeniz gerektiğinde kullanışlıdır. İnsanlar tarafından yapılan push işlemlerini de kapsayan bir geçit için aynı komut dosyasını git pre-push kancası olarak yükleyin.

7. Güvenlik Kapısı Kancasının İşleyiş Şekli

security_gate_hook.sh, .agents/lib/ adresinden üç modül alan ince bir giriş noktasıdır:

Modül	Rol
gate_common.sh	Yapılandırma varsayılanları, allow/deny çıkışı, önem derecesi sıralaması, NDJSON denetleme günlüğü, deneme sayımı, commit ve CONTEXT.md yardımcıları.
engine_semgrep.sh	1. aşama Semgrep ile isteğe bağlı deterministik tarama. semgrep, PATH üzerinde değilse atlanır.
engine_codemender.sh	2. aşama. cm find ile semantik tarama, sınıflandırma, deneme takibi ve cm verify ile üst birime iletme.

1. adım: Bunun bir push olup olmadığına karar verin

Giriş noktası, komutu stdin yükünden çıkarır ve git push komutunu yaygın biçimlerinde (git -C /repo push, cd x && git push, sudo git push) tanıyan bir normal ifadeye göre test ederken git commit -m "before git push" gibi tırnak içine alınmış metinleri yoksayar. Push olmayan her şeye hemen izin verilir:

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

2. adım: Tarayıcıları seçin

SECURITY_GATE_SCANNER, ardışık düzeni seçer. Varsayılan değer olan auto, Semgrep ve CodeMender'dan hangileri yüklüyse sırayla çalıştırır:

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

1. aşama, ardışık düzen modunda engelleyici sorunlar bulduğunda bunları kendi başına reddetmez. Bunları, 2. aşamanın aldığı geçici bir dosyaya yazar. Böylece son sözü CodeMender söyler.

3. adım: CodeMender aşaması

engine_codemender.sh içindeki run_codemender_gate, sırasıyla şu işlemleri yapar:

1. git diff --name-only origin/main (HEAD~1 değerine geri dönülür) ile değiştirilen dosyaları bulma. Değişiklik olmaması, izin verildiği anlamına gelir.
2. cm find "$file" -y --bypass-warning ile her dosyayı tarayın, ardından cm report --format json ile her şeyi geri çekin. cm report başarısız olursa veya geçersiz JSON döndürürse bu bir tarama hatasıdır, temiz bir sonuç değildir.
3. Durumu OPEN veya REOPENED olan ve file_path değeri değiştirilen dosyalardan biriyle biten bulguları filtreleyin. CodeMender CLI Basics'te daha önce düzelttiğiniz veya reddettiğiniz bulgular yok sayılır.
4. Her bulguyu sınıflandırın. SECURITY_GATE_BLOCK_SEVERITY (varsayılan HIGH) veya daha yüksek önem derecesi engellemeye neden olur. Daha düşük önem derecesi ise tavsiye niteliğindedir, günlüğe kaydedilir ve yazdırılır ancak aktarımı durdurmaz.
5. Engelleyen bir şey yoksa izin ver. Önceki bir push işlemini engelleyen bir bulgu artık yoksa geçit bunu FIXED olarak günlüğe kaydeder, ## 4. Continuous Evolution altındaki CONTEXT.md dosyasına bir kural ekler ve bu değişikliği uygular.
6. Kendi denetleme günlüğünü okuyarak her bir engelleme bulgusu için deneme sayısını sayar. Her ret bir deneme sayılır. 1 ila SECURITY_GATE_MAX_RETRIES (varsayılan olarak 3) arasındaki denemelerde, geçit DENIED_TO_AGENT kaydeder ve bulguyu bir ret mesajına ekler.
7. Bütçe harcandıktan sonra üst birime iletin. Aynı bulgu için dördüncü denemede kapı cm verify çalışır. Bulgu kötüye kullanılamıyorsa (çıkış kodu 1 veya durum DISMISSED) tavsiye niteliğinde olacak şekilde eski sürüme geçirilir. Onaylanırsa veya cm verify kilitlenirse ağ geçidi BLOCKED kaydeder ve gerçek kişi tarafından inceleme isteğiyle reddeder.
8. Talimatlarla reddetme İşlem yapılabilir bulgular varsa kapı, temsilciye şu nedeni döndürür:

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

Bu, dikkat çekici giriş ile beceriler arasındaki geçişi sağlar. Kanca, cm fix yöntemini çağırmıyor. Temsilcinin kullanması gereken becerileri adlandırır, temsilci önce test düzeltmesini yapar ve bir sonraki git push, geçidi yeniden çalıştırır.

Not: Kapı, ~/.codemender/state.db adresindeki global CodeMender veritabanını yeniden kullanır. Bu veritabanı, cm report tarafından okunan veritabanıyla aynıdır. Dosya yoluna ve OPEN durumuna göre filtreleme yaptığı için CodeMender CLI Basics'ten gelen ve hiç düzeltmediğiniz sample_app/data_service.py ile ilgili eski bulgular (örneğin, /ping içindeki OS komut enjeksiyonu), bu dosyaya dokunan ilk push işlemini engeller. Bu, tasarım gereğidir: Kapı, "önceden var olan" kavramını değil, yalnızca "gönderdiğiniz bir dosyada açık" kavramını dikkate alır.

Yapılandırma referansı

Tüm ayarlar, gate_common.sh içinde varsayılan değerleri ayarlanmış ortam değişkenleridir:

Değişken	Varsayılan	Etki
SECURITY_GATE_SCANNER	auto	auto, codemender (veya cm) ya da semgrep.
SECURITY_GATE_BLOCK_SEVERITY	HIGH	Engelleme yapan en düşük önem düzeyi. CRITICAL, HIGH, MEDIUM veya LOW.
SECURITY_GATE_MAX_RETRIES	3	cm verify ile görüşülmeden önce bulgu başına ret sayısı.
SECURITY_GATE_ALLOW_ON_ERROR	false	true, tarayıcı çalışmadığında push işlemine izin verir ve kaydetmeyi unverified-scan- olarak etiketler.
SECURITY_GATE_TEST_CMD	python3 -m unittest discover -s tests	Reddetme istemlerinde ve commit mesajlarında alıntılanan test komutu.
SECURITY_GATE_EVOLVE_CONTEXT	true	Doğrulanmış kuralları CONTEXT.md adlı kurala ekleyin.
SECURITY_GATE_LOG	.security-gate/findings-log.ndjson	Yalnızca ekleme yapılabilen denetleme günlüğü.
SECURITY_GATE_NOTIFY_CMD	(boş)	Her kapı etkinliğini stdin'de JSON olarak alan isteğe bağlı komut.

İpucu: Kancalar, Antigravity'nin ortamını devralır. Bu ortamı çalışma alanı başına değiştirmek zordur. Bir ayarı sabitlemek için hooks.json içindeki command dizesine yerleştirin (ör. "command": "SECURITY_GATE_SCANNER=codemender bash -c '...'"). Semgrep'i yüklediyseniz ve tek bir öngörülebilir tarayıcı istiyorsanız bu laboratuvarda codemender'i zorunlu kılmak iyi bir seçimdir.

8. Kancayı Çevrimdışı Doğrulama

Kapı gerçek cm ile etkileşime girmeden önce, taklitlerle doğru şekilde çalıştığını onaylayın. Çerçeve; izin verme, tavsiye, reddetme, hata ve üst birime iletme yollarını kapsayan sahte cm ve semgrep ikili dosyaları içeren bir test bandı sunar:

bash .agents/tests/run_tests.sh

Çalıştırma işlemi birkaç saniye sürer ve şu şekilde sona erer:

-- test_pipeline_tools_missing_passes_smoothly
-- test_skills_frontmatter_valid
60 passed, 0 failed

Son test, .agents/skills/ altındaki her becerinin ön metnini de doğrular. Bu nedenle, bir SKILL.md dosyasını düzenledikten sonra bu komutu yeniden çalıştırmanız gerekir.

Ardından, Antigravity'nin push olmayan bir komut için ne gönderdiğini simüle edin. Komut dosyası, herhangi bir tarayıcıya dokunmadan allow sorusunu yanıtlamalıdır:

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

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

Şimdi origin/main için yerel değişiklik içermeyen bir push simülasyonu yapın. Henüz uzak bir depo olmadığından geçit HEAD~1'e geri döner ve son kaydetmenizdeki dosyaları tarar. Bu adımı çevrimdışı tutmak için sahte cm ve semgrep'e yönlendirin:

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

Sahte dizinde sahte bir semgrep ve sahte bir cm olduğu için her iki aşama da çalıştırıldı. İlerleme mesajları stderr'ye, yalnızca JSON kararı ise stdout'a gider. Bu sayede Antigravity, sonucu ayrıştırabilir.

Uyarı: Aynı push yükünü, mock PATH ön eki olmadan çalıştırmak, çalışma alanınızda gerçek cm find ve cm report'yı çağırır. Bu, kapıyı bir terminalden uçtan uca test etmenin geçerli bir yoludur ancak birkaç dakika sürer ve son commit'inizdeki dosyalarda bulunan tüm açık bulguları bildirir. Bu davranışı, bir sonraki codelab'de kullanmak üzere saklayın.

Son olarak, çerçeve dosyalarını depoyla birlikte taşınmaları için kaydedin:

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

9. Antigravity'de çalışma alanı açma

~/codemender-lab dosyasını Antigravity'de klasör olarak açın. Yüklendikten sonra temsilci şunlara sahip olur:

• Her turda secure_tdd_workflow kuralı.
• İstediğiniz zaman erişebileceğiniz altı beceri.
• security-gate kancası run_command tarihinde kaydedildi.

Becerilerin görünür olduğunu doğrulamanın hızlı bir yolu, yeni bir sohbette temsilciye "Hangi Workspace becerilerine sahipsin ve her biri ne işe yarıyor?" diye sormaktır. Altı öğeyi adlarıyla listelemelidir.

İzinler

Kanca, temsilci tarafından değil Antigravity tarafından başlatılır. Bu nedenle, araç izni istemlerinden geçmez. Temsilcinin kendi komutları için onay gerekir. Bir sonraki codelab'de test komutu, git işlemleri ve temsilcinin doğrudan çalıştırmaya karar verdiği tüm cm komutları için onay istemleri gösterilir. İstendiğinde bunları onaylayın. Antigravity, bir komut öneki için kararı hatırlamayı teklif ederse bunu kabul ederek döngü boyunca yeniden istemleri önleyebilirsiniz.

git push tarihinde ne olacak?

1. Temsilci, terminal aracını git push origin main ile çağırır.
2. Antigravity, run_command ile hooks.json eşleştirir ve stdin'de araç çağrısıyla security_gate_hook.sh çalıştırır.
3. Komut dosyası, push işlemini tanır, değiştirilen dosyaları bulur, cm find ile tarar ve cm report dosyasını okur.
4. Engelleme yoksa {"decision": "allow"} yazdırılır ve push işlemi devam eder.
5. Bulgular engellenirse {"decision": "deny", "reason": "..."} yazdırılır. Push işlemi çalışmaz, temsilci nedenini görür ve her zaman açık kuralı ile adlandırılmış beceriler, temsilciye ne yapması gerektiğini söyler: bir başarısız test, bir minimum düzeltme, paketi yeniden çalıştır, tekrar push işlemi yap.

Tebrikler! "Antigravity için CodeMender Becerileri ve Kancaları" codelab'ini tamamladınız. Bir sonraki codelab'de, temsilciye bir özellik isteği gönderecek ve bu döngünün tehdit modelinden kapıyı geçen bir push'a kadar uçtan uca çalışmasını izleyeceksiniz.