मूल अवधारणाएँ

AWR किसी प्रोजेक्ट के कार्य-तथ्यों को किसी एक एजेंट वार्तालाप के बाहर रखता है, ताकि काम कॉन्टेक्स्ट खोने, एजेंट बदलने और रीस्टार्ट के बावजूद जीवित रहे। यह लेख उस मॉडल के पीछे के पाँच विचार समझाता है; फिर Quickstart के कमांड और दैनिक वर्कफ़्लो की दिनचर्या स्वाभाविक रूप से समझ आती है।

मूल सिद्धांत: आपकी स्रोत फ़ाइलें (लेजर, योजनाएँ) ही अधिकार हैं, और रनटाइम जो कुछ भी संग्रहित करता है — सत्र, क्लेम, साक्ष्य — उन तथ्यों का जाँचने योग्य प्रोजेक्शन है। AWR कभी गायब आशय का आविष्कार नहीं करता, और कभी भी वार्तालाप ट्रांसक्रिप्ट को दर्ज तथ्य का विकल्प नहीं बनने देता।

प्रोजेक्ट तथ्य: स्रोत लेजर

AWR का स्रोत लेजर (source ledger) एक छोटा कार्य-कॉन्ट्रैक्ट है जो आप साधारण प्रोजेक्ट फ़ाइलों में रखते हैं: एक YAML लेजर जैसे work-ledger.yaml, या कोई मौजूदा Markdown लेजर (*-ledger.md) जो AWR के माध्यम से केवल-पढ़ने योग्य रहता है और अपनी मूल फ़ाइल में संपादित होता है। लेजर दो तरह के तथ्य दर्ज करता है:

लक्ष्य (Goals) — प्रोजेक्ट क्या हासिल करना चाहता है, सफलता के मानदंडों के साथ। लक्ष्य अनिश्चित होने पर draft, candidate या needs_confirmation हो सकते हैं, और स्रोत सामग्री या उपयोगकर्ता निर्देश से समर्थित होने पर active या confirmed। AWR घोषणा की जाँच करता है; यह प्रमाणित नहीं करता कि लक्ष्य किसी इंसान के इरादे से मेल खाता है।
कार्य-आइटम (Work items) — टास्क, जिनका वर्णन नीचे है।

एक न्यूनतम लेजर ऐसा दिखता है:

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

आप इन फ़ाइलों को init के साथ AWR के प्रबंधन में लाते हैं। जब तक आप प्रीव्यू स्वीकार नहीं करते, कुछ भी नहीं लिखा जाता:

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

Init कभी मौजूदा फ़ाइलों को ओवरराइट नहीं करता, और निरीक्षण केवल एक पुनर्निर्मित प्रोजेक्शन कैश को ताज़ा करता है — कभी भी आपके लक्ष्यों, टास्क फ़ाइलों या निष्पादन स्थिति को नहीं।

टास्क: कार्य-आइटम

कार्य-आइटम लेजर का एक टास्क है। इसके मुख्य फ़ील्ड वही हैं जिन्हें AWR वास्तव में जाँच सकता है:

acceptance — पूर्णता मानदंड: टास्क पूरा होने पर क्या अवलोकन योग्य रूप से सत्य होना चाहिए। बाद में पूर्णता रिपोर्ट इन्हीं सटीक मानदंडों से जाँची जाती है।
next_action — स्थायी रूप से दर्ज अगला कदम, और रिकवरी के लिए सबसे मूल्यवान फ़ील्ड: यह किसी नए सत्र को इतिहास दोबारा पढ़े बिना जारी रखने देता है।
सहायक फ़ील्ड: summary, goal, kind, paths, tags, priority, depends_on, owner और milestone।

आप एक JSON ड्राफ़्ट से टास्क बनाते हैं जो केवल स्पष्ट रूप से ज्ञात तथ्य बताता है:

awr work create --input draft.json

निर्माण हमेशा एक ड्राफ़्ट बनाता है। गायब लक्ष्य या आवश्यक तथ्य दिखाई देते रहते हैं, और ड्राफ़्ट कुछ भी निष्पादित या पूर्ण करने की अनुमति नहीं देता; उसे लागू करना एक अलग, स्पष्ट कदम है।

AWR प्रोजेक्ट-स्तरीय संगठन स्थितियाँ भी रिपोर्ट करता है, जैसे not_initialized, needs_organization, ready, blocked, awaiting_verification, completed और closed_without_completion। दो स्थितियाँ रोज़मर्रा में सबसे ज़्यादा मायने रखती हैं: ready का अर्थ है कि कम से कम एक टास्क में स्रोत-घोषित लक्ष्य, स्वीकृति मानदंड, अगली कार्रवाई और हल की गई पूर्व-आवश्यकताएँ हैं; awaiting_verification का अर्थ है कि लेजर के अनुसार टास्क पूरे हैं लेकिन उनकी स्वीकृति रिपोर्ट अभी सभी सत्यापित नहीं हुई हैं।

चेकपॉइंट और सत्र

सत्र किसी एक एजेंट का किसी कार्य-आइटम से जुड़ा कार्यकारी संलग्नक है। चेकपॉइंट उस सत्र की स्थिति का स्थायी रिकॉर्ड है: दर्ज अगली कार्रवाई, खुले लूप, और वास्तविक AWR इवेंट व स्रोत डेल्टा — वार्तालाप की कॉपी नहीं।

जब कोई क्लाइंट सत्र कम्पैक्शन के बाद शुरू या फिर से शुरू होता है, तो AWR चेकपॉइंट से बना रिकवरी कॉन्टेक्स्ट लौटाता है। जब टर्न रुकता या समाप्त होता है, तो बदली हुई अगली कार्रवाई और खुले लूप खोने से पहले सहेज लिए जाते हैं:

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

बिना बदले काम वाले डुप्लिकेट इवेंट अपना चेकपॉइंट पुनः उपयोग करते हैं; बदली हुई प्रगति वाला जारी टर्न एक नया चेकपॉइंट बनाता है। एक ईमानदार सीमा: इसे स्वचालित करने वाला नेटिव हुक एडाप्टर फ़िलहाल केवल Codex के लिए इंस्टॉल होता है। अन्य होस्ट L0 बाइंडर (--client generic) का उपयोग करते हैं, जो किसी होस्ट वार्तालाप को सक्रिय AWR सत्र से जोड़ता है, बिना हुक इंस्टॉल किए। एडाप्टर कभी ट्रांसक्रिप्ट के मुख्य भाग नहीं पढ़ता — यह वही दर्ज करता है जो आप बताते हैं, न कि वह जो कोई मॉडल ने कहा।

क्लेम और हैंडऑफ़

क्लेम वह स्पष्ट लॉक है जो कोई सत्र टास्क निष्पादित करने से पहले धारण करता है। AWR निष्पादन से पहले सत्र क्लेम प्राप्त करना अनिवार्य करता है, और पूर्णता उसकी पुनः जाँच करती है — इसी तरह दो एजेंट चुपचाप एक ही टास्क पर काम करने से बचते हैं।

हैंडऑफ़ काम को एक सत्र या क्लाइंट से उत्तराधिकारी को ले जाता है। आप सत्र को स्पष्ट रूप से फिर से शुरू करते हैं, रिवीज़न जाँचों और उत्तराधिकारी संक्रमण के साथ:

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

या किसी नए क्लाइंट वार्तालाप को उसके पूर्ववर्ती से बाँधें:

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

हैंडऑफ़ दर्ज तथ्यों को ले जाता है — लेजर स्थिति, चेकपॉइंट, निष्पादन इतिहास — प्रोसेस मेमोरी को नहीं। शटडाउन हुक केवल सलाहकार हैं: वे कभी क्लेम रिलीज़ नहीं करते और न सत्र समाप्त करते हैं — हैंडऑफ़ पर वह आपकी स्पष्ट ज़िम्मेदारी बनी रहती है।

डिलीवरी और स्वीकृति

स्वीकृति (acceptance) वह जगह है जहाँ AWR जानबूझकर सख़्त है। कोई टास्क इसलिए पूरा नहीं माना जाता क्योंकि किसी ने लेजर में status: completed लिख दिया। वह तब पूरा माना जाता है जब कोई पंजीकृत पूर्णता रिपोर्ट लेजर के मौजूदा स्वीकृति मानदंडों से सत्यापित हो जाती है।

पूर्णता रिपोर्ट वास्तव में चलाए गए कमांड, वास्तव में सत्यापित दायरा, समय, और नामित जाँचें दर्ज करती है — हर जाँच किसी सटीक स्वीकृति मानदंड से जुड़ती है और अपेक्षित परिणाम के बजाय अवलोकित परिणाम बताती है:

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

पूर्ण करने से पहले, आप रिपोर्ट का प्रीफ़्लाइट करते हैं:

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

प्रीफ़्लाइट कोई कमांड नहीं चलाता, कोई साक्ष्य पंजीकृत नहीं करता और कोई टास्क पूरा नहीं करता — यह रिपोर्ट के बाइट्स पढ़ता है और साक्ष्य तर्क व स्वीकृति मैपिंग लौटाता है। पूर्णता स्वयं एक अलग लेखन है जो क्लेम, निर्भरताएँ, स्रोत ताज़गी और रिपोर्ट बाइट्स की पुनः जाँच करती है; प्रीफ़्लाइट के बाद रिपोर्ट बदलने से उसका डाइजेस्ट अमान्य हो जाता है। केवल स्रोत-घोषित पूर्णता कभी सत्यापित रसीद नहीं देती, और source_completed व verified_completed स्थिति रिपोर्टों में अलग-अलग गिनती बनी रहती है।

एक टास्क, शुरू से अंत तक

ऊपर के लेजर के search टास्क से सब कुछ जोड़कर देखते हैं:

तथ्य। आप awr --project /absolute/project init --accept चलाते हैं; search लक्ष्य और search-api कार्य-आइटम वाला लेजर अधिकार बन जाता है।
टास्क। कार्य-आइटम में स्वीकृति मानदंड और अगली कार्रवाई होती है, इसलिए प्रोजेक्ट ready रिपोर्ट करता है।
सत्र और क्लेम। आप एक स्नैपशॉट से काम तैयार करते हैं, फिर कोड छूने से पहले सत्र क्लेम प्राप्त करते हैं:

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

चेकपॉइंट। काम करते हुए, आप awr client progress से प्रगति सहेजते हैं, ताकि अगली कार्रवाई और खुले लूप क्रैश या कम्पैक्शन के बाद भी बचे रहें।
हैंडऑफ़ (यदि आवश्यक हो)। उत्तराधिकारी awr session resume --from-session … से फिर से शुरू करता है और वही तथ्य पाता है, बिना कोई चैट इतिहास दोहराए।
डिलीवरी। आप ऐसी रिपोर्ट लिखते हैं जिसकी जाँचें सटीक स्वीकृति मानदंड से जुड़ती हैं, उसे awr work prepare-completion से प्रीफ़्लाइट करते हैं, और तभी पूर्णता दर्ज करते हैं। स्थिति अब टास्क को स्रोत SHA के सापेक्ष सत्यापित दिखाती है, न कि केवल पूर्ण चिह्नित।

आगे कहाँ जाएँ

Quickstart — इन अवधारणाओं को पहली बार चलाएँ।
दैनिक वर्कफ़्लो — तैयारी, क्लेम, चेकपॉइंट और पूर्णता का नियमित लूप।