@xelth/eck-snapshot 6.4.0 → 6.4.2

package/README.md

@@ -171,6 +171,13 @@ Both `scout` and `link` use the same depth scale to control content granularity:
 * **📚 NotebookLM Export:** Semantic chunking for Google's NotebookLM with "Brain + Body" architecture (see below).
 * **🧠 Multi-Agent Protocol:** Junior Architect delegation system for multi-agent coding workflows (see below).
 
+### 🤖 Autonomous AI Protocols
+`eckSnapshot` automatically injects strict behavioral protocols into the AI Architect's prompt (`multiAgent.md`) to ensure high code quality and prevent context degradation:
+1. **Context Hygiene Protocol:** The AI actively monitors the directory tree for bloat (logs, DB dumps, binaries). If detected, it autonomously constructs an `.eckignore` file to hide the garbage, saving tokens and context space.
+2. **Proactive Tech Debt:** The AI scans for `TODO`, `FIXME`, and `HACK` comments, evaluating them against the actual code. It will autonomously delete obsolete comments, fix quick bugs, or document major issues in `.eck/TECH_DEBT.md`.
+3. **The Boy Scout Rule:** Whenever the AI modifies or creates a function, it is forced to write or update its JSDoc/Docstring to explain *why* the code exists, keeping documentation perfectly synced.
+4. **Zero-Broken-Windows (Reliability):** Blind commits are strictly forbidden. The AI must run the project's test suite (e.g., `npm test`, `cargo test`) and ensure all tests pass before calling the task completion tool.
+
 ---
 
 ## 📚 NotebookLM Integration (New in v6.3 — Testing)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "6.4.0",
+  "version": "6.4.2",
   "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories. Optimized for AI context, LLM workflows, and multi-agent Swarm coordination.",
   "keywords": [
     "ai",

package/setup.json

@@ -368,7 +368,11 @@
       ".jpg",
       ".jpeg",
       ".gif",
-      ".svg"
+      ".svg",
+      ".wal",
+      ".pcapng",
+      ".jsonl",
+      ".csv"
     ],
     "dirsToIgnore": [
       "node_modules/",

package/src/templates/multiAgent.md

@@ -34,6 +34,46 @@ The `.eck/` directory files are your "Source of Knowledge".
 
 **Documentation is part of the "Definition of Done". A task is not finished if the relevant manifest files still contain [STUB] warnings.**
 
+### 🧹 CONTEXT HYGIENE PROTOCOL (CRITICAL)
+
+You are responsible for keeping your own context window clean and efficient.
+**Mandatory Full Snapshot Evaluation:** Whenever you receive a FULL snapshot, you MUST evaluate the `Directory Structure` and file list for irrelevant bloat (e.g., compiled binaries, DB dumps like .wal, huge logs, decompiled code).
+
+If bloat is detected:
+1. **Report to User:** Briefly tell the user how much garbage was found.
+   - *Massive Bloat:* Suggest pausing the main task. Generate an `eck_task` ONLY to create/update `.eckignore`, and ask the user to generate a fresh full snapshot before proceeding.
+   - *Minor Bloat:* Append the `.eckignore` creation/update to your current `eck_task` alongside the user's main request. Tell the user it's just a cleanup for the future and you can work with the current context.
+2. **Execution:** Instruct the Coder to use standard `.gitignore` syntax in `.eckignore` (e.g., `data/surreal_data/`, `*.wal`).
+
+**🚨 MANUAL OVERRIDE (THE CODE WORD):**
+If the human user includes the phrase **`[EXECUTE HYGIENE]`** or **`[ВРЕМЯ УБОРКИ]`**, immediately suspend all feature development and dedicate your response exclusively to cleaning the context via `.eckignore`.
+
+### 📝 PROACTIVE TECH DEBT & TODO PROTOCOL
+
+As a Senior Architect, you must actively manage code quality. When analyzing files in this snapshot, do not ignore developer comments:
+1. **Spot:** Actively look for `TODO`, `FIXME`, `HACK`, or `BUG` comments in the provided source code.
+2. **Evaluate:** Compare the comment against the actual implementation. Developers often fix things but forget to remove the comment.
+3. **Resolve (The 3 Actions):**
+   - **Obsolete:** If the code already does what the TODO asks, instruct the Coder to **delete the comment**.
+   - **Quick Fix:** If it's a small missing piece or an obvious bug, instruct the Coder to **implement the fix and remove the comment**.
+   - **Real Debt:** If it requires significant architectural work, instruct the Coder to **document it in `.eck/TECH_DEBT.md`** so it is officially tracked, and leave the comment in the code for now.
+
+### 🏕️ THE BOY SCOUT RULE (Docstrings & Comments)
+
+Leave the codebase better than you found it.
+Whenever you instruct the Coder to **modify an existing function/class** or **create a new one**, you MUST explicitly add this requirement to their task:
+> *"Ensure the JSDoc / Docstring for this function is created or updated to accurately reflect its new behavior, parameters, and return types. Explain WHY it exists, not just WHAT it does."*
+Do not rewrite documentation for the entire file—only strictly for the components you are touching.
+
+### 🛡️ RELIABILITY & ZERO-BROKEN-WINDOWS PROTOCOL
+
+You are the final gatekeeper of quality. A task is NEVER complete if the code doesn't compile or tests fail.
+Whenever you delegate a task to the Coder, you MUST enforce the following verification steps:
+1. **Identify the Test Suite:** Check the environment (e.g., `npm test`, `cargo test`, `pytest`).
+2. **Mandate Verification:** Explicitly instruct the Coder:
+   > *"Before calling `eck_finish_task`, you MUST run the project's test suite and ensure all tests pass. If there are no automated tests, you MUST manually verify the core functionality via CLI/Bash. Do NOT finish the task if there are compilation errors or test failures."*
+3. **No Blind Commits:** Never allow the Coder to commit code blindly. Verification is mandatory.
+
 ### CRITICAL WORKFLOW: Structured Commits via `journal_entry`
 
 To ensure proper project history, all code changes **MUST** be committed using the project's built-in structured workflow.

package/src/utils/fileUtils.js

@@ -205,7 +205,10 @@ export async function scanDirectoryRecursively(dirPath, config, relativeTo = dir
         if (entry.name === 'node_modules' ||
             entry.name === '.git' ||
             entry.name === '.idea' ||
-            entry.name === '.vscode') {
+            entry.name === '.vscode' ||
+            entry.name === '.gradle' ||
+            entry.name === 'build' ||
+            entry.name === '__pycache__') {
           continue;
         }
       } else {
@@ -270,14 +273,23 @@ export async function scanDirectoryRecursively(dirPath, config, relativeTo = dir
 }
 
 export async function loadGitignore(repoPath) {
+  const ig = ignore();
+
   try {
     const gitignoreContent = await fs.readFile(path.join(repoPath, '.gitignore'), 'utf-8');
-    const ig = ignore().add(gitignoreContent);
-    return ig;
+    ig.add(gitignoreContent);
   } catch {
     console.log('ℹ️ No .gitignore file found or could not be read');
-    return ignore();
   }
+
+  try {
+    const eckignoreContent = await fs.readFile(path.join(repoPath, '.eckignore'), 'utf-8');
+    ig.add(eckignoreContent);
+  } catch {
+    // .eckignore is optional, silently skip if missing
+  }
+
+  return ig;
 }
 
 export async function readFileWithSizeCheck(filePath, maxFileSize) {
@@ -308,6 +320,24 @@ export async function generateDirectoryTree(dir, prefix = '', allFiles, depth =
     const validEntries = [];
     
     for (const entry of sortedEntries) {
+      // --- GLOBAL HARD IGNORES ---
+      if (entry.isDirectory() && (
+        entry.name === 'node_modules' ||
+        entry.name === '.git' ||
+        entry.name === '.idea' ||
+        entry.name === '.vscode' ||
+        entry.name === '.gradle' ||
+        entry.name === 'build' ||
+        entry.name === '__pycache__'
+      )) continue;
+      if (!entry.isDirectory() && (
+        entry.name === 'package-lock.json' ||
+        entry.name === 'yarn.lock' ||
+        entry.name === 'pnpm-lock.yaml' ||
+        entry.name === 'go.sum'
+      )) continue;
+      // ---------------------------
+
       // Skip hidden directories and files (starting with '.')
       // EXCEPT: Allow .eck to be visible
       if (entry.name.startsWith('.') && entry.name !== '.eck') {