बहु-सतह हार्नेस अभिसमय

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

1. बहुवचन क्यों

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

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

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

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

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

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

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

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

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

इस कार्य के लिए संचालक ने फ़िक्स्चर द्वारा दर्ज वैकल्पिक सहायक सतहों में ऑप्ट-इन किया। अप्रयुक्त विक्रेता-विशिष्ट रूट कॉन्फ़िग जानबूझकर अनुपस्थित हैं; किसी टूल-विशिष्ट कॉन्फ़िग फ़ाइल को केवल तब जोड़ा जाता है जब वह टूल इस रिपॉज़िटरी के लिए एक सक्रिय संपादन सतह हो।

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

.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, इस अभिसमय दस्तावेज़, schemas/, और CONTRIBUTING.md की ओर लिंक।

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

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

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

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 authorship-header banner per site/content/docs/reference/authorship-header.mdx."
  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. सामंजस्य नियम

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

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

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

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

7. वैलिडेटर

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

- 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 में गणित प्रत्येक कैनोनिकल अनुभाग समाहित करती है, और कैनोनिकल authorship बैनर से प्रारंभ होती है।
• दूसरा प्रत्येक सतह के कैनोनिकल अनुभागों का विश्लेषण करता है; एक सामान्यीकृत तुलक के अंतर्गत साझा अनुभागों के परस्पर संगत होने की पुष्टि करता है (केस-असंवेदनशील, श्वेतस्थान-सहिष्णु, शाब्दिक पुनर्वाक्यांश की अनुमति देता है किन्तु फ़िक्स्चर-परिभाषित दावा सूची पर अर्थपूर्ण समतुल्यता की अपेक्षा करता है)।
• तीसरा यह पुष्टि करता है कि LICENSE की कॉपीराइट पंक्ति और कैनोनिकल बैनर की "Copyright (c)" पंक्ति एक ही लेखक का नाम लेती हैं।

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

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

यह भी देखें

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