انضباط الخطط — ذاكرة عمل عابرة محلية للمشروع

مرجع معياري كنسي للمساهمين في المراحل اللاحقة. يعكس هذا المستند قسم انضباط الخطط من مواصفة المشروع (Spec §3)؛ وهو المرجع المستقل الذي يُشحَن مع المستودع المنشور. الانضباط المُقدَّم هنا أساسيٌّ؛ وكل توجيه أدناه هو MUST ما لم يُؤشَّر صراحةً بخلاف ذلك. السند المعماري مُسجَّل في ADR-0001.

1. التعريف والحدود

الخطة (plan) هي أي أثر عمل مقصود وعابر يُنتَج أثناء التفكير في مشروع ما، بما في ذلك على سبيل المثال لا الحصر:

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

تختلف الخطط فئويًّا عن هذه الأصناف المجاورة:

تسبق الخطط سجلات القرار المعمارية. حين تتقارب خطة نحو قرار مُعمَّر، يُرقَّى القرار إلى سجل قرار معماري (§4 دورة الحياة)؛ أما الخطة نفسها فتُؤرشَف أو تُتلَف.

2. الموقع والظهور والتسمية

• المسار. <project-root>/.apothem/plans/ هو الموطن الكنسي الوحيد. ولم تعد شجرة <project-root>/.plans/ القديمة كنسية — رقِّها بـapothem migrate-workspace (§5). ليس دليل تهيئة harness (مثل ~/.claude/plans/، أو ~/.claude/.plans/، أو ~/.codex/.plans/). وليس مجلد مسوّدات على سطح المكتب. وليس ~/notes/. وليس tmp/plans/.
• الظهور. يُسجَّل المجلد في ملف .gitignore الخاص بالمشروع وفق المقتطف الكنسي في §6. يجب على وقت تشغيل harness التحقق من وجود هذا المُدخَل قبل أي كتابة؛ وإن غاب، فإنه يُلحِق المُدخَل مع سطر تعليق ترويسي واحد ورابط إلى هذا المستند.
• اصطلاح اسم الملف. YYYY-MM-DD--<kebab-case-slug>.md. لمساحات العمل الأكبر، صنِّف فرعيًّا تحت .apothem/plans/<area>/YYYY-MM-DD--<slug>.md.
  • أمثلة: .apothem/plans/2026-04-30--auth-refactor-strategy.md، .apothem/plans/api/2026-04-30--rate-limit-rollout.md.
• الفهرس. قد يُجمِّع ملف .apothem/plans/INDEX.md اختياري (مستثنى عبر gitignore أيضًا) الروابط والحالات؛ وإن وُجد، يصونه وقت تشغيل harness عند كل كتابة خطة.
• الأرشيف. تُنقَل الخطط المتقاربة أو المهجورة إلى .apothem/plans/_archive/. ولا تُحذَف أبدًا دون تأكيد استعلام منظم صريح.
• ترويسة الكِتابة في الخطط. الخطط مُعفاة من سطر SPDX لترويسة الكِتابة (وفق site/content/docs/reference/authorship-header.mdx §قائمة الاستثناءات). فهي عابرات مستثناة عبر gitignore؛ وتطبيق علامة مصدريّة دائمة على ذاكرة عمل عابرة هو خطأ فئوي. تحمل الواجهة الأمامية (§3) مصدريّة الخطة.

3. مخطط الواجهة الأمامية (مُتحقَّق منه)

يحمل كل ملف خطة:

---
title: <human-readable title>
project: <git-remote-url-or-canonical-local-path>
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
status: draft | in-progress | converged | abandoned
tags: [<kebab>, ...]
supersedes: <prior-plan-relative-path or null>
promotes-to: <ADR path or null>
---

يوجد مخطط JSON Schema للخطط في src/apothem/schemas/plan.schema.json. يتحقق الأمر المائل /plan (والمُتحقِّق plans-discipline-language) تجاهه عند كل كتابة.

4. دورة الحياة وسير عمل الترقية

1. مسوّدة — الإنشاء الأولي؛ status: draft.
2. قيد التقدّم — مُكرَّرة بنشاط؛ status: in-progress؛ ويُحدَّث updated عند كل تحرير جوهري.
3. التقارب — يتبلور قرار مُعمَّر:
   1. استخرج القرار في سجل قرار معماري جديد في موقع ADR المُصادَق عليه من المشروع.
   2. اضبط promotes-to للخطة على مسار الـADR.
   3. اضبط status: converged.
   4. انقلها اختياريًّا إلى .apothem/plans/_archive/.
4. الهجر — هُجِر الاتجاه؛ status: abandoned؛ أرشِف أو، باستعلام منظم صريح، أتلِف.
5. الإحلال — حين تحل خطة جديدة محل خطة أقدم، اضبط supersedes للخطة الجديدة على مسار الخطة القديمة، واضبط status الخطة القديمة وفقًا لذلك.

الترقية هي المسار الوحيد الذي يصبح به محتوى الخطة مُعمَّرًا ومحكومًا بالإصدارات ومرئيًّا لزملاء الفريق. ولا تُرحَّل أي خطة بكاملها إلى مصدر مُودَع أبدًا.

5. بروتوكول الترحيل — مرة واحدة، من دليل خطط harness إلى .apothem/plans/ لكل مشروع

ملاحظة. ينطبق هذا البروتوكول على المشاريع في المراحل اللاحقة التي تتبنى انضباط الخطط لأول مرة، حيث تعيش آثار التخطيط السابقة داخل دليل تهيئة harness (مثل ~/.claude/plans/، أو ~/.claude/.plans/، أو المسار المكافئ لـharness آخر). أما الحالة العَوْدية للمنظومة نفسها فتُحَلّ باستثناء حالة الخطط المحلية للـharness عبر gitignore بدل ترحيلها فيزيائيًّا إلى المصدر.

الأدوات. للمشاريع التي على التخطيط القديم بالفعل — شجرة <project-root>/.plans/ شقيقة بالإضافة إلى مخازن <project-root>/.apothem/<harness>/{memory,contexts,learning} لكل harness — يطوي الأمر apothem migrate-workspace كليهما في دليل العمل المشترك <project-root>/.apothem/{plans,memory,learning,contexts}. والأمر عديم الأثر التكراري وغير تدميري: إذ يحتاط لكل مصدر يستهلكه، وينقل .plans/ إلى .apothem/plans/، ويدمج اتحاديًّا مخازن الذاكرة والسياق لكل harness، ويُسلسِل-ويُزيل-التكرار من إشارات التعلّم، ولا يطمس أبدًا سجلًّا متعارضًا. شغِّل apothem migrate-workspace --dry-run لمعاينة النقلات أولًا.

الترحيل عديم الأثر التكراري وقابل للعكس حتى لحظة إزالة دليل الخطط المحلي للـharness (وبعدها يوفر أرشيف tarball الاحتياطي في ./.audit/plans-backup-<timestamp>.tar.gz أثر التراجع). تستخدم الأمثلة أدناه ~/.claude/plans/؛ استبدِل بها المسار المكافئ للـharness النشط.

الخطوة 1 — الجَرد. يُعدَّد كل ملف تحت دليل الخطط المحلي للـharness ويُصنَّف plan-artifact (quarantined).

الخطوة 2 — خريطة المصدريّة. يُبنى سجل مصدريّة لكل خطة، مع مشروع وجهة مُستنتَج ودرجة ثقة مُشتقَّة من حقل project في الواجهة الأمامية، وإشارات مسح المتن (روابط المستودعات، أسماء الحُزَم، المسارات المطلقة)، والمؤشرات السياقية.

الخطوة 3 — تأكيد التعيين. تُقدَّم الخريطة الكاملة إلى المُشغِّل كاستعلام منظم موحَّد واحد (أو تسلسل مُجمَّع بإحكام حين يتجاوز عدد الملفات حجم مُوجِّه مفرد مريح). لكل خطة، يختار المُشغِّل من بين:

• Confirm (تأكيد) مشروع الوجهة المُستنتَج.
• Reassign (إعادة تعيين) إلى مشروع مختلف (يقدّم الخيار قائمة المشاريع المعروفة للمُشغِّل).
• Defer (تأجيل) — النقل إلى ~/.claude/.audit/orphan-plans/<original-name> للفرز لاحقًا.
• Discard (إتلاف) — فقط باستعلام منظم صريح ومؤكَّد على حدة (هذا إجراء تدميري).

حين تكون الثقة high لكثير من الخطط، يقدّم المُوجِّه إتاحة confirm-all-high-confidence لضغط الذهابات والإيابات مع إظهار كل قرار فردي في السجل رغم ذلك.

الخطوة 4 — تجهيز المشروع قبل النقل. لكل مشروع وجهة فريد:

1. تحقَّق من وجود جذر المشروع وقابليته للقراءة.
2. تحقَّق من كونه مستودع git (للجذور غير الـgit، اطرح عبر قناة الاستعلام المنظم ما إذا كان ينبغي المتابعة أو التهيئة أو التخطّي).
3. تأكَّد من وجود <project-root>/.apothem/plans/؛ وأنشِئه بـmkdir -p إن لم يكن موجودًا.
4. تحقَّق من احتواء .gitignore المشروع على المقتطف الكنسي من §6؛ وإن غاب، فألحِقه مع تعليق ترويسي يُنسِب هذا الترحيل.
5. تحقَّق من أن <project-root>/.apothem/plans/ ليس متتبَّعًا بالفعل من git؛ وإن كان كذلك (خطأ مساهم سابق)، فاطرح عبر قناة الاستعلام المنظم بخيارات untrack-and-keep، وuntrack-and-remove-from-history، وabort.

الخطوة 5 — النقل. لكل اقتران مؤكَّد من خطة → وجهة:

1. احسب اسم ملف الوجهة: إن كان للمصدر واجهة أمامية، فطبِّعه وفق §3؛ وإلا فلُفّ المتن بواجهة أمامية (status draft، حقل project مضبوط، created من mtime، tags [migrated]) وأعِد تسميته إلى YYYY-MM-DD--<slug>.md.
2. إن وُجد تصادم في الاسم عند الوجهة، فألحِق -imported-<unix-timestamp> وسجِّل إعادة التسمية.
3. انسخ الملف (مع الحفاظ على mtime)، وتحقَّق من تطابق SHA-256 عند الوجهة، ثم افصل ارتباط المصدر.
4. ألحِق مُدخَلًا في <project-root>/.apothem/plans/_migration-manifest.md (مستثنى عبر gitignore أيضًا) يُسجِّل: المسار المحلي الأصلي للـharness، ومسار الوجهة، وSHA-256 الأصلي، والطابع الزمني، وإجابة الاستعلام المنظم الذي رخّص هذا النقل.

الخطوة 6 — التحقق. بعد كل عمليات النقل:

1. أكِّد أن دليل الخطط المحلي للـharness فارغ (الخطط اليتيمة، إن وُجدت، تكون داخل دليل التدقيق/الحجر الخاص بذلك الـharness خارج الدليل المُزمَع حذفه قريبًا).
2. أكِّد أن لكل مشروع وجهة .apothem/plans/ مأهولة وبيانًا.
3. افحص عيِّنيًّا بـSHA-256 أن المحتوى المُرحَّل يطابق الأصول.

الخطوة 7 — الأرشيف والإزالة. أنشِئ ./.audit/plans-backup-<ISO-timestamp>.tar.gz يحتوي شجرة خطط الـharness المحلية بأكملها قبل النقل (مُستخرَجة من لقطة مؤقتة أُخِذت في الخطوة 1). ثم، عبر استعلام منظم نهائي يؤكد الجاهزية، أزِل دليل الخطط المحلي للـharness الذي صار فارغًا الآن.

الخطوة 8 — سجل التدقيق. أصدِر ./.audit/plans-migration.md يُلخِّص كل نقل، وكل ملف مؤجَّل، وكل إتلاف، وكل إعادة تسمية بسبب تصادم، وكل إلحاق بـgitignore.

6. مقتطف .gitignore للمراحل اللاحقة (كنسي، انسخ-والصق)

يجب على كل مشروع يتبنى هذه المنظومة إضافة الكتلة التالية إلى .gitignore الخاص به:

# دليل عمل Apothem (حالة مشتركة محلية للمشروع: الخطط، والذاكرة،
# والتعلّم، والسياقات؛ مستثنى عبر gitignore — لا يُودَع أبدًا). الموطن الكنسي
# الوحيد للخطط هو `.apothem/plans/`.
# انظر: <repo-url>/blob/main/site/content/docs/reference/plans-discipline.mdx
# استثنِ محتويات هذا الدليل (لا الدليل نفسه) كي يأخذ نفي
# `.keep` أدناه مفعوله.
.apothem/*
!.apothem/.keep

يحفظ استثناء .keep الاختياري وجود الدليل في الأدوات التي تقلِّم المسارات الفارغة، دون تسريب المحتوى. ويُقرَّر تضمين .keep من عدمه لكل مشروع عبر قناة الاستعلام المنظم عند أول استدعاء لـ/plan. سطرا .apothem/* + !.apothem/.keep هما المقتطف الكنسي؛ والمشروع الذي ما زال يحمل شجرة <project-root>/.plans/ قديمة يُشغِّل apothem migrate-workspace (§5) لترقيتها إلى .apothem/plans/.

7. آليات الفرض الذاتي

يجب أن ينجو هذا الانضباط من كل جلسة مستقبلية. أسطح الفرض التالية إلزامية ومُشفَّرة في المنظومة المنشورة:

1. AGENTS.md وأسطح التعليمات المرآتية — كتلة سلوك إلزامي عُليا تنص على: «تُكتَب آثار التخطيط إلى <project-root>/.apothem/plans/ — الموطن الكنسي الوحيد للخطط (تُرقَّى شجرة <project-root>/.plans/ القديمة عبر apothem migrate-workspace) — ولا تُكتَب أبدًا إلى أي دليل تهيئة harness (مثل ~/.codex/ أو ~/.claude/) ولا إلى موقع عام أبدًا. هذه القاعدة غير قابلة للتفاوض؛ استشهِد بـ§3 من مواصفة المشروع في كل قرار ذي صلة.» تكتشف هذه الكتلةَ المُتحقِّقُ plans-discipline-language.
2. ملف تعليمات داخل المستودع لكل harness — يعكس التوجيه نفسه بالصياغة الملائمة لسطح تعليمات ذلك الـharness (§4 انضباط الخطط)؛ ويكتشفه المُتحقِّق نفسه على كل سطح harness مُسجَّل.
3. نمط الإخراج الافتراضي — حين تنتج استجابةٌ محتوًى بشكل خطة (استراتيجية متعددة الخطوات، تفكيك، جولة تصميم، يوميات تنقيح أخطاء)، يوجِّه النمطُ الأثرَ إلى كتابة .apothem/plans/ محلية للمشروع بدل الطباعة-والإهمال السطري. ويوعِز النمط صراحةً: «إن تعذَّر اكتشاف جذر المشروع، فتوقّف باستعلام منظم يسأل المُشغِّل أين يُخطِّط.»
4. كل مُوجِّه عامل مُفوَّض — يحمل مقطع Output Surface الذي يسمّي .apothem/plans/ وجهةً لأي أثر تخطيط، ومقطع Anti-Pattern الذي يسمّي أدلة الخطط المحلية للـharness ممنوعةً.
5. أمر مائل /plan مُخصَّص — يقبل slug + متنًا، ويكتب إلى <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md بواجهة أمامية صحيحة، ويتأكد من صحة .gitignore الوجهة، ويرفض الكتابة إلى مسارات جذر تهيئة الـharness.
6. خطّاف pre-tool-use — plan-write-guard — يعترض كل استدعاء أداة كتابة ملف. إن طابق مسار الهدف موقع خطة محليًّا للـharness (مثل ~/.claude/plans/... أو ~/.codex/.plans/...) أو أي مسار منظومة عام آخر تُحدِّده الاستدلالية على أنه بشكل خطة، فإن الخطّاف يحجب الكتابة ويرفع استعلامًا منظمًا يقترح إعادة التوجيه إلى .apothem/plans/ الخاصة بالمشروع الحالي.
7. مُتحقِّقات CI — يُفشِل no-global-plans البناءَ إذا عادت ذاكرة عمل الخطط المُودَعة للظهور في الشجرة المنشورة؛ ويُفشِل plans-discipline-language إذا سقط التوجيه الكنسي من أي ملف تعليمات harness مُسجَّل أو من نمط الإخراج الافتراضي. أسطح الهدف الكنسية للمُتحقِّق (محفوظة كعقود نظام ملفات) مُدرَجة في الكتلة المُسيَّجة أدناه.

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

8. خطافات pre-commit — تعكس ما سبق محليًّا بحيث يُفرَض الانضباط قبل أن يحط أي إيداع.

8. الأنماط المضادة (محظورة فئويًّا)

• كتابة الخطط داخل دليل تهيئة harness (مثل ~/.claude/plans/ أو ~/.codex/.plans/) أو أي موقع عام آخر.
• إيداع الخطط في تاريخ git الخاص بمشروع (ينبغي للخطافات عند الإيداع أن ترفض ذلك).
• خلط الخطط مع سجلات القرار المعمارية (دورات حياة مختلفة، مواقع مختلفة، حالة إيداع مختلفة).
• خطط بلا واجهة أمامية، خطط بلا أسماء ملفات مسبوقة بتاريخ، خطط بلا حقل project.
• خطط عابرة للمشاريع (خطة واحدة، مشروعان). جزِّئها — خطة واحدة لكل مشروع.
• مشاركة الخطط عبر الأجهزة من خلال مزامنة تهيئة الـharness (مثل ~/.claude لـClaude Code) — حجة بنيوية لإبقاء الخطط محلية للمشروع: مستودع المشروع هو آلية المزامنة، في المناسبات النادرة التي تستحق فيها الخطط المشاركة — وذلك الاستحقاق ذاته إشارة إلى أن المحتوى ينبغي أن يُرقَّى إلى سجل قرار معماري.
• محتوى خطة مُضمَّن داخل مُوجِّهات العامل المُفوَّض، أو متون المهارات، أو أنماط الإخراج. تلك الأسطح تهيئة سلوكية مُعمّرة؛ والخطط ذاكرة عمل عابرة.
• تطبيق سطر SPDX لترويسة الكِتابة على ملف خطة (الخطط مُعفاة بحكم التصميم — §2، site/content/docs/reference/authorship-header.mdx §قائمة الاستثناءات).

انظر أيضًا

• ADR-0001 — السند المعماري، والبدائل المدروسة، والمفاضلات المقبولة.
• site/content/docs/reference/authorship-header.mdx — انضباط سطر SPDX لترويسة الكِتابة (الخطط مُعفاة فئويًّا).
• صفحة اصطلاحات harness — اصطلاحات harness متعددة الأسطح (يظهر انضباط الخطط بوصفه ادعاءً مشتركًا عبر كل ملف تعليمات harness مُسجَّل وكل سطح اختياري مُنضَمّ إليه). المسار:

site/content/docs/reference/ai-conventions.mdx

• مواصفة المشروع §3 — النص الكنسي الكامل المعكوس هنا.