מיומנויות ו-hooks של CodeMender ל-Antigravity

1. מבוא

ב-Codelab הזה תגדירו סוכן תכנות מבוסס-AI‏ (Antigravity) כדי שהאבטחה תהיה חלק מתהליך הפיתוח הרגיל שלו, ולא שלב בדיקה נפרד. תתקינו קבוצה של מיומנויות סוכן שמנחות את הסוכן במחזור של תכנון ← אדום ← ירוק ← ארגון מחדש של הקוד, ו-hook של PreToolUse שמיירט את git push, סורק את הקבצים שהשתנו באמצעות CodeMender ומחזיר את הממצאים לסוכן עם הוראות לתקן אותם קודם בבדיקה.

הסקילים וההוק מגיעים מ-Secure TDD Agent Framework בקוד פתוח. אתם תתקינו אותם באותה סביבת עבודה ב-~/codemender-lab שיצרתם ב-CodeMender CLI Basics.

טיפ: נכון לעכשיו, CodeMender זמין לגרסת טרום-השקה ציבורית לקבוצה מוגבלת של לקוחות. כדי לקבל גישה, פנו לצוות המכירות.

מה תלמדו

• איך Antigravity מגלה כללים, מיומנויות ו-hooks של סביבת העבודה ב-.agents/.
• מה עושות שש המיומנויות של Secure TDD ובאיזה שלב בלולאה כל אחת מהן פועלת.
• איך הוק של PreToolUse מקבל את קריאת ה-API לכלי של הנציג ב-stdin ומחזיר החלטה אם לאשר או לדחות.
• איך ה-hook של שער האבטחה (security_gate_hook.sh) מריץ את cm find, מסווג את הממצאים לפי חומרה, עוקב אחרי ניסיונות התיקון ומעביר את הטיפול ל-cm verify.
• איך לאמת את כל צינור העיבוד של ה-hook אופליין באמצעות סורקים מדומים לפני שמפנים אותו אל cm האמיתי.

דרישות מוקדמות

• השלמת הקורס "העקרונות הבסיסיים של CodeMender CLI". ה-Lab הזה ממשיך בספרייה ~/codemender-lab ומשתמש מחדש ב-sample_app/, ב-CONTEXT.md, בהיסטוריית ה-Git וב-~/.codemender/config.yaml.
• Antigravity מותקן, עם אפשרות לפתוח תיקייה מקומית כסביבת עבודה.
• ‫git,‏ jq ו-bash מותקנים. סקריפטי ה-hook הם סקריפטים פשוטים של bash והם פועלים ב-bash 3.2 המובנה של macOS וגם בגרסאות חדשות יותר.
• הסביבה הווירטואלית של Python מ-CodeMender CLI Basics (~/codemender-lab/.venv) עם Flask מותקן.
• ידע בסיסי בכתיבת סקריפטים של מעטפת.

2. הגדרת Workspace

שלב 1: חוזרים למאגר של Lab

כל הפקודות ב-Lab הזה מופעלות מ-~/codemender-lab כשהסביבה הווירטואלית פעילה:

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

מוודאים שסביבת העבודה מהשיעור הקודם תקינה ושעץ העבודה נקי:

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

הפקודה git status --short לא אמורה להדפיס כלום. אם מופיעים קבצים, צריך לבצע commit לפני שממשיכים.

שלב 2: נותנים שם להסתעפות main

שער האבטחה משווה בין עץ העבודה לבין origin/main כדי להחליט אילו קבצים לסרוק. אם ההפניה הזו לא קיימת, המערכת חוזרת ל-HEAD~1, שמכסה רק את ה-commit האחרון. מוודאים שההסתעפות נקראת 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, וייתכן שמחזור מאוחר יותר של Secure TDD יחליף אותו. מכיוון שהבדיקה רק מוודאת שהתוצאה היא מחרוזת הקסדצימלית, היא ממשיכה לעבור כשהמצב הזה קורה. בקובץ ה-README של המסגרת, הבדיקה הזו נקראת "בדיקת אפיון" ומומלץ לבצע אותה כשלב ראשון לפני שנוגעים בקוד מדור קודם.

שלב 4: מרחיבים את .gitignore ומאשרים את השינויים

מוסיפים את קובצי זמן הריצה שנוצרו ב-Lab הזה ל-.gitignore, ואז מבצעים commit של קו הבסיס:

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

3. התקנת קובצי המסגרת

היכולות, הכלל, ה-hook ומסגרת הבדיקה אופליין נמצאים כולם בספרייה אחת של .agents/. במקום להקליד ידנית כ-800 שורות של bash, משכפלים את ה-framework ומעתיקים את הספרייה הזו לסביבת העבודה:

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

מוודאים שנקודת הכניסה של ה-hook ניתנת להפעלה:

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

הערה: Antigravity מגלה התאמות אישיות של סביבת העבודה על ידי מעבר על הספרייה .agents/ בתיקיית הבסיס של התיקייה הפתוחה: rules/*.md להוראות שפועלות תמיד או מותנות, skills//SKILL.md להליכים על פי דרישה ו-hooks.json ל-lifecycle hooks. לא צריך לרשום שום דבר אחר. אם Antigravity כבר פתוח בתיקייה הזו, צריך לסגור ולפתוח אותו מחדש אחרי העתקת הקבצים כדי שהוא יזהה את hooks.json.

בשיעור ה-Lab הזה נסביר מה התקנתם, חלק אחר חלק.

4. כלל תהליך העבודה "זמינות תמידית"

הסוכן טוען את המיומנויות לפי הצורך, כשהוא מחליט שתיאור המיומנות מתאים למשימה. משהו צריך להגיד לסוכן להגיע אליהם בסדר הנכון. זה התפקיד של .agents/rules/secure_tdd_workflow.md. ה-frontmatter שלו מגדיר את 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 CLI Basics. אותו קובץ שהנחה את cm fix לגבי מוסכמת השאילתה עם הפרמטרים מנחה עכשיו את התכנון של הנציג. פריט 6 הוא החשוב ביותר במעבדה הזו: זה מה שהסוכן פועל לפיו כששער האבטחה דוחה דחיפה עם כמה ממצאים בבת אחת.

טיפ: הכללים תומכים בטריגרים נוספים מלבד always_on: model_decision (הסוכן קורא description ומחליט אם לטעון את הכלל), glob (מופעל כשקבצים תואמים פתוחים) ו-manual (רק כשמתייגים אותו באמצעות @). always_on עולה אסימונים בכל תור, אז כדאי שהכללים האלה יהיו קצרים ולהעביר את הפרטים למיומנויות.

5. ששת הסקילים האג'נטיים

כל מיומנות היא ספרייה שמכילה SKILL.md עם Frontmatter של YAML. צריך למלא שני שדות:

• ‫name: מזהה באותיות קטנות עם מקפים.
• ‫description: מה הסקיל עושה ומתי להשתמש בו. הסוכן קורא רק את השדה הזה כשהוא מחליט אם לטעון את הסקיל המלא, לכן כל תיאור בהמשך מציין גם למה הסקיל לא מיועד.

מיומנות	שלב	מטרה
threat-model-assessor	תשובה: תוכנית	הגדרת היקף התכונה, הפעלת STRIDE, כתיבת threat_model.md.
security-test-writer	B: אדום	לכתוב בדיקות פונקציונליות ובדיקות גבולות שנכשלות מהסיבה הנכונה.
defensive-developer	C: ירוק	כתבו את הקוד המינימלי שגורם לבדיקות להצליח, באמצעות תבניות בטוחות.
local-refactor-scanner	D: Refactor	מנקים, מריצים את חבילת הבדיקות המלאה, מריצים סורקים מקומיים, בודקים את ההבדלים.
skill-evolution-updater	Continuous	מתעדים מוסכמות חדשות בקובצי CONTEXT.md ו-SKILL.md.
history-context-seeder	תהליך הגדרה	אפשר לחפש בהיסטוריית Git כדי להוסיף את CONTEXT.md למאגר קיים.

התוכן המלא מופיע בהמשך כדי שתוכלו לראות איך ה-frontmatter וההוראות משתלבים יחד.

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.

אזהרה: המיומנות הזו מאפשרת לסוכן לערוך את ההוראות שלו. זה נוח למפתח עצמאי שעובד בארגז חול כמו בשיעור ה-Lab הזה. בסביבת עבודה של צוות, בקובץ ה-README של המסגרת מומלץ שהסוכנים יציעו שינויים במיומנויות (כ-PR או ככרטיס) במקום להחיל אותם ישירות על מאגר מיומנויות משותף.

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. הגדרת ה-Hook של Antigravity

‫.agents/hooks.json מורה ל-Antigravity להריץ את שער האבטחה לפני כל פקודת טרמינל שהסוכן מריץ:

{
  "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 הוא ביטוי רגולרי (regex) של שמות כלים, לא של טקסט פקודה. ‫PreToolUse מופעל לפני שכלי פועל, וההתאמה קובעת אילו כלים. ‫run_command הוא כלי הטרמינל של Antigravity. החלופות האחרות כוללות וריאציות של מרחבי שמות של פלאגינים ופלטפורמות אחרות של סוכנים שמשתפות את הקבצים האלה. התאמה כמו git push* אף פעם לא תופעל כי אין כלי עם שם כזה. הסינון של הפקודה עצמה מתבצע בתוך הסקריפט.
• ה-hook מקבל את קריאת ה-API לכלי ב-stdin. ‫Antigravity מעביר מטען ייעודי (payload) של JSON כמו {"toolCall": {"name": "run_command", "args": {"CommandLine": "git push origin main"}}, ...}. הסקריפט קורא את .toolCall.args.CommandLine ויוצא מיד עם החלטת אישור לכל מה שאינו git push.
• ספריית העבודה היא הספרייה שמכילה את hooks.json, ולכן ה-hook מתחיל בתוך .agents/. ה-wrapper של bash -c 'if [ -x ./security_gate_hook.sh ] ...' מטפל גם במקרה הזה וגם בהפעלה מהשורש של המאגר. לאחר מכן, הסקריפט cd אל git rev-parse --show-toplevel לפני ביצוע פעולה כלשהי.
• הסקריפט משיב ב-stdout באמצעות JSON. ‫{"decision": "allow"} מאפשרת להריץ את הפקודה המקורית. מערכת {"decision": "deny", "reason": "..."} חוסמת את ההודעה ומציגה לנציג את הסיבה לכך. ה-framework גם פולט ערך בוליאני של allow_tool כדי לאפשר תאימות עם חוזי הוק ישנים יותר.
• הוקים פועלים באופן סינכרוני וחוסמים את לולאת הסוכן עד שהם מסתיימים או מגיעים ל-timeout (בשניות, ברירת המחדל היא 30 אם לא צוין ערך).

אזהרה: 120 שניות זה זמן קצר מדי להפעלה אמיתית של CodeMender. ב-CodeMender CLI Basics, cm find בקובץ אחד נמשך בערך דקה, ו-cm verify בערך שלוש דקות. השער מריץ את cm find פעם אחת לכל קובץ שהשתנה, ואחרי כמה כישלונות הוא מריץ את cm verify. צריך להגדיל את זמן הקצוב לתפוגה לפני שמחברים את ה-hook ל-cm האמיתי.

הפורמט -i.bak פועל גם עם GNU וגם עם BSD (macOS) sed:

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

טיפ: ה-hook מיירט רק דחיפות שהנציג מבצע דרך כלי הטרמינל שלו. אם מריצים את git push בעצמכם במעטפת, אתם עוקפים את זה לגמרי, וזה שימושי כשצריך לדחוף את קובצי ה-hook בפעם הראשונה. כדי להגדיר שער שכולל גם דחיפות ידניות, צריך להתקין את אותו הסקריפט בתור הוק pre-push של git.

7. איך פועל ה-Security Gate Hook

‫security_gate_hook.sh היא נקודת כניסה קטנה שמקבלת שלושה מודולים מ-.agents/lib/:

יחידת לימוד	תפקיד
gate_common.sh	הגדרות ברירת מחדל, פלט allow/deny, דירוג חומרה, יומן הביקורת של NDJSON, ספירת ניסיונות, פונקציות עזר של commit ו-CONTEXT.md.
engine_semgrep.sh	שלב 1. סריקה דטרמיניסטית אופציונלית באמצעות Semgrep. המערכת מדלגת על השלב הזה אם semgrep לא מותקן ב-PATH.
engine_codemender.sh	שלב 2. סריקה סמנטית באמצעות cm find, סיווג, מעקב אחרי ניסיונות והעברה לטיפול ברמה גבוהה יותר באמצעות cm verify.

שלב 1: מחליטים אם מדובר בדחיפה

נקודת הכניסה מחלצת את הפקודה ממטען הייעודי (payload) של 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

כאשר שלב 1 מוצא בעיות חסימה במצב צינור עיבוד נתונים, הוא לא דוחה אותן בעצמו. הוא כותב אותן לקובץ זמני ששלב 2 אוסף, כך שההחלטה הסופית היא של 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) חוסמת את הפעולה. כל רמה נמוכה יותר היא בגדר המלצה, נרשמת ביומן ומודפסת, אבל לא עוצרת את פעולת ה-push.
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) יחסמו את ה-push הראשון שנוגע בקובץ הזה. זה מכוון: לשער אין מושג לגבי "קיים מראש", אלא רק לגבי "פתוח בקובץ שאתם דוחפים".

הפניה להגדרות האישיות

כל ההגדרות הן משתני סביבה עם ערכי ברירת מחדל שמוגדרים ב-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 מאפשרת לדחוף קוד כשסורק לא פועל, ומתייגת את ה-commit בתור unverified-scan-.
SECURITY_GATE_TEST_CMD	python3 -m unittest discover -s tests	פקודת הבדיקה שצוטטה בהודעות commit ובהנחיות לדחייה.
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 '...'". אם Semgrep מותקן אצלכם ואתם רוצים סורק אחד שניתן לחיזוי, כדאי לאלץ את codemender בשיעור ה-Lab הזה.

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

הבדיקה האחרונה גם מאמתת את ה-frontmatter של כל מיומנות ב-.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 וסורק את הקבצים מה-commit האחרון. כדי להשאיר את השלב הזה אופליין, צריך להפנות אותו אל ה-mock של 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 לנתח את התוצאה.

אזהרה: אם מריצים את אותו מטען ייעודי (payload) של דחיפה בלי הקידומת המדומה PATH, מתבצעת קריאה ל-cm find ול-cm report האמיתיים בסביבת העבודה. זו דרך לגיטימית לבדוק את השער מקצה לקצה ממסוף, אבל היא נמשכת כמה דקות ומדווחת על כל הממצאים הפתוחים בקבצים מה-commit האחרון. שמרו את זה ל-Codelab הבא, שבו ההתנהגות הזו היא העניין.

בסוף, מבצעים commit לקובצי ה-framework כדי שהם יועברו עם המאגר:

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

9. פתיחת סביבת העבודה ב-Antigravity

פותחים את ~/codemender-lab כתיקייה ב-Antigravity. אחרי שהסוכן נטען, יש לו:

• הכלל של secure_tdd_workflow בכל תור.
• שש המיומנויות זמינות על פי דרישה.
• ה-hook של security-gate נרשם ב-run_command.

דרך מהירה לוודא שהמיומנויות גלויות היא לשאול את הסוכן בשיחה חדשה: "אילו מיומנויות של Workspace זמינות לך, ומה כל אחת מהן עושה?" צריך לציין את שמות ששת המאפיינים.

הרשאות

ה-hook עצמו מופעל על ידי Antigravity, ולא על ידי הנציג, ולכן הוא לא עובר דרך ההנחיות להרשאות של הכלים. הפקודות של הנציג עצמו כן. במהלך ה-Codelab הבא, צפו להנחיות אישור לפקודת הבדיקה, לפעולות של git ולכל פקודת cm שהנציג מחליט להריץ ישירות. אשרו אותן כשתתבקשו. אם Antigravity מציע לזכור את ההחלטה לגבי קידומת של פקודה, קבלת ההצעה תמנע בקשות חוזרות במהלך הלולאה.

מה קורה ב-git push

1. הנציג מפעיל את כלי הטרמינל שלו עם git push origin main.
2. ‫Antigravity מתאים את run_command ל-hooks.json ומריץ את security_gate_hook.sh עם קריאת ה-API לכלי ב-stdin.
3. הסקריפט מזהה דחיפה, מוצא קבצים שהשתנו, סורק אותם באמצעות cm find וקורא את cm report.
4. אם אין חסימה, מודפס {"decision": "allow"} והדחיפה ממשיכה.
5. אם הממצאים חוסמים, יודפס {"decision": "deny", "reason": "..."}. הדחיפה לא פועלת, הסוכן רואה את הסיבה, והכלל שפועל תמיד בתוספת המיומנויות שצוינו אומרים לו מה לעשות הלאה: בדיקה אחת שנכשלה, תיקון מינימלי אחד, הפעלה מחדש של החבילה, דחיפה שוב.

מעולה! סיימתם את שיעור ה-Codelab בנושא מיומנויות ו-hooks של CodeMender ל-Antigravity. ב-Codelab הבא תתנו לסוכן הגשת בקשה להוספת תכונה ותראו את הלולאה הזו פועלת מקצה לקצה, ממודל האיומים ועד לדחיפה שעוברת את השער.