loop-engineering 0.2.0

Deterministic control-plane for bounded software-quality loops.

Loop Engineering

نصب نسخهٔ منتشرشده:

python -m pip install loop-engineering

این مخزن چارچوب مهندسی لوپ‌های عامل‌محور و چندعاملی برای افزایش کیفیت محصولات ساخته‌شده با وایب‌کدینگ است.

هدف، تولید بیشترین حجم کد یا بیشترین تعداد اجرای عامل نیست. هدف، ساخت سامانه‌هایی است که تغییرات کوچک، قابل‌اندازه‌گیری، قابل‌بازبینی و قابل بازگردانی ایجاد کنند و مالکیت انسانی محصول را حفظ کنند.

استفاده به‌عنوان محصول

نسخهٔ محصولی می‌تواند یک پروژهٔ دیگر را بدون انتقال کد آن پروژه و در حالت فقط‌خواندنی بررسی کند. نصب توسعه‌ای در این مخزن:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

راه‌اندازی روی هر پروژهٔ محلی:

loop-engineering init C:\path\to\project
loop-engineering doctor C:\path\to\project\.loop-engineering\inspection.yaml
loop-engineering run C:\path\to\project\.loop-engineering\inspection.yaml
loop-engineering reports C:\path\to\project\.loop-engineering\inspection.yaml --open

فرمان init فناوری‌های اعلام‌شدهٔ پروژه را بدون اجرای کد آن تشخیص می‌دهد و پروفایلی قابل‌حمل با مسیر نسبی می‌سازد. فرمان doctor پیش‌نیازها را کنترل می‌کند. فرمان run شواهد JSON، Markdown و HTML را بیرون از مخزن هدف در پوشهٔ وضعیت کاربر ذخیره می‌کند. فرمان reports نمای فهرست اجراها را می‌سازد.

برای تولید گیت‌های مستقل GitHub Actions:

loop-engineering github C:\path\to\project\.loop-engineering\inspection.yaml

فایل موجود بدون گزینهٔ صریح زیر بازنویسی نمی‌شود:

--force

شرح معماری محصول:

رابط خط فرمان قابل‌استفادهٔ مجدد

راهنمای عملیاتی:

راه‌اندازی محصول Loop Engineering

از کجا شروع کنیم

برای آشنایی و طراحی یک لوپ جدید، اسناد را به این ترتیب بخوانید:

1. مبنای فکری استخراج‌شده از ویدیو:

   مهندسی لوپ از اصول پایه

2. تصمیم معماری پذیرفته‌شده:

   تصمیم ۰۰۰۱: معماری کنترل‌لوپ‌محور

3. اجزا و مرزهای معماری:

   معماری مرجع لوپ‌های چندعاملی

4. قرارداد الزامی هر لوپ:

   قرارداد تعریف و اجرای لوپ

5. کنترل کیفیت، ریسک و توقف:

   گیت‌های کیفیت و سیاست ریسک

6. راه‌اندازی و بهره‌برداری:

   چرخهٔ عمر عملیاتی لوپ

7. پیاده‌سازی مرحلهٔ اول مشاهدهٔ وب‌اپ:

   معماری مشاهدهٔ فقط‌خواندنی

8. مرجع ماژول‌های پایتون:

   مرجع صفحهٔ کنترل پایتونی

ساختار مخزن

.
├── AGENTS.md
├── README.md
├── config/
│   └── portfolio.yaml
├── docs/
│   ├── api/
│   ├── architecture/
│   ├── decisions/
│   ├── foundations/
│   ├── operations/
│   └── standards/
├── loops/
│   ├── README.md
│   └── webapp-quality-observer/
├── pyproject.toml
├── requirements-dev.txt
├── schemas/
│   ├── inspection-profile.schema.json
│   ├── inspection-report.schema.json
│   ├── loop-definition.schema.json
│   └── portfolio.schema.json
├── scripts/
│   ├── run_inspection.py
│   └── validate_loop.py
├── src/
│   └── loop_engineering/
├── tests/
└── templates/
    └── loop/
        ├── feedback.md
        ├── golden-patterns.md
        ├── iteration-report.md
        ├── loop.yaml
        ├── runbook.md
        └── skill.md

هر لوپ واقعی در مسیر زیر قرار می‌گیرد:

loops/<loop-id>/

ساخت یک لوپ جدید

1. بستهٔ زیر را کپی کنید:

   templates/loop/

2. مقصد را با شناسهٔ یکتای لوپ بسازید:

   loops/<loop-id>/

3. فایل تعریف را تکمیل و با شِما اعتبارسنجی کنید:

   schemas/loop-definition.schema.json

   پس از آماده‌سازی وابستگی‌های توسعه، فرمان مرجع اعتبارسنجی چنین است:

   python -m pip install -r requirements-dev.txt
   python scripts/validate_loop.py loops/<loop-id>/loop.yaml
   

   برای بررسی قالب پایه و همهٔ لوپ‌ها:

   python scripts/validate_loop.py --all
   

4. حسگر و خط پایه را پیش از فعال‌کردن عامل اثبات کنید.

5. لوپ را ابتدا در حالت مشاهده‌ای اجرا کنید.

6. پس از تأیید خروجی‌های محدود، آن را به‌تدریج فعال کنید.

شرح کامل این فرایند در سند چرخهٔ عمر آمده است.

ترتیب اعتبار اسناد

اگر میان اسناد تعارضی وجود داشت، این ترتیب حاکم است:

1. تصمیم‌های معماری پذیرفته‌شده؛
2. استانداردهای پروژه؛
3. تعریف نسخه‌بندی‌شدهٔ همان لوپ؛
4. ران‌بوک و مهارت همان لوپ؛
5. اسناد مبنا و یادداشت‌های منبع.

فایل بازخورد می‌تواند رفتار آیندهٔ یک لوپ را دقیق‌تر کند، اما حق نقض استانداردها، گیت‌های ریسک یا تصمیم‌های معماری را ندارد.

اصول غیرقابل چشم‌پوشی

• ابزار قطعی بر عامل زبانی مقدم است.
• هر تکرار باید محدود و قابل‌اندازه‌گیری باشد.
• ارزیابی نباید فقط در اختیار عامل اعمال‌کنندهٔ تغییر باشد.
• خروجی بازبینی‌نشده نباید بدون حد انباشته شود.
• خودکارسازی با شواهد پایداری افزایش می‌یابد، نه با اعتماد اولیه.
• انسان برای ادغام تغییرات محصول، مالک نهایی باقی می‌ماند مگر اینکه یک تصمیم معماری دامنهٔ کم‌ریسک مشخصی را صریحاً مستثنا کند.

وضعیت فعلی

این مخزن اکنون افزون بر بستهٔ پایه، موتور مشاهدهٔ فقط‌خواندنی و پروفایل اثبات‌شدهٔ محصول Sana را دارد. بازرسی‌های Django، پایگاه‌داده، TypeScript، ساخت Vite و یکپارچگی Django/React روی کپی آزمایشی اجرا شده‌اند. حسگر React Doctor نیز با نسخهٔ دقیق، دامنهٔ منبع محدود و خروجی قطعی به بازرس فرانت‌اند متصل است.

لوپ webapp-quality-observer همچنان در وضعیت پیش‌نویس باقی می‌ماند، زیرا مالک و تأییدکنندهٔ انسانی هنوز از مقادیر نمونه جایگزین نشده‌اند و هیچ عملگر اصلاح خودکار یا زمان‌بندی فعال نشده است.

آزمون هسته بدون نصب وابستگی خارجی:

python -m unittest discover -s tests -t . -v

پس از ساخت محیط مجازی و نصب وابستگی‌ها، پروفایل محصول را اعتبارسنجی و با موتور اصلی اجرا کنید:

python scripts/run_inspection.py validate config/inspection.local.yaml
python scripts/run_inspection.py run config/inspection.local.yaml --runtime langgraph