rasd

Imported from iSltanX/rasd (AGENTS.md). Install upstream with npx skills add iSltanX/rasd. Copyright stays with the author.

تعليمات التنفيذ — رصد

تُقرأ في مستهلّ كل جلسة، قبل أي ملفّ آخر، وتحكم المساعد الرئيسي وكل وكيل فرعي. البيئة والأوامر والبنية في Docs/Development.md، والمرجع الهندسي وسجلّ القرارات في Docs/Engineering.md، والقرارات المعمارية في Docs/ADR/.

أرقام الأقسام ثابتة — تعليقات الشيفرة والوثائق تُحيل إليها (AGENTS.md §4 و§7 خاصّةً). وخطّة التنفيذ التي بُني بها 1.0 (المراحل 01–34 ثمّ نظام SS وموجاته ولوحاته) نُقلت في 2026-10-04 إلى أرشيف التخطيط خارج المستودع العامّ؛ النصّ الكامل السابق لهذا الملفّ معها (Docs/Engineering.md §6 الصفّ 477).

0. الهدف

إضافة متصفّح احترافية للفحص البصري، عربيةٌ أوّلًا ومحلّيةٌ على الجهاز، منشورة في Chrome Web Store (1.0.0) وقنواتها الأخرى في Docs/Release/channels.md. تقديم الإضافة لأي متجر، ونشر إصدار، بأمر المالك وحده.

1. مستهلّ الجلسة

1. اقرأ هذا الملفّ ثمّ ما يخصّ المهمّة من Docs/ — من أحدث نسخة على origin/main (git fetch أولًا).
2. افحص Git قبل أي عمل: git status -sb · git log --oneline -5 · git branch -a · gh pr list --state open · git worktree list. ما يوجد غير ملتزم يُحفَظ جانبًا ويُسأل عنه (§7).
3. هيّئ البيئة: nvm use && corepack enable && pnpm install --frozen-lockfile.
4. على نسخة جديدة على الجهاز، أو شجرة غير نظيفة: pnpm gate:a مرّة لإثبات البيئة. عطلٌ سابق على عملك يُسجَّل قبل أن تبدأ.

القراءة مباشرة لا مسحًا بوكلاء. لا تعتمد على ذاكرة محادثة ولا على ملفّ خارج Git.

2. الأوامر

3. تنفيذ تغيير

1. اقرأ كما في §1، وافحص Git والفروع وطلبات الدمج والتغييرات المحلّية.
2. حدّد النطاق كتابةً قبل التنفيذ. ما يقع خارجه يُسجَّل ولا يُنفَّذ، إلا عطلًا يحبس العمل فيُصلَح بأضيق نطاق ويُسجَّل.
3. نفّذ وشغّل أثناءه الفحوص التي تمسّ ما تغيّر وحدها — «اقتصاد الفحوص» في §4.
4. تحقّق مرّة قرب الإغلاق: أوامر القبول وتُقرأ مخرجاتها الفعلية، ثمّ RASD_GATE_BASE=origin/main pnpm gate:a، ثمّ كل verify:* يطبعه مخروط الأثر (pnpm verify:wave --base origin/main).
5. وثّق ما تغيّر في مرجعه (Docs/… والـADR وصفّ §6 إن كان قرارًا أو تناقضًا مقيسًا)، وCHANGELOG.md لما يراه المستخدم.
6. سلّم وفق §5، وأبلغ: النتيجة، والالتزام أو طلب الدمج، وما سقط باسمه.

لا يُعلَن تغييرٌ مكتملًا وفي أوامر قبوله فشلٌ غير محسوم. إن تعذّر تحقّق يُكتب السبب وما يلزم لاستكماله.

4. قواعد التحقّق

• الشيفرة ونتائج التشغيل هي دليل الحالة، لا كلمة «مكتمل» في وثيقة. عند الشكّ يُقاس.
• لا تُخفَّض عتبة اختبار ولا ميزانية أداء لتظهر النتيجة ناجحة.
• لا يُحذف اختبار ولا يُعطَّل حارس إلا بسجلّ مؤرَّخ بسببه في Docs/Engineering.md §6.
• كل حارس جديد يُثبَت بحالتين: موجبة يمرّ عليها، وسالبة يسقط عليها. حارس بلا سالبة ليس ضمانًا.
• كل إصلاح عطل معه اختبار يسقط قبله وينجح بعده.
• ادّعاء إغلاق بلا أمر يُعاد تشغيله مرفوض. pnpm docs:lint يفرضه على صفوف §6.
• نصّ يراه المستخدم لا يحمل رقم مرحلة — يحرسه tests/unit/no-plan-leak.test.ts.
• عنصر واجهة بلا محرّك يُعرض معطَّلًا بسبب مفهوم للمستخدم، أو يُحذف. لا زرّ صامت.
• رسم ميزة في Figma ليس تنفيذًا لها، وكل شاشة منفَّذة مربوطة بإطارها في Docs/Design.md وكل اختلاف مقصود مكتوب بسببه.
• النطاق في Docs/Scope.md: المستبعَد (SVG وما فيه) لا يعود إلا بقرار مالك مكتوب هناك. والتفويض العامّ يشمل قرارات النطاق والتصميم، ولا يشمل الأفعال التي لا تُعكَس (§7).
• الفشل السابق يُميَّز عن الجديد بجولة أقدم تحمل السقوط نفسه، أو بعَرَضه المسجَّل في Docs/Flaky.md. لا يُعلَن نجاح لم يُثبَت.
• مواد المتجر تطابق الوظائف المنفَّذة فعلًا، ومتطلّبات كل متجر تُقرأ من مصادرها الرسمية يوم التقديم.

اقتصاد الفحوص

القصد حذف التكرار لا تخفيف الجودة: كل فحص يُشغَّل حين يستطيع أن يقول شيئًا جديدًا، ومرّة واحدة.

• البوّابة تُشغَّل على الحالة التي ستُلتزَم. تعديلٌ بعدها يعيدها مرّة؛ وإصلاحٌ بعد سقوط يعيد الساقط وما يمسّه لا الطقم كلّه.
• الأعطال المتقطّعة المعروفة في Docs/Flaky.md، وverify:wave يعيد الساقط مرّة. سقوطٌ بعَرَضه المسجَّل وضمن مداه يُكتب سطرًا ولا يوقف التغيير؛ وعَرَضٌ جديد، أو خارج مداه، أو في حارسٍ ليس في الجدول، يُحقَّق فيه.
• CI استشاريّ لا شرط (ADR 0026): الحكم البوّابة المحلّية وحرّاسها في كروم حقيقي. وإن جرت جولة وقُرئت: خواتيم الوظائف بنداء واحد gh run view <id> --json jobs، والسجلّ للساقطة وحدها. ومسار التوثيق في ci.yml (AGENTS.md · README.md · Docs/**.md|png|svg) يشغّل docs:lint وentrypoints:lint وformat:check وحدها؛ وما عداه المسار الكامل.

البوّابة المحلّية — pnpm gate:a

حتمية بالكامل وسقفها 48 ثانية: pnpm check · pnpm build:bundle · verify:dist · docs:lint · entrypoints:lint · guards:check · guards:firefox-check. ثمّ تطبع مخروط الأثر: أي verify:* يلزم تشغيله لما تغيّر. تجاوز السقف يفرض تقليمًا، لا توسيعًا صامتًا.

المراجعة المستقلّة

قبل تسليم تغييرٍ يمسّ منطقة حسّاسة يراجعه وكيل لم يكتب الشيفرة: src/shared/messaging/contract.ts · src/shared/storage/ · src/shared/settings/ · src/content/host.ts · src/shared/permission-policy.ts · manifest.config.ts · src/background/lifecycle.ts · src/background/gate.ts. المراجع يثبت كل ملاحظة بسيناريو ملموس أو اختبار، وما لا يُثبَت يُسقَط مع ذكر إسقاطه، والمخرَج يشمل قائمة «فُحص ووُجد سليمًا». مراجعٌ واحد افتراضيًّا، وحتى ثلاثة حين يمسّ التغيير الأمن أو المعمار أو التخزين أو الصلاحيات أو عقد الرسائل.

الحرّاس وسجلّهم

• لا تُعدَّل scripts/verify-*.mjs ولا أسماء tests/visual-baselines/phase-NN لإعادة ترقيم أو تحديث مرجع أو تنسيق: سجلّ الترقية يربط سلسلة كل حارس ببصمة ملفّه وما يستورده تحت scripts/، فتعديل تعليقٍ فيه يصفّر سلسلته.
• الحاجبة ما يطبعه pnpm guards:check من عمود blocking المشتقّ. لا يُنزَل حارس حاجب إلا بتعديل ملفّه لسبب وظيفي، ولا يُرقّى إلا بعشر جولات CI خضراء. وpnpm guards:sync بعد تعديل حارسٍ أو إضافته، أو بعد جولة يدوية مكتملة — لا غير.
• حرّاس كروم عبر pnpm verify:wave وحده، وحرّاس Firefox عبر pnpm verify:firefox — منافذها ثابتة متشاركة والقفل على الجهاز.

ثوابت معمارية

• حدود الاستيراد: modules/ لا يستورد من ui/ · content/ لا يستورد من pages/ · shared/ لا يستورد ممّا فوقه.
• التخزين الدائم تملكه الخلفية وصفحات الإضافة. سكربت المحتوى يتعامل بالرسائل وحدها، وdist/content.js خالية من indexedDB.
• كل حقن يمرّ من البوّابة الواحدة (ADR 0020). كل ترميز صورة يمرّ من المخرج الواحد (ADR 0015 و0021).
• كل كتابة إعدادات: تقرأ بـgetSettingsResult() لا بما يبتلع الفشل، وتمرّ من الطابور، ولا تكتب افتراضيات على قراءة فاشلة.
• التوكنز مولَّدة من لقطة Figma. لا قيمة حرفية في مكوّن، ولا تحرير يدوي لـtokens.css.
• الواجهة عربية RTL. الأرقام الهندية للعدّ البشري، والغربية للقياسات والقيم التقنية.
• كل معرفة بالهدف أو باسم متصفّح في src/shared/platform/ وحده (tests/unit/platform-isolation.test.ts).

5. الالتزام والرفع

1. git diff --stat وgit status: الفرق يخصّ التغيير وحده، وتغييرات محلّية غير مرتبطة لا تُضمّ.
2. الالتزام يجمع الشيفرة والاختبارات والوثائق. تغييرٌ بدفعات: كل دفعة التزام محلّي والرفع عند الإغلاق.
3. الفرع: main غير محميّ اليوم، فالالتزام إليه مباشرةً مسموح؛ وإن فُعّلت حماية أو طلب المالك طلب دمج: فرعٌ قصير من آخر main ثمّ PR. حماية الفرع لا تُتجاوَز. وبعد الرفع: git fetch && git rev-parse HEAD origin/<الفرع> — القيمتان متطابقتان.
4. CI لا يُنتظر شرطًا (§4)؛ وعطلٌ يُعاد إنتاجه محلّيًّا يُصلَح بإصلاحٍ حابس.
5. ممنوع: push --force، وإعادة كتابة التاريخ، و--no-verify، وتحريك وسمٍ موضوع أو حذفه.
6. إن تعذّر الرفع أو فشلت المصادقة: يُقال صراحةً «العمل محلّي فقط». لا يوصف بأنه منشور.
7. نُسَخ العمل المعزولة (.claude/worktrees/، خارج Git): تُزال مع فرعها بعد دمجه — فرعٌ غير مدمج أو شجرةٌ غير نظيفة تُحفَظ وتُسأل عنها (§7). ولا تُبقِ فروع مراحل أو جلسات منتهية؛ الحالة الجارية على main وحده.

6. الوكلاء الفرعيون

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

7. البيانات والأسرار

• لا تغيير في مخطّط IndexedDB أو صيغة ملفّ محفوظ بلا ترحيل مرقَّم واختبار يبدأ ببيانات النسخة السابقة، ويُكتب الاختبار ويخضرّ قبل تغيير التخزين لا بعده.
• الشيفرة والاختبارات والأصول وبيانات المستخدم والعمل المحلّي غير الملتزم تُحفَظ. ما يوجد غير ملتزم عند البدء يُحفَظ جانبًا ويُسأل عنه، ولا يُضمّ ولا يُمحى.
• لا أسرار ولا بيانات شخصية ولا node_modules/ ولا dist/ في Git. والمستودع عامّ: كل ما يُلتزَم يُقرأ.
• الإجراءات التي لا تُعكَس — حذف بيانات، نشر في متجر، تغيير صلاحية — تتطلّب موافقة المالك الصريحة في كل مرّة.
• Figma: لا تعديل على الملفّ Gr0dOsmjcVBcaX9M1slf5m إلا بأمر المالك وبقائمةٍ مكتوبة، ولا يُحذف مكوّن قبل عدّ نُسخه.
• المتجر والمستودع: لا تُقدَّم الإضافة للمتجر، ولا تُغيَّر خصوصية مستودع، إلا بأمر صريح من المالك. ومستودع البلاغات iSltanX/app-reports خاصّ دائمًا. ولا يُعرض في الواجهة رابط يعطي 404.

8. قراءة الترقيم التاريخي

تعليقات الشيفرة والـADR وصفوف Docs/Engineering.md §6 تذكر «المرحلة 12» أو «الوحدة 20.3» أو STAGES/NN أو SSn أو «الموجة» أو «الدستور» أو «البوّابة B». هذه كلّها من خطّة التنفيذ التي بُني بها 1.0:

• «المرحلة N» و«الوحدة N.M»: الترقيم الأوّل (قبل 2026-09-29). وSTAGES/NN: المراحل 01–34. وSSn: نظام SS حتى نشر 1.0. ملفّاتها في أرشيف التخطيط خارج المستودع العامّ — تُقرأ أسماءً لمصدر القرار لا روابط.
• «الدستور»: قواعد العمل التي صارت هذا الملفّ. «البوّابة A»: pnpm gate:a. «البوّابة B»: المراجعة المستقلّة في §4.
• Rasd_Plan.md في تعليقات scripts/verify-*.mjs: هو اليوم Docs/Engineering.md — لم تُحدَّث لأن تعديل ملفّ حارس يصفّر سجلّ ترقيته (ADR 0019 و0023).
• tests/visual-baselines/phase-NN: 05 المعرض · 07 النافذة · 08 الالتقاط · 15 المحرّر · 18 المكتبة · 20 الإعدادات.