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

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

1. لماذا التعدّدCopy Anchor Link

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

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

إعداد بيئات تشغيل أُطُر العمل متعدّد بحكم واقع النشر. يجب أن تشحن المنظومة المنشورة الأسطح الثلاثة الإلزامية الواردة في §3: AGENTS.md، وملف ذاكرة سلوكية لبيئة تشغيل لوحة الدردشة (CLAUDE.md)، وملف تعليمات بنطاق المستودع لبيئة تشغيل الإكمال داخل بيئة التطوير. ويجب أن تكون الأسطح متّسقة فيما بينها — بلا تناقض ولا انحراف — وأن تُرمِّز معًا الانضباطات نفسها.

2. عقد الاتّساقCopy Anchor Link

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

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

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

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

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

في هذا المستودع، أسطح الاشتراك الاختياري هي الأسطح التي تُدرجها تجهيزة قائمة الادّعاءات (tests/fixtures/multi-surface-claims.yaml) تحت optional-in. أما ملفات إعداد الجذر الخاصة بالمورّدين غير المستخدَمة فغائبة عمدًا؛ ولا يُضاف ملف إعداد خاص بأداة إلا حين تكون تلك الأداة سطح تحرير نشطًا لهذا المستودع.

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

يجب أن يحتوي ملف التعليمات بنطاق المستودع تحت .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، ومستند الاصطلاحات هذا، وsrc/apothem/schemas/، وCONTRIBUTING.md.

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

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

5. مرجع قائمة الادّعاءاتCopy Anchor Link

تُعدِّد التجهيزة في 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 SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  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. قاعدة المصالحةCopy Anchor Link

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

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

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

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

7. المدقّقاتCopy Anchor Link

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

- 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، ويبدأ بسطر SPDX-License-Identifier: MIT المرجعي (شكل Markdown).
• يُحلِّل الثاني الأقسام المرجعية لكل سطح؛ ويؤكّد أن الأقسام المشتركة متّسقة فيما بينها وفق مُقارِن مُوحَّد (غير حسّاس لحالة الأحرف، ومتسامح مع المسافات البيضاء، ويسمح بإعادة الصياغة اللفظية لكنه يشترط التكافؤ الدلالي في قائمة الادّعاءات المُعرَّفة في التجهيزة).
• يؤكّد الثالث فقط أن ملف LICENSE في الجذر يحمل سطر Copyright (c) <name> قابلًا للتحليل. ولا يقرأ ترويسات الملفات، التي لا تحمل اسم مؤلّف.

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

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

انظر أيضًاCopy Anchor Link

• 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 — النص المرجعي الكامل المعكوس هنا.