DWP विनिर्देश

संस्करण 1.2. स्थिति: स्थिर। यह दस्तावेज़ Deep Work Plan (DWP) पद्धति का मानक विनिर्देश है। कीवर्ड MUST, MUST NOT, SHOULD, SHOULD NOT और MAY की व्याख्या RFC 2119 में वर्णित अनुसार की जानी है।

v1.2 में योगात्मक। चार योगात्मक क्षमताएँ, कोई breaking changes नहीं: (1) मशीन-पठनीय योजना स्थिति परत (manifest.json + state.json, देखें योजना-स्थिति); (2) आनुपातिक कठोरता स्तर (micro / standard / deep, देखें आनुपातिक कठोरता); (3) कार्य-संरचना में brownfield व्यवहार परिवर्तनों के लिए वैकल्पिक Delta खंड; और (4) DWP Resume Protocol को एक नाम-प्राप्त, उद्धरण-योग्य छह-चरण अनुष्ठान के रूप में प्रोन्नत किया गया। मौजूदा v1.1 योजनाएँ अनुरूप बनी रहती हैं।

परिभाषा

एक Deep Work Plan एक संरचित, केवल-markdown आर्टिफ़ैक्ट है जो एक जटिल इंजीनियरिंग कार्य का वर्णन करता है, जिसे क्रमिक, समीक्षा योग्य काम की इकाइयों में विघटित किया गया है, और जिसे स्वायत्त रूप से काम करने वाले AI कोडिंग एजेंट्स द्वारा बनाने, निष्पादित करने और बनाए रखने के लिए डिज़ाइन किया गया है।

DWP स्पेक-ड्रिवन है: योजना ही विनिर्देश है, और एजेंट्स को सुधार करने के बजाय इसके स्पष्ट स्वीकृति मानदंडों और सत्यापन-गेटों के विरुद्ध निष्पादन करना MUST। विनिर्देश — न कि कोई चैट प्रतिलेख — सत्य का टिकाऊ स्रोत है, इसलिए काम सत्रों और एजेंट्स के पार सत्यापन योग्य और फिर से शुरू होने योग्य है। यह हार्नेस इंजीनियरिंग को पोर्टेबल बनाना भी है: वह कॉन्टेक्स्ट, कंट्रोल लूप, सुरक्षा-कवच और फिर से शुरू होने योग्य स्थिति जो एक एजेंट को भरोसेमंद बनाती है, रिपॉज़िटरी में ही सादे markdown के रूप में स्थापित की जाती है, इसलिए कोई भी अनुरूप एजेंट एक उपकरण-विशिष्ट फ़्रेमवर्क के बिना रिपॉज़िटरी को संचालित कर MAY।

योजना संरचना

एक योजना .dwp/plans/ के अंतर्गत PLAN_<slug>/ नाम की एक डायरेक्टरी MUST होनी चाहिए। डायरेक्टरी में निम्नलिखित MUST होना चाहिए:

• README.md — योजना अवलोकन, लक्ष्य, कार्य-तालिका और स्थिति।
• प्रति कार्य एक फ़ाइल, जिसका नाम <n>.task_<slug>.md है।
• PROGRESS.md — निष्पादन का एक चालू लॉग।

एक योजना MAY अतिरिक्त रूप से मशीन-पठनीय स्थिति परत भी रख सकती है: manifest.json (स्थिर पहचान, मैटेरियलाइज़ेशन पर एक बार लिखी जाती है) और state.json (सजीव प्रति-कार्य निष्पादन स्थिति)। स्थिति परत नई योजनाओं के लिए RECOMMENDED है और अनुपस्थित निष्पादन तथा git के बिना एजेंट कार्यस्थलों के लिए REQUIRED है। देखें योजना-स्थिति।

कार्य-संरचना

कार्य फ़ाइल

1. 01 लक्ष्य
2. 02 संदर्भ
3. 03 चरण
4. 04 स्वीकृति मानदंड
5. 05 सत्यापन
6. 06 फ़ाइलें
7. 07 निर्भरताएँ
8. 08 जोखिम
9. 09 समापन और लॉग

हर कार्य फ़ाइल में ये नौ खंड क्रम में MUST होने चाहिए:

1. Goal — एक अनुच्छेद का कथन कि कार्य क्या हासिल करता है।
2. Context — पृष्ठभूमि, लिंक, और यह कार्य क्यों मौजूद है।
3. Steps — करने के लिए क्रमबद्ध, ठोस क्रियाएँ।
4. Acceptance criteria — उन शर्तों की एक चेकलिस्ट जो पूर्णता को परिभाषित करती हैं।
5. Validation — सत्यापन के लिए चलाई जाने वाली कमांड्स या परीक्षण।
6. Files — बनाई या संशोधित किए जाने की अपेक्षित पाथ।
7. Dependencies — अन्य कार्य या बाहरी पूर्वापेक्षाएँ।
8. Risks — क्या गलत हो सकता है, और शमन-उपाय।
9. Completion & Log — एक स्थिति-चिह्न और कालानुक्रमिक टिप्पणियाँ।

एक कार्य MAY अतिरिक्त रूप से एक Delta खंड (brownfield व्यवहार परिवर्तनों के लिए RECOMMENDED — नीचे देखें) और एक Rollback खंड (माइग्रेशन, अवसंरचना परिवर्तन, या deployment के लिए RECOMMENDED) भी शामिल कर सकता है।

Delta खंड (brownfield परिवर्तन)

अधिकांश वास्तविक काम नया व्यवहार बनाने के बजाय मौजूदा व्यवहार को बदलता है। एक कार्य जो किसी मौजूदा सिस्टम के व्यवहार को बदलता है, उसे SHOULD तीन सूची शीर्षकों का उपयोग करते हुए परिवर्तन को एक स्पष्ट before/after अनुबंध के रूप में वर्णित करते हुए एक Delta खंड रखना चाहिए:

• ADDED — वह व्यवहार जो कार्य के बाद अस्तित्व में है और पहले नहीं था।
• MODIFIED — वह व्यवहार जो दोनों में अस्तित्व में है, was: … → now: … के रूप में कहा गया।
• REMOVED — वह व्यवहार जो पहले अस्तित्व में था और जानबूझकर बाद में चला गया।

प्रत्येक प्रविष्टि MUST एक observable व्यवहार होनी चाहिए — किसी endpoint की प्रतिक्रिया, एक CLI फ़्लैग, एक UI स्थिति, एक default मान — न कि कोई implementation detail। Delta खंड व्यवहार स्तर पर reviewer का diff है: acceptance criteria ADDED/MODIFIED प्रविष्टियों को सत्यापित करती हैं, और REMOVED प्रविष्टियाँ हटाने का स्पष्ट लाइसेंस हैं। REMOVED के रूप में सूचीबद्ध नहीं कुछ भी MUST काम करता रहना चाहिए, और कार्य का सत्यापन गेट (मौजूदा परीक्षण हरे रहना) वही लागू करता है।

सत्यापन-गेट और परीक्षण

सत्यापन वह गेट है जो पूर्णता के दावे को उसके प्रमाण में बदल देता है: किसी कार्य को तब तक पूर्ण अंकित MUST NOT किया जाए जब तक उसके Validation खंड की हर कमांड चल न ली हो और पास न हो गई हो। परीक्षण इस गेट का एक प्रथम-श्रेणी हिस्सा हैं, कोई वैकल्पिक अतिरिक्त वस्तु नहीं — वे ही वह चीज़ हैं जो किसी योजना द्वारा भेजे जाने वाले कोड को भरोसेमंद और सत्यापन योग्य बनाती हैं।

जब कोई कार्य नई मूल कार्यक्षमता जोड़ता है या मौजूदा व्यवहार को सारभूत रूप से बदलता है:

• उसके स्वीकृति मानदंडों में नए या बदले गए व्यवहार के लिए स्वचालित परीक्षण कवरेज शामिल होना MUST (हैप्पी पाथ के साथ-साथ सार्थक एज और त्रुटि मामले), रिपॉज़िटरी की परीक्षण परिपाटी और कवरेज अपेक्षा का अनुसरण करते हुए।
• उसका सत्यापन रिपॉज़िटरी के परीक्षणों को उसकी lint, type-check और format जाँचों के साथ चलाना MUST — रिपॉज़िटरी द्वारा परिभाषित पूर्ण कोड-गुणवत्ता जाँच — न कि अकेले build। किसी व्यवहार-परिवर्तन के लिए “यह build होता है” एक पर्याप्त गेट नहीं है।
• मौजूदा परीक्षण हरे बने रहने MUST। ऐसा परिवर्तन जो प्रभावित कोड को कवर करने वाले किसी परीक्षण को तोड़ता है, उस परीक्षण को इच्छित नए व्यवहार के अनुरूप अद्यतन करना MUST; गेट को पास कराने के लिए किसी परीक्षण को मात्र हटाना, छोड़ना या कमज़ोर करना MUST NOT।

केवल-दस्तावेज़ीकरण, कॉन्फ़िगरेशन, या शोध कार्य परीक्षण बनाने से छूट प्राप्त हैं पर फिर भी रिपॉज़िटरी द्वारा परिभाषित जो भी सत्यापन-गेट हो उसे चलाना MUST। परीक्षण की गहराई परिवर्तन के आकार और रिपॉज़िटरी की परिपक्वता के अनुपात में होती है। जहाँ किसी रिपॉज़िटरी के पास कोई परीक्षण या lint टूलचेन ही न हो, वहाँ एजेंट को इस अनुशासन को चुपचाप छोड़ना MUST NOT — यह ऑनबोर्डिंग के दौरान प्रस्तावित टूलचेन पर निर्भर करता है (देखें अनुरूपता)।

सुरक्षा अनुशासन

सुरक्षा ठीक उसी तरह प्रथम-श्रेणी है जैसे परीक्षण हैं, और यह उसी दो-परत मॉडल का अनुसरण करती है: काम के होते समय प्रति-कार्य अनुशासन, साथ ही अंत में पूरे change set पर एक अनिवार्य Security Review गेट। जब भी कोई कार्य प्रमाणीकरण या प्राधिकरण, input handling, secrets या कॉन्फ़िगरेशन, network, file, या shell सतह, या dependencies को छूता है:

• उसके स्वीकृति मानदंडों में परिवर्तन की सुरक्षा अपेक्षाएँ बताई जानी MUST — input validated और escaped हो, कोड या fixtures में कोई गुप्त सामग्री न हो, auth जाँचें संरक्षित या सुदृढ़ हों — docs/SECURITY.md के अनुरूप।
• हर commit के land होने से पहले उसे secrets या credentials से मुक्त होने की पुष्टि की जानी MUST, test fixtures और दस्तावेज़ीकरण उदाहरण समेत। किसी push किए गए commit में मौजूद secret को लीक हुआ माना और rotate किया जाना MUST, केवल हटाया नहीं।
• जहाँ सुरक्षा-संवेदनशील काम सारभूत हो, वहाँ एक समर्पित hardening कार्य implementation कार्यों के ठीक बाद और comprehensive-tests कार्य से पहले रखा जाना SHOULD, ताकि परीक्षण के व्यवहार को कोड करने से पहले निष्कर्ष ठीक कर लिए जाएँ और हर निष्कर्ष पुनः-काम के बजाय एक regression मामला बन जाए।

यह प्रति-कार्य अनुशासन Security Review अंतिम कार्य का स्थान नहीं लेता: प्रति-कार्य जाँचें उस commit में समस्याएँ पकड़ती हैं जहाँ वे जन्म लेती हैं, जबकि अंतिम गेट पूरी योजना का ऑडिट करता है — परीक्षण और दस्तावेज़ीकरण कार्यों सहित। इसलिए हर योजना तीन अनिवार्य अंतिम कार्यों के साथ समाप्त होती है — Security Review, फिर Skills & Agents Discovery, फिर Executive Report — और एक गंभीर सुरक्षा निष्कर्ष पूर्णता को तब तक अवरुद्ध करता है जब तक उसे ठीक न कर लिया जाए या स्पष्ट रूप से स्वीकार न कर लिया जाए।

कार्य-पूर्णता प्रोटोकॉल

सत्यापन पार करने के बाद और अगले कार्य पर जाने से पहले, एजेंट को क्रम में MUST: (1) योजना README में कार्य को [x] चिह्नित करें; (2) योजना स्थिति गिनती बढ़ाएँ; (3) कार्य के Completion & Log को बिना placeholder मानों के भरें; (4) PROGRESS.md में 3–5 bullet प्रविष्टि जोड़ें; (5) जहाँ योजना कमिट करती है, {type}({scope}): {description} — Task {N} of PLAN_{name} प्रारूप के साथ कमिट करें; (6) जहाँ योजना स्थिति परत रखती है, state.json परमाणु रूप से पुनर्लिखें — कार्य completed, गेट रिकॉर्ड, परिणाम रिकॉर्ड, commit hash।

छह चरण एक तार्किक लेनदेन बनाते हैं। प्रोटोकॉल के बीच में बाधित एजेंट को MUST NOT अगला कार्य शुरू करना चाहिए — उसे पहले आंशिक पूर्णता पूरी या वापस लेनी होगी।

DWP Resume Protocol

रिज्यूम MUST केवल योजना की फ़ाइलों और git लॉग से संभव होना चाहिए, बिना किसी बाहरी स्थिति के। git के बिना एक कार्यस्थल में — देखें आर्किटाइप §3 — योजना का state.json REQUIRED है और git लॉग की जगह लेता है।

एक रिज्यूम करने वाला एजेंट — एक नया सत्र, एक अलग एजेंट, एक अनुसूचित डेमन turn, या एक क्लाउड सत्र जागना — क्रम में यह अनुष्ठान MUST करना चाहिए:

1. पुनः-लंगर डालें। योजना README पढ़ें: लक्ष्य, वैश्विक दिशानिर्देश, कार्य सूची।
2. चेकपॉइंट खोजें। README में पहला अचिह्नित कार्य खोजें; git लॉग और git status (या जहाँ git अनुपस्थित हो state.json का checkpoint) पढ़ें।
3. स्थिति का पुनर्मेल करें। जहाँ state.json मौजूद हो, इसे README चेकबॉक्सों से तुलना करें; desync पर, जारी रखने से पहले markdown से इसे पुनर्जनित करें।
4. Seam का निरीक्षण करें। रिज्यूम-बिंदु कार्य का Completion & Log और अंतिम PROGRESS.md प्रविष्टि पढ़ें — पिछले सत्र की अंतिम सत्यापित भूमि।
5. Smoke-test। यह पुष्टि करने के लिए कि उस पर बनाने से पहले दुनिया अभी भी काम करती है, रिपॉज़िटरी का सबसे सस्ता standing validation चलाएँ। एक विफल smoke test पहले जाँचा जाता है, उस पर बनाया नहीं जाता।
6. परमाणु रूप से जारी रखें। ठीक अगला कार्य निष्पादित करें; आगे batch न करें।

एजेंट को पूर्ण ([x]) चिह्नों पर MUST भरोसा करना चाहिए और MUST NOT पूर्ण किए गए कार्यों को पुनः-सत्यापित करना चाहिए जब तक उपयोगकर्ता इसे स्पष्ट रूप से अनुरोध न करे, या smoke test किसी पूर्ण कार्य को प्रभावित करने वाले तरीके से विफल न हो।

निष्पादन लूप

DWP पाँच संक्रियाएँ परिभाषित करता है:

• create — एक लक्ष्य से एक नई योजना तैयार करें।
• execute — योजना को कार्य-दर-कार्य निष्पादित करें।
• refine — एक मौजूदा योजना को संशोधित करें।
• resume — एक बाधित योजना को फिर से शुरू करें।
• status — बिना निष्पादन के योजना की स्थिति की रिपोर्ट दें।

आउटपुट कार्यस्थल

आउटपुट कार्यक्षेत्र

• .dwp/ git द्वारा अनदेखा · हटाने योग्य
• drafts/ परिष्कृत मसौदे की स्टेजिंग
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ रिपोर्ट
• SECURITY_REVIEW.md सुरक्षा समीक्षा
• EXECUTIVE_REPORT.md कार्यकारी रिपोर्ट

सभी DWP आर्टिफ़ैक्ट रिपॉज़िटरी रूट पर एक gitignored .dwp/ डायरेक्टरी के अंतर्गत MUST रहने चाहिए।

मशीन-पठनीय योजना स्थिति

एक योजना MAY मशीन-पठनीय स्थिति परत रख सकती है — manifest.json (स्थिर पहचान) और state.json (सजीव प्रति-कार्य स्थिति, सत्यापन-गेट रिकॉर्ड, परिणाम रिकॉर्ड, चेकपॉइंट, अवरुद्ध स्थिति)। markdown योजना सत्य का स्रोत बनी रहती है; JSON परत एक व्युत्पन्न प्रक्षेपण है, प्रोटोकॉल बिंदुओं पर पुनर्जनित और रिज्यूम पर पुनर्मेलित।

स्थिति परत नई योजनाओं के लिए RECOMMENDED है, अनुपस्थित निष्पादन के लिए REQUIRED है, और git के बिना एजेंट कार्यस्थलों के लिए REQUIRED है। पूर्ण मानक परिभाषा देखें योजना-स्थिति में।

आनुपातिक कठोरता

कठोरता काम के अनुपात में MUST होनी चाहिए। तुच्छ परिवर्तनों पर अनुष्ठान एक पद्धति विफलता है, अतिरिक्त सुरक्षा नहीं। काम का हर टुकड़ा ठीक एक स्तर में आता है:

micro-tier काम के लिए योजना बनाने के लिए कहे गए एजेंट को MUST कहना चाहिए कि एक योजना अनुपातहीन है और इसके बजाय inline रूप प्रस्तावित करना चाहिए। एक तुच्छ single-file परिवर्तन के लिए plan folder MUST NOT बनाया जाना चाहिए।

Micro-tier काम अभी भी non-negotiables बनाए रखता है: एक स्पष्ट लक्ष्य, एक सत्यापन गेट जो चलता और पास होता है, और व्यवहार परिवर्तनों के लिए परीक्षण अनुशासन। स्तर पैकेजिंग बदलता है, कभी गेट नहीं।

जब scope mid-flight बढ़ता है — एक micro कार्य वास्तविक scope उजागर करता है, एक standard योजना में sub-repositories निकलती हैं — एजेंट को MUST रुकना और काम को अगले स्तर पर प्रोन्नत करना चाहिए बजाय वर्तमान को खींचने के।

संस्करण-निर्धारण

यह विनिर्देश सिमैंटिक वर्शनिंग का अनुसरण करता है।