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

اصل کلی: یک موضوع، یک مرجع. صفحهٔ مرجع هر موضوع را کامل توضیح می‌دهد و بقیهٔ صفحات فقط لینک می‌دهند. سه وضعیت «کد فعلی»، «هدف» و «پیشنهاد» باید از هم جدا بمانند.

موضوع	منبع مرجع
قرارداد wire	packages/contracts؛ OpenAPI خروجی آن
رفتار اجراشده	route/service/client و تست‌های مرتبط؛ خلاصهٔ انسانی در sync
قید ذخیره	Prisma schema و migrations (با هم)
هدف/پذیرش طراحی	طراحی و وضعیت پذیرش با شاهد کد
توکن طراحی	packages/design-tokens/tokens.json، نه خروجی‌های تولیدشده
تاریخچه	Git و ui-design/history — نه مرجع رفتار فعلی

چرخهٔ عمر

صفحات design/ui و هر صفحه‌ای که doc_type دارد، این فیلدهای 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	تاریخ ISO

تفسیر فیلدها: normative می‌تواند هدف باشد و implementation می‌گوید چقدر از آن واقعاً اجرا شده — این دو را با هم یکی نگیرید. proposal رفتار فعلی نیست و archive از ناوبری جاری کنار می‌رود. تاریخ last_reviewed فقط بعد از مرور واقعی تغییر کند؛ دیدن DTO/تصویر/تست محدود، تضمین قابلیت یا بی‌اتلاف‌بودن نیست.

کنترل

از ریشه:

npm run check:governance --prefix docs

این بررسی metadata را کامل می‌سنجد، لینک مرجع به specهای تاریخ‌دار را رد می‌کند، فایل‌های UI در sidebar را می‌پذیرد/رد می‌کند، وجود تصاویر catalog را چک می‌کند و منبع prototype/catalog را کنترل می‌کند. تعداد و عنوان بخش‌های اجباری نیست. توجه: build لینک شکسته را می‌گیرد اما صحت نثر را نه — تست‌ها.