مهارات CodeMender وخطافات Antigravity

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستُعدّ وكيل ترميز مستنِد إلى الذكاء الاصطناعي (Antigravity) ليكون الأمان جزءًا من حلقة التطوير العادية بدلاً من خطوة مراجعة منفصلة. ستثبّت مجموعة من مهارات الوكيل التي توجّهه خلال دورة "التخطيط" ← "الخطأ" ← "الصواب" ← "إعادة الهيكلة"، وخطاف PreToolUse يعترض git push، ويفحص الملفات التي تم تغييرها باستخدام CodeMender، ويعيد أي نتائج إلى الوكيل مع تعليمات لإصلاحها من خلال الاختبار أولاً.

تأتي المهارات والخطاف من إطار عمل وكيل TDD الآمن المفتوح المصدر. ستثبّتها في مساحة عمل ~/codemender-lab نفسها التي أنشأتها في أساسيات واجهة سطر أوامر CodeMender.

ملاحظة: يتوفّر CodeMender حاليًا لمجموعة محدودة من العملاء في الميزات التجريبية المتاحة للجميع. يُرجى التواصل مع فريق المبيعات للحصول على إذن بالوصول.

ما ستتعرّف عليه

• كيفية عثور Antigravity على قواعد مساحة العمل والمهارات والروابط ضمن .agents/
• ما تفعله مهارات التطوير المستند إلى الاختبار (TDD) الآمن الست والمرحلة التي تملكها كل مهارة في الحلقة.
• كيفية تلقّي دالة ربط PreToolUse لطلب أداة الوكيل على stdin وإرجاع قرار السماح/الرفض.
• How the security gate hook (security_gate_hook.sh) runs cm find, classifies findings by severity, tracks fix attempts, and escalates with cm verify.
• كيفية التحقّق من مسار الردّ التلقائي بالكامل بلا إنترنت باستخدام أدوات فحص وهمية قبل توجيهه إلى cm الحقيقي

المتطلبات الأساسية

• إكمال أساسيات CodeMender CLI يستمر هذا التمرين في دليل ~/codemender-lab ويعيد استخدام sample_app/ وCONTEXT.md وسجلّ git و~/.codemender/config.yaml.
• تثبيت Antigravity، مع إمكانية فتح مجلد على الجهاز كمساحة عمل
• تم تثبيت "git" و"jq" و"bash". تكون نصوص الربط البرمجية بلغة bash عادية ويتم تشغيلها على الإصدار 3.2 من bash في نظام التشغيل macOS والإصدارات الأحدث.
• بيئة Python الافتراضية من أساسيات CodeMender CLI ‏(~/codemender-lab/.venv) مع تثبيت Flask.
• معرفة أساسية بلغة البرمجة النصية Shell

2. إعداد Workspace

الخطوة 1: العودة إلى دليل التمرين العملي

يتم تشغيل جميع الأوامر في هذا التمرين من ~/codemender-lab مع تفعيل البيئة الافتراضية:

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

تأكَّد من أنّ مساحة العمل من التمرين السابق سليمة وأنّ شجرة العمل نظيفة:

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

من المفترض ألّا يطبع git status --short أي شيء. إذا كان يسرد الملفات، فقم بتنفيذها قبل المتابعة.

الخطوة 2: تسمية الفرع main

تقارن بوابة الأمان بين شجرة العمل و"origin/main" لتحديد الملفات التي يجب فحصها. إذا لم يكن هذا المرجع متوفّرًا، يتم استخدام HEAD~1، الذي يغطي فقط أحدث عملية دمج. تأكَّد من أنّ الفرع يحمل الاسم main:

git branch -M main

الخطوة 3: إضافة نقطة دخول إلى الحزمة الاختبارية

تطلب حلقة "التطوير المستند إلى الاختبار" (TDD) الآمنة من الوكيل تشغيل python3 -m unittest discover -s tests بعد كل إصلاح، لذا تحتاج مساحة العمل إلى دليل tests/. ابدأ باختبار توصيف واحد حتى يكون لدى المجموعة شيء حقيقي لتشغيله:

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

ملاحظة: يوثّق هذا الاختبار ما يفعله الرمز اليوم، وليس ما يجب أن يفعله. لا يزال hash_password يستخدم MD5، وقد تستبدله دورة تطوير آمنة لاحقة مستندة إلى الاختبار. بما أنّ الاختبار يؤكّد فقط أنّ النتيجة هي سلسلة سداسية عشرية، سيستمر في النجاح عند حدوث ذلك. يُطلق ملف README الخاص بإطار العمل على هذا الاختبار اسم "اختبار التوصيف"، وينصح به كخطوة أولى قبل التعامل مع الرموز البرمجية القديمة.

الخطوة 4: تمديد فترة استخدام .gitignore والالتزام بها

أضِف ملفات وقت التشغيل التي ينتجها هذا التمرين إلى .gitignore، ثم ثبِّت المرجع:

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

3- تثبيت ملفات إطار العمل

تتوفّر المهارات والقاعدة والخطاف ومفعِّل الاختبار بلا إنترنت ضمن دليل .agents/ واحد. بدلاً من كتابة ما يقرب من 800 سطر من bash يدويًا، انسخ إطار العمل وانسخ هذا الدليل إلى مساحة العمل الخاصة بك:

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

تأكيد التخطيط:

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

تأكَّد من أنّ نقطة دخول الخطاف قابلة للتنفيذ:

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

ملاحظة: تكتشف Antigravity تخصيصات مساحة العمل من خلال الانتقال إلى دليل .agents/ في جذر المجلد المفتوح: rules/*.md للتعليمات التي تعمل دائمًا أو التعليمات الشرطية، وskills//SKILL.md للإجراءات عند الطلب، وhooks.json لخطافات دورة الحياة. ولا يلزم تسجيل أي شيء آخر. إذا كان تطبيق Antigravity مفتوحًا على هذا المجلد، يُرجى إغلاقه وإعادة فتحه بعد نسخ الملفات لكي يتمكّن من رصد hooks.json.

يستعرض الجزء المتبقي من هذا الدرس التطبيقي ما قمت بتثبيته للتو، جزءًا تلو الآخر.

4. قاعدة سير العمل "التشغيل دائمًا"

يتم تحميل المهارات عند الطلب، عندما يقرّر الوكيل أنّ وصف المهارة يتطابق مع المهمة. يجب أن يخبر شيء ما الوكيل بالوصول إليها بالترتيب الصحيح. هذه هي مهمة .agents/rules/secure_tdd_workflow.md. يضبط القسم التمهيدي trigger: always_on، وبالتالي يتم إدخال القاعدة في كل دور:

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

تشير القاعدة إلى CONTEXT.md الذي أنشأته في أساسيات واجهة سطر الأوامر في CodeMender. الملف نفسه الذي وجّه cm fix نحو اصطلاح طلب البحث المزوّد بمَعلمات يوجّه الآن تخطيط الوكيل. العنصر 6 هو الأهم في هذا التمرين، فهو ما يتّبعه الوكيل عندما ترفض بوابة الأمان عملية دفع تتضمّن نتائج متعددة في الوقت نفسه.

ملاحظة: تتيح القواعد استخدام عوامل تشغيل أخرى إلى جانب always_on: model_decision (يقرأ الوكيل description ويقرّر ما إذا كان سيحمّل القاعدة)، وglob (يتم تفعيله عند فتح الملفات المطابقة)، وmanual (فقط عند الإشارة إليه باستخدام @). تستهلك always_on الرموز المميّزة في كل دور، لذا يجب أن تكون هذه القواعد قصيرة وأن يتم نقل التفاصيل إلى المهارات.

5- مهارات الوكيل الست

كل مهارة هي دليل يحتوي على SKILL.md مع بيانات وصفية تمهيدية بتنسيق YAML. يجب ملء حقلَين:

• ‫name: معرّف بأحرف صغيرة ومفصول بشرطات
• ‫description: ما تفعله المهارة ومتى يجب استخدامها يقرأ الوكيل هذا الحقل فقط عند تحديد ما إذا كان سيحمّل المهارة الكاملة، لذا يوضّح كل وصف أدناه أيضًا ما لا تصلح له المهارة.

المهارة	المرحلة	الغرض
threat-model-assessor	أ: الخطة	تحديد نطاق الميزة، وتشغيل STRIDE، وكتابة threat_model.md
security-test-writer	ب: أحمر	كتابة اختبارات وظيفية واختبارات حدودية تفشل للسبب الصحيح
defensive-developer	C: أخضر	اكتب الحد الأدنى من الرموز البرمجية التي تجعل الاختبارات ناجحة، باستخدام أنماط آمنة.
local-refactor-scanner	D: إعادة الهيكلة	نظِّف الملفات، وشغِّل الحزمة الكاملة، وشغِّل أدوات الفحص المحلية، وراجِع الاختلافات.
skill-evolution-updater	غير متقطع	تسجيل الاصطلاحات الجديدة في ملفات CONTEXT.md وSKILL.md
history-context-seeder	الإعداد	استخرِج سجلّ Git لإضافة CONTEXT.md في مستودع حالي.

في ما يلي المحتوى الكامل حتى تتمكّن من معرفة كيفية توافق الواجهة والتعليمات معًا.

1. ‫threat-model-assessor (المرحلة أ)

.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 (المرحلة ب)

.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 (المرحلة ج)

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

ملاحظة: تشير المهارة إلى utils.security.resolve_safe_path كمثال على المساعد. يتم شحن هذه الوحدة مع نموذج التطبيق الخاص بإطار العمل، وليس مع sample_app/data_service.py من أساسيات CodeMender CLI. سيعود الوكيل إلى الأنماط في CONTEXT.md (على سبيل المثال، os.path.realpath بالإضافة إلى التحقّق من البادئة). إذا أردت الاستعانة بمساعدين مشترَكين، أضِفهم إلى مشروعك وأدرِجهم في القسم 2 من CONTEXT.md.

4. ‫local-refactor-scanner (المرحلة د)

.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 (التطوُّر المستمر)

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

تحذير: تتيح هذه المهارة للوكيل تعديل تعليماته الخاصة. وهذا مناسب لمطوّر مستقل يعمل في بيئة اختبار معزولة مثل هذا التمرين. في بيئة العمل الجماعي، ينصح ملف README الخاص بإطار العمل بأن يقترح الوكلاء تغييرات في المهارات (من خلال طلب دمج أو تذكرة) بدلاً من تطبيقها مباشرةً على سجلّ مهارات مشترك.

6. ‫history-context-seeder (الإعداد)

.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 موجود بالفعل، ولكنها المهارة التي يجب الوصول إليها عند إحضار إطار العمل إلى مستودع له سنوات من التاريخ ولا توجد اتفاقيات مكتوبة.

6. ضبط Antigravity Hook

يطلب .agents/hooks.json من Antigravity تشغيل بوابة الأمان قبل أي أمر في Terminal ينفّذه الوكيل:

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

توضّح بعض التفاصيل حول هذا الملف تصميم النص البرمجي الذي يشغّله:

• matcher هو تعبير نمطي لأسماء الأدوات، وليس لنص الأمر. يتم تشغيل PreToolUse قبل تشغيل أداة، ويحدّد المطابق الأدوات التي سيتم تشغيلها. ‫run_command هي أداة Terminal من Antigravity، بينما تشمل البدائل الأخرى الأنواع التي تستخدم مساحات أسماء المكوّنات الإضافية ومنصات الوكلاء الأخرى التي تشارك هذه الملفات. لن يتم تفعيل أداة مطابقة مثل git push* أبدًا لأنّه لا توجد أداة بهذا الاسم. تتم الفلترة على الأمر الفعلي داخل النص البرمجي.
• يتلقّى الـ hook طلب الأداة على stdin. يُرسل Antigravity حمولة JSON مثل {"toolCall": {"name": "run_command", "args": {"CommandLine": "git push origin main"}}, ...}. يقرأ النص البرمجي .toolCall.args.CommandLine ويخرج على الفور بقرار السماح لأي شيء ليس git push.
• دليل العمل هو الدليل الذي يحتوي على hooks.json، لذا يبدأ الـ hook داخل .agents/. يتعامل برنامج تضمين bash -c 'if [ -x ./security_gate_hook.sh ] ...' مع كل من هذه الحالة ويتم تشغيله من جذر المستودع. بعد ذلك، ينتقل النص البرمجي إلى cd في git rev-parse --show-toplevel قبل تنفيذ أي عمل.
• يستجيب النص البرمجي على stdout باستخدام JSON. يسمح {"decision": "allow"} بتشغيل الأمر الأصلي. يحظر {"decision": "deny", "reason": "..."} الإجراء ويعرض السبب للوكيل. يُصدر إطار العمل أيضًا قيمة منطقية allow_tool للتوافق مع عقود الربط القديمة.
• يتم تشغيل الروابط بشكل متزامن وتحظر حلقة الوكيل إلى أن تنتهي أو تصل إلى timeout (بالثواني، والقيمة التلقائية هي 30 في حال حذفها).

تحذير: 120 ثانية هي مدة قصيرة جدًا لتشغيل CodeMender بشكل فعلي. في أساسيات واجهة سطر أوامر CodeMender، استغرق cm find على ملف واحد دقيقة واحدة تقريبًا، بينما استغرق cm verify حوالي ثلاث دقائق. يتم تشغيل cm find مرة واحدة لكل ملف تم تغييره، وبعد تكرار حالات الفشل، يتم تشغيل cm verify. يُرجى زيادة مهلة الانتظار قبل ربط الخطاف بـ cm الحقيقي.

يعمل النموذج -i.bak مع كل من GNU وBSD (macOS) sed:

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

ملاحظة: لا يعترض الـ hook سوى عمليات الدفع التي يُجريها الوكيل من خلال أداة Terminal. يؤدي تشغيل git push بنفسك في واجهة أوامر إلى تجاوزها بالكامل، وهو أمر مفيد عندما تحتاج إلى إرسال ملفات الربط لأول مرة. لإنشاء بوابة تغطي أيضًا عمليات الدفع اليدوية، يمكنك تثبيت النص البرمجي نفسه كخطاف pre-push في git.

7. طريقة عمل خطّاف بوابة الأمان

‫security_gate_hook.sh هي نقطة دخول بسيطة تستخدم ثلاث وحدات من .agents/lib/:

الوحدة	الدور
gate_common.sh	الإعدادات التلقائية، ومخرجات allow/deny، وترتيب الخطورة، وسجلّ تدقيق NDJSON، واحتساب المحاولات، وأدوات المساعدة في عمليات الإرسال وCONTEXT.md.
engine_semgrep.sh	المرحلة 1: فحص حتمي اختياري باستخدام Semgrep يتم تخطّي هذا الإجراء إذا لم يكن "semgrep" مفعَّلاً على "PATH".
engine_codemender.sh	المرحلة 2: فحص دلالي باستخدام cm find، وتصنيف، وتتبُّع المحاولات، وتصعيد cm verify

الخطوة 1: تحديد ما إذا كان هذا إشعارًا فوريًا

تستخرج نقطة الدخول الأمر من حمولة stdin وتختبره مقابل تعبير نمطي يتعرّف على git push في أشكاله الشائعة (git -C /repo push وcd x && git push وsudo git push) مع تجاهل النص المقتبس مثل git commit -m "before git push". يُسمح فورًا بأي إجراء لا يتعلّق بالدفع:

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: اختيار الماسحات الضوئية

يختار "SECURITY_GATE_SCANNER" مسار المعالجة. يؤدي الخيار التلقائي auto إلى تشغيل أي من Semgrep وCodeMender المثبّتَين، بهذا الترتيب:

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

عندما تعثر المرحلة الأولى على مشاكل حظر في وضع المسار، لا ترفضها من تلقاء نفسها، بل تكتبها في ملف مؤقت تلتقطه المرحلة الثانية، وبالتالي يكون لـ CodeMender الكلمة الأخيرة.

الخطوة 3: مرحلة CodeMender

تنفّذ دالة run_codemender_gate في engine_codemender.sh ما يلي بالترتيب:

1. العثور على الملفات التي تم تغييرها باستخدام git diff --name-only origin/main (الرجوع إلى HEAD~1). يعني عدم إجراء أي تغييرات السماح بذلك.
2. افحص كل ملف باستخدام cm find "$file" -y --bypass-warning، ثم اسحب كل شيء باستخدام cm report --format json. إذا تعذّر تنفيذ cm report أو عرض ملف JSON غير صالح، يشير ذلك إلى حدوث خطأ في الفحص، وليس إلى نتيجة نظيفة.
3. فلترة النتائج التي تكون حالتها OPEN أو REOPENED والتي ينتهي file_path الخاص بها بأحد الملفات التي تم تغييرها يتم تجاهل النتائج التي سبق لك إصلاحها أو تجاهلها في CodeMender CLI Basics.
4. تصنيف كل نتيجة يتم حظر مستوى الخطورة الذي يساوي SECURITY_GATE_BLOCK_SEVERITY أو يزيد عنه (القيمة التلقائية هي HIGH)، أما أي مستوى أقل من ذلك فيكون استشاريًا ويتم تسجيله وطباعته، ولكنه لا يوقف عملية الإرسال.
5. السماح في حال عدم وجود أي حظر: إذا اختفت النتيجة التي حظرت عملية دفع سابقة، يسجّلها البوّابة على أنّها FIXED، ويُلحق اصطلاحًا بـ CONTEXT.md ضمن ## 4. Continuous Evolution، ويُثبّت هذا التغيير.
6. احتساب المحاولات لكل نتيجة حظر من خلال قراءة سجلّ التدقيق الخاص بها ويُعدّ كل رفض محاولة واحدة. في المحاولات من 1 إلى SECURITY_GATE_MAX_RETRIES (القيمة التلقائية هي 3)، يسجّل البوابة DENIED_TO_AGENT ويضيف النتيجة إلى رسالة رفض.
7. تصعيد المشكلة بعد إنفاق الميزانية في المحاولة الرابعة للنتيجة نفسها، يشغّل البوابة cm verify. إذا لم تكن الثغرة قابلة للاستغلال (رمز الخروج 1 أو الحالة DISMISSED)، يتم تخفيض تصنيفها إلى "إرشادية". إذا تم تأكيد ذلك أو تعطّل "cm verify"، يسجّل البوابة "BLOCKED" ويرفض الطلب مع طلب إجراء مراجعة يجريها فريق.
8. الرفض مع تقديم تعليمات: إذا بقيت أي نتائج قابلة للتنفيذ، ستعرض البوابة هذا السبب للوكيل:

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

هذا هو التسليم بين الخطاف والمهارات. لا يستدعي الـ hook الدالة cm fix. ويحدّد المهارات التي يجب أن يستخدمها الوكيل، وينفّذ الوكيل الإصلاح المستند إلى الاختبار أولاً، ثم يعيد git push التالي تشغيل البوابة.

ملاحظة: تعيد البوابة استخدام قاعدة بيانات CodeMender العامة في ~/.codemender/state.db، وهي نفسها التي يقرأها cm report. بما أنّها تفلتر حسب مسار الملف وحالة OPEN، فإنّ النتائج القديمة المتعلّقة بـ sample_app/data_service.py من CodeMender CLI Basics التي لم يتم إصلاحها (على سبيل المثال، حقن أوامر نظام التشغيل في /ping) ستحظر عملية الدفع الأولى التي تؤثر في هذا الملف. هذا مقصود، فالبوابة لا تضع في اعتبارها "التعليقات الموجودة مسبقًا"، بل "التعليقات المفتوحة في ملف يتم دفعه".

مرجع الإعدادات

جميع الإعدادات هي متغيّرات بيئة تم ضبطها تلقائيًا في gate_common.sh:

متغيّر	تلقائي	التأثير
SECURITY_GATE_SCANNER	auto	‫auto أو codemender (أو cm) أو semgrep
SECURITY_GATE_BLOCK_SEVERITY	HIGH	أدنى مستوى خطورة يحظر النشر CRITICAL أو HIGH أو MEDIUM أو LOW
SECURITY_GATE_MAX_RETRIES	3	عدد حالات الرفض لكل نتيجة قبل استشارة "cm verify"
SECURITY_GATE_ALLOW_ON_ERROR	false	يسمح true بإجراء عملية دفع عند تعذُّر تشغيل الماسح الضوئي، مع وضع علامة على عملية الإرسال unverified-scan-.
SECURITY_GATE_TEST_CMD	python3 -m unittest discover -s tests	أمر الاختبار المقتبس في مطالبات الرفض ورسائل الالتزام.
SECURITY_GATE_EVOLVE_CONTEXT	true	إلحاق الاتفاقيات التي تم التحقّق منها بـ CONTEXT.md
SECURITY_GATE_LOG	.security-gate/findings-log.ndjson	سجلّ تدقيق للإلحاق فقط
SECURITY_GATE_NOTIFY_CMD	(فارغ)	أمر اختياري يتلقّى كل حدث بوابة كملف JSON على stdin.

ملاحظة: تكتسب الخطافات بيئة Antigravity، والتي يصعب تغييرها لكل مساحة عمل. لتثبيت إعداد، ضعه في السلسلة command في hooks.json، على سبيل المثال "command": "SECURITY_GATE_SCANNER=codemender bash -c '...'". يُعدّ فرض استخدام codemender خيارًا جيدًا لهذا التمرين إذا كان Semgrep مثبّتًا لديك وأردت استخدام أداة فحص واحدة يمكن توقّع نتائجها.

8. التحقّق من Hook بلا إنترنت

قبل أن يتفاعل البوّابة مع cm الحقيقي، تأكَّد من أنّه يعمل بشكل صحيح مع النماذج الوهمية. يوفّر إطار العمل مفعِّل اختبار يتضمّن ملفات ثنائية زائفة لـ cm وsemgrep تغطي مسارات السماح والإرشاد والرفض والخطأ والتصعيد:

bash .agents/tests/run_tests.sh

يستغرق التشغيل بضع ثوانٍ وينتهي بما يلي:

-- test_pipeline_tools_missing_passes_smoothly
-- test_skills_frontmatter_valid
60 passed, 0 failed

يتحقّق الاختبار الأخير أيضًا من صحة البيانات الوصفية لكل مهارة ضمن .agents/skills/، لذا يجب إعادة تشغيل هذا الأمر بعد تعديل SKILL.md.

بعد ذلك، يمكنك محاكاة ما يرسله Antigravity لأمر ليس إشعارًا فوريًا. يجب أن يجيب النص على allow بدون لمس أي ماسح ضوئي:

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

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

يمكنك الآن محاكاة عملية دفع بدون تغييرات محلية على origin/main. بما أنّه لا يتوفّر مستودع عن بُعد بعد، يعود البوابة إلى HEAD~1 ويفحص الملفات من آخر عملية دمج. لإبقاء هذه الخطوة بلا إنترنت، وجِّهها إلى cm و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"}

تم تنفيذ المرحلتَين لأنّ الدليل الوهمي يحتوي على semgrep مزيّف بالإضافة إلى cm مزيّف. تنتقل رسائل مستوى التقدّم إلى stderr وينتقل قرار JSON فقط إلى stdout، وهو ما يتيح لـ Antigravity تحليل النتيجة.

تحذير: يؤدي تشغيل حمولة البيانات نفسها بدون البادئة الوهمية PATH إلى استدعاء cm find وcm report الحقيقيين في مساحة العمل. هذه طريقة مشروعة لاختبار البوابة من طرف إلى طرف من محطة طرفية، ولكنها تستغرق عدة دقائق وستبلغ عن أي نتائج مفتوحة في الملفات من آخر عملية إرسال. يمكنك حفظه للدرس التطبيقي التالي حول الترميز، حيث يكون هذا السلوك هو النقطة الأساسية.

أخيرًا، عليك تنفيذ ملفات إطار العمل لكي يتم نقلها مع المستودع:

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

9. فتح مساحة العمل في Antigravity

افتح ~/codemender-lab كمجلد في Antigravity. بعد تحميل الوكيل، يتوفّر له ما يلي:

• قاعدة secure_tdd_workflow في كل دور
• المهارات الست المتاحة عند الطلب.
• تم تسجيل الخطاف security-gate في run_command.

للتأكّد بسرعة من أنّ المهارات ظاهرة، يمكنك أن تسأل الوكيل في محادثة جديدة: "ما هي مهارات Workspace المتاحة لديك، وما هي وظيفة كل منها؟" يجب أن يسرد الستة بالاسم.

الأذونات

يتم تشغيل الرمز البرمجي بواسطة Antigravity، وليس بواسطة الوكيل، لذا لا يمرّ عبر طلبات إذن الأداة. بل أوامر الوكيل نفسه. خلال الدرس التطبيقي التالي حول الترميز، ستظهر لك طلبات الموافقة على أمر الاختبار وعمليات git وأي أمر cm يقرر الوكيل تنفيذه مباشرةً. يُرجى الموافقة عليها عند طلبها. إذا عرضت Antigravity تذكُّر القرار الخاص ببادئة أمر، فإنّ قبول ذلك يتجنّب إعادة الطلب في جميع مراحل التكرار.

ماذا يحدث في ‎git push؟

1. يستدعي الوكيل أداة Terminal مع git push origin main.
2. تطابق أداة Antigravity السمة run_command مع hooks.json وتُشغّل security_gate_hook.sh مع استدعاء الأداة على stdin.
3. يتعرّف النص البرمجي على عملية دفع، ويعثر على الملفات التي تم تغييرها، ويفحصها باستخدام cm find، ويقرأ cm report.
4. إذا لم يتم حظر أي شيء، ستتم طباعة {"decision": "allow"} وستتم متابعة عملية الإرسال.
5. إذا كانت النتائج محظورة، ستظهر الرسالة {"decision": "deny", "reason": "..."}. لا يتم تنفيذ عملية الإرسال، ويرى الوكيل السبب، وتخبره القاعدة الدائمة بالإضافة إلى المهارات المُسمّاة بما يجب فعله بعد ذلك: اختبار واحد فاشل، وإصلاح واحد بسيط، وإعادة تشغيل المجموعة، والإرسال مرة أخرى.

تهانينا! لقد أكملت الدرس التطبيقي حول الترميز "مهارات CodeMender وخطافات Antigravity". في الدرس التطبيقي التالي حول الترميز، ستطلب من الوكيل إضافة ميزة جديدة وستشاهد هذه الحلقة تعمل من البداية إلى النهاية، بدءًا من نموذج التهديد وحتى إرسال التغييرات التي تجتاز الاختبارات.