Module 01: Context-Bloat & Token-Pruner Protocol (RULE-BOOST-CONTEXT-OPTIMIZER)

Severity: BLOCKING | Scope: Root Constitutions (CLAUDE.md, GEMINI.md), Scoped Rules (.cursor/rules/*.mdc), Skills (SKILL.md), & Context Hygiene
Platforms: Google Antigravity (GEMINI.md), Cursor IDE (.cursor/rules/*.mdc), Claude Code (CLAUDE.md / SKILL.md), ChatGPT Projects

1. Core Constitutional Invariants (Nguyên Tắc Bất Biến)

🇬🇧 English Specification

1. Zero Monolithic Prompt Stuffing (200-Line Root Constitution Cap):
   • Whenever an agent initializes a workspace, audits token usage via /boost, or adds a new engineering rule, it is STRICTLY FORBIDDEN to dump encyclopedic documentation, raw API schemas, or edge-case tutorials into root instruction files (CLAUDE.md, GEMINI.md, .cursorrules).
   • Root instruction files load on every single turn and consume primary attention heads. Keep every root constitution file strictly at or below 200 lines (<= 1,800 tokens) so the model retains over 90% active reasoning capacity for live code and user intent.
   • When a root constitution file approaches 180 lines, extract domain-specific sections into dedicated .cursor/rules/*.mdc or .claude/skills/*/SKILL.md files before adding a single new line (One-In, Consolidation-Out). Before adding any new rule or script, evaluate Option 0 (Keep Current State) across 5 Lean-Harness questions to confirm that existing gates do not already catch the bug.
2. Step 1 - Progressive Disclosure & Lazy-Loaded Skill Sharding:
   • Partition workspace rules into a 3-tier attention hierarchy before writing new instructions:
     • Tier A - Root Constitution (CLAUDE.md / GEMINI.md <= 200 lines): Global architectural invariants, build/test commands, and high-level routing pointers only.
     • Tier B - Path-Scoped Cursor Rules (.cursor/rules/*.mdc): Domain rules restricted by explicit globs (for example src/components/**/*.tsx or scripts/**/*.mjs) with alwaysApply: false unless the rule governs universal safety.
     • Tier C - On-Demand Agent Skills (.claude/skills/*/SKILL.md & .agents/skills/*/SKILL.md): Deep workflows, reference tables, and verification scripts loaded lazily only when the active task matches the skill trigger description.
3. Step 2 - Subagent Search Offloading & Context Compaction:
   • Never run broad directory walks, unfiltered grep dumps, or multi-megabyte log reads inside the primary orchestrator thread.
   • Offload exploratory file searches, dependency audits, and log triage to isolated subagents or targeted ripgrep queries capped at 50 matches. Return only a concise structured summary (<= 300 tokens) to the main thread.
   • Trigger /compact or summarize completed sub-tasks whenever active context utilization crosses 60% of the model context window to prevent middle-curve attention dilution.
4. Step 3 - Heavy Directory Exclusion & Verifiable Budget Receipt:
   • Configure .cursorignore and .claudeignore to block high-volume, low-signal directories (node_modules/, dist/, build/, .next/, coverage/, package-lock.json, pnpm-lock.yaml, *.min.js).
   • Before concluding any /boost optimization pass, write a deterministic audit receipt to .boost-context-budget.json recording root file line counts, glob coverage across .mdc rules, excluded heavy directories, and estimated token savings.

🇻🇳 Đặc Tả Tiếng Việt

1. Cấm Nhồi Nhét File Cấu Hình Gốc (Trần 200 Dòng Cho File Gốc):
   • Khi AI khởi tạo dự án hoặc chạy lệnh /boost để dọn dẹp ngữ cảnh, CẤM TUYỆT ĐỐI nhồi tài liệu dài dòng vào file gốc. Bạn không được chép bảng dữ liệu thô hay hướng dẫn chi tiết vào CLAUDE.md, GEMINI.md hoặc .cursorrules.
   • File cấu hình gốc luôn tự động nạp vào bộ nhớ ở mọi lượt hội thoại. Bạn phải giữ file gốc gọn dưới 200 dòng (<= 1.800 token) để mô hình dành trọn trên 90% năng lượng chú ý cho mã nguồn thực tế.
   • Khi file cấu hình gốc chạm mốc 180 dòng, bạn bắt buộc phải tách các hướng dẫn chuyên ngành sang thư mục .cursor/rules/ hoặc .claude/skills/ trước khi viết thêm luật mới (One-In, Consolidation-Out). Trước khi thêm bất kỳ quy tắc hay công cụ nào, luôn đối chiếu Phương án 0 (Giữ nguyên hiện trạng) để tránh làm phình bộ khung kiểm soát.
2. Bước 1 - Phân Tầng Nạp Chậm Theo Ngữ Cảnh (3-Tier Lazy Loading):
   • Chia nhỏ hệ thống quy tắc thành 3 tầng rõ rệt thay vì gom chung một chỗ:
     • Tầng A - Hiến Pháp Gốc (CLAUDE.md / GEMINI.md <= 200 dòng): Chỉ chứa nguyên tắc sống còn, lệnh chạy kiểm thử và danh mục điều hướng ngắn gọn.
     • Tầng B - Luật Theo Đường Dẫn File (.cursor/rules/*.mdc): Gắn bộ lọc đường dẫn globs cụ thể (như src/ui/**/*.tsx) để chỉ nạp luật khi chạm đúng thư mục đó.
     • Tầng C - Kỹ Năng Chuyên Biệt Nạp Khi Cần (SKILL.md): Tách các quy trình dài, bảng tham chiếu và công cụ kiểm tra vào thư mục kỹ năng riêng để AI chỉ mở ra đọc khi đúng việc.
3. Bước 2 - Cách Ly Tác Vụ Tìm Kiếm Nặng Sang Luồng Phụ (Subagent Offloading):
   • Không chạy lệnh quét toàn bộ ổ đĩa hoặc đọc file nhật ký hàng chục nghìn dòng ngay trong luồng trò chuyện chính.
   • Hãy giao việc dò tìm file hoặc lọc lỗi nhật ký cho một luồng tác vụ phụ độc lập. Luồng phụ chỉ trả về bản tóm tắt kết quả ngắn gọn dưới 300 token cho luồng chính.
   • Chủ động nén lịch sử trò chuyện ngay khi dung lượng bộ nhớ chạm ngưỡng 60% giới hạn cửa sổ ngữ cảnh để tránh hiện tượng quên đầu quên đuôi.
4. Bước 3 - Chặn Thư Mục Rác & Xuất Biên Bản Kiểm Toán (Context Budget Receipt):
   • Thiết lập file .cursorignore và .claudeignore để chặn triệt để các thư mục ngốn bộ nhớ như node_modules/, dist/, .next/, coverage/ và package-lock.json.
   • Sau mỗi lần tối ưu bằng /boost, hệ thống phải ghi kết quả đo đạc thực tế vào file .boost-context-budget.json. Biên bản này lưu rõ số dòng của file gốc, tỷ lệ gắn nhãn globs và danh sách thư mục nặng đã chặn.

Decision Matrix: Context Tier Routing (Ma Trận Phân Tầng Ngữ Cảnh)

2. 10-Pair Anti-Pattern vs. World-Class Execution Table (10 Cặp Đối Sánh)

3. Ready-to-Run Node.js Linter (exit code 1)

Save this script as scripts/lint_boost_context_optimizer.mjs and run node scripts/lint_boost_context_optimizer.mjs in your pre-commit hook or CI pipeline. It enforces root constitution line ceilings, checks .cursorignore coverage, verifies .mdc frontmatter hygiene, and validates .boost-context-budget.json.

#!/usr/bin/env node
/**
 * MODULE 01 LINTER: Context-Bloat & Token-Pruner Auditor (RULE-BOOST-CONTEXT-OPTIMIZER)
 * Enforces <= 200 line root constitutions, .cursorignore hygiene, and .boost-context-budget.json receipts.
 * Exits with code 1 on any context-bloat violation.
 */
import fs from 'node:fs';
import path from 'node:path';

const ROOT = process.cwd();
const BUDGET_FILE = path.join(ROOT, '.boost-context-budget.json');
const ROOT_CONSTITUTION_MAX_LINES = 200;
const RULE_FILE_MAX_LINES = 320;
const REQUIRED_IGNORE_PATTERNS = ['node_modules', 'dist', 'package-lock.json'];

let violations = [];

// Gate 1: Verify .boost-context-budget.json exists and records audited metrics
if (!fs.existsSync(BUDGET_FILE)) {
  violations.push(
    '[BOOST-001] Missing .boost-context-budget.json in workspace root. ' +
    'Run the /boost context audit and record root constitution line counts and token budget metrics.'
  );
} else {
  try {
    const budget = JSON.parse(fs.readFileSync(BUDGET_FILE, 'utf8'));
    if (typeof budget.rootConstitutionLines !== 'number' || budget.rootConstitutionLines > ROOT_CONSTITUTION_MAX_LINES) {
      violations.push(
        `[BOOST-002] .boost-context-budget.json reports rootConstitutionLines=${budget.rootConstitutionLines} ` +
        `(exceeds hard cap of ${ROOT_CONSTITUTION_MAX_LINES} lines).`
      );
    }
    if (!Array.isArray(budget.ignoredHeavyPaths) || budget.ignoredHeavyPaths.length < 3) {
      violations.push(
        '[BOOST-003] .boost-context-budget.json must list at least 3 ignoredHeavyPaths (e.g., node_modules, dist, package-lock.json).'
      );
    }
    if (typeof budget.estimatedTokenSavingsPct !== 'number' || budget.estimatedTokenSavingsPct < 25) {
      violations.push(
        '[BOOST-004] .boost-context-budget.json must document estimatedTokenSavingsPct >= 25.'
      );
    }
  } catch (err) {
    violations.push(`[BOOST-005] Invalid JSON in .boost-context-budget.json: ${err.message}`);
  }
}

// Gate 2: Check root constitution files (CLAUDE.md, GEMINI.md, .cursorrules) for monolithic bloat
let maxObservedRootLines = 0;
for (const rootFile of ['CLAUDE.md', 'GEMINI.md', '.cursorrules']) {
  const fullPath = path.join(ROOT, rootFile);
  if (fs.existsSync(fullPath)) {
    const lines = fs.readFileSync(fullPath, 'utf8').split(/\r?\n/).length;
    if (lines > maxObservedRootLines) maxObservedRootLines = lines;
    if (lines > ROOT_CONSTITUTION_MAX_LINES) {
      violations.push(
        `[BOOST-006] Root constitution ${rootFile} has ${lines} lines (hard cap is ${ROOT_CONSTITUTION_MAX_LINES} lines). ` +
        `Shard detailed playbooks into .claude/skills/*/SKILL.md or .cursor/rules/*.mdc.`
      );
    }
  }
}

// Gate 3: Check .cursor/rules/*.mdc line caps and frontmatter validity
const cursorRulesDir = path.join(ROOT, '.cursor', 'rules');
if (fs.existsSync(cursorRulesDir)) {
  const mdcFiles = fs.readdirSync(cursorRulesDir).filter((f) => f.endsWith('.mdc'));
  for (const file of mdcFiles) {
    const fullPath = path.join(cursorRulesDir, file);
    const content = fs.readFileSync(fullPath, 'utf8');
    const lines = content.split(/\r?\n/).length;
    if (lines > RULE_FILE_MAX_LINES) {
      violations.push(`[BOOST-007] .cursor/rules/${file} has ${lines} lines (max ${RULE_FILE_MAX_LINES}).`);
    }
    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
      violations.push(`[BOOST-008] .cursor/rules/${file} is missing YAML frontmatter (description, globs, alwaysApply).`);
    }
  }
}

// Gate 4: Verify .cursorignore, .claudeignore, or .gitignore exists and blocks heavy token-burning paths
const ignoreCandidates = ['.cursorignore', '.claudeignore', '.gitignore']
  .map((f) => path.join(ROOT, f))
  .filter((p) => fs.existsSync(p));

if (ignoreCandidates.length === 0) {
  violations.push(
    '[BOOST-009] Missing workspace ignore file (.cursorignore, .claudeignore, or .gitignore). ' +
    'Create one excluding node_modules, dist, and package-lock.json.'
  );
} else {
  const combinedIgnore = ignoreCandidates.map((p) => fs.readFileSync(p, 'utf8')).join('\n');
  for (const pattern of REQUIRED_IGNORE_PATTERNS) {
    if (!combinedIgnore.includes(pattern)) {
      violations.push(`[BOOST-009] Workspace ignore files are missing heavy token-bloat path: "${pattern}".`);
    }
  }
}

if (violations.length > 0) {
  console.error('❌ [RULE-BOOST-CONTEXT-OPTIMIZER FAILED] Context-bloat violations detected:');
  for (const v of violations) console.error(`  - ${v}`);
  process.exit(1);
}

console.log('✅ [RULE-BOOST-CONTEXT-OPTIMIZER PASSED] Context budget & lazy-loading invariants verified.');
process.exit(0);

4. Schema Example: .boost-context-budget.json & .cursorignore

Create .boost-context-budget.json in your project root after running /boost to pass Gate 1 of the linter:

{
  "task": "Audit workspace context window hygiene and shard monolithic instructions",
  "auditedAt": "2026-10-22",
  "rootConstitutionLines": 96,
  "activeAlwaysApplyRules": 4,
  "lazyLoadedSkillsCount": 4,
  "ignoredHeavyPaths": [
    "node_modules",
    "dist",
    ".next",
    "coverage",
    "package-lock.json"
  ],
  "estimatedTokenSavingsPct": 68,
  "compactionThresholdPct": 60
}

Recommended .cursorignore / .claudeignore baseline template for every repository:

# Heavy dependencies and lockfiles
node_modules/
package-lock.json
pnpm-lock.yaml
yarn.lock

# Build artifacts and caches
dist/
build/
.next/
.astro/
coverage/
*.min.js
*.map

5. Multi-Platform Installation Guide (Hướng Dẫn Cài Đặt Đa Nền Tảng)

1. Google Antigravity (GEMINI.md & .agents/skills/)

• Copy the core rule block into ~/.gemini/GEMINI.md (Global) or <workspace>/.agents/skills/boost-context-bloat-optimizer/SKILL.md.
• Antigravity will automatically keep root instructions compact, enforce .cursorignore exclusions, and offload broad searches to subagents.
• Tiếng Việt: Chép khối quy tắc vào ~/.gemini/GEMINI.md hoặc thư mục .agents/skills/boost-context-bloat-optimizer/SKILL.md. Hệ thống sẽ tự động giữ file gốc tinh gọn và đẩy các lệnh dò tìm nặng sang luồng phụ.

2. Cursor IDE (.cursor/rules/01-boost-context-bloat-optimizer.mdc)

• Copy .cursor/rules/01-boost-context-bloat-optimizer.mdc into your project's .cursor/rules/ folder.
• Keep CLAUDE.md and .cursorrules under 200 lines and bind domain rules to specific globs.
• Tiếng Việt: Thả file .cursor/rules/01-boost-context-bloat-optimizer.mdc vào thư mục .cursor/rules/ của dự án. Giữ file gốc dưới 200 dòng và gắn đường dẫn globs cho từng nhóm luật.

3. Claude Code (CLAUDE.md & .claude/skills/)

• Place SKILL.md inside .claude/skills/boost-context-bloat-optimizer/SKILL.md and keep root CLAUDE.md concise.
• Run /compact whenever active context exceeds 60% capacity so reasoning stays sharp.
• Tiếng Việt: Đặt file SKILL.md vào .claude/skills/boost-context-bloat-optimizer/SKILL.md và chủ động chạy lệnh /compact khi bộ nhớ hội thoại vượt ngưỡng 60%.

4. ChatGPT (Custom Instructions / Projects)

• Upload 01-boost-context-bloat-optimizer.md into your ChatGPT Project Files so the assistant structures project instructions into modular files instead of one giant prompt.
• Tiếng Việt: Tải file 01-boost-context-bloat-optimizer.md lên mục tài liệu dự án trên ChatGPT để AI chia nhỏ hướng dẫn thành từng mô-đun rõ ràng.