اصطلاحات إطار العمل متعدّد الأسطح

مرجع معياري كانوني للمساهمين اللاحقين. يعكس هذا المستند أقسام «اصطلاحات إطار العمل متعدّد الأسطح» من مواصفة المشروع (المواصفة §0.6 + §2.8 + §4.7)؛ وهو المرجع المستقلّ الذي يُشحَن مع المستودع المنشور. الأساس المعماري مُدوَّن في ADR-0003.

1. لماذا الصيغة الجمع

يلمس السطحَ الهندسيَّ الحديثَ عددٌ من أوقات تشغيل إطار العمل — لوحات الدردشة، ومحرّكات الإكمال داخل بيئة التطوير، ورفقاء البرمجة الثنائية، ومراجِعو طلبات السحب. ويقرأ كلٌّ منها ملفّ إعداده الكانونيَّ الخاصّ. فإن شحن المشروعُ ملفًّا واحدًا فقط من هذا النوع، فإنّ بقيّة أوقات التشغيل ترتجل بصمت في مواجهة اصطلاحات غير مُصرَّح بها؛ وتتسرّب الذاكرة المفقودة داخل المستودع على الفور.

كلفة السطح المفقود هي انجراف صامت في الشِّفرة المُولَّدة آليًّا — أسوأ أنواع العلل لأنّه يتراكم بلا ظهور. فكلّ مُنتَج مُولَّد آليًّا يُفاقِم التباعد؛ وحين يلحظ مراجِعٌ بشريٌّ التناقض، تكون قاعدة الشِّفرة قد حملت أسابيع من الاصطلاحات غير المتّسقة.

إعداد وقت تشغيل البرمجة جمعيٌّ بحكم واقع النشر. على المنظومة المنشورة أن تشحن ملفَّ ذاكرةٍ سلوكيّةٍ لوقت تشغيل لوحة الدردشة و ملفَّ تعليماتٍ بنطاق المستودع لوقت تشغيل الإكمال داخل بيئة التطوير. وعلى السطحَيْن أن يكونا متّسقَيْن تبادليًّا — بلا تناقض، بلا انجراف — وأن يُرمِّزا معًا الانضباطات ذاتها.

2. عقد الاتّساق

كلّ سطح اصطلاحات ضمن النطاق (§3) هو قناة تُعبِّر عن مواصفة الاصطلاحات الوحيدة للمشروع. وتتفكّك المواصفة إلى:

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

يعمل المُحقِّق multi-surface-coherence (§7) في كلّ تشغيلٍ لـCI وعند pre-commit، مؤكِّدًا العقد.

السطحان (أو أكثر) هما قنوات مختلفة تُعبِّر عن مواصفة واحدة. على الأقسام المشتركة أن تتطابق — دلاليًّا، وحيثما أمكن، لفظيًّا — عبر الأسطح. ولا يجوز للأقسام الخاصّة بالسطح أن تتناقض مع الأقسام المشتركة.

3. الأسطح ضمن النطاق

في هذا التكليف اختار المُشغِّل تفعيل أسطح المساعِد الاختياريّة المُسجَّلة في التجهيزة. أمّا إعدادات الجذر الخاصّة بالمورّد غير المستخدَمة فغائبةٌ قصدًا؛ ولا يُضاف ملفّ إعدادٍ خاصٌّ بأداةٍ إلّا حين تكون تلك الأداة سطح تحريرٍ نشطًا لهذا المستودع.

4. قائمة الأقسام لملفّ التعليمات داخل بيئة التطوير

على ملفّ التعليمات بنطاق المستودع تحت .github/ أن يحوي، بهذا الترتيب، الأقسام التالية (كلٌّ بنصّ العنوان الدقيق أدناه؛ متون الأقسام مُؤلَّفة لا مختومة بقالب، لكن على كلٍّ منها أن يُغطّي المزاعم المُدرَجة):

1. Project Context — فقرة واحدة: ما هو هذا المستودع، ومن يستخدمه، وشكله على المستوى الأعلى. واقعيّ؛ بلا تسويق.
2. Coding Conventions — التسمية، والتدرّج الوصفيّ، والترويسة الأماميّة، وأسلوب markdown، ونقاط الأسلوب الخاصّة بكلّ لغة حيث تنحرف عن الإعدادات الافتراضيّة.

3. File Headers — على كلّ ملفّ يولّده وقت التشغيل أن يبدأ بالسطر الكانونيّ المفرد SPDX-License-Identifier: MIT وفق site/content/docs/reference/authorship-header.mdx، في صيغة التعليق المطابقة لنوع الملفّ. مؤشِّر إلى scripts/inject-header.* وsite/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — لا يجوز لوقت التشغيل أن يولّد شِفرةً أو سكربتاتٍ تكتب إلى دليل إعداد إطار العمل (مثل ~/.claude/plans/ أو ~/.codex/.plans/) أو أيّ موضع خطط عموميّ آخر. تذهب منتجات التخطيط إلى <project-root>/.apothem/plans/ (تُرقّى شجرة <project-root>/.plans/ القديمة عبر apothem migrate-workspace) وفق site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — حين يكون وقت التشغيل غير متيقِّن، لا يجوز له أن يختلق بصمت. بل يُدرِج كتلة استيضاحٍ معلَّمةً بوضوح (مثل تعليق # TODO(clarify): <question>) ويُبرِز السؤال في الدردشة حيث يسمح السطح. بلا واجهات برمجة مختلَقة، بلا أسماء نماذج مختلَقة، بلا مسارات ملفّات مختلَقة.
6. Forbidden Patterns — مَنوعاتٌ صريحة: لا صفات تسويقيّة، ولا حشوٌ متهرِّب، ولا فضلات تنقيح console.log، ولا مسارات مطلقة مُثبَّتة إلى منزل المستخدم، ولا إيداع أسرار، ولا إيداع ملفّات تحت .apothem/plans/ (أو القديم .plans/)، ولا تناقض مع ملفّ تعليمات المشروع الكانونيّ.
7. Output Format — تتوافق الشِّفرة/النثر المُولَّد مع اصطلاحات الإخراج الحواريّ الموحَّدة: الحَسم، والتقسيم المنتظِم، والكثافة، وانضباط الخلاصة، والاقتباس. وبالنسبة إلى الشِّفرة: سطحٌ عموميّ موثَّق، ومُنمَّط حيث تدعم اللغة الأنواع، ومُختبَر حيث يوجد سقالة اختبار.
8. Review Checklist — ما يجب على المراجِع (بشرٌ أو وقت تشغيل في وضع مراجعة طلب السحب) أن يتحقّق منه قبل الموافقة: الترويسة حاضرة، والتسمية ممتثلة، ولا كتابات إلى .apothem/plans/، ولا تناقضات مع ملفّ تعليمات المشروع الكانونيّ، والمُحقِّقات خضراء محليًّا.
9. Pointers — روابط إلى AGENTS.md وCLAUDE.md وsite/content/docs/reference/plans-discipline.mdx وsite/content/docs/reference/authorship-header.mdx ومستند الاصطلاحات هذا وschemas/ وCONTRIBUTING.md.

يبدأ الملفّ بسطر SPDX الكانونيّ لترويسة التأليف (صيغة Markdown) وفق site/content/docs/reference/authorship-header.mdx §2 — مرئيًّا أو غير مرئيّ بحسب سياسة رؤية الترويسة التي اختارها المشروع.

ملفّ التعليمات داخل بيئة التطوير ليس نسخةً حرفيّةً من AGENTS.md أو CLAUDE.md. فـAGENTS.md هو سطح تعليمات المشروع الكانونيّ، وCLAUDE.md يعكسه لأجل Claude Code، وملفّ التعليمات داخل بيئة التطوير مُصاغٌ بصوتٍ لوقت تشغيل إكمال الشِّفرة داخل المحرِّر الذي يبثّ اقتراحاتٍ يقبلها المطوِّر أو يرفضها. المعلومات (الانضباطات، الاصطلاحات، أنماط المنع) متطابقة؛ والتأطير يختلف.

5. مرجع قائمة المزاعم

تُعدِّد التجهيزة في tests/fixtures/multi-surface-claims.yaml كلَّ زعمٍ مشترك. مدخلات نموذجيّة:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical authorship-header banner per site/content/docs/reference/authorship-header.mdx."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

يحلّل المُحقِّق كلَّ سطح، ويحاول إيجاد حضور كلّ زعمٍ على السطح (عبر تدرّج العناوين + استخلاص الكلمات المفتاحيّة من المتن)، ويُخفِق عند أيّ فوات أو تناقض.

6. قاعدة المصالحة

حين يُكتشَف أنّ سطحَيْن يتناقضان على زعمٍ مشترك، تكون المصالحة الافتراضيّة:

AGENTS.md هو صوت المشروع الكانونيّ. ويُعاد كتابة أيّ سطح متناقض ليعكس دلالات AGENTS.md في تأطيرٍ ملائمٍ للسطح.

لا يُسمَح بتجاوزٍ خاصٍّ بالسطح إلّا بعلامةٍ صريحة داخل الملفّ <!-- coherence-override: <claim-id> --> تشير إلى ADR يشرح التباعد المقصود. وعلامة التجاوز نفسها مُعدَّدة في قائمة سماح المُحقِّق وتظهر في تقرير CI.

بالنسبة إلى هذا المستودع، تكون استراتيجيّة المصالحة المُصدَّق عليها هي agents-md-wins: AGENTS.md كانونيّ، وكلّ مرآة إطار عملٍ نشطة تبقى متكافئة دلاليًّا.

7. المُحقِّقات

ثلاثة مُحقِّقات تُنفِّذ معًا عقد الاتّساق:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• الأوّل يؤكِّد أنّ ملفّ التعليمات داخل بيئة التطوير موجود، ويتحلّل، ويحوي كلّ قسمٍ كانونيّ مُعدَّد في §4، ويبدأ ببَنر التأليف الكانونيّ.
• الثاني يحلّل الأقسام الكانونيّة لكلّ سطح؛ ويؤكِّد أنّ الأقسام المشتركة متّسقة تبادليًّا تحت مقارِنٍ مُسوًّى (غير حسّاسٍ لحالة الأحرف، متسامحٍ مع المسافات، يُجيز إعادة الصياغة اللفظيّة لكن يشترط التكافؤ الدلاليّ على قائمة المزاعم المُعرَّفة في التجهيزة).
• الثالث يؤكِّد أنّ سطر حقوق النشر في LICENSE وسطر «Copyright (c)» في البَنر الكانونيّ يسمّيان المؤلِّف نفسه.

8. دورة حياة السطح

• إضافة سطح. يختار المُشغِّل التفعيل عبر قناة الاستعلام البنيويّ أو عبر make surfaces-add <name> لاحقًا. ويؤلِّف المُولِّد السطح في مواجهة قائمة المزاعم، ويُشغِّل المُحقِّق، ويرفع ADR إن لزم تجاوزٌ خاصّ بالسطح.
• إزالة سطح. يؤكِّد الاستعلام البنيويّ الإزالة، ويُدوِّن ADR الأساس، وتُعدَّل قائمة required-in للمُحقِّق.
• اكتشاف الانجراف. أيّ إيداعٍ ينحرف عن قائمة المزاعم يرفضه pre-commit / CI؛ ويُعيد مؤلِّف الإيداع كتابة السطح لاستعادة الاتّساق.

انظر أيضًا

• ADR-0003 — الأساس المعماريّ، والبدائل المدروسة.
• tests/fixtures/multi-surface-claims.yaml — تجهيزة قائمة المزاعم الكانونيّة.
• AGENTS.md — صوت المشروع الكانونيّ.
• CLAUDE.md — مرآة Claude Code.
• site/content/docs/reference/plans-discipline.mdx — المرجع الكانونيّ لزعم انضباط الخطط المشترك.
• site/content/docs/reference/authorship-header.mdx — المرجع الكانونيّ لزعم ترويسة التأليف المشترك.
• مواصفة المشروع §0.6 + §2.8 + §4.7 — النصّ الكانونيّ الكامل المعكوس هنا.