প্রকল্প সম্পর্কে

CoalLedger হলো AI কোডিং এজেন্টদের জন্য তৈরি একটি ডকুমেন্টেশন-কোয়ালিটি টুল, যাকে এর লেখক "ডকুমেন্টেশনের জন্য CoalMine" হিসেবে বর্ণনা করেছেন। এটি TheColliery-এর অংশ, যা ছোট ছোট অ্যাড-অন স্যুটগুলোর (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) একটি পরিবার। এই পরিবারটির মূল নীতি হলো জিরো-ডিপেন্ডেন্সি হুকস, সিঙ্গেল-সোর্স কনফিগ স্কিমা, অনুমতিক্রমে খরচ এবং কোনো স্বয়ংক্রিয় এডিট না করা। CoalLedger এককভাবে অথবা অন্যান্য টুলের সাথে ইনস্টল করা যেতে পারে। এর মূল ধারণাটি হলো—কোডের জন্য লিন্টার, টেস্ট এবং CI থাকলেও ডকুমেন্টেশনের ক্ষেত্রে মূলত আশার ওপর নির্ভর করতে হয়: যেমন কোড থেকে দূরে সরে যাওয়া README, অনুবাদ যা মূল টেক্সটের সাথে মেলে না, মৃত ইনস্টল লিঙ্ক বা পুরনো ভার্সন ব্যাজ—এগুলো এমন নীরব ব্যর্থতা যা পাঠক তবুও বিশ্বাস করে। CoalLedger যেকোনো ডকুমেন্ট (README, স্পেক, রিপোর্ট, অনুবাদ) স্ক্যান করে এবং যা রেন্ডার হয় তার সাথে যা দাবি করা হয়েছে তার তুলনা করে। সাতটি ক্যানারি, যার প্রতিটির আলাদা ব্যর্থতা শনাক্ত করার ক্ষমতা রয়েছে: ১. doc-grounding — এমন দাবি শনাক্ত করে যা তথ্যের উৎসের (কোড, ডেটা, মূল টেক্সট, বাস্তবতা) সাথে মেলে না; এটি রিয়েল-টাইমে একাধিক উৎস থেকে যাচাই করা হয় এবং অফলাইনে থাকলে "unverified" হিসেবে দেখায়। ২. doc-standard — ওই ধরণের ডকুমেন্টের স্ট্যান্ডার্ড অনুযায়ী অসম্পূর্ণতা শনাক্ত করে, যার মধ্যে প্রয়োজনীয় সেকশন এবং নথিবদ্ধ না করা পাবলিক সারফেস অন্তর্ভুক্ত। ৩. doc-rot — পুরনো ভার্সন, তারিখ, ব্যাজ, মৃত TODO এবং বাতিল হয়ে যাওয়া নির্দেশনা শনাক্ত করে। ৪. doc-consistency — পরস্পরবিরোধী ডকুমেন্ট, পরিভাষার বিচ্যুতি এবং বিভিন্ন ভাষার মধ্যে অমিল শনাক্ত করে। ৫. doc-structure — ভাঙা লিঙ্ক, অ্যাঙ্কর, হেডিং, টেবিল, রেফারেন্স এবং ইমেজের অল্ট টেক্সট শনাক্ত করে। ৬. doc-quality — অতিরিক্ত শব্দ, অস্পষ্ট গদ্য এবং টাইপো, গ্রামার ও স্পেলিং-এর মতো ভাষাগত ত্রুটি শনাক্ত করে। ৭. doc-leak (কনফিগ-গেটেড) — পাবলিক ডকুমেন্টে গদ্য-স্তরের সংবেদনশীল বিষয়বস্তু ফ্ল্যাগ করে; টোকেন-আকৃতির সিক্রেটগুলো অন্যান্য টুলের জন্য ছেড়ে দেওয়া হয়েছে। এটি কেবল সন্দেহজনক বিষয়গুলো রিপোর্ট করে। স্ক্যান দুটি স্তরে চলে। 'Quick' স্তরটি মেকানিক্যাল লেয়ার কভার করে যা ডিটারমিনিস্টিক এবং কার্যত বিনামূল্যে, এবং এটি কেবল রিপোর্ট প্রদান করে। 'Full' স্তরে সেমান্টিক লেয়ার যুক্ত হয়, যা মডেলের বিচারবুদ্ধি ব্যবহার করে, যার জন্য অর্থ প্রদান করতে হয় এবং সর্বদা আলাদা সম্মতির প্রয়োজন হয়। ক্যানারিগুলোর মধ্যে চারটি মেকানিক্যাল এবং সেমান্টিক লেয়ারের সংমিশ্রণ; doc-consistency এবং doc-leak শুধুমাত্র সেমান্টিক। একটি বান্ডেলড জিরো-ডিপেন্ডেন্সি CommonMark+GFM AST ইঞ্জিন স্ট্রাকচারাল চেকগুলো পরিচালনা করে যাতে সঠিকভাবে রেন্ডার হওয়া কন্টেন্ট ফ্ল্যাগ না হয়; লেখক স্পষ্ট করেছেন যে এর নির্ভুলতার সীমা স্পেক-লেভেল, পিক্সেল-পারফেক্ট GitHub রেন্ডারিং নয়, এবং হোস্টের অদ্ভুত আচরণগুলোকে অনুমানের বদলে সীমাবদ্ধতা হিসেবে রিপোর্ট করা হয়। গুরুত্ব (Severity) সর্বদা মেক্যানিক্যালি নয় বরং প্রসঙ্গের ভিত্তিতে বিচার করা হয়: আর্কাইভের একটি ভাঙা লিঙ্ক হলে তা 'low', কিন্তু ইনস্টলেশন স্টেপের একই লিঙ্ক হলে তা 'critical'। নিশ্চিত করা প্রাপ্ত ফলাফলগুলো সন্দেহজনক ফলাফল থেকে আলাদাভাবে রিপোর্ট করা হয়। কোনো ফিক্স কখনোই স্বয়ংক্রিয়ভাবে প্রয়োগ করা হয় না; প্রতিটি রিপোর্টের শেষে একটি মেনু থাকে যেখানে নিরাপদ ফিক্স, ব্যবহারকারী-নির্বাচিত ফিক্স অথবা কেবল রিপোর্ট করার সুযোগ থাকে। মেক্যানিকাল লেয়ারগুলো ডিজাইনের কারণেই ভাষা-নিরপেক্ষ—এগুলো ইংরেজি কি-ওয়ার্ডের বদলে স্ট্রাকচার, পজিশন এবং অর্থের ওপর ভিত্তি করে কাজ করে—এবং সেমান্টিক লেয়ারগুলো ডকুমেন্টের নিজস্ব ভাষায় কাজ করে। একটি আলাদা, অপ্ট-ইন ফিচার হলো 'docs memory-drift reminder'। এটি কিছু স্ক্যান বা রিপোর্ট করে না। যদি ডকুমেন্টেশন ফাইলগুলো (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) এডিট করা হয় কিন্তু সেশনে MEMORY.md আপডেট না করা হয়, এবং প্রজেক্টটি MEMORY.md কনভেনশন ব্যবহার করে, তবে CoalLedger এজেন্ট রেসপন্স শেষ করার পর একটি শান্ত সিস্টেম মেসেজ দেয়; MEMORY.md আপডেট করার পর এটি নীরব থাকে। এটি নিষ্ক্রিয় করা সম্ভব। এটি CoalMine-এর কোড এডিট নজ-এর পরিপূরক; এই দুটি ভিন্ন ফাইল এক্সটেনশন পর্যবেক্ষণ করে। সামঞ্জস্যতা (Compatibility) প্ল্যাটফর্ম টেবিলের পরিবর্তে সক্ষমতার ওপর ভিত্তি করে নির্ধারিত: লাইফসাইকেল হুকস থাকা প্ল্যাটফর্মগুলো একটি সেশন-স্টার্ট কন্ডাক্টর পায় যা সঠিক সময়ে সঠিক ক্যানারি অফার করে; হুকস ছাড়া প্ল্যাটফর্মগুলো এজেন্ট-চালিত ইনভোকেশন পায়; সব ক্ষেত্রেই ক্যানারিগুলোকে নাম ধরে ম্যানুয়ালি কল করা যায়। লেখক সাপোর্ট টিয়ারগুলোকে সততার সাথে লেবেল করেছেন—Claude Code-কে লাইভ প্লাগইন এবং ডগফুডিং-এর মাধ্যমে ভ্যালিডেটেড বলা হয়েছে, আর অন্যান্য প্ল্যাটফর্ম (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai)-কে "works with" বলা হয়েছে: অর্থাৎ এগুলোর জন্য তৈরি করা হয়েছে, তবে এখনও এন্ড-টু-এন্ড প্রমাণিত হয়নি। Antigravity ওয়্যারিং-এর ক্ষেত্রে সতর্ক করা হয়েছে যে hooks.json-এর অবস্থান আপডেটের পর পরিবর্তিত হয়েছে এবং এটি Antigravity-র নিজস্ব ডক্স থেকে পুনরায় বের করে নিতে হবে; ভুল পাথে ওয়্যারিং থাকলে তা নিষ্ক্রিয় কিন্তু ক্ষতিকারক নয়। Claude Code-এর জন্য ইনস্টলেশন হলো দুটি কমান্ডের মার্কেটপ্লেস অ্যাড এবং প্লাগইন ইনস্টল, যা কন্ডাক্টর এবং মেমোরি-ড্রিফট রিমাইন্ডারকেও যুক্ত করে। অন্যান্য এজেন্টরা সেলফ-কন্টেইন্ড স্কিল ফোল্ডারগুলো কপি করে (AST ইঞ্জিনটি doc-structure ফোল্ডারের ভেতরে থাকে)। claude.ai ব্যবহারকারীদের স্কিলগুলো হাতে জিপ করতে নিষেধ করা হয়েছে কারণ ফ্রন্টম্যাটার ডেসক্রিপশন ওই প্ল্যাটফর্মের লিমিট অতিক্রম করে; পরিবর্তে ট্রিমড ডেসক্রিপশনসহ প্রতি-ক্যানারি ZIP ফাইল SHA256 চেকসামসহ Releases পেজে পাবলিশ করা হয়েছে। কমান্ডগুলোর মধ্যে প্রতিটি ক্যানারির জন্য একটি করে কমান্ডের পাশাপাশি /coalledger:stats (সেশন-লোকাল স্ক্যান এবং প্রাপ্ত ফলাফলের পরিসংখ্যান) এবং /coalledger:update (ভার্সন চেক এবং আপডেট হ্যান্ডলিং) রয়েছে। কনফিগারেশনে একটি গ্লোবাল ফাইল এবং প্রতি-প্রজেক্ট ফাইল সমর্থন করে যা বেশ কিছু পরিচিত এজেন্ট ডিরেক্টরি থেকে রেজলভ করা হয়, এবং একটি লিগাসি রুট পাথ এখনও পড়া হয়। কি-গুলোর মধ্যে রয়েছে অন/অফ মোড, রিপোর্টের ভাষা, ডিজেবল করা ক্যানারি, সেভেরিটি ফ্লোর, স্ক্যান-অল ওভাররাইড, কুইক-ভার্সেস-ফুল ডিফল্ট টিয়ার, doc-leak গেট, পাবলিক-ফেসিং ডক্স ফ্ল্যাগ, মেমোরি-ড্রিফট নজ, একটি ঐচ্ছিক em-dash টাইপোগ্রাফি রুল এবং আপডেট-চেক আচরণ। একটি প্রজেক্ট সম্পূর্ণভাবে বন্ধ করা যেতে পারে যাতে সেখানে স্কিলটি লোড না হয়। পারমিশনগুলো সংকীর্ণভাবে নির্ধারিত: এটি কেবল নামযুক্ত ডকুমেন্ট এবং তাদের লিঙ্ক করা ফাইলগুলো পড়ে, কেবল নিজস্ব স্ক্র্যাচ ফাইল এবং আপডেট স্ট্যাম্প লেখে, সর্বোচ্চ তিনটি লোকাল জিনিস চালায় (রিড-অনলি AST ইঞ্জিন, ফিক্সের আগে একটি git stash চেকপয়েন্ট, এবং সম্মতির ভিত্তিতে একটি ডকুমেন্ট দ্বারা দাবি করা উদাহরণ), এবং কখনোই নিজে থেকে কোনো ডকুমেন্ট এডিট করে না। নেটওয়ার্ক ব্যবহার অপ্ট-ইন: পেইড Full টিয়ারের সোর্স ভেরিফিকেশন এবং সেলফ-আপডেট চেকের জন্য আলাদা সম্মতির প্রয়োজন; হুকস এবং ইঞ্জিন কখনোই অনলাইনে যায় না। কোনো API কি বা npm install-এর প্রয়োজন নেই। বেঞ্চমার্কিং-এর ক্ষেত্রে প্রজেক্টটি সৎ: এটি কোনো বানানো সংখ্যা দিয়ে লঞ্চ করার বদলে আনবেঞ্চমার্কড হিসেবে লঞ্চ করা হয়েছে। মেক্যানিকাল লেয়ারটি ইন-রেপো ফিক্সচার-গেটেড (রোপণ করা ত্রুটি খুঁজে পাওয়া গেছে, ক্লিন ডিকয়গুলো নীরব ছিল) একটি ভেরিফিকেশন স্ক্রিপ্টের মাধ্যমে যাচাই করা হয়েছে, এবং একটি রেজাল্ট ডাইজেস্ট পরিকল্পনা করা হয়েছে যা প্রথম ডেটেড, ভার্সনড রান থেকে পূরণ করা হবে, যেখানে ক্যানারি অনুযায়ী সিডেড ডকুমেন্টেশন ত্রুটির রিকল পরিমাপ করা হবে। Apache 2.0 লাইসেন্সের অধীনে প্রকাশিত।