عن المشروع

## نظرة عامة jira-integration هو ملحق (Plugin) مخصص لـ Claude Code، يعالج مسألة Jira واحدة من إنشاء الفرع ← تصميم المقاربة (approach) ← التنفيذ ← الاختبار ← المراجعة ← الدمج المحلي، ويُسجّل نتائج كل مرحلة في تعليقات Jira والمرفقات وانتقالات الحالة. صُمم بحيث تُوضع عدة مسائل في قائمة انتظار وتُستنفد تباعًا، ثم تُلخَّص نتائج النجاح/العزل في تقرير استثناءات واحد ليحكم الإنسان على الحالات المعزولة فقط. ## بنية التشغيل يتكوّن من حلقتين: - حلقة المراحل (`auto`): تنفّذ مهمة واحدة بترتيب start ← approach ← impl+test ← review. كل مرحلة تعمل عبر وكيل فرعي معزول، وتُخصص نماذج مختلفة لكل مرحلة. بوابة المراجعة تعتمد على قيم مهيكلة لنسبة تطابق التصميم-التنفيذ وعدد الحالات الحرجة (Critical)، وعند عدم الاجتياز، يعمل وكيل التصحيح عبر حلقة استشعار (بحد أقصى 5 مرات) تقتصر على lint وtypecheck والاختبارات ذات الصلة فقط، لتقريب النتيجة نحو الاجتياز، ثم تُنفَّذ الاختبارات الكاملة وإعادة مراجعة الدلتا مرة واحدة لكل منهما. الحد الأقصى للحلقة الخارجية مرتان. - حلقة المهام (`loop`): تستنفد قائمة الانتظار التي أُنشئت عبر `init` بالترتيب، وتنفّذ لكل مهمة: auto ← دمج محلي بـ`--no-ff` ← rebase لباقي worktrees. عند عدم اجتياز البوابة أو فشل مرحلة أو حدوث تعارض في الدمج/rebase، تُعزل المهمة المعنية فقط ويُتابَع إلى التالية. لا يتوقف النظام بالكامل إلا عند إشارات البنية التحتية مثل فشل المصادقة (401/403)، أو انقطاع اتصال MCP، أو تلف base، أو عند فشل متتابع لمهام مختلفة. يُوثَّق في الدليل أن تدفق التحكم لا يُفسَّر من خلال prompt بل يُنفَّذ حتميًا عبر سكربت Workflow (`scripts/auto.workflow.js`). ## الربط مع Jira مفتاح مسألة واحد يقابل فرعًا (`feature/<KEY>`) وworktree وملف سياق. ملف `.jira-context.json` في المستودع الرئيسي هو مجمّع لقائمة الانتظار بأكملها، بينما ملف سياق كل worktree يمثّل حالة المهمة المعنية. لكل أمر انتقالات حالة (للقيام ← قيد التنفيذ ← قيد المراجعة ← مكتمل)، وتعليقات، ومرفقات (وثائق approach/review وتقارير الاختبار). العزل يُسجَّل محليًا فقط دون تغيير Jira. استدعاءات Jira تتولاها `scripts/jira-cli.py` (REST) التي تستخدم المكتبة القياسية فقط، وتُخزَّن بيانات الاعتماد في كتلة `jira` داخل `.jira-context.json` على مستوى مساحة العمل، وتُرحَّل تلقائيًا من متغيرات البيئة وإعدادات MCP القديمة. تسجيل MCP server اختياري. ## الأوامر الرئيسية - إنشاء المسائل: `epic set/show/clear`، `discover`، `create` - قائمة الانتظار/الأتمتة: `init`، `loop`، `auto` - المراحل الفردية: `start`، `approach`، `impl`، `test`، `review`، `merge`، `pr`، `done` - الاستعلام/التنظيف: `status`، `report`، `clean` - أخرى: `/jira setup`، `/jira dashboard` ## قواعد التشغيل يُحدَّد حجم العمل بـ L1/L2/L3 لضبط كمية المخرجات وعمق المراجعة، وإذا لامس العمل نموذج البيانات أو حدود المعاملات أو عقود API الخارجية أو التزامن أو الحدود الأمنية، يُرفَع التصنيف إلى L2 حتى لو كان من فئة L1. يمكن لـ `start` أن يوصي بالتخطي لمرحلتي approach وtest فقط، بينما لا تُتخطَّى impl وreview وmerge. تُسجَّل جميع المراحل في `completedSteps` بحيث تُتجاوز المراحل المكتملة عند إعادة التشغيل. ## المخرجات ولوحة المعلومات تحت `docs/` تتكدس مستندات requirements وapproach وtest وreview بالإضافة إلى review-log وrun-log بصيغة jsonl. يُستخدم run-log وreview-log كبيانات رصد خاصة بالمنظومة نفسها، مثل معدل النتائج الإيجابية الكاذبة في المراجعة، والوقت المستغرق لكل مرحلة، وتكرار الإصلاحات، وأسباب العزل. تعرض لوحة المعلومات على `http://127.0.0.1:8765` بطاقات لكل worktree (المرحلة الجارية، استدعاءات الأدوات، حالة Jira، مخطط blocks) بشكل لحظي عبر SSE، وهي مخصصة لـ localhost فقط وبدون مصادقة. ## الترخيص MIT.