بازیابی، تحویل و ثبت وضعیت پروژه

وقتی «کار تمام شده» قابل اعتماد نیست

فرض کن یک feature branch برای تغییر coupon-audit به تو تحویل شده است. نام branch مناسب به نظر می‌رسد و README هم می‌گوید کار تمام شده. با این حال، checkout سه نشانه دیگر دارد: یک path در index تغییر دارد، یک path دیگر فقط در working tree تغییر کرده، و path سومی untracked است. کنار repository یک گزارش verification وجود دارد که PASS شده، اما قبل از آخرین تغییر working tree ساخته شده است.

اگر handoff فقط بگوید «روی branch فلان هستیم، تست‌ها سبزند و مرحله بعد merge است»، نفر بعدی نمی‌تواند بفهمد دقیقاً چه stateی را تحویل گرفته، کدام تغییرها جزو کارند، کدام evidence هنوز معتبر است و اولین اقدام امن چیست. این درس برای حل همین مسئله است.

خروجی تو Project State Handoff Record v1 است: یک رکورد قابل بازرسی که resume anchor، deltaهای جاری، evidence اجراشده، محدودیت‌ها و unknownها، و next safe action را طوری ثبت می‌کند که مهندس دیگری بتواند مستقل از حافظه یا chat summary همان وضعیت را بازسازی کند.

این درس قرار نیست workflow روزانه Git، سیاست branch/merge/rebase یا راهبرد تست سازمان را آموزش دهد. Git اینجا فقط یکی از منابع evidence برای state است. معیار نهایی این نیست که چند command اجرا کردی؛ معیار این است که آیا handoff قابل بازیابی و قابل دفاع است یا نه.

سه مسیر، یک معیار تحویل

Foundation برای زمانی است که هنوز بین history، working state و verification evidence مرز روشنی نداری. تعریف‌ها و یک case هدایت‌شده را کامل می‌کنی و سپس scaffold حذف می‌شود.

Repair فقط به اولین تمایز خراب برمی‌گردد. اگر branch و commit را درست ثبت می‌کنی ولی staged و unstaged را قاطی می‌کنی، کل درس از ابتدا تکرار نمی‌شود؛ همان تمایز با یک probe مشخص ترمیم می‌شود.

Experienced / Fast Path syntax آشنا را کوتاه می‌کند، نه evidence bar را. حتی اگر هر روز با Git کار می‌کنی، باید همان artifact، همان limitation disclosure، همان changed-context transfer و همان تصمیم انسانی را ارائه دهی.

یک self-check سریع: اگر فقط branch name و آخرین commit message را داشته باشی، آیا می‌توانی وجود یک unstaged fix یا یک فایل untracked را رد کنی؟ اگر یک verification report مربوط به قبل از آخرین تغییر باشد، آیا PASS قبلی هنوز claim «state فعلی verified است» را پشتیبانی می‌کند؟ اگر پاسخ این دو سؤال روشن نیست، مسیر Foundation را نگه دار.

مدل ذهنی: handoff یک زنجیره evidence است

یک handoff دفاع‌پذیر را به پنج بخش جدا تقسیم کن:

1. Resume anchor: کدام repository، ref/branch و commit نقطه شروع بازسازی هستند؟
2. Working-state boundary: چه deltaهایی نسبت به anchor دیده می‌شوند و هرکدام staged، unstaged یا untracked هستند؟
3. Intent boundary: کدام delta با مسئله تحویلی مرتبط است و کدام incidental است؟ این برچسب باید از evidence پروژه بیاید، نه از حدس بر اساس نام فایل.
4. Evidence ledger: چه checkی اجرا شده، روی کدام state، نتیجه چه بوده، evidence کجاست و چه چیزی هنوز پوشش داده نشده یا stale شده است؟
5. Human next action: با evidence فعلی، اولین اقدام امن چیست و چه blocker یا unknownی مانع claim قوی‌تر می‌شود؟

بین history و state تفاوت مهمی وجود دارد. commit history درباره snapshotهای ثبت‌شده صحبت می‌کند. working tree و index می‌توانند تغییرهایی داشته باشند که هنوز در آن history نیستند. پس «آخرین commit» فقط بخشی از anchor است، نه خلاصه کامل وضعیت جاری.

در fixture این درس، خروجی machine-readable از git status --porcelain=v1 برای تفکیک index، working tree و untracked path استفاده می‌شود. این claim فقط به semantics همین command مربوط است؛ سبزبودن status یا clean بودن tree به‌تنهایی completion یا correctness را ثابت نمی‌کند.

Checkpoint اول

قبل از ادامه، برای سناریوی افتتاحیه یک claim بنویس که هنوز مجاز نیستی مطرح کنی. سپس دقیقاً evidence گمشده را نام ببر. نمونه جنس پاسخ: «نمی‌توانم بگویم state فعلی verified است، چون report باید به current file state وصل شود.» متن دقیق مهم نیست؛ مرز claim مهم است.

ساخت Project State Handoff Record v1

رکورد را با narrative طولانی شروع نکن. ابتدا fieldهای قابل بازرسی را ببند.

1) Resume anchor را قابل تکرار کن

حداقل repository identity، current ref/branch و HEAD object id را ثبت کن. اگر پروژه اطلاعات بیشتری برای بازسازی لازم دارد—مثلاً submodule state یا workspace خاص—آن را هم در boundary خودت اضافه کن. در lab، probe محلی این مقادیر را از checkout مصنوعی گزارش می‌کند؛ لازم نیست commandهای Git را به یک tutorial تبدیل کنی.

branch name به‌تنهایی کافی نیست. همان نام می‌تواند بعداً به commit دیگری اشاره کند. commit id به‌تنهایی هم تمام handoff نیست، چون staged/unstaged/untracked delta ممکن است وجود داشته باشد. anchor باید نقطه ثبت‌شده را مشخص کند و ledger باید تغییرهای بیرون آن نقطه را جداگانه نگه دارد.

2) Deltaها را قبل از خلاصه‌نویسی طبقه‌بندی کن

برای هر path قابل مشاهده، حداقل این‌ها را ثبت کن: path، state class، ارتباط با مسئله، evidence این ارتباط و action پیشنهادی. «مرتبط» یا «نامرتبط» را از روی staged بودن نتیجه نگیر. staged فقط جایگاه change را نسبت به index نشان می‌دهد؛ intention از task brief، محتوا، owner context یا evidence معادل می‌آید.

3) Verification را به state متصل کن

یک PASS بدون scope و state locator به‌سرعت گمراه‌کننده می‌شود. در evidence ledger بنویس check چه زمانی یا روی چه fingerprintی اجرا شده و آیا بعد از آن delta مؤثری ایجاد شده است. اگر report قبل از تغییر فعلی ساخته شده، آن report هنوز یک واقعیت تاریخی است، اما evidence کافی برای claim «current state verified» نیست.

4) Unknown و non-claim را ثبت کن

هنداف خوب فقط چیزهایی را که می‌داند ثبت نمی‌کند؛ چیزهایی را که نمی‌داند هم صریح می‌کند. مثلاً ممکن است ندانیم untracked scratch باید نگه داشته شود یا حذف شود؛ تا وقتی owner evidence نداریم، نباید آن را خودکار وارد deliverable کنیم. یا ممکن است check محلی پاس شود ولی هیچ evidenceای درباره deployment واقعی وجود نداشته باشد. این limitation باید در record بماند.

5) Next safe action را محدود کن

«ادامه بده» action نیست. action باید آن‌قدر bounded باشد که نفر بعدی بداند ابتدا چه کاری را بدون تخریب evidence انجام دهد. در سناریوی این درس، قبل از هر claim نهایی باید state و freshness verification با هم reconcile شوند. ممکن است تصمیم نهایی ACCEPT، MODIFY، REJECT یا BOUNDED_DEFER باشد؛ انتخاب با انسان است و باید به evidence و non-claim وصل شود.

توضیح عمیق: state، intent و evidence سه محور مستقل‌اند

بیشتر handoffهای ضعیف سه سؤال را در یک جمله مخلوط می‌کنند:

• «این change کجاست؟» سؤال state است.
• «این change برای task فعلی است؟» سؤال intent/scope است.
• «این change بررسی شده و قابل قبول است؟» سؤال verification است.

یک فایل می‌تواند staged و در عین حال incidental باشد. یک فایل می‌تواند unstaged ولی کاملاً لازم برای task باشد. یک working tree می‌تواند clean باشد ولی هیچ verification معتبری نداشته باشد. یک report می‌تواند PASS باشد ولی برای snapshot دیگری تولید شده باشد. وقتی این محورهای مستقل را یکی می‌کنی، handoff ظاهراً کوتاه می‌شود ولی recoverability از بین می‌رود.

زنجیره پیشنهادی بازیابی:

exact anchor → current delta → intended/incidental boundary → evidence ledger → unresolved boundary → next safe action → independent recovery check

این همان رابطه‌ای است که asset FND007-A01 نمایش می‌دهد. هیچ امتیاز درصدی یا score تزئینی در این زنجیره وجود ندارد؛ arrowها فقط dependency استدلالی را نشان می‌دهند.

چرا chat summary authority نیست؟

یک summary برای انتقال intent مفید است، اما mutable، ناقص و سخت برای بازتولید است. اگر summary بگوید «همه چیز staged و تست‌شده است» ولی checkout خلاف آن را نشان دهد، repository/evidence state بر narrative مقدم است. این به معنی بی‌ارزش بودن توضیح انسانی نیست؛ توضیح انسانی باید روی evidence قابل اشاره سوار شود.

stale evidence دقیقاً چه مشکلی دارد؟

وقتی report قبل از delta جدید تولید شده، report لزوماً غلط نیست. claim آن محدود شده است: «این check روی state قبلی PASS شده.» promotion نامعتبر زمانی رخ می‌دهد که آن را بدون revalidation به state بعدی تعمیم دهیم. repair معمولاً افزایش تعداد commandها نیست؛ یک probe متمایزکننده است که نشان دهد آیا evidence فعلی همان state را پوشش می‌دهد یا نه.

independent recovery چه چیزی را می‌سنجد؟

نویسنده handoff ممکن است از context ذهنی خودش جاهای خالی را پر کند. successor آن context را ندارد. اگر successor بتواند anchor را پیدا کند، deltaها را همان‌طور طبقه‌بندی کند، stale/fresh evidence را تشخیص دهد و به همان bounded next-action برسد، handoff کار کرده است. لازم نیست command sequence یا wording دو نفر یکسان باشد.

مثال کارشده: coupon-audit را بدون حدس تحویل بده

در checkout درس سه path دیده می‌شود. یکی در index تغییر دارد، یکی فقط در working tree تغییر دارد و یکی untracked است. README جمله‌ای شبیه «complete» دارد. report قبلی نیز PASS است.

گام ۱ — anchor: ابتدا branch/ref و HEAD را ثبت کن. این اطلاعات نقطه تاریخ ثبت‌شده را مشخص می‌کند، نه کل current state را.

گام ۲ — delta ledger: خروجی status را به path-level rowها تبدیل کن و intention را از staged بودن نتیجه نگیر. برای هر path، task brief، diff/content و هر owner evidence موجود را بررسی کن. اگر evidence برای intended یا incidental بودن کافی نیست، UNKNOWN را حفظ کن؛ state class به‌تنهایی مجوز include یا delete نیست.

گام ۳ — evidence freshness: report قبلی fingerprint فایل coupon را ثبت کرده است. اگر hash فعلی با آن fingerprint فرق دارد، report به state قبلی تعلق دارد. عبارت درست این نیست که «تست‌ها خراب‌اند»؛ عبارت دقیق‌تر این است که «PASS قبلی current unstaged delta را پوشش نمی‌دهد.»

گام ۴ — bounded decision: README به‌تنهایی اجازه ACCEPT نمی‌دهد. اگر بعد از تغییر مشاهده‌شده در working tree هنوز current verification دوباره برقرار نشده باشد، MODIFY یا BOUNDED_DEFER ممکن است از ACCEPT دفاع‌پذیرتر باشد، بسته به evidence و policy مسئله. تصمیم باید توسط learner/reviewer انسانی گرفته شود.

گام ۵ — handoff test: نفر دوم فقط با record و checkout باید بتواند بگوید از کدام anchor شروع کند، چه deltaهایی را دست نزند، کدام evidence stale است و اولین action امن چیست. اگر برای این پاسخ مجبور شود از نویسنده بپرسد «منظورت کدام فایل بود؟»، artifact هنوز کافی نیست.

Counterexample: آخرین commit message همان state فعلی است

این shortcut بسیار plausible است، چون commit message intent را خوب خلاصه می‌کند. اما در همین fixture، تغییرهای staged و unstaged خارج از HEAD وجود دارند. پس commit message می‌تواند توضیح history باشد، اما current state را exhaust نمی‌کند. repair این misconception یک state ledger است، نه یک summary طولانی‌تر.

failure modeهای رایج و repair متمایزکننده

«branch درست است، پس می‌توان ادامه داد»

branch فقط بخشی از anchor است. commit target و working delta را هم ثبت کن. اگر branch بعداً به commit دیگری اشاره کند، handoffی که commit id ندارد ambiguity ایجاد می‌کند.

«clean tree یعنی کار تمام شده و verified است»

cleanliness فقط درباره نبودن deltaهای خاص در working/index صحبت می‌کند. completion، acceptance و verification claimهای دیگری‌اند. repair: evidence ledger را جدا از state ledger نگه دار.

«report PASS است، پس current state PASS است»

اول coverage زمانی/state را بررسی کن. اگر report قبل از change جدید ساخته شده، claim را محدود کن و reverification را next action قرار بده.

«هر untracked file باید حذف یا commit شود»

این تصمیم از state class به intent می‌پرد. untracked بودن به‌تنهایی نمی‌گوید فایل متعلق به task هست یا نه. repair: task scope و محتوا را بررسی کن و اگر ambiguity باقی ماند، آن را unknown ثبت کن.

«summary مفصل همه چیز را پوشش می‌دهد»

اگر summary locator ندارد، reviewer نمی‌تواند ادعاها را مستقل reproduce کند. repair: narrative را به anchor، path-level ledger، evidence locator و explicit next action متصل کن.

برای هر failure mode یک سؤال متمایزکننده بپرس: «چه evidenceای می‌تواند این نتیجه را غلط نشان دهد؟» اگر هیچ پاسخ مشخصی نداری، claim احتمالاً بیش از حد قوی است.

برای مهندس باتجربه: context حرفه‌ای را قابل بازبینی کن

در تیم‌های واقعی ممکن است از commit SHA، pull request، ticket، CI link، patch series، worktree یا ابزار داخلی استفاده کنی. این درس شکل واحدی را تحمیل نمی‌کند. invariantها را حفظ کن:

• anchor باید reproducible باشد؛
• deltaهای current state باید جدا از history دیده شوند؛
• intention باید evidence داشته باشد؛
• verification باید به state و scope خودش وصل شود؛
• unknown و residual risk نباید حذف شوند؛
• successor باید بتواند next action را بدون حافظه نویسنده بازسازی کند.

اگر ابزار داخلی شما این invariantها را بهتر از CSV پیاده می‌کند، artifact می‌تواند شکل دیگری داشته باشد؛ اما Project State Handoff Record v1 در این درس baseline قابل بازرسی را تعریف می‌کند. Fast Path مجوز حذف transfer یا human decision نیست.

AI می‌تواند بعد از ثبت state اولیه به مرتب‌سازی record، پیشنهاد probe یا خلاصه‌سازی evidence کمک کند. استفاده material باید disclosure شود. AI نمی‌تواند از روی naming convention اعلام کند change intended است، نمی‌تواند verification را جعل کند و نمی‌تواند تصمیم نهایی را به جای انسان بگیرد.

گزینه‌ها و trade-offها: چه زمانی snapshot بیشتری لازم است؟

گاهی ثبت branch + HEAD + status کافی است؛ گاهی پروژه stateهای دیگری دارد که بدون آن‌ها recovery ناقص می‌شود. مثال‌ها می‌تواند configuration محلی، generated artifact یا dependency state باشد. معیار اضافه‌کردن field این است که آیا بدون آن successor می‌تواند same bounded state را بازسازی کند یا نه.

رکورد حداقلی سریع‌تر است و noise کمتری دارد، اما اگر یک dependency مهم را جا بیندازد، recovery شکست می‌خورد. رکورد بسیار جامع ممکن است همه چیز را dump کند ولی signal مهم را پنهان کند و freshness آن سخت شود. هدف، بیشترین حجم evidence نیست؛ evidence کافی و traceable برای claimهای blocking است.

برای تغییرهای incidental نیز دو خطر متقابل داریم. حذف فوری ممکن است داده مفید صاحب کار را از بین ببرد؛ واردکردن خودکار هم scope را آلوده می‌کند. وقتی evidence intention کافی نیست، گزینه سالم می‌تواند BOUNDED_DEFER باشد: فایل را دست‌نخورده نگه دار، ambiguity را ثبت کن و owner clarification را blocker مشخص قرار بده.

در نهایت، Git success هیچ decision enumی را خودکار انتخاب نمی‌کند. ACCEPT زمانی معنی دارد که artifact و evidence برای claim مورد نظر کافی باشند. MODIFY یعنی مسیر قابل ادامه است ولی state/evidence نیاز به اصلاح مشخص دارد. REJECT برای مسیری است که با evidence موجود قابل دفاع نیست. BOUNDED_DEFER زمانی است که برای تصمیم قوی‌تر evidence یا authority کافی نداریم و scope تعویق روشن است.

تمرین هدایت‌شده و مستقل

تمرین هدایت‌شده

در fixture FND007-LAB1 ابتدا فقط probe غیرمخرب را اجرا کن. سه row برای current delta بساز و برای هر row state class را از intention جدا نگه دار. سپس prior verification report را با current file fingerprint مقایسه کن. اگر پوشش state شکسته است، آن را به‌عنوان limitation ثبت کن، نه به‌عنوان «FAIL جدید» مگر اینکه check فعلی واقعاً fail شده باشد.

Project State Handoff Record را با این fieldها پر کن: repository/ref/HEAD anchor، path، state class، intended/incidental/unknown، evidence locator، verification status/freshness، unresolved assumption، next safe action، human decision و non-claim. scaffold فقط برای pass اول است؛ در submission نهایی باید خودت evidence را تولید و دفاع کنی.

تمرین مستقل / transfer

در transfer case، فقط می‌دانی که نشانه‌های state/history نسبت به case اول تغییر کرده‌اند. anchor و delta را دوباره از evidence فعلی observe کن و هیچ classification قبلی را carry over نکن. اگر strategy به حافظهٔ مثال قبلی وابسته باشد، record می‌تواند بدون هشدار اشتباه شود.

هدف transfer این است که invariantها را نگه داری ولی strategy را با context جدید تطبیق دهی. exact command sequence بخشی از oracle نیست.

چه evidenceای handoff را قابل دفاع می‌کند؟

حداقل evidence package این درس شامل این موارد است:

• resume anchor که successor بتواند همان checkout/ref/HEAD را locate کند؛
• path-level change ledger که staged، unstaged و untracked را جدا می‌کند؛
• intention evidence یا explicit unknown برای هر delta مهم؛
• verification ledger با check name، observed result، evidence locator، covered state و freshness/limitation؛
• حداقل یک unresolved assumption یا صریحاً «none observed» با basis؛
• next safe action محدود و قابل انجام بدون تخریب evidence؛
• human decision از enum چهارگانه و rationale؛
• حداقل یک non-claim؛
• disclosure استفاده از AI/support در صورت material بودن؛
• independent recovery check روی artifact نهایی.

یک evidence item باید بتواند claim را ابطال کند، نه اینکه فقط همان claim را تکرار کند. «README می‌گوید complete» به تنهایی confirmation loop است. اما status، file fingerprint، report locator و task brief می‌توانند مستقل از آن narrative بررسی شوند.

در lab، baseline script فقط تأیید می‌کند fixture مصنوعی به‌صورت سازگار قابل بازرسی است و پاسخ handoff را در اختیار learner نمی‌گذارد. یک submission قابل دفاع باید state/history boundary درست، evidence قابل ردیابی، limitationهای صریح انسانی و recovery موفق در changed-context case را نشان دهد؛ نه اینکه wording خاصی را تقلید کند.

ارزیابی: از یادآوری تا transfer

S1 — retrieval، non-blocking: در یک case کوچک resume anchor، current delta و verification evidence را از هم جدا کن و دو claim را بدون overclaim توضیح بده.

S2 — application، blocking: از case اصلی Project State Handoff Record v1 بساز. narrative-only یا command-only کافی نیست؛ row-level evidence باید قابل بازرسی باشد.

S3 — diagnosis، blocking: اولین promotion نامعتبر را در یک handoff ظاهراً plausible پیدا کن؛ مثلاً تبدیل PASS قدیمی به claim درباره current state. سپس یک probe متمایزکننده پیشنهاد بده.

S4 — decision، blocking: با evidence موجود یکی از ACCEPT، MODIFY، REJECT یا BOUNDED_DEFER را انتخاب کن. evidence، limitation، residual uncertainty و دست‌کم یک non-claim را ثبت کن. AI یا Git نمی‌تواند این تصمیم را به جای تو بگیرد.

S5 — transfer، blocking: repository دوم را بازیابی کن که staged/unstaged split و resume commit آن با case اول فرق دارد، هرچند file contents شبیه‌اند. strategy باید تغییر context را ببیند، نه اینکه record قبلی را کپی کند.

چهار dimension بحرانی non-compensatory هستند: state/history correctness، evidence traceability، human judgment/limitation disclosure و transfer. نمره بالا در یک بعد شکست بحرانی بعد دیگر را جبران نمی‌کند.

منبع و freshness

claim فنی current این درس محدود است: مستندات رسمی Git برای git status توضیح می‌دهد که status تفاوت pathها را میان HEAD/index/working tree گزارش می‌کند، untracked files را جدا نشان می‌دهد و porcelain format برای machine-readable consumption در نظر گرفته شده است. authority این منبع فقط semantics همان command است؛ از آن correctness، intended scope یا readiness نتیجه نمی‌گیریم.

• SRC-GIT-STATUS — FACT / PRIMARY_OFFICIAL

https://git-scm.com/docs/git-status Retrieved: 2026-09-02 Review due: 2026-10-17 Boundary: Git status semantics only.

دو claim دیگر طراحی آموزشی MAKNOW هستند، نه ادعای مستندات Git: handoff باید exact anchor + change ledger + evidence ledger + unresolved boundary + next action را کنار هم نگه دارد؛ و acceptance oracle این artifact، independent recovery است.

در تاریخ authoring این درس هیچ source قفل‌شده‌ای به review_due نرسیده است. اگر source رسمی materially تغییر کند، review_due بگذرد یا authoring claim فنی جدیدی خارج از research map اضافه کند، source verification باید دوباره انجام شود. uncertainty پروژه‌ای نیز باقی می‌ماند: branch، release و workspace conventions بین تیم‌ها متفاوت‌اند و مثال این درس policy جهانی تعریف نمی‌کند.