kortext 1.0.0 → 2.2.3

package/rules/models.md

@@ -0,0 +1,93 @@
+# Model Konfigürasyonu
+
+Bu dosya, personanın görev türüne göre hangi model profilini kullanacağını merkezi olarak tanımlar. Persona dosyalarında doğrudan model adı yazılmaz; persona dosyaları yalnızca görev kategorisini belirtir.
+
+## Görev Kategorileri
+
+| Kategori | Kullanım Alanı | Varsayılan Profil | Fallback Profil |
+| :--- | :--- | :--- | :--- |
+| `deep-research` | Araştırma, analiz, mimari tasarım, strateji, karmaşık kod üretimi, güvenlik değerlendirmesi | `high-reasoning` | `standard-reasoning` |
+| `routine` | Format düzenleme, standart güncelleme, raporlama, basit denetim, düşük riskli rutin işler | `fast-reasoning` | `standard-reasoning` |
+
+## Model Profilleri
+
+| Profil | Beklenen Özellik | Kullanım |
+| :--- | :--- | :--- |
+| `high-reasoning` | En güçlü muhakeme, uzun bağlam, karmaşık analiz | Kritik teknik kararlar ve çok adımlı üretim işleri |
+| `standard-reasoning` | Dengeli muhakeme ve hız | Fallback veya orta karmaşıklıktaki işler |
+| `fast-reasoning` | Hızlı cevap, düşük maliyet | Rutin raporlama ve basit kontrol işleri |
+
+## Rol → Kategori Ataması
+
+| Persona | Varsayılan Kategori | Not |
+| :--- | :--- | :--- |
+| `+operation-manager` | `routine` | Orkestrasyon, durum takibi, raporlama |
+| `+product-manager` | `deep-research` | Ürün gereksinimi, kapsam ve önceliklendirme |
+| `+engineering-manager` | `deep-research` | Mimari, teknik karar, code review |
+| `+delivery-manager` | `routine` | Release koordinasyonu ve teslimat raporları |
+| `+backend-developer` | `deep-research` | Backend uygulama ve servis mantığı |
+| `+frontend-developer` | `deep-research` | UI uygulama ve frontend mimarisi |
+| `+db-admin` | `deep-research` | Veri modeli, migration, performans |
+| `+devops-engineer` | `routine` | CI/CD, ortam, deployment operasyonları |
+| `+qa-engineer` | `routine` | Test yürütme, doğrulama, raporlama |
+| `+security-engineer` | `deep-research` | Güvenlik analizi, risk ve zafiyet değerlendirmesi |
+| `+designer` | `deep-research` | Tasarım sistemi, UX/UI değerlendirmesi |
+| `+copywriter` | `deep-research` | İçerik stratejisi, marka dili, mikro metin |
+| `+growth-expert` | `deep-research` | SEO/GEO, analitik, büyüme stratejisi |
+| `+compliance-expert` | `deep-research` | KVKK/GDPR ve yasal değerlendirme |
+
+## Sağlayıcı Seçimi
+
+Gerçek model ID'leri sağlayıcıya ve kurulu ortama göre değişebilir. Bu nedenle model ID'leri persona dosyalarına yazılmaz.
+
+## Resmi Model Kaynakları
+
+Model seçimi veya model güncellemesi yapılmadan önce sağlayıcının resmi model dokümantasyonu kontrol edilir.
+
+| Sağlayıcı | Resmi Kaynak |
+| :--- | :--- |
+| Anthropic / Claude | https://docs.anthropic.com/en/docs/about-claude/models/overview |
+| Google / Gemini | https://ai.google.dev/gemini-api/docs/models |
+| OpenAI | https://developers.openai.com/api/docs/models |
+
+## Güncellik Kuralı
+
+- +prime "en güncel", "latest" veya belirli bir sağlayıcıdaki yeni model ailesini isterse ajan resmi model dokümanını kontrol etmeden model önermemelidir.
+- Varsayılan tercih +prime aksi yönde belirtmedikçe en güncel uygun modeldir.
+- Production kullanımında model ID sabitlenmesi gerekiyorsa ilgili snapshot/stable ID `workspace/references/access.md` veya `workspace/references/tech-stack.md` içinde ayrıca belgelenir.
+- Bir sağlayıcının "latest" alias'ı ile sabit snapshot ID'si farklı amaçlara hizmet ediyorsa bu fark raporda açıkça belirtilir.
+
+Model seçimi yapılırken:
+
+1. Önce görevin kategorisi belirlenir.
+2. Resmi model kaynağı kontrol edilir.
+3. Kategoriye karşılık gelen varsayılan profil seçilir.
+4. Mevcut ortamda bu profile karşılık gelen en güncel uygun model kullanılır.
+5. Model erişilemezse fallback profil kullanılır.
+6. Fallback kullanımı `workspace/reports/status-reports.md` veya ilgili görev raporuna not edilir.
+
+## Fallback Politikası
+
+- Fallback modeli aynı görevi tamamlamak için yeterliyse işlem devam eder.
+- Fallback kalite riski oluşturuyorsa görev `Blocked` yapılır ve +operation-manager'a eskale edilir.
+- `deep-research` görevlerinde fallback kullanıldıysa sonuç kalitesi özellikle belirtilir.
+- API/LLM kesintilerinde retry ve fallback sırası `rules/emergency.md` içindeki Self-Healing Protocol'e göre yürütülür.
+
+## Persona Dosyalarında Kullanım
+
+Persona dosyalarının `instructions` bölümünde her görev adımında model adı yerine kategori referansı kullanılır:
+
+```markdown
+### 1. Araştırma Protokolü
+**Kategori:** `deep-research`
+
+### 2. Rutin Güncelleme
+**Kategori:** `routine`
+```
+
+## Güncelleme Politikası
+
+- Model profili veya kategori değişikliklerinde yalnızca bu dosya güncellenir.
+- Gerçek sağlayıcı/model ID eşleşmeleri proje ortamına göre `workspace/references/tech-stack.md` veya `workspace/references/access.md` içinde belgelenir.
+- Model değişikliği önerisi +operation-manager tarafından yapılır.
+- Stratejik model değişikliği +prime onayı gerektirir.

package/scripts/kortext-backlog-add.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+
+BACKLOG_ROOT = Path("workspace/memory/backlog")
+
+
+def _atomic_commit(message: str, paths: list[str]) -> None:
+    # Kortext atomic operation: dosyaları add edip commit'ler.
+    if not shutil.which("git"):
+        return
+    try:
+        subprocess.run(["git", "add", "--", *paths], check=True, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", message, "--", *paths],
+            check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError:
+        return
+
+
+def slugify(title: str) -> str:
+    return "-".join(title.lower().split())
+
+
+def dashboard_path(kind: str) -> Path:
+    mapping = {
+        "version": BACKLOG_ROOT / "version-dashboard.md",
+        "epic": BACKLOG_ROOT / "epic-dashboard.md",
+        "debt": BACKLOG_ROOT / "debt-dashboard.md",
+    }
+    return mapping[kind]
+
+
+def append_row(path: Path, row: str) -> None:
+    content = path.read_text() if path.exists() else ""
+    if row not in content:
+        if content and not content.endswith("\n"):
+            content += "\n"
+        content += row + "\n"
+        path.write_text(content)
+
+
+def build_item_content(item_type: str, item_id: str, title: str, persona: str, epic: str | None) -> str:
+    date_str = datetime.now().strftime("%Y.%m.%d-%H:%M")
+    epic_line = f"> **Epic:** {epic}\n" if epic else ""
+    return f"""# {item_id}: {title}
+{epic_line}> **Assignee:** [{persona}]
+> **Model:** [selected-ai-model]
+> **Status:** To Do
+
+---
+
+## Description
+{title} açıklaması.
+
+## Acceptance Criteria
+- [ ] Code review
+- [ ] Quality control
+- [ ] Security check
+
+## Dependencies
+- [task-id] - [task-name]
+
+## Work Log
+- **[{date_str}] ({persona}):** {item_type.capitalize()} oluşturuldu.
+
+## Decisions
+- [alınan karar]
+
+## Notes
+- [notlar]
+"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Kortext Backlog Add Tool")
+    parser.add_argument("--type", choices=["task", "bug", "debt"], required=True)
+    parser.add_argument("--id", required=True, help="e.g. T01, B01, D01")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--persona", default="+persona")
+    parser.add_argument("--epic", help="e.g. E01-auth (required for task and bug)")
+    parser.add_argument("--no-commit", action="store_true", help="Atomic git commit'i atla")
+    args = parser.parse_args()
+
+    if args.type in {"task", "bug"} and not args.epic:
+        raise SystemExit("Hata: task ve bug türleri için --epic zorunludur.")
+
+    BACKLOG_ROOT.mkdir(parents=True, exist_ok=True)
+    file_path = BACKLOG_ROOT / f"{args.id}-{slugify(args.title)}.md"
+    file_path.write_text(build_item_content(args.type, args.id, args.title, args.persona, args.epic))
+
+    if args.type in {"task", "bug"}:
+        dashboard = dashboard_path("epic")
+        append_row(
+            dashboard,
+            f"| {args.id} | [{args.title}](./{file_path.name}) | {args.epic} | {args.persona} | To Do |",
+        )
+    else:
+        dashboard = dashboard_path("debt")
+        append_row(
+            dashboard,
+            f"| {args.id} | [{args.title}](./{file_path.name}) | {args.persona} | To Do |",
+        )
+
+    print(f"✅ {args.type.capitalize()} oluşturuldu: {file_path}")
+
+    if not args.no_commit:
+        _atomic_commit(
+            f"chore(kortext): add {args.type} {args.id} [skip ci]",
+            [str(file_path), str(dashboard)],
+        )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/kortext-backlog-health.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Kortext Backlog Health
+----------------------
+Backlog'un genel sağlık durumunu raporlar. Blocker itemlar, stale In Progress'ler,
+review bekleyenler ve hazır (başlanabilir) itemlar özetlenir.
+"""
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+BACKLOG_DIR = ROOT / "workspace/memory/backlog"
+# In Progress backlog item'larının stale eşiği. Env var ile override edilebilir.
+STALE_HOURS = int(os.environ.get("KORTEXT_STALE_HOURS_BACKLOG", "48"))
+
+STATUS_PATTERN = re.compile(r"\*\*Status:\*\*\s*(.+)")
+BLOCKED_BY_PATTERN = re.compile(r"\*\*Blocked By:\*\*\s*(.+)")
+RISK_PATTERN = re.compile(r"\*\*Risk:\*\*\s*(Blocker|High|Critical)", re.IGNORECASE)
+
+
+def parse_items() -> list[dict]:
+    items = []
+    if not BACKLOG_DIR.exists():
+        return items
+    for f in sorted(BACKLOG_DIR.glob("[TBD]*.md")):
+        text = f.read_text(errors="ignore")
+        status_m = STATUS_PATTERN.search(text)
+        blocked_m = BLOCKED_BY_PATTERN.search(text)
+        risk_m = RISK_PATTERN.search(text)
+
+        status = status_m.group(1).strip() if status_m else "?"
+        has_blocker = blocked_m is not None and blocked_m.group(1).strip() not in ("", "-", "Yok")
+        is_high_risk = risk_m is not None
+        mtime = datetime.fromtimestamp(f.stat().st_mtime)
+        age_hours = (datetime.now() - mtime).total_seconds() / 3600
+
+        items.append({
+            "id": f.stem,
+            "status": status,
+            "has_blocker": has_blocker,
+            "is_high_risk": is_high_risk,
+            "age_hours": round(age_hours, 1),
+            "stale": status == "In Progress" and age_hours > STALE_HOURS,
+        })
+    return items
+
+
+def compute_score(items: list[dict]) -> tuple[int, int]:
+    """Basit sağlık skoru: toplam item sayısı üzerinden sorunlu itemları düşür."""
+    total = len(items)
+    if total == 0:
+        return 100, 100
+    problems = sum(1 for i in items if i["stale"] or i["has_blocker"])
+    score = max(0, round((1 - problems / total) * 100))
+    return score, 100
+
+
+def main() -> None:
+    items = parse_items()
+    now = datetime.now().strftime("%d.%m.%Y %H:%M")
+
+    # Grupla
+    todo = [i for i in items if i["status"] == "To Do" and not i["has_blocker"]]
+    in_progress = [i for i in items if i["status"] == "In Progress"]
+    review = [i for i in items if i["status"] == "Review"]
+    blocked = [i for i in items if i["has_blocker"] or i["status"] == "Blocked"]
+    stale = [i for i in items if i["stale"]]
+    done = [i for i in items if i["status"] == "Done"]
+    score, max_score = compute_score(items)
+
+    print("=" * 60)
+    print(f"  KORTEXT BACKLOG HEALTH — {now}")
+    print("=" * 60)
+    print(f"\n  Toplam item       : {len(items)}")
+    print(f"  ✅ Başlanabilir    : {len(todo)}")
+    print(f"  🔄 In Progress     : {len(in_progress)}")
+    print(f"  👀 Review bekliyor : {len(review)}")
+    print(f"  🚫 Bloklu          : {len(blocked)}")
+    print(f"  ⚠️  Stale ({STALE_HOURS}s+)   : {len(stale)}")
+    print(f"  ✔️  Done            : {len(done)}")
+
+    if blocked:
+        print(f"\n  🚫 BLOKLANAN İTEMLAR:")
+        for i in blocked:
+            print(f"    • {i['id']} ({i['status']})")
+
+    if stale:
+        print(f"\n  ⚠️  STALE İTEMLAR:")
+        for i in stale:
+            print(f"    • {i['id']} — {i['age_hours']} saat önce güncellendi")
+
+    if review:
+        print(f"\n  👀 REVIEW BEKLEYENLER (+prime aksiyonu gerekebilir):")
+        for i in review:
+            print(f"    • {i['id']}")
+
+    bar_filled = int(score / 5)
+    bar = "█" * bar_filled + "░" * (20 - bar_filled)
+    print(f"\n  Sağlık Skoru: {score}/{max_score}  [{bar}]")
+    print("=" * 60)
+
+    if score < 50:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/kortext-backlog-sync.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+BACKLOG_ROOT = Path("workspace/memory/backlog")
+
+
+@dataclass
+class Item:
+    item_id: str
+    title: str
+    status: str
+    path: Path
+    epic: str | None
+
+
+def parse_item(path: Path) -> Item:
+    content = path.read_text()
+    header = re.search(r"^# ([TBD]\d+): (.+)$", content, re.M)
+    status = re.search(r"> \*\*Status:\*\* (.+)", content)
+    epic = re.search(r"> \*\*Epic:\*\* (.+)", content)
+    if not header or not status:
+        raise ValueError(f"Geçersiz item şablonu: {path}")
+    return Item(
+        item_id=header.group(1),
+        title=header.group(2),
+        status=status.group(1).strip(),
+        path=path,
+        epic=epic.group(1).strip() if epic else None,
+    )
+
+
+def actual_items() -> list[Item]:
+    items: list[Item] = []
+    for path in BACKLOG_ROOT.glob("*.md"):
+        if path.name.endswith("dashboard.md"):
+            continue
+        if re.match(r"^[TBD]\d+-", path.name):
+            items.append(parse_item(path))
+    return items
+
+
+def expected_epic_rows(items: list[Item]) -> set[str]:
+    return {
+        f"| {item.item_id} | [{item.title}](./{item.path.name}) | {item.epic} | "
+        f"{read_assignee(item.path)} | {item.status} |"
+        for item in items
+        if item.item_id.startswith(("T", "B"))
+    }
+
+
+def expected_debt_rows(items: list[Item]) -> set[str]:
+    return {
+        f"| {item.item_id} | [{item.title}](./{item.path.name}) | "
+        f"{read_assignee(item.path)} | {item.status} |"
+        for item in items
+        if item.item_id.startswith("D")
+    }
+
+
+def read_assignee(path: Path) -> str:
+    match = re.search(r"> \*\*Assignee:\*\* \[(.+)\]", path.read_text())
+    return match.group(1) if match else "+persona"
+
+
+def actual_rows(path: Path) -> set[str]:
+    if not path.exists():
+        return set()
+    return {
+        line
+        for line in path.read_text().splitlines()
+        if re.match(r"^\| [TBD]\d+ \|", line)
+    }
+
+
+def compare(label: str, expected: set[str], actual: set[str]) -> list[str]:
+    failures: list[str] = []
+    for row in sorted(expected - actual):
+        failures.append(f"{label}: eksik satır -> {row}")
+    for row in sorted(actual - expected):
+        failures.append(f"{label}: beklenmeyen satır -> {row}")
+    return failures
+
+
+def main() -> None:
+    items = actual_items()
+    failures: list[str] = []
+    failures.extend(
+        compare(
+            "epic-dashboard.md",
+            expected_epic_rows(items),
+            actual_rows(BACKLOG_ROOT / "epic-dashboard.md"),
+        )
+    )
+    failures.extend(
+        compare(
+            "debt-dashboard.md",
+            expected_debt_rows(items),
+            actual_rows(BACKLOG_ROOT / "debt-dashboard.md"),
+        )
+    )
+
+    if failures:
+        print("❌ Backlog dashboard drift tespit edildi:")
+        for failure in failures:
+            print(f"- {failure}")
+        raise SystemExit(1)
+
+    print("✅ Backlog dashboard'ları item dosyalarıyla uyumlu.")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/kortext-bulk-plan.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+SCRIPT_ADD = Path(__file__).with_name("kortext-backlog-add.py")
+
+
+def run_add_task(item_type: str, epic: str | None, item_id: str, title: str, persona: str) -> None:
+    cmd = [
+        sys.executable,
+        str(SCRIPT_ADD),
+        "--type",
+        item_type,
+        "--id",
+        item_id,
+        "--title",
+        title,
+        "--persona",
+        persona,
+    ]
+    if epic:
+        cmd.extend(["--epic", epic])
+    subprocess.run(cmd, check=True)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        raise SystemExit("Kullanım: kortext-bulk-plan.py <plan.json>")
+
+    data = json.loads(Path(sys.argv[1]).read_text())
+
+    for epic in data.get("epics", []):
+        epic_id = epic.get("id")
+        for item in epic.get("tasks", []):
+            print(f"⌛ Oluşturuluyor: {item.get('id')}...")
+            run_add_task(
+                item.get("type", "task"),
+                epic_id,
+                item.get("id"),
+                item.get("title"),
+                item.get("persona", "+persona"),
+            )
+
+    for debt in data.get("debts", []):
+        print(f"⌛ Oluşturuluyor: {debt.get('id')}...")
+        run_add_task(
+            "debt",
+            None,
+            debt.get("id"),
+            debt.get("title"),
+            debt.get("persona", "+persona"),
+        )
+
+    print("\n🚀 Toplu planlama başarıyla tamamlandı!")
+
+
+if __name__ == "__main__":
+    main()