प्लान अनुशासन — प्रोजेक्ट-स्थानीय क्षणभंगुर वर्किंग मेमोरी

डाउनस्ट्रीम योगदानकर्ताओं के लिए कैनोनिकल मानक संदर्भ। यह दस्तावेज़ प्रोजेक्ट विनिर्देश के Plans Discipline खंड (Spec §3) को प्रतिबिंबित करता है; यह प्रकाशित रिपॉज़िटरी के साथ आने वाला स्वतंत्र संदर्भ है। यहाँ प्रस्तुत अनुशासन मूलभूत है; नीचे का हर निर्देश MUST है, जब तक स्पष्ट रूप से अन्यथा चिह्नित न हो। वास्तुशिल्पीय तर्क ADR-0001 में दर्ज है।

1. परिभाषा और सीमाएँCopy Anchor Link

प्लान किसी प्रोजेक्ट पर विचार करते समय उत्पन्न कोई भी जानबूझकर बनाया गया, अस्थायी कार्यशील आर्टिफ़ैक्ट है, जिसमें ये शामिल हैं पर केवल ये ही नहीं:

• आर्किटेक्चर स्केच, सिस्टम-डिज़ाइन वॉकथ्रू, घटक अपघटन।
• कार्य-विभाजन संरचनाएँ, बहु-चरणीय कार्य सूचियाँ, अपघटन वृक्ष।
• रीफ़ैक्टर रणनीतियाँ, माइग्रेशन वॉकथ्रू, रोलआउट अनुक्रम।
• डीबगिंग जर्नल, परिकल्पना लॉग, पुनरुत्पादन नोट्स।
• अन्वेषण नोट्स, स्पाइक राइट-अप, प्रॉम्प्ट ड्राफ़्ट, बाद में उपयोग के लिए रखे गए सहायक ट्रांसक्रिप्ट।
• कोई भी दस्तावेज़ जो सोचने के लिए लिखा गया हो, शिप करने के लिए नहीं।

प्लान इन निकट के वर्गों से श्रेणीबद्ध रूप से भिन्न हैं:

प्लान ADR से पहले आते हैं। जब कोई प्लान किसी टिकाऊ निर्णय पर अभिसरित होता है, तो वह निर्णय एक ADR में पदोन्नत किया जाता है (§4 जीवनचक्र); प्लान स्वयं संग्रहीत या त्यागा जाता है।

2. स्थान, दृश्यता और नामकरणCopy Anchor Link

• पथ। <project-root>/.apothem/plans/ एकमात्र कैनोनिकल होम है। लीगेसी <project-root>/.plans/ ट्री अब कैनोनिकल नहीं है — उसे apothem migrate-workspace (§5) से अपग्रेड करें। यह किसी हार्नेस कॉन्फ़िगरेशन डायरेक्टरी में नहीं है (उदाहरण के लिए ~/.claude/plans/, ~/.claude/.plans/, या ~/.codex/.plans/)। यह किसी डेस्कटॉप स्क्रैच फ़ोल्डर में नहीं है। यह ~/notes/ में नहीं है। यह tmp/plans/ में नहीं है।
• दृश्यता। यह फ़ोल्डर §6 के कैनोनिकल स्निपेट के अनुसार प्रोजेक्ट के .gitignore में पंजीकृत होता है। हार्नेस को किसी भी लेखन से पहले इस प्रविष्टि की उपस्थिति अवश्य सत्यापित करनी चाहिए; अनुपस्थित होने पर वह एक-पंक्ति की हेडर टिप्पणी और इस दस्तावेज़ के लिंक के साथ प्रविष्टि जोड़ देता है।
• फ़ाइलनाम परिपाटी। YYYY-MM-DD--<kebab-case-slug>.md। बड़े वर्कस्पेस के लिए, .apothem/plans/<area>/YYYY-MM-DD--<slug>.md के अंतर्गत उप-वर्गीकृत करें।
  • उदाहरण: .apothem/plans/2026-04-30--auth-refactor-strategy.md, .apothem/plans/api/2026-04-30--rate-limit-rollout.md।
• इंडेक्स। एक वैकल्पिक .apothem/plans/INDEX.md (जो भी gitignore की गई हो) लिंक और स्थितियों को एकत्र कर सकती है; यदि मौजूद हो, तो हार्नेस हर प्लान लेखन पर उसे अद्यतन रखता है।
• संग्रह। अभिसरित या परित्यक्त प्लान .apothem/plans/_archive/ में स्थानांतरित होते हैं। स्पष्ट संरचित-पूछताछ की पुष्टि के बिना उन्हें कभी नहीं हटाया जाता।
• प्लान पर लेखकत्व-हेडर। प्लान, लेखकत्व-हेडर SPDX पंक्ति से छूट प्राप्त हैं (देखें site/content/docs/reference/authorship-header.mdx §Exception List)। वे gitignore की गई क्षणिक सामग्री हैं; क्षणिक कार्यशील मेमोरी पर स्थायी प्रोवेनेंस मार्कर लगाना एक श्रेणी-त्रुटि है। फ़्रंटमैटर (§3) प्लान का प्रोवेनेंस वहन करता है।

3. फ़्रंटमैटर स्कीमा (सत्यापित)Copy Anchor Link

हर प्लान फ़ाइल यह वहन करती है:

---
title: <human-readable title>
project: <git-remote-url-or-canonical-local-path>
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
status: draft | in-progress | converged | abandoned
tags: [<kebab>, ...]
supersedes: <prior-plan-relative-path or null>
promotes-to: <ADR path or null>
---

प्लान के लिए एक JSON Schema src/apothem/schemas/plan.schema.json में रहती है। /plan स्लैश कमांड (और plans-discipline-language सत्यापक) हर लेखन पर इसके विरुद्ध सत्यापन करता है।

4. जीवनचक्र और पदोन्नति वर्कफ़्लोCopy Anchor Link

1. Draft — प्रारंभिक निर्माण; status: draft।
2. In-progress — सक्रिय रूप से पुनरावृत्त; status: in-progress; हर सारवान संपादन पर updated ताज़ा होता है।
3. अभिसरण (Convergence) — एक टिकाऊ निर्णय आकार लेता है:
   1. निर्णय को प्रोजेक्ट के अनुसमर्थित ADR स्थान पर एक नए ADR में निकालें।
   2. प्लान का promotes-to ADR पथ पर सेट करें।
   3. status: converged सेट करें।
   4. वैकल्पिक रूप से .apothem/plans/_archive/ में स्थानांतरित करें।
4. परित्याग (Abandonment) — दिशा परित्यक्त; status: abandoned; संग्रहीत करें या, स्पष्ट संरचित पूछताछ के साथ, त्याग दें।
5. अधिक्रमण (Supersession) — जब कोई नया प्लान किसी पुराने का स्थान लेता है, तो नए प्लान के supersedes को पुराने प्लान के पथ पर सेट करें, और पुराने प्लान का status तदनुसार सेट करें।

पदोन्नति एकमात्र मार्ग है जिससे प्लान की सामग्री टिकाऊ, संस्करण-नियंत्रित और टीम के साथियों को दिखाई देने योग्य बनती है। कोई भी प्लान कभी भी पूरी तरह से कमिट किए गए स्रोत में स्थानांतरित नहीं होता।

5. माइग्रेशन प्रोटोकॉल — एक-बारगी, हार्नेस प्लान डायरेक्टरी से प्रति-प्रोजेक्ट .apothem/plans/ तकCopy Anchor Link

नोट। यह प्रोटोकॉल उन डाउनस्ट्रीम प्रोजेक्ट्स पर लागू होता है जो पहली बार Plans Discipline अपना रहे हैं, जहाँ पहले के योजना आर्टिफ़ैक्ट किसी हार्नेस कॉन्फ़िगरेशन डायरेक्टरी के भीतर रहते हैं (उदाहरण के लिए ~/.claude/plans/, ~/.claude/.plans/, या किसी अन्य हार्नेस के समतुल्य पथ)। इकोसिस्टम के स्वयं के मामले में पुनरावर्ती स्थिति को हल करने के लिए हार्नेस-स्थानीय प्लान स्थिति को भौतिक रूप से स्रोत में स्थानांतरित करने के बजाय उसे gitignore किया जाता है।

टूलिंग। जो प्रोजेक्ट पहले से लीगेसी लेआउट पर हैं — एक साथ रहने वाला <project-root>/.plans/ ट्री तथा प्रति-हार्नेस <project-root>/.apothem/<harness>/{memory,contexts,learning} स्टोर — उनके लिए apothem migrate-workspace कमांड दोनों को साझा <project-root>/.apothem/{plans,memory,learning,contexts} कार्यशील डायरेक्टरी में समेट देता है। यह कमांड इडेमपोटेंट और गैर-विनाशकारी है: यह हर उपभोग किए गए स्रोत का बैकअप लेता है, .plans/ को .apothem/plans/ में ले जाता है, प्रति-हार्नेस मेमोरी और संदर्भ स्टोरों को यूनियन-मर्ज करता है, लर्निंग संकेतों को जोड़-और-डुप्लिकेट-हटाकर संयोजित करता है, और किसी विरोधी रिकॉर्ड को कभी अधिलेखित नहीं करता। पहले स्थानांतरणों का पूर्वावलोकन करने के लिए apothem migrate-workspace --dry-run चलाएँ।

माइग्रेशन इडेमपोटेंट है और हार्नेस-स्थानीय प्लान डायरेक्टरी हटाए जाने के क्षण तक प्रतिवर्ती है (उसके बाद ./.audit/plans-backup-<timestamp>.tar.gz पर एक बैकअप टारबॉल रोलबैक आर्टिफ़ैक्ट देता है)। नीचे के उदाहरण ~/.claude/plans/ का उपयोग करते हैं; सक्रिय हार्नेस के लिए समतुल्य पथ प्रतिस्थापित करें।

चरण 1 — सूची-निर्माण। हार्नेस-स्थानीय प्लान डायरेक्टरी के अंतर्गत हर फ़ाइल की गणना की जाती है और उसे plan-artifact (quarantined) के रूप में वर्गीकृत किया जाता है।

चरण 2 — प्रोवेनेंस मानचित्र। हर प्लान के लिए एक प्रोवेनेंस रिकॉर्ड बनाया जाता है, जिसमें एक अनुमानित गंतव्य प्रोजेक्ट और विश्वास स्कोर होता है, जो frontmatter के project फ़ील्ड, बॉडी-स्कैन संकेतों (रिपॉज़िटरी URL, पैकेज नाम, निरपेक्ष पथ) और संदर्भगत संकेतों से व्युत्पन्न होता है।

चरण 3 — मानचित्र की पुष्टि। पूरा मानचित्र ऑपरेटर को एकल समेकित संरचित पूछताछ के रूप में प्रस्तुत किया जाता है (या जब फ़ाइलों की संख्या सुविधाजनक एकल-प्रॉम्प्ट आकार से अधिक हो, तो कसे हुए बैच के क्रम में)। हर प्लान के लिए, ऑपरेटर इनमें से चुनता है:

• पुष्टि करें अनुमानित गंतव्य प्रोजेक्ट की।
• पुनर्निर्दिष्ट करें (Reassign) किसी भिन्न प्रोजेक्ट को (विकल्प ऑपरेटर की ज्ञात प्रोजेक्ट सूची प्रस्तुत करता है)।
• स्थगित करें (Defer) — बाद में छाँटने के लिए ~/.claude/.audit/orphan-plans/<original-name> में ले जाएँ।
• त्यागें (Discard) — केवल स्पष्ट, अलग से पुष्ट संरचित पूछताछ के साथ (यह विनाशकारी है)।

जब कई प्लान के लिए विश्वास high हो, तो प्रॉम्प्ट राउंड-ट्रिप घटाने के लिए एक confirm-all-high-confidence सुविधा देता है, फिर भी लॉग में हर व्यक्तिगत निर्णय सामने रखता है।

चरण 4 — स्थानांतरण से पहले प्रोजेक्ट की तैयारी। हर अद्वितीय गंतव्य प्रोजेक्ट के लिए:

1. सत्यापित करें कि प्रोजेक्ट रूट मौजूद है और पढ़ने योग्य है।
2. सत्यापित करें कि यह एक git रिपॉज़िटरी है (गैर-git रूट के लिए, संरचित-पूछताछ चैनल के माध्यम से पूछें कि आगे बढ़ना है, आरंभ करना है, या छोड़ना है)।
3. सुनिश्चित करें कि <project-root>/.apothem/plans/ मौजूद है; यदि नहीं, तो mkdir -p से बनाएँ।
4. सत्यापित करें कि प्रोजेक्ट के .gitignore में §6 का कैनोनिकल स्निपेट है; यदि नहीं, तो इस माइग्रेशन का श्रेय देने वाली हेडर टिप्पणी के साथ उसे जोड़ें।
5. सत्यापित करें कि <project-root>/.apothem/plans/ पहले से git द्वारा ट्रैक नहीं हो रहा; यदि हो रहा है (किसी पूर्व योगदानकर्ता की भूल), तो untrack-and-keep, untrack-and-remove-from-history, abort विकल्पों के साथ संरचित-पूछताछ चैनल के माध्यम से सामने लाएँ।

चरण 5 — स्थानांतरण। हर पुष्ट प्लान → गंतव्य जोड़े के लिए:

1. गंतव्य फ़ाइलनाम की गणना करें: यदि स्रोत में frontmatter है, तो §3 के अनुसार सामान्यीकृत करें; अन्यथा बॉडी को frontmatter से लपेटें (status draft, project फ़ील्ड सेट, created mtime से, tags [migrated]) और उसका नाम YYYY-MM-DD--<slug>.md रखें।
2. यदि गंतव्य पर नाम का टकराव हो, तो -imported-<unix-timestamp> जोड़ें और नाम-परिवर्तन को लॉग करें।
3. फ़ाइल कॉपी करें (mtime संरक्षित रखते हुए), गंतव्य पर SHA-256 मेल सत्यापित करें, फिर स्रोत को अनलिंक करें।
4. <project-root>/.apothem/plans/_migration-manifest.md (जो भी gitignore की गई हो) में एक प्रविष्टि जोड़ें, जिसमें यह दर्ज हो: मूल हार्नेस-स्थानीय पथ, गंतव्य पथ, मूल SHA-256, टाइमस्टैम्प, और वह संरचित-पूछताछ उत्तर जिसने इस स्थानांतरण को अधिकृत किया।

चरण 6 — सत्यापन। सभी स्थानांतरणों के बाद:

1. पुष्टि करें कि हार्नेस-स्थानीय प्लान डायरेक्टरी खाली है (अनाथ प्लान, यदि कोई हों, उस हार्नेस की ऑडिट/क्वारंटीन डायरेक्टरी में हैं, जो शीघ्र ही हटाई जाने वाली डायरेक्टरी के बाहर है)।
2. पुष्टि करें कि हर गंतव्य प्रोजेक्ट में एक भरी हुई .apothem/plans/ और एक मैनिफ़ेस्ट है।
3. SHA-256 से स्पॉट-चेक करें कि स्थानांतरित सामग्री मूल से मेल खाती है।

चरण 7 — टारबॉल और हटाना। ./.audit/plans-backup-<ISO-timestamp>.tar.gz बनाएँ, जिसमें पूरा पूर्व-स्थानांतरण हार्नेस-स्थानीय प्लान ट्री हो (चरण 1 पर लिए गए अस्थायी स्नैपशॉट से निकाला गया)। फिर, तैयारी की पुष्टि करने वाली अंतिम संरचित पूछताछ के माध्यम से, अब-खाली हार्नेस-स्थानीय प्लान डायरेक्टरी हटाएँ।

चरण 8 — ऑडिट रिकॉर्ड। ./.audit/plans-migration.md जारी करें, जो हर स्थानांतरण, हर स्थगित फ़ाइल, हर त्याग, हर नाम-टकराव पुनर्नामन और हर gitignore जोड़ का सारांश देता है।

6. डाउनस्ट्रीम .gitignore स्निपेट (कैनोनिकल, कॉपी-पेस्ट)Copy Anchor Link

इस इकोसिस्टम को अपनाने वाले हर प्रोजेक्ट को अपनी .gitignore में निम्न ब्लॉक अवश्य जोड़ना होगा:

# Apothem working directory (project-local shared state: plans, memory,
# learning, contexts; gitignored — never committed). The sole canonical plans
# home is `.apothem/plans/`.
# See: <repo-url>/blob/main/site/content/docs/reference/plans-discipline.mdx
# Ignore the CONTENTS of this directory (not the directory) so the
# `.keep` negation below can take effect.
.apothem/*
!.apothem/.keep

वैकल्पिक .keep छूट, खाली पथों को छाँटने वाले टूल्स में डायरेक्टरी के अस्तित्व को बनाए रखती है, बिना सामग्री लीक किए। .keep शामिल करना है या नहीं, यह /plan के पहले आह्वान पर संरचित-पूछताछ चैनल के माध्यम से प्रति-प्रोजेक्ट तय होता है। .apothem/* + !.apothem/.keep पंक्तियाँ कैनोनिकल स्निपेट हैं; जो प्रोजेक्ट अब भी लीगेसी <project-root>/.plans/ ट्री रखता है, वह apothem migrate-workspace (§5) चलाता है, ताकि उसे .apothem/plans/ में अपग्रेड किया जा सके।

7. स्व-प्रवर्तन तंत्रCopy Anchor Link

यह अनुशासन हर भावी सत्र में टिके रहना चाहिए। निम्नलिखित प्रवर्तन सतहें अनिवार्य हैं और प्रकाशित इकोसिस्टम में एन्कोड की गई हैं:

1. AGENTS.md और मिरर निर्देश सतहें — शीर्ष-स्तरीय अनिवार्य व्यवहार-ब्लॉक, जो यह कहता है: "Planning artifacts are written to <project-root>/.apothem/plans/ — the sole canonical plans home (a legacy <project-root>/.plans/ tree is upgraded via apothem migrate-workspace) — never to any harness configuration directory (for example ~/.codex/ or ~/.claude/) and never to a global location. This rule is non-negotiable; cite §3 of the project spec on every related decision." यह ब्लॉक plans-discipline-language सत्यापक द्वारा पहचाना जाता है।
2. प्रति-हार्नेस इन-रिपॉज़िटरी निर्देश फ़ाइल — उस हार्नेस की निर्देश सतह के ढाँचे में वही निर्देश प्रतिबिंबित करती है (§4 Plans Discipline); प्रत्येक पंजीकृत हार्नेस सतह पर वही सत्यापक इसे खोजता है।
3. डिफ़ॉल्ट आउटपुट-स्टाइल — जब कोई प्रतिक्रिया प्लान-आकार की सामग्री उत्पन्न करेगी (बहु-चरणीय रणनीति, अपघटन, डिज़ाइन वॉकथ्रू, डीबगिंग जर्नल), तो स्टाइल आर्टिफ़ैक्ट को इनलाइन प्रिंट-करके-त्यागने के बजाय एक प्रोजेक्ट-स्थानीय .apothem/plans/ लेखन की ओर रूट करता है। स्टाइल स्पष्ट रूप से निर्देश देता है: "If no project root is discoverable, halt with a structured inquiry asking the operator where to plan."
4. हर प्रत्यायोजित वर्कर प्रॉम्प्ट — किसी भी योजना आर्टिफ़ैक्ट के गंतव्य के रूप में .apothem/plans/ को नामित करने वाली एक Output Surface स्टैन्ज़ा, और हार्नेस-स्थानीय प्लान डायरेक्टरियों को निषिद्ध के रूप में नामित करने वाली एक Anti-Pattern स्टैन्ज़ा वहन करता है।
5. एक समर्पित /plan स्लैश कमांड — एक slug और बॉडी स्वीकार करता है, सही frontmatter के साथ <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md पर लिखता है, गंतव्य के .gitignore की शुद्धता सुनिश्चित करता है, और हार्नेस-कॉन्फ़िग-रूट पथों पर लिखने से इनकार करता है।
6. एक pre-tool-use हुक — plan-write-guard — हर फ़ाइल-लेखन टूल कॉल को इंटरसेप्ट करता है। यदि लक्ष्य पथ किसी हार्नेस-स्थानीय प्लान स्थान (उदाहरण के लिए ~/.claude/plans/... या ~/.codex/.plans/...) या किसी अन्य वैश्विक-इकोसिस्टम पथ से मेल खाता है, जिसे ह्यूरिस्टिक प्लान-आकार का पहचानता है, तो हुक लेखन रोक देता है और वर्तमान प्रोजेक्ट के .apothem/plans/ की ओर पुनर्निर्देशन प्रस्तावित करते हुए एक संरचित पूछताछ उठाता है।
7. CI सत्यापक — no-global-plans बिल्ड को विफल करता है यदि कमिट की गई प्लान कार्यशील मेमोरी प्रकाशित ट्री में दोबारा दिखती है; plans-discipline-language विफल होता है यदि कैनोनिकल निर्देश किसी पंजीकृत हार्नेस निर्देश फ़ाइल या डिफ़ॉल्ट आउटपुट-स्टाइल से हट जाता है। सत्यापक की कैनोनिकल लक्ष्य सतहें (फ़ाइलसिस्टम अनुबंध के रूप में संरक्षित) नीचे के फ़ेंस्ड ब्लॉक में सूचीबद्ध हैं।

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

8. पूर्व-कमिट हुक — उपरोक्त को स्थानीय रूप से प्रतिबिंबित करते हैं ताकि कोई भी कमिट दर्ज होने से पहले अनुशासन लागू हो।

8. एंटी-पैटर्न (श्रेणीबद्ध रूप से निषिद्ध)Copy Anchor Link

• हार्नेस कॉन्फ़िगरेशन डायरेक्टरी (उदाहरण के लिए ~/.claude/plans/ या ~/.codex/.plans/) या किसी अन्य वैश्विक स्थान के भीतर प्लान लिखना।
• प्लान को किसी प्रोजेक्ट के git इतिहास में कमिट करना (कमिट-समय हुक को इसे अस्वीकार करना चाहिए)।
• प्लान को ADR के साथ मिलाना (भिन्न जीवनचक्र, भिन्न स्थान, भिन्न कमिट-स्थिति)।
• frontmatter के बिना प्लान, दिनांक-उपसर्ग रहित फ़ाइलनाम वाले प्लान, project फ़ील्ड के बिना प्लान।
• क्रॉस-प्रोजेक्ट प्लान (एक प्लान, दो प्रोजेक्ट)। उन्हें विभाजित करें — हर प्रोजेक्ट के लिए एक प्लान।
• हार्नेस कॉन्फ़िग सिंक (उदाहरण के लिए Claude Code के लिए ~/.claude) के माध्यम से मशीनों के बीच प्लान साझा करना — प्लान को प्रोजेक्ट-स्थानीय रखने का एक संरचनात्मक तर्क यह है: जब कभी प्लान साझा करना उचित हो, तो प्रोजेक्ट रिपॉज़िटरी स्वयं सिंक तंत्र है — और ऐसा औचित्य स्वयं एक संकेत है कि सामग्री को ADR में पदोन्नत किया जाना चाहिए।
• प्रत्यायोजित-वर्कर प्रॉम्प्ट, स्किल बॉडी, या आउटपुट-स्टाइल के भीतर प्लान सामग्री एम्बेड करना। वे सतहें टिकाऊ व्यवहार-कॉन्फ़िगरेशन हैं; प्लान क्षणिक कार्यशील मेमोरी हैं।
• किसी प्लान फ़ाइल पर लेखकत्व-हेडर SPDX पंक्ति लगाना (प्लान अपने डिज़ाइन से छूट प्राप्त हैं — §2, site/content/docs/reference/authorship-header.mdx §Exception List)।

यह भी देखेंCopy Anchor Link

• ADR-0001 — वास्तुशिल्पीय तर्क, विचारित विकल्प, स्वीकार किए गए समझौते।
• site/content/docs/reference/authorship-header.mdx — लेखकत्व-हेडर SPDX-पंक्ति अनुशासन (प्लान श्रेणीबद्ध रूप से छूट प्राप्त हैं)।
• हार्नेस परिपाटी पृष्ठ — बहु-सतह हार्नेस परिपाटियाँ (Plans Discipline हर पंजीकृत हार्नेस निर्देश फ़ाइल और हर ऑप्ट-इन वैकल्पिक सतह पर एक साझा दावे के रूप में दिखता है)। पथ:

site/content/docs/reference/ai-conventions.mdx

• प्रोजेक्ट विनिर्देश §3 — यहाँ प्रतिबिंबित पूर्ण कैनोनिकल पाठ।