عن المشروع

تعد CoalLedger أداة بجودة التوثيق موجهة لوكلاء البرمجة بالذكاء الاصطناعي، وصفها مؤلفها بأنها "CoalMine للتوثيق". وهي جزء من TheColliery، وهي مجموعة من الإضافات الصغيرة (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) التي تشترك في عقيدة قائمة على خطافات (hooks) خالية من التبعيات، ومخططات تكوين أحادية المصدر، وإنفاق مقيد بالموافقة، وعدم إجراء تعديلات تلقائية. يمكن تثبيت CoalLedger بمفردها أو إلى جانب الأدوات الأخرى. الفرضية هي أن الكود البرمجي يمتلك أدوات فحص (linters) واختبارات وتكامل مستمر (CI)، بينما يعتمد التوثيق غالباً على "الأمل": ملف README انحرف عن الكود، أو ترجمة لم تعد تطابق الأصل، أو رابط تثبيت معطل، أو شارة إصدار قديمة؛ وهي إخفاقات صامتة لا يزال القارئ يثق بها. تقوم CoalLedger بمسح أي مستند — سواء كان README أو مواصفات أو تقريراً أو ترجمة — وتقارن ما يتم عرضه بما يدعيه المستند. توجد سبعة "كناريات" (canaries)، لكل منها نمط فشل واحد: 1. doc-grounding — يرصد الادعاءات التي لا تطابق مصدر الحقيقة (الكود، البيانات، النص الأصلي، الواقع)؛ ويتم التحقق منها في الوقت الفعلي من مصادر متعددة، وتتحول إلى "غير متحقق منها" عند عدم الاتصال. 2. doc-standard — يرصد عدم الاكتمال وفقاً لمعيار هذا النوع من المستندات، بما في ذلك الأقسام المطلوبة والواجهات العامة غير الموثقة. 3. doc-rot — يرصد الإصدارات والتواريخ والشارات القديمة، ومهام TODO المنسية، والتعليمات التي تم استبدالها. 4. doc-consistency — يرصد المستندات التي تناقض بعضها البعض، وانحراف المصطلحات، والانحراف بين اللغات. 5. doc-structure — يرصد الروابط المكسورة، والمراسي (anchors)، والعناوين، والجداول، والمراجع، والنصوص البديلة للصور. 6. doc-quality — يرصد الحشو، والنثر غير الواضح، وميكانيكا اللغة مثل الأخطاء المطبعية والقواعد والإملاء. 7. doc-leak (مقيد بالتكوين) — يشير إلى المحتوى الحساس على مستوى النثر في المستندات العامة؛ أما الأسرار التي تشبه الرموز (tokens) فتترك لأدوات أخرى، وهو يبلغ فقط عن النتائج المشتبه بها. تتم عمليات المسح على مستويين. يغطي المستوى السريع (Quick) الطبقات الميكانيكية الحتمية والمجانية فعلياً، ويقدم تقارير فقط. أما المستوى الكامل (Full) فيضيف الطبقات الدلالية (semantic) التي تستخدم حكم النموذج، وهي مدفوعة وتتطلب دائماً موافقة منفصلة. تجمع أربعة من الكناريات بين الطبقات الميكانيكية والدلالية، بينما تقتصر doc-consistency و doc-leak على الطبقة الدلالية فقط. يدعم الفحص الهيكلي محرك CommonMark+GFM AST مدمج وخالٍ من التبعيات لضمان عدم الإبلاغ عن المحتوى الذي يتم عرضه بشكل صحيح؛ ويوضح المؤلف أن سقف الدقة هو مستوى المواصفات وليس عرض GitHub بدقة البكسل، ويتم الإبلاغ عن غرائب المضيف كقيود بدلاً من التخمين. يتم الحكم على الخطورة دائماً في السياق وليس ميكانيكياً: فرابط مكسور في أرشيف يعتبر منخفض الخطورة، بينما الرابط نفسه في خطوة التثبيت يعتبر حرجاً. يتم الإبلاغ عن النتائج المؤكدة بشكل منفصل عن المشتبه بها. لا يتم تطبيق الإصلاحات تلقائياً أبداً؛ ينتهي كل تقرير بقائمة تقدم إصلاحات آمنة، أو إصلاحات يختارها المستخدم، أو مجرد تقرير. الطبقات الميكانيكية مصممة لتكون محايدة لغوياً — فهي تعتمد على الهيكل والموقع والمعنى بدلاً من الكلمات المفتاحية الإنجليزية — بينما تعمل الطبقات الدلالية بلغة المستند نفسه. هناك ميزة منفصلة اختيارية وهي تذكير "انحراف ذاكرة التوثيق" (docs memory-drift reminder). هي لا تمسح ولا تبلغ عن شيء، ولكن إذا تم تحرير ملفات التوثيق (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) ولم يتم تحديث MEMORY.md في الجلسة، وكان المشروع يستخدم اتفاقية MEMORY.md، فإن CoalLedger ترسل رسالة نظام هادئة واحدة عندما ينتهي الوكيل من الاستجابة، ثم تصمت بعد تحديث MEMORY.md. يمكن تعطيل هذه الميزة، وهي تكمل تنبيه CoalMine المماثل لتعديلات الكود؛ حيث يراقب الاثنان امتدادات ملفات مختلفة. التوافق يعتمد على القدرات وليس على جدول المنصات: المنصات التي تمتلك خطافات دورة الحياة تحصل على موصل لبداية الجلسة يقدم الكناري المناسب في الوقت المناسب؛ أما المنصات التي تفتقر للخطافات فتحصل على استدعاء يقوده الوكيل بأفضل جهد ممكن؛ وفي جميع الحالات يمكن استدعاء الكناريات يدوياً بالاسم. يصنف المؤلف مستويات الدعم بصدق — حيث يوصف Claude Code بأنه "تم التحقق منه" عبر إضافة حية واستخدام داخلي، بينما جميع المنصات الأخرى (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) تندرج تحت "يعمل مع": أي أنها صُممت لها ولكن لم يتم إثبات كفاءتها من البداية إلى النهاية بعد. تم توثيق ربط Antigravity مع تنبيه بأن موقع hooks.json قد تغير بعد تحديث ويجب استخراجه مجدداً من وثائق Antigravity؛ والربط بمسار ميت يكون خاملاً ولكن غير ضار. التثبيت لـ Claude Code يتم عبر أمرين لإضافة المتجر وتثبيت المكون الإضافي، وهو ما يربط الموصل وتذكير انحراف الذاكرة. أما الوكلاء الآخرون فيقومون بنسخ مجلدات المهارات المستقلة (محرك AST ينتقل داخل مجلد doc-structure). ويُنصح مستخدمو claude.ai بعدم ضغط المهارات يدوياً لأن أوصاف frontmatter تتجاوز حد القائمة في تلك المنصة؛ بدلاً من ذلك، يتم نشر ملفات ZIP لكل كناري بأوصاف مختصرة في صفحة الإصدارات (Releases) مع مجموع تحققي SHA256. تتضمن الأوامر أمراً لكل كناري بالإضافة إلى /coalledger:stats (إحصائيات المسح والنتائج المحلية للجلسة) و /coalledger:update (التحقق من الإصدار ومعالجة التحديث). يدعم التكوين ملفاً عاماً وملفاً لكل مشروع يتم حله من عدة أدلة معروفة للوكلاء، مع استمرار قراءة مسار الجذر القديم. تغطي المفاتيح وضع التشغيل/الإيقاف، لغة التقرير، الكناريات المعطلة، الحد الأدنى للخطورة، تجاوز المسح الشامل، المستوى الافتراضي (سريع مقابل كامل)، بوابة doc-leak، علامة التوثيق العام، تنبيه انحراف الذاكرة، قاعدة اختيارية لطباعة الشرطة الطويلة (em-dash)، وسلوك التحقق من التحديث. يمكن إيقاف تشغيل المشروع بالكامل بحيث تتوقف المهارة عن التحميل هناك. الصلاحيات محددة بدقة: تقرأ المستندات المذكورة والملفات التي تشير إليها الروابط، وتكتب فقط ملفات الخدش الخاصة بها وطابع التحديث، وتشغل ما يصل إلى ثلاثة أشياء محلية (محرك AST للقراءة فقط، ونقطة استعادة git stash قبل الإصلاحات، ومثال موثق يدعي المستند أنه يعمل — فقط بموافقة)، ولا تعدل مستنداً بمفردها أبداً. استخدام الشبكة اختياري: يتطلب التحقق من المصدر في المستوى الكامل (Full) المدفوع والتحقق من التحديث الذاتي موافقة منفصلة؛ أما الخطافات والمحرك فلا يتصلان بالإنترنت أبداً. لا يلزم وجود مفاتيح API أو تثبيت npm. فيما يخص قياس الأداء، يتسم المشروع بالصدق: فهو ينطلق بدون قياسات بدلاً من اختراع رقم. الطبقة الميكانيكية محمية داخل المستودع (يتم العثور على العيوب المزروعة، وتظل الخداعات النظيفة صامتة) عبر نص برمجي للتحقق، ومن المخطط ملء ملخص النتائج من أول تشغيل مؤرخ ومحدد الإصدار يقيس الاستدعاء على عيوب التوثيق المزروعة، كناري تلو الآخر. مرخصة بموجب Apache 2.0.