@xelth/eck-snapshot 6.4.1 → 6.4.3

package/README.md

@@ -36,6 +36,8 @@ Pass the Architect's technical plan to your local **Coder agent** (Claude Code /
 ### 3. Auto-Updates
 When the Coder agent finishes a task, it automatically calls the built-in MCP tool (`eck_finish_task`), which commits the code and generates an incremental delta update snapshot. Feed that update back to the Architect to keep it in sync.
 
+> **Custom base:** Use `eck-snapshot update --base <snapshot.md>` to generate a delta relative to any past snapshot file. Pass the filename (e.g. `eckRepo26-04-01_f2e1bd4_up1_29kb.md`) — the anchor hash is extracted automatically. This doesn't disturb the automatic sequence counter — custom-base snapshots get a `_upcustom` suffix. A raw git hash (7+ hex chars) also works.
+
 ---
 
 ## 🧠 Which Models to Use
@@ -83,7 +85,7 @@ For humans typing in the terminal, short commands work too:
 | # | Command | Description |
 |---|---------|-------------|
 | 1 | `eck-snapshot snapshot` | Full project snapshot |
-| 2 | `eck-snapshot update` | Delta update (changed files only) |
+| 2 | `eck-snapshot update` | Delta update (changed files only). Supports `--base <snapshot.md>` to compare against an old snapshot file. |
 | 3 | `eck-snapshot profile [name]` | Snapshot filtered by profile (no arg = list profiles) |
 | 4 | `eck-snapshot scout [0-9]` | Scout external repo (see depth scale below) |
 | 5 | `eck-snapshot fetch "src/**/*.rs"` | Fetch specific files by glob |
@@ -171,6 +173,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.1",
+  "version": "6.4.3",
   "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/src/cli/cli.js

@@ -43,9 +43,17 @@ import { runTokenTools } from './commands/trainTokens.js';
 // Legacy command shims: translate old positional commands to JSON payloads
 // so internal callers (mcp-eck-core.js) keep working after the JSON migration.
 const LEGACY_COMMANDS = {
-  'update-auto': (args) => ({ name: 'eck_update_auto', arguments: { fail: args.includes('--fail') || args.includes('-f') } }),
+  'update-auto': (args) => {
+    const baseIdx = args.indexOf('--base');
+    const base = baseIdx !== -1 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
+    return { name: 'eck_update_auto', arguments: { fail: args.includes('--fail') || args.includes('-f'), base } };
+  },
   'snapshot':    () => ({ name: 'eck_snapshot', arguments: {} }),
-  'update':      (args) => ({ name: 'eck_update', arguments: { fail: args.includes('--fail') || args.includes('-f') } }),
+  'update':      (args) => {
+    const baseIdx = args.indexOf('--base');
+    const base = baseIdx !== -1 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
+    return { name: 'eck_update', arguments: { fail: args.includes('--fail') || args.includes('-f'), base } };
+  },
   'setup-mcp':   (args) => ({ name: 'eck_setup_mcp', arguments: { opencode: args.includes('--opencode'), both: args.includes('--both') } }),
   'detect':      () => ({ name: 'eck_detect', arguments: {} }),
   'doctor':      () => ({ name: 'eck_doctor', arguments: {} }),
@@ -90,6 +98,7 @@ Ranked by frequency of use:
 
   1. eck-snapshot snapshot          Full project snapshot
   2. eck-snapshot update            Delta update (changed files only)
+                                     --base <snapshot.md> : Compare against an old snapshot file
   3. eck-snapshot profile [name]    Snapshot filtered by profile (from .eck/profiles.json)
                                      No arg = list available profiles
                                      Example: eck-snapshot profile backend

package/src/cli/commands/updateSnapshot.js

@@ -37,6 +37,15 @@ async function autoCommit(repoPath) {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+function resolveBaseHash(base) {
+  if (!base) return null;
+  const basename = path.basename(base, '.md');
+  const match = basename.match(/_([0-9a-f]{7,40})_/);
+  if (match) return match[1];
+  if (/^[0-9a-f]{7,40}$/i.test(base)) return base;
+  throw new Error(`Invalid --base value: "${base}". Expected a snapshot filename or a git commit hash.`);
+}
+
 // Shared logic to generate the snapshot content string
 async function generateSnapshotContent(repoPath, changedFiles, anchor, config, gitignore) {
   let contentOutput = '';
@@ -160,7 +169,9 @@ async function generateSnapshotContent(repoPath, changedFiles, anchor, config, g
 export async function updateSnapshot(repoPath, options) {
   const spinner = ora('Generating update snapshot...').start();
   try {
-    const anchor = await getGitAnchor(repoPath);
+    const isCustomBase = !!options.base;
+    const anchor = resolveBaseHash(options.base) || await getGitAnchor(repoPath);
+
     if (!anchor) {
       throw new Error('No snapshot anchor found. Run a full snapshot first: eck-snapshot snapshot');
     }
@@ -175,6 +186,11 @@ export async function updateSnapshot(repoPath, options) {
     } else {
       spinner.info('Fail flag passed: skipping auto-commit.');
     }
+
+    if (isCustomBase) {
+      spinner.info(`Using custom base: ${anchor.substring(0, 7)} (from ${path.basename(options.base)})`);
+    }
+
     spinner.start('Generating update snapshot...');
 
     const changedFiles = await getChangedFiles(repoPath, anchor, options.fail);
@@ -203,24 +219,28 @@ export async function updateSnapshot(repoPath, options) {
     const { fullContent, includedCount, agentReport } = await generateSnapshotContent(repoPath, changedFiles, anchor, config, gitignore);
 
     // Determine sequence number
-    let seqNum = 1;
-    const counterPath = path.join(repoPath, '.eck', 'update_seq');
-    try {
-      const seqData = await fs.readFile(counterPath, 'utf-8');
-      const [savedHash, savedCount] = seqData.split(':');
-      if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
-        seqNum = parseInt(savedCount || '0') + 1;
-      }
-    } catch (e) {}
+    let seqStr = 'custom';
+    if (!isCustomBase) {
+      let seqNum = 1;
+      const counterPath = path.join(repoPath, '.eck', 'update_seq');
+      try {
+        const seqData = await fs.readFile(counterPath, 'utf-8');
+        const [savedHash, savedCount] = seqData.split(':');
+        if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
+          seqNum = parseInt(savedCount || '0') + 1;
+        }
+      } catch (e) {}
 
-    try {
-      await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
-    } catch (e) {}
+      try {
+        await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
+      } catch (e) {}
+      seqStr = seqNum.toString();
+    }
 
     const timestamp = generateTimestamp();
     const shortRepoName = getShortRepoName(path.basename(repoPath));
     const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
-    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqNum}_${sizeKB}kb.md`;
+    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqStr}_${sizeKB}kb.md`;
     const outputPath = path.join(repoPath, '.eck', 'snapshots', outputFilename);
 
     await fs.mkdir(path.dirname(outputPath), { recursive: true });
@@ -267,7 +287,9 @@ export async function updateSnapshot(repoPath, options) {
 // New Silent/JSON command for Agents
 export async function updateSnapshotJson(repoPath, options = {}) {
   try {
-    const anchor = await getGitAnchor(repoPath);
+    const isCustomBase = !!options.base;
+    const anchor = resolveBaseHash(options.base) || await getGitAnchor(repoPath);
+    
     if (!anchor) {
       console.log(JSON.stringify({ status: "error", message: "No snapshot anchor found" }));
       return;
@@ -303,24 +325,28 @@ export async function updateSnapshotJson(repoPath, options = {}) {
 
     const { fullContent, includedCount, agentReport } = await generateSnapshotContent(repoPath, changedFiles, anchor, config, gitignore);
 
-    let seqNum = 1;
-    const counterPath = path.join(repoPath, '.eck', 'update_seq');
-    try {
-      const seqData = await fs.readFile(counterPath, 'utf-8');
-      const [savedHash, savedCount] = seqData.split(':');
-      if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
-        seqNum = parseInt(savedCount || '0') + 1;
-      }
-    } catch (e) {}
+    let seqStr = 'custom';
+    if (!isCustomBase) {
+      let seqNum = 1;
+      const counterPath = path.join(repoPath, '.eck', 'update_seq');
+      try {
+        const seqData = await fs.readFile(counterPath, 'utf-8');
+        const [savedHash, savedCount] = seqData.split(':');
+        if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
+          seqNum = parseInt(savedCount || '0') + 1;
+        }
+      } catch (e) {}
 
-    try {
-      await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
-    } catch (e) {}
+      try {
+        await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
+      } catch (e) {}
+      seqStr = seqNum.toString();
+    }
 
     const timestamp = generateTimestamp();
     const shortRepoName = getShortRepoName(path.basename(repoPath));
     const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
-    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqNum}_${sizeKB}kb.md`;
+    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqStr}_${sizeKB}kb.md`;
     const outputPath = path.join(repoPath, '.eck', 'snapshots', outputFilename);
     await fs.mkdir(path.dirname(outputPath), { recursive: true });
     await fs.writeFile(outputPath, fullContent);

package/src/templates/multiAgent.md

@@ -37,10 +37,16 @@ The `.eck/` directory files are your "Source of Knowledge".
 ### 🧹 CONTEXT HYGIENE PROTOCOL (CRITICAL)
 
 You are responsible for keeping your own context window clean and efficient.
-If you notice in the "Directory Structure" or file list that the snapshot has captured irrelevant data (e.g., compiled binaries, database dumps like .wal, huge generated logs, raw data arrays, or decompiled third-party code):
-1. **Take Immediate Action:** You MUST instruct the Coder to create or update a `.eckignore` file in the project root.
-2. **Syntax:** Use standard `.gitignore` syntax (e.g., `data/surreal_data/`, `*.wal`, `decompiled_dll/`).
-3. **Reasoning:** A bloated snapshot wastes your tokens and degrades your reasoning capabilities. Be aggressive in hiding non-source-code artifacts.
+**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
 
@@ -59,6 +65,15 @@ Whenever you instruct the Coder to **modify an existing function/class** or **cr
 > *"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

@@ -320,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') {