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

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

1. परिभाषा एवं सीमाएँ

एक प्लान किसी प्रोजेक्ट के बारे में तर्क करते समय उत्पन्न कोई भी जानबूझकर बनाया गया, क्षणभंगुर वर्किंग आर्टिफ़ैक्ट है, जिसमें निम्नलिखित शामिल हैं किन्तु इन्हीं तक सीमित नहीं:

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

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

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

2. स्थान, दृश्यता एवं नामकरण

• पथ। <project-root>/.apothem/plans/ एकमात्र कैनोनिकल होम है। लीगेसी <project-root>/.plans/ ट्री अब कैनोनिकल नहीं है — इसे apothem migrate-workspace (§5) से अपग्रेड करें। किसी harness कॉन्फ़िगरेशन निर्देशिका में नहीं (उदाहरण के लिए ~/.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 की गई क्षणभंगुर सामग्री हैं; क्षणभंगुर वर्किंग मेमोरी पर एक स्थायी प्रॉवेनेंस मार्कर लगाना एक श्रेणी-त्रुटि है। Frontmatter (§3) प्लान का प्रॉवेनेंस वहन करता है।

3. Frontmatter स्कीमा (सत्यापित)

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

---
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. जीवनचक्र एवं पदोन्नति वर्कफ़्लो

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. माइग्रेशन प्रोटोकॉल — एक-बारगी, किसी Harness प्लान निर्देशिका से प्रति-प्रोजेक्ट .apothem/plans/ तक

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

Tooling. For projects already on the legacy layout — a sibling <project-root>/.plans/ tree plus per-harness <project-root>/.apothem/<harness>/{memory,contexts,learning} stores — the apothem migrate-workspace command collapses both into the shared <project-root>/.apothem/{plans,memory,learning,contexts} working directory. The command is idempotent and non-destructive: it backs up every source it consumes, moves .plans/ to .apothem/plans/, union-merges the per-harness memory and context stores, concatenate-dedups the learning signals, and never overwrites a conflicting record. Run apothem migrate-workspace --dry-run to preview the moves first.

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

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

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

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

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

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

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

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

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

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

इस ईकोसिस्टम को अपनाने वाले प्रत्येक प्रोजेक्ट को अपने .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/plans/ में अपग्रेड करने के लिए apothem migrate-workspace (§5) चलाता है।

7. स्व-प्रवर्तन तंत्र

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

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. प्रति-harness इन-रिपॉज़िटरी निर्देश फ़ाइल — उस harness की निर्देश सतह के लिए उपयुक्त ढाँचे में वही निर्देश प्रतिबिंबित करती है (§4 Plans Discipline); प्रत्येक पंजीकृत harness सतह पर वही सत्यापक द्वारा खोजी जाती है।
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 स्टैन्ज़ा, और harness-स्थानीय प्लान निर्देशिकाओं को निषिद्ध के रूप में नामित करने वाली एक Anti-Pattern स्टैन्ज़ा वहन करता है।
5. एक समर्पित /plan स्लैश कमांड — एक slug + बॉडी स्वीकार करता है, सही frontmatter के साथ <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md पर लिखता है, गंतव्य के .gitignore के सही होने को सुनिश्चित करता है, और harness-config-root पथों पर लिखने से इनकार करता है।
6. एक pre-tool-use हुक — plan-write-guard — प्रत्येक फ़ाइल-लेखन टूल कॉल को इंटरसेप्ट करता है। यदि लक्ष्य पथ किसी harness-स्थानीय प्लान स्थान (उदाहरण के लिए ~/.claude/plans/... या ~/.codex/.plans/...) या किसी अन्य वैश्विक-ईकोसिस्टम पथ से मेल खाता है जिसे ह्यूरिस्टिक प्लान-आकार के रूप में पहचानता है, तो हुक लेखन को रोकता है और वर्तमान प्रोजेक्ट के .apothem/plans/ की ओर पुनर्निर्देशन प्रस्तावित करते हुए एक संरचित पूछताछ उठाता है।
7. CI सत्यापक — no-global-plans बिल्ड को विफल करता है यदि कमिट की गई प्लान वर्किंग मेमोरी प्रकाशित वृक्ष में पुनः प्रकट होती है; plans-discipline-language विफल होता है यदि कैनोनिकल निर्देश किसी पंजीकृत harness निर्देश फ़ाइल या डिफ़ॉल्ट आउटपुट-स्टाइल से हट जाता है। सत्यापक की कैनोनिकल लक्ष्य सतहें (फ़ाइलसिस्टम अनुबंध के रूप में संरक्षित) नीचे के फ़ेंस ब्लॉक में सूचीबद्ध हैं।

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

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

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

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

यह भी देखें

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

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

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