> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-mintlify-9e781f1d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# الذاكرة عبر الجلسات

> تثبيت الجلسة، وبوّابة الإكمال، ولقطات التسليم، وسجل القرارات — الطبقة التي تقتل فقدان ذاكرة الجلسة والعمل الجزئي.

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

## تثبيت الجلسة

عند `SessionStart` (`src/session.js`)، يسجل Forge `HEAD` مرة واحدة لكل جلسة، ويُقلّم
قطع الجلسات الأقدم من أسبوع، ويحقن توجيهًا طازجًا:

<CardGroup cols={2}>
  <Card title="الدروس المتعلَّمة" icon="graduation-cap">
    دروس Cortex المستنبطة من التصحيحات الماضية.
  </Card>

  <Card title="الهدف المُثبَّت" icon="bullseye">
    الهدف المُعلن، بحيث يمكن قياس الانحراف مقابله.
  </Card>

  <Card title="لقطة التسليم" icon="camera">
    ملف `.forge/state.md` المحدود الذي كتبته الجلسة السابقة.
  </Card>

  <Card title="أحدث الالتزامات + التغييرات" icon="code-commit">
    أحدث الالتزامات والتغييرات غير المُلتزَم بها — أدلة لا افتراضات.
  </Card>
</CardGroup>

تتوجّه الجلسة الجديدة بالأدلة، لا بالافتراضات المسبقة.

## بوّابة الإكمال

الحاجز الوحيد الذي قد يُجيب على مسار Stop هو `completion-gate.sh`
(`src/gate.js`). يعمل بشكل متزامن؛ يظل `cortex.sh stop` الخاص بتنقيب الدروس
منفصلًا ولا يستطيع الحجب أبدًا.

مجموعة التغييرات محدودة بالجلسة: الملفات من الالتزامات التي زمن مُلتزمها عند بداية
الجلسة أو بعدها، إضافةً إلى تغييرات شجرة العمل ناقصًا الأوساخ المُلتقطة عند
`SessionStart` — بحيث لا تُلصَق التعديلات السابقة، وتبديل الفروع، و`git pull` بالوكيل.

<Note>
  إذا تحرّكت الشيفرة دون أن يتبعها توثيق أو أثر حالة، تحجب البوّابة **مرة واحدة** مع
  قائمة إصلاح كسبب. كل حالة أخرى تسمح، وكل خطأ داخلي يسمح (فشل بلطف).
  `FORGE_STOPGATE=0` يوقفه.
</Note>

بالنسبة للجلسات التي غيّرت الشيفرة، تشترط البوّابة أيضًا **دليلًا اختباريًا** — إما ملف
اختبار في فرق الجلسة، أو تشغيلًا طازجًا ناجحًا لـ `forge verify` مقابل التغييرات
الحالية. لم تعُد لقطة `forge handoff` وحدها كافية لتجاوز فرع تغيير الشيفرة من البوّابة.

قائمة الإصلاح تُشير إلى الأدوات التي تُنهي العمل:

```bash theme={null}
forge verify                             # record the test evidence for code changes
forge docs sync                          # sweep the diff for stale doc mentions
forge handoff "<done>" --next "<next>"   # write the bounded session snapshot
forge decide "<decision> — <reason>"     # record a choice so no session re-decides it
```

## التسليم والقرارات

مخزنان يحفظان المعرفة عبر الجلسات:

| المخزن                | الدلالة                                                                  |
| --------------------- | ------------------------------------------------------------------------ |
| `.forge/state.md`     | **إعادة كتابة** محدودة (لقطة) — تكلفة التحميل تبقى `O(bound)` إلى الأبد. |
| `.forge/decisions.md` | **ADR-lite** إضافي فقط (`D-####`) مع توأم آلي القراءة لسجل القرارات.     |

كلاهما يرفض الأسرار عند الكتابة. يُعاد حقن `state.md` عند بداية كل جلسة؛ ويُقرأ
`decisions.md` قبل إعادة تقرير أي شيء استقرّت عليه جلسة سابقة.

```bash theme={null}
forge handoff "<what's done>" --next "<what's next>"
forge decide "<decision> — <reason>"
forge decide                 # read the log before re-deciding
```

## مسح التوثيق المدفوع بالفرق

يُجيب `forge docs sync` عن السؤال ذي الشكل الفرقي: المعرِّفات المُغيَّرة (المسارات،
والتعاريف، والرموز المُستدعاة، من الأسطر المضافة *والمحذوفة*) مقابل كل قطعة توثيق
→ UPDATED / STALE (مع إصابات file:line) / VERIFIED-UNAFFECTED، مع تسجيل السبب. هو
مُبلِّغ محض؛ بوّابة الإكمال توفر الأسنان.

<Warning>
  `recall` و`cortex` ذاكرة ملفات وطلبات فقط — **ليست** تعلمًا على مستوى الأوزان.
  التجميع مُلخِّص قد يُهلوس، لذا يبقى إرشاديًا وقابلًا لمراجعة الإنسان وخاليًا من
  الأسرار.
</Warning>