बहु-सतह हार्नेस परिपाटियाँ

डाउनस्ट्रीम योगदानकर्ताओं के लिए कैनोनिकल मानक संदर्भ। यह दस्तावेज़ परियोजना विनिर्देश के बहु-सतह हार्नेस परिपाटी अनुभागों (Spec §0.6 + §2.8 + §4.7) को प्रतिबिंबित करता है; यह वह स्वतंत्र संदर्भ है जो प्रकाशित रिपॉज़िटरी के साथ शिप होता है। आर्किटेक्चरल औचित्य ADR-0003 में दर्ज है।

1. बहुलता क्योंCopy Anchor Link

एक आधुनिक इंजीनियरिंग सतह को कई हार्नेस छूते हैं — चैट कंसोल, IDE-आंतरिक पूर्णता इंजन, पेयर-प्रोग्रामिंग साथी, और पुल रिक्वेस्ट समीक्षक। प्रत्येक अपनी कैनोनिकल कॉन्फ़िगरेशन फ़ाइल पढ़ता है। यदि परियोजना ऐसी केवल एक फ़ाइल शिप करती है, तो शेष रनटाइम अघोषित परिपाटियों के आधार पर चुपचाप मनमाने ढंग से काम करते हैं; रिपॉज़िटरी के भीतर की अनुपस्थित स्मृति तुरंत रिस जाती है।

किसी अनुपस्थित सतह की कीमत मशीन-जनित कोड में मौन ड्रिफ़्ट है — दोष का सबसे बुरा वर्ग, क्योंकि यह अदृश्य रूप से संचित होता है। हर मशीन-जनित आर्टिफ़ैक्ट विचलन को और बढ़ाता है; जब तक कोई मानव समीक्षक विरोधाभास पकड़ता है, तब तक कोडबेस में हफ़्तों की असंगत परिपाटियाँ जमा हो चुकी होती हैं।

हार्नेस-रनटाइम कॉन्फ़िगरेशन परिनियोजन की वास्तविकता के कारण बहुल है। प्रकाशित ईकोसिस्टम को अनिवार्य रूप से §3 में दी गई तीन अनिवार्य सतहें शिप करनी होंगी: AGENTS.md, चैट-कंसोल रनटाइम के लिए एक व्यवहार-स्मृति फ़ाइल (CLAUDE.md), और IDE-आंतरिक पूर्णता रनटाइम के लिए एक रिपो-दायरे वाली निर्देश फ़ाइल। सतहों को अनिवार्य रूप से परस्पर सुसंगत होना होगा — कोई विरोधाभास नहीं, कोई ड्रिफ़्ट नहीं — और उन्हें अनिवार्य रूप से मिलकर एक ही अनुशासन एन्कोड करने होंगे।

2. सुसंगति अनुबंधCopy Anchor Link

दायरे में आने वाली हर परिपाटी सतह (§3) एक चैनल है जो परियोजना के एकल परिपाटी विनिर्देश को व्यक्त करती है। विनिर्देश इनमें विभाजित है:

• साझा अनुभाग — Plans Discipline, संरचित पूछताछ (या सतह-समतुल्य), Authorship Header, Naming, Anti-Patterns, Modal Hierarchy। इन्हें अनिवार्य रूप से हर आवश्यक सतह में दिखना होगा और सभी सतहों में अर्थ की दृष्टि से समतुल्य होना होगा।
• सतह-विशिष्ट अनुभाग — क्षमता फ़्रेमिंग, टूल-कॉल पैटर्न, कोडजेन-बनाम-चैट अंतर। ये सतहों के बीच भिन्न हो सकते हैं, किंतु इनके लिए साझा अनुभागों का खंडन करना वर्जित है।

multi-surface-coherence वैलिडेटर (§7) हर CI रन पर और pre-commit पर चलता है, और अनुबंध को अभिकथित करता है।

सतहें एक ही विनिर्देश को व्यक्त करने वाले अलग-अलग चैनल हैं। साझा अनुभागों को अनिवार्य रूप से सभी सतहों में मेल खाना होगा — अर्थ की दृष्टि से और, जहाँ संभव हो, शब्दशः। सतह-विशिष्ट अनुभागों के लिए साझा अनुभागों का खंडन करना वर्जित है।

3. दायरे में सतहेंCopy Anchor Link

इस रिपॉज़िटरी के लिए ऑप्ट-इन सतहें वे हैं जिन्हें दावा-सूची फ़िक्स्चर (tests/fixtures/multi-surface-claims.yaml) optional-in के अंतर्गत सूचीबद्ध करता है। अप्रयुक्त वेंडर-विशिष्ट रूट कॉन्फ़िग जानबूझकर अनुपस्थित हैं; कोई टूल-विशिष्ट कॉन्फ़िग फ़ाइल केवल तभी जोड़ी जाती है जब वह टूल इस रिपॉज़िटरी के लिए एक सक्रिय संपादन सतह हो।

4. IDE-आंतरिक निर्देश फ़ाइल के लिए अनुभाग सूचीCopy Anchor Link

.github/ के अंतर्गत रिपो-दायरे वाली निर्देश फ़ाइल में अनिवार्य रूप से, इसी क्रम में, निम्नलिखित अनुभाग होने होंगे (प्रत्येक नीचे दिए गए सटीक शीर्षक पाठ के साथ; अनुभागों का मुख्य भाग लिखा जाता है, टेम्पलेट से मुद्रित नहीं किया जाता, किंतु प्रत्येक को अनिवार्य रूप से सूचीबद्ध दावों को कवर करना होगा):

1. Project Context — एक अनुच्छेद: यह रिपॉज़िटरी क्या है, इसे कौन उपयोग करता है, इसकी शीर्ष-स्तरीय संरचना। ठोस; कोई मार्केटिंग नहीं।
2. Coding Conventions — नामकरण, मोडल पदानुक्रम, frontmatter, markdown शैली, और भाषा-विशिष्ट शैली बिंदु जहाँ वे डिफ़ॉल्ट से भिन्न हों।

3. File Headers — रनटाइम द्वारा जनित हर फ़ाइल को अनिवार्य रूप से site/content/docs/reference/authorship-header.mdx के अनुसार, फ़ाइल-प्रकार से मेल खाते टिप्पणी रूप में, कैनोनिकल एकल SPDX-License-Identifier: MIT पंक्ति से शुरू होना होगा। scripts/inject-header.* और site/content/docs/reference/authorship-header.mdx का संदर्भ।

4. Plans Discipline — रनटाइम के लिए ऐसा कोड या स्क्रिप्ट जनित करना वर्जित है जो किसी हार्नेस कॉन्फ़िगरेशन डायरेक्टरी (उदाहरण के लिए ~/.claude/plans/ या ~/.codex/.plans/) या किसी अन्य वैश्विक plans स्थान में लिखे। योजना आर्टिफ़ैक्ट site/content/docs/reference/plans-discipline.mdx के अनुसार <project-root>/.apothem/plans/ में जाते हैं (एक विरासत <project-root>/.plans/ वृक्ष को apothem migrate-workspace के माध्यम से उन्नत किया जाता है)।
5. Structured Inquiry Behavior — जब रनटाइम अनिश्चित हो, तो उसके लिए चुपचाप कुछ गढ़ना वर्जित है। इसके बजाय वह एक स्पष्ट रूप से चिह्नित स्पष्टीकरण ब्लॉक (उदाहरण के लिए, एक # TODO(clarify): <question> टिप्पणी) डालता है और जहाँ सतह अनुमति दे, वहाँ प्रश्न को चैट में सामने रखता है। कोई गढ़ी हुई API नहीं, कोई गढ़े हुए मॉडल नाम नहीं, कोई गढ़े हुए फ़ाइल पथ नहीं।
6. Forbidden Patterns — स्पष्ट निषेध: कोई मार्केटिंग विशेषण नहीं, कोई टालमटोल वाला भराव नहीं, कोई console.log डिबग कचरा नहीं, उपयोगकर्ता होम के लिए कोई हार्ड-कोडेड निरपेक्ष पथ नहीं, सीक्रेट कमिट करना नहीं, .apothem/plans/ (या विरासत .plans/) के अंतर्गत फ़ाइलें कमिट करना नहीं, कैनोनिकल परियोजना निर्देश फ़ाइल का खंडन नहीं।
7. Output Format — जनित कोड/गद्य एकीकृत संवादात्मक आउटपुट परिपाटियों के अनुरूप होता है: निश्चयात्मकता, एकसमान अनुभाग-विभाजन, सघनता, सारांश अनुशासन, उद्धरण। कोड के लिए: प्रलेखित सार्वजनिक सतह, जहाँ भाषा प्रकारों का समर्थन करती है वहाँ टाइप किया हुआ, जहाँ परीक्षण ढाँचा मौजूद हो वहाँ परीक्षित।
8. Review Checklist — अनुमोदन से पहले किसी समीक्षक (मानव या PR-समीक्षा मोड में रनटाइम) को अनिवार्य रूप से क्या सत्यापित करना होगा: हेडर मौजूद, नामकरण अनुपालक, कोई .apothem/plans/ लेखन नहीं, कैनोनिकल परियोजना निर्देश फ़ाइल से कोई विरोधाभास नहीं, वैलिडेटर स्थानीय रूप से हरे।
9. Pointers — AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, यह परिपाटी दस्तावेज़, src/apothem/schemas/, और CONTRIBUTING.md के लिंक।

फ़ाइल site/content/docs/reference/authorship-header.mdx §2 के अनुसार कैनोनिकल लेखकत्व-हेडर SPDX पंक्ति (Markdown रूप) से शुरू होती है — परियोजना द्वारा चुनी गई हेडर-दृश्यता नीति के अनुसार दृश्य या अदृश्य।

IDE-आंतरिक निर्देश फ़ाइल AGENTS.md या CLAUDE.md की शब्दशः प्रति नहीं है। AGENTS.md कैनोनिकल परियोजना निर्देश सतह है, CLAUDE.md उसे Claude Code के लिए प्रतिबिंबित करती है, और IDE-आंतरिक निर्देश फ़ाइल एक इन-एडिटर कोड-पूर्णता रनटाइम को ध्यान में रखकर लिखी गई है, जो ऐसे सुझाव देता है जिन्हें डेवलपर स्वीकार या अस्वीकार करता है। जानकारी (अनुशासन, परिपाटियाँ, एंटी-पैटर्न) समान है; फ़्रेमिंग भिन्न है।

5. दावा सूची संदर्भCopy Anchor Link

tests/fixtures/multi-surface-claims.yaml पर स्थित फ़िक्स्चर प्रत्येक साझा दावे को सूचीबद्ध करता है। नमूना प्रविष्टियाँ:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

वैलिडेटर प्रत्येक सतह को पार्स करता है, प्रत्येक दावे की सतह पर उपस्थिति खोजने का प्रयास करता है (शीर्षक पदानुक्रम + मुख्य-भाग कीवर्ड निष्कर्षण के माध्यम से), और किसी भी चूक या विरोधाभास पर विफल होता है।

6. सामंजस्य नियमCopy Anchor Link

जब दो सतहें किसी साझा दावे पर परस्पर विरोधी पाई जाती हैं, तो डिफ़ॉल्ट सामंजस्य यह है:

AGENTS.md कैनोनिकल परियोजना स्वर है। कोई भी विरोधी सतह सतह-उपयुक्त फ़्रेमिंग में AGENTS.md के अर्थ को प्रतिबिंबित करने के लिए फिर से लिखी जाती है।

सतह-विशिष्ट ओवरराइड की अनुमति केवल एक स्पष्ट, फ़ाइल के भीतर <!-- coherence-override: <claim-id> --> मार्कर के साथ है, जो जानबूझकर किए गए विचलन को समझाने वाले किसी ADR की ओर संकेत करता है। ओवरराइड मार्कर स्वयं वैलिडेटर की अनुमति-सूची में सूचीबद्ध होता है और CI रिपोर्ट में दिखाई देता है।

इस रिपॉज़िटरी के लिए अनुमोदित सामंजस्य रणनीति agents-md-wins है: AGENTS.md कैनोनिकल है, और हर सक्रिय हार्नेस प्रतिबिंब अर्थ की दृष्टि से समतुल्य रहता है।

7. वैलिडेटरCopy Anchor Link

तीन वैलिडेटर मिलकर सुसंगति अनुबंध को लागू करते हैं:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• पहला अभिकथित करता है कि IDE-आंतरिक निर्देश फ़ाइल मौजूद है, पार्स होती है, §4 में गिनाए गए हर कैनोनिकल अनुभाग को रखती है, और कैनोनिकल SPDX-License-Identifier: MIT पंक्ति (Markdown रूप) से शुरू होती है।
• दूसरा प्रत्येक सतह के कैनोनिकल अनुभागों को पार्स करता है; और एक सामान्यीकृत तुलनित्र के अंतर्गत अभिकथित करता है कि साझा अनुभाग परस्पर सुसंगत हैं (केस-असंवेदी, व्हाइटस्पेस-सहिष्णु, शाब्दिक पुनर्कथन की अनुमति देता है किंतु फ़िक्स्चर-परिभाषित दावा सूची पर अर्थगत समतुल्यता की माँग करता है)।
• तीसरा केवल यह अभिकथित करता है कि रूट LICENSE में पार्स-योग्य Copyright (c) <name> पंक्ति है। यह प्रति-फ़ाइल हेडर नहीं पढ़ता, जिनमें कोई लेखक नाम नहीं होता।

8. सतह जीवनचक्रCopy Anchor Link

• सतह जोड़ना। ऑपरेटर संरचित-पूछताछ चैनल के माध्यम से ऑप्ट-इन करता है। जनरेटर दावा सूची के आधार पर सतह लिखता है, वैलिडेटर चलाता है, और यदि सतह-विशिष्ट ओवरराइड की आवश्यकता हो तो ADR दर्ज करता है।
• सतह हटाना। संरचित पूछताछ हटाने की पुष्टि करती है, ADR औचित्य दर्ज करता है, और वैलिडेटर की required-in सूची संशोधित होती है।
• ड्रिफ़्ट पहचान। दावा सूची से भटकने वाला कोई भी कमिट pre-commit / CI द्वारा अस्वीकार किया जाता है; कमिट का लेखक सुसंगति बहाल करने के लिए सतह को फिर से लिखता है।

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

• ADR-0003 — आर्किटेक्चरल औचित्य, विचार किए गए विकल्प।
• tests/fixtures/multi-surface-claims.yaml — कैनोनिकल दावा सूची फ़िक्स्चर।
• AGENTS.md — कैनोनिकल परियोजना स्वर।
• CLAUDE.md — Claude Code प्रतिबिंब।
• site/content/docs/reference/plans-discipline.mdx — Plans Discipline साझा दावे का कैनोनिकल संदर्भ।
• site/content/docs/reference/authorship-header.mdx — Authorship Header साझा दावे का कैनोनिकल संदर्भ।
• परियोजना विनिर्देश §0.6 + §2.8 + §4.7 — यहाँ प्रतिबिंबित पूर्ण कैनोनिकल पाठ।