حکمرانی مستندات

این مستندات چند مخاطب دارد: توسعه‌دهندهٔ بک‌اند، توسعه‌دهندهٔ کلاینت، طراح سیستم طراحی و مخربِ تاریخچه. وقتی چند روایت موازی از یک چیز وجود دارد، باید از همان جا معلوم باشد کدام را ملاک قرار دهیم. این صفحه آن قرارداد را تعریف می‌کند و npm run check:governance آن را در CI اجرا می‌کند.

سلسله‌مراتب منبع حقیقت

موضوع	مرجع	مواد پشتیبان
شکل wire اینجا API	packages/contracts و apps/api/openapi.json تولیدشده	مرجع API و راهنماها
رفتار runtime	کد و تست‌های production	مستندات توضیحی فنی
پایگاه داده	اسکیمای Prisma و migrations	راهنمای پایگاه داده
معنای همگام‌سازی	همگام‌سازی، راستی‌آزمایی‌شده روی کد و تست	specهای تاریخ‌دار فقط زمینهٔ تاریخی‌اند
جهتِ تأییدشدهٔ طراحی	طراحی، مبانی و قراردادهای ui/*	ماتریس وضعیت پذیرش فاصلهٔ هدف تا کد را گزارش می‌کند
طراحی پیاده‌شده	کد production وب و موبایل	استوری‌بوک وب (apps/calendar-web) و گالری خروجی‌های اندروید شاهدِ زنده‌اند؛ ماتریس وضعیت پذیرش شکاف را گزارش می‌کند
توکن‌های ماشین‌خوان	packages/design-tokens/tokens.json	مبانیِ normative مقدارها را تصویب می‌کنند؛ خروجی‌های تولیدشده (tokens.css، اسکیمای Kotlin، tokens-generated.css) هرگز دست‌نویس نمی‌شوند (CI گارد می‌کند)
کارهای تاریخی طراحی	ui-design/history، ui-design/explorations، بریف آرشیوشده	هرگز normative نیستند

قاعده: مستندات به مرجعِ پایین‌تر لینک می‌دهند، نه این‌که ادعا کنند نثر جای کد را می‌گیرد. اگر متنِ صفحه‌ای با مرجعش اختلاف دارد، مرجع ملاک است و صفحه باید اصلاح شود.

چرخهٔ عمر صفحات

صفحاتِ سیستم طراحی و نقشهٔ راه این frontmatter را دارند:

doc_type: reference | guide | proposal | archive
status: normative | experimental | deprecated
implementation: complete | partial | not-started | not-applicable
platforms: [web, android, docs, api]
owner: design-system | api | web | mobile | docs
last_reviewed: 2026-09-09

• implementation پذیرشِ واقعی را جدا از هدف ثبت می‌کند؛ ماتریس دستیِ وضعیت پذیرش همین فاصله را ردیف‌به‌ردیف نگه می‌دارد.
• proposal رفتار آینده را صریح توصیف می‌کند؛ هرگز به‌جای رفتار فعلی خوانده نمی‌شود.
• archive از ناوبری منتشرشده حذف می‌شود و فقط در مخزن می‌ماند.
• last_reviewed فقط بعد از راستی‌آزمایی دوباره در برابر مرجع عوض می‌شود.

راستی‌آزمایی خودکار

اسکریپت docs/scripts/check-doc-governance.mjs (بدون وابستگی، فقط Node builtins):

1. متادیتای چرخهٔ عمر را روی design*.md، ui/*.md و هر صفحه‌ای که doc_type اعلام می‌کند اعتبارسنجی می‌کند — فیلدهای اجباری، مقادیر enum و تاریخ ISO.
2. صفحات منتشرشده را از لینک‌دادن به specهای تاریخ‌دارِ .agents/superpowers/specs منع می‌کند؛ آن‌ها تاریخ‌اند، نه مرجع.
3. هر شناسهٔ ui/* در sidebars.js باید به فایل موجود برسد.
4. نبودِ ui-design/prototypes (منبع پروتایپ‌ها) خطای CI است — از طریق copy-prototypes.mjs --check که در همان زنجیرهٔ check:governance اجرا می‌شود.

اجرا:

npm test --prefix docs                # تست‌های node:test اسکریپت‌های docs
npm run check:governance --prefix docs  # اسکن کامل مخزن

هر دو در job «Docusaurus build»ِ workflow docs بعد از install اجرا می‌شوند. Docusaurus خودش درِ گیتِ لینک‌شکن و رندر است (onBrokenLinks: 'throw').

چه چیزی این صفحه نیست

این صفحه فرایندِ نوشتن مستند را حکمرانی نمی‌کند؛ فقط مرجع و چرخهٔ عمر را صریح می‌کند. ترجمهٔ کامل انگلیسی، مهاجرتِ production به دیدگاه پروتوتایپ‌ها و تولید توکن مشترک ماشین‌خوان، هر کدام پروژه‌های بعدی‌اند و باید تصمیم جدا گرفته شوند.