@xelth/eck-snapshot 5.9.0 → 6.0.0

package/README.md

@@ -1,190 +1,71 @@
-# eck-snapshot
+# 📸 eckSnapshot v6.0
 
-A CLI tool that packs your entire Git repository into a single text file optimized for LLMs. Give any AI full project context in one copy-paste.
+A specialized, AI-native CLI tool designed to create and restore single-file text snapshots of Git repositories. Optimized for providing full project context to Large Language Models (LLMs) and serving as the coordination hub for Multi-Agent AI Architectures.
 
-```bash
-npm install -g @xelth/eck-snapshot
-```
-
-## Recommended AI Setup
-
-For best results, we recommend splitting roles between models:
+## 🌟 Key Features
 
-- **Architect** (large context window): Gemini, Grok Fast, ChatGPT — upload the full snapshot, design the architecture, plan tasks
-- **Coder** (execution): Claude (via Claude Code), GLM (via OpenCode) — receive tasks from the architect, write and fix code
+* **🧠 Multi-Agent Protocol (Royal Court):** Built-in support for the "Royal Court" architecture. Delegate tasks from a Senior Architect (Claude/Gemini) to Junior Managers, who orchestrate a swarm of specialized GLM-4.7 workers.
+* **☠️ Skeleton Mode:** Uses `Tree-sitter` and `Babel` to strip function bodies, drastically reducing token count while preserving structural context. Supports JS/TS, Rust, Go, Python, C, Java, and Kotlin.
+* **🔄 Smart Delta Updates:** Tracks incremental changes via Git anchors with sequential numbering. Now accurately tracks and reports deleted files to prevent LLM hallucinations.
+* **🛡️ Security (SecretScanner):** Automatically redacts API keys and credentials before sending context to LLMs. Features both Regex matching and **Shannon Entropy** analysis for catching non-standard hardcoded secrets.
+* **📊 Telemetry Hub:** Integrated with a Rust-based microservice (`eck-telemetry`) for tracking agent execution metrics, auto-syncing token estimation weights via linear regression, and in-memory caching.
+* **🔌 Native MCP Integration:** Instantly spins up Model Context Protocol (MCP) servers (`eck-core` for context sync and `glm-zai` for worker swarms) for Claude Code and OpenCode.
 
-eck-snapshot generates tailored instructions (`CLAUDE.md`, `AGENTS.md`) for each role automatically.
-
-## Core Workflow
-
-### 1. Full Snapshot
-
-Run `eck-snapshot` in your project root. It scans every tracked file, filters out noise (lock files, build artifacts, secrets), and produces a single `.md` file ready for an AI chat.
+## 🚀 Quick Start
 
+### Installation
 ```bash
-eck-snapshot
-# -> .eck/snapshots/eckMyProject_26-02-15_12-00_abc1234.md
-```
-
-Upload the file to your architect AI and start working.
-
-### 2. Incremental Update
-
-After you make changes, don't re-send the entire project. Send only what changed since the last full snapshot:
-
-```bash
-eck-snapshot update
-# -> .eck/snapshots/eckMyProject_26-02-15_14-30_abc1234_up1_42kb.md
-```
-
-This uses a Git anchor (saved automatically during full snapshot) to detect all modified files and includes their full content. No redundant diffs, no wasted tokens.
-
-Notice the `_42kb` suffix in the filename — this is the **Anti-Truncation Guard** (see below).
-
-## Context Profiles
-
-Large repositories waste tokens on irrelevant code. Profiles let you partition the codebase so the AI only sees what matters.
-
-### Auto-Detection
-
-Let AI scan your directory tree and generate profiles automatically:
-
-```bash
-eck-snapshot profile-detect
-# -> Saves profiles to .eck/profiles.json
-```
-
-### Manual Guide
-
-For very large repos where auto-detection is too slow, generate a prompt guide, paste it into a powerful Web LLM (Gemini, ChatGPT), and save the resulting JSON:
-
-```bash
-eck-snapshot generate-profile-guide
-# -> .eck/profile_generation_guide.md (paste into AI, get profiles back)
-```
-
-### Using Profiles
-
-```bash
-eck-snapshot --profile                            # List all available profiles
-eck-snapshot --profile backend                    # Use a named profile
-eck-snapshot --profile backend --skeleton         # Profile + skeleton mode
-eck-snapshot --profile "src/**/*.rs,-**/test_*"   # Ad-hoc glob filtering
-```
-
-Profiles work with both full snapshots and incremental updates.
-
-## Anti-Truncation Guard
-
-Web AI interfaces (Gemini, ChatGPT) sometimes silently drop the content of large uploaded files, replacing them with a small JSON metadata stub like `{"fileName": "...", "contentFetchId": "..."}`. The AI then hallucinates code it never actually received.
-
-eck-snapshot counters this with two mechanisms:
-
-**1. Size-stamped filenames.** Every snapshot — full and incremental — embeds its exact size in kilobytes directly in the filename:
-
-```
-eckMyProject_26-02-15_12-00_abc1234_1250kb.md      ← full snapshot
-eckMyProject_26-02-15_14-30_abc1234_up1_42kb.md    ← incremental update
+npm install -g @xelth/eck-snapshot
 ```
 
-**2. AI instructions baked into the snapshot.** The snapshot header instructs the AI to cross-check the `kb` value in the filename against the actual payload it received. If there is a mismatch, the AI is required to stop and alert you instead of hallucinating:
-
-> 🚨 **System Error:** The web interface truncated the file `eckMyProject_..._1250kb.md`. I only received the metadata/JSON stub, not the actual 1250 kb of code. Please split the snapshot or paste the text directly.
-
-This protection works on any web interface that embeds the filename (Gemini, ChatGPT, Grok, etc.).
-
-## Smart Filtering
-
-eck-snapshot automatically detects your project type (Rust, Node.js, Android, Python, etc.) and excludes language-specific noise:
-
-- **Rust**: `Cargo.lock`, `target/`
-- **Node.js**: `package-lock.json`, `node_modules/`
-- **Android**: build artifacts, generated code
-- **All projects**: `.git/`, IDE configs, binary files
-
-The built-in `SecretScanner` also redacts API keys, tokens, and credentials before they reach the AI.
-
-## Multi-Agent Architecture
-
-eck-snapshot generates tailored `CLAUDE.md` instructions for different AI agent roles:
-
+### Basic Usage
 ```bash
-eck-snapshot --jas    # Junior Architect Sonnet - fast, standard features
-eck-snapshot --jao    # Junior Architect Opus - deep, critical architecture
-eck-snapshot --jag    # Junior Architect Gemini - massive context tasks
-```
-
-### Chinese Delegation (`--zh`)
+# Create a standard full snapshot
+eck-snapshot snapshot
 
-For GLM Z.AI workers (trained on Chinese data), the `--zh` flag instructs the architect to formulate all worker tasks in Chinese, improving output quality:
+# Create a highly compressed skeleton snapshot
+eck-snapshot snapshot --skeleton
 
-```bash
-eck-snapshot --jas --zh    # Claude Code: delegate to GLM workers in Chinese
-eck-snapshot --zh          # OpenCode/GLM: generate AGENTS.md with Chinese protocol
+# Create an incremental update (only changed/deleted files)
+eck-snapshot update
 ```
 
-The architect still communicates with you in your language. Only the `instruction` parameter sent to GLM workers switches to Chinese. Code, variable names, and commit messages stay in English.
+## 🤖 AI Swarm Setup (GLM Z.AI)
 
-### MCP Server Integration
+eckSnapshot v6 acts as the bridge between your primary AI IDE (Claude Code or OpenCode) and a cost-effective GLM-4.7 worker swarm.
 
-Delegate coding tasks to the GLM Z.AI Worker Fleet via MCP:
+1. **Get an API Key:** Register at [Z.AI](https://z.ai) and set `export ZAI_API_KEY="your-key"`.
+2. **Setup MCP Servers:**
+   ```bash
+   eck-snapshot setup-mcp --both
+   ```
+3. **Initialize Project Manifests:**
+   ```bash
+   # Generates smart instructions (CLAUDE.md / AGENTS.md)
+   eck-snapshot snapshot --jas  # For Claude Code (Sonnet 4.5)
+   eck-snapshot snapshot --jaz  # For OpenCode (GLM-4.7)
+   ```
 
-```bash
-export ZAI_API_KEY="your-key"
-eck-snapshot setup-mcp --both    # Setup for Claude Code + OpenCode
-```
+## 📁 The `.eck/` Manifest Directory
 
-This gives your AI access to specialized workers: `glm_zai_frontend`, `glm_zai_backend`, `glm_zai_qa`, `glm_zai_refactor`, and the `eck_finish_task` commit tool.
+eckSnapshot automatically maintains a `.eck/` directory in your project to provide deep context to AI agents:
+- `CONTEXT.md` - High-level architecture (Auto-generated)
+- `ENVIRONMENT.md` - Runtime specifics (Auto-generated)
+- `ROADMAP.md` & `TECH_DEBT.md` - Strategic planning
+- `RUNTIME_STATE.md` - Live port/process status
 
-## Skeleton Mode & Lazy Loading
+*Note: The tool automatically filters confidential files like `SERVER_ACCESS.md` from snapshots to ensure security.*
 
-For extremely large projects, skeleton mode strips function bodies and keeps only signatures, types, and structure:
+## 📈 Token Estimation
 
+Train the local estimator to perfectly predict token counts for your specific project:
 ```bash
-eck-snapshot --skeleton
-```
-
-When using skeleton mode, the AI can request full content of specific files on demand:
-
-```bash
-eck-snapshot show src/auth.rs src/handlers/sync.rs
-```
-
-Useful for initial orientation in massive codebases, but full snapshots with profiles are usually more practical.
-
-## Other Commands
+# Manually push agent telemetry
+eck-snapshot telemetry push
 
-```bash
-eck-snapshot restore <snapshot>    # Restore files from a snapshot to disk
-eck-snapshot prune <snapshot>      # AI-powered snapshot size reduction
-eck-snapshot doctor                # Check project health
-eck-snapshot env push              # Encrypt and sync .eck/ config between machines
-eck-snapshot env pull              # Restore .eck/ config on another machine
+# Sync global token weights from the Telemetry Hub
+eck-snapshot telemetry sync-weights
 ```
 
-## Changelog
-
-### v5.8.6
-- **Anti-Truncation Guard:** Every snapshot filename now includes its size in KB (e.g., `_1250kb.md`). The snapshot header instructs the AI to verify the payload size matches the filename and alert the user if the web UI truncated the file instead of hallucinating missing code.
-- **Incremental snapshot filtering parity:** `eck-snapshot update` now applies the same file guards as full snapshots — hidden paths (`.idea/`, `.vscode/`), binary files, and glob patterns in `filesToIgnore` are all properly filtered out, preventing IDE config files or committed binaries from bloating update snapshots.
-
-### v5.8.5
-- Re-publish to fix missing README on npmjs.com.
-
-### v5.8.4
-- Fixed directory filtering in incremental snapshots. Paths like `web/build/app.js` are now correctly ignored when `build/` is in the ignore list.
-
-### v5.8.3
-- Optimized agent report formatting with clean Markdown to improve token efficiency.
-- Fixed report injection order so it appears correctly after system instructions.
-
-### v5.8.2
-- Fixed agent report injection in incremental snapshots. The `AnswerToSA.md` file is now preserved on disk for manual debugging and uses an internal `[SYSTEM: EMBEDDED]` marker to prevent duplicate injections into future snapshots.
-
-### v5.8.1
-- Improved Android project parsing by ignoring boilerplate and vector graphics.
-- Removed duplicate `ecksnapshot` MCP server and fixed JSON parsing in `update-auto`.
-
 ## License
-
-MIT
+MIT © xelth-com

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "5.9.0",
-  "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories and directories. Optimized for AI context and LLM workflows.",
+  "version": "6.0.0",
+  "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.",
   "main": "index.js",
   "type": "module",
   "bin": {

package/scripts/mcp-eck-core.js

@@ -24,8 +24,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
       {
-        name: "eck_finish_task",
-        description: "Completes the current coding task. 1) Overwrites AnswerToSA.md with status for the Architect. 2) Stages all changes. 3) Commits with the provided message. 4) Automatically updates the context snapshot. Use this instead of manual git commands.",
+        name: "eck_fail_task",
+        description: "Use this if you are stuck, blocked, or unable to complete the task. It saves your report to AnswerToSA.md and generates an emergency snapshot WITHOUT committing broken code. Do NOT use this if tests pass.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            status: {
+              type: "string",
+              description: "Detailed explanation of why you are blocked, what you tried, and what the Architect should know."
+            }
+          },
+          required: ["status"]
+        }
+      },
+      {
+        name: "eck_finish_task",
+        description: "Completes the current coding task. 1) Overwrites AnswerToSA.md with status for the Architect. 2) Stages all changes. 3) Commits with the provided message. 4) Automatically updates the context snapshot. WARNING: USE ONLY ONCE PER TASK WHEN 100% FINISHED. Do NOT use this for intermediate saves or testing during your debugging loop.",
         inputSchema: {
           type: "object",
           properties: {
@@ -46,6 +60,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "eck_fail_task") {
+    const { status } = request.params.arguments;
+    const workDir = process.cwd();
+
+    try {
+      const answerDir = path.join(workDir, '.eck', 'lastsnapshot');
+      await fs.mkdir(answerDir, { recursive: true });
+      await fs.writeFile(
+        path.join(answerDir, 'AnswerToSA.md'),
+        `# Agent Report (BLOCKED/FAILED)\n\n${status}\n`,
+        'utf-8'
+      );
+
+      const cliPath = path.join(PROJECT_ROOT, "index.js");
+      const { stdout } = await execa("node", [cliPath, "update-auto", "--fail"], { cwd: workDir, timeout: 120000 });
+
+      let result;
+      try {
+        result = JSON.parse(stdout);
+      } catch (e) {
+        return { content: [{ type: "text", text: `⚠️ Task aborted, but snapshot update returned invalid JSON: ${stdout}` }] };
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `🚨 Task marked as FAILED.\n📝 AnswerToSA.md updated\n📸 Emergency Snapshot: ${result.snapshot_file} (${result.files_count} files)`
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: `❌ Error: ${error.message}\n${error.stderr || ''}` }], isError: true };
+    }
+  }
+
   if (request.params.name === "eck_finish_task") {
     const { status, message } = request.params.arguments;
     const workDir = process.cwd();
@@ -106,14 +154,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-// --- Graceful Shutdown Handler ---
-process.stdout.on('error', (err) => {
-  if (err.code === 'EPIPE') {
-    process.exit(0);
-  }
-});
-process.on('SIGINT', () => process.exit(0));
-process.on('SIGTERM', () => process.exit(0));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// --- Graceful Shutdown Handler ---
+process.stdout.on('error', (err) => {
+  if (err.code === 'EPIPE') {
+    process.exit(0);
+  }
+});
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));

package/src/cli/cli.js

@@ -205,6 +205,7 @@ Quick --profile Examples:
     .description('Create a delta snapshot of changed files since the last full snapshot')
     .argument('[repoPath]', 'Path to the repository', process.cwd())
     .option('--config <path>', 'Configuration file path')
+    .option('-f, --fail', 'Create an emergency snapshot without git commit')
     .action(updateSnapshot);
 
   // Auto/Silent Update command for Agents
@@ -212,6 +213,7 @@ Quick --profile Examples:
     .command('update-auto')
     .description('Silent update for AI agents (JSON output)')
     .argument('[repoPath]', 'Path to the repository', process.cwd())
+    .option('-f, --fail', 'Create an emergency snapshot without git commit')
     .action(updateSnapshotJson);
 
   // Restore command

package/src/cli/commands/updateSnapshot.js

@@ -1,15 +1,16 @@
-import fs from 'fs/promises';
-import path from 'path';
-import ora from 'ora';
-import chalk from 'chalk';
-import isBinaryPath from 'is-binary-path';
-import { getGitAnchor, getChangedFiles } from '../../utils/gitUtils.js';
-import { loadSetupConfig } from '../../config.js';
-import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore, generateTimestamp, getShortRepoName } from '../../utils/fileUtils.js';
-import { detectProjectType, getProjectSpecificFiltering } from '../../utils/projectDetector.js';
-import { execa } from 'execa';
-import { fileURLToPath } from 'url';
-import { pushTelemetry } from '../../utils/telemetry.js';
+import fs from 'fs/promises';
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import isBinaryPath from 'is-binary-path';
+import { getGitAnchor, getChangedFiles } from '../../utils/gitUtils.js';
+import { loadSetupConfig } from '../../config.js';
+import { readFileWithSizeCheck, parseSize, formatSize, matchesPattern, loadGitignore, generateTimestamp, getShortRepoName } from '../../utils/fileUtils.js';
+import { detectProjectType, getProjectSpecificFiltering } from '../../utils/projectDetector.js';
+import { execa } from 'execa';
+import { fileURLToPath } from 'url';
+import { pushTelemetry } from '../../utils/telemetry.js';
+import { syncTokenWeights } from '../../utils/tokenEstimator.js';
 
 // Mirror the same hidden-path guard used in createSnapshot.js
 function isHiddenPath(filePath) {
@@ -42,52 +43,95 @@ async function generateSnapshotContent(repoPath, changedFiles, anchor, config, g
   let includedCount = 0;
   const fileList = [];
 
-  // Include Agent Report if it exists and hasn't been embedded yet
-  let agentReport = null;
-  const reportPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.md');
-  try {
-    const reportContent = await fs.readFile(reportPath, 'utf-8');
-    if (!reportContent.includes('[SYSTEM: EMBEDDED]')) {
-      agentReport = reportContent;
-      await fs.appendFile(reportPath, '\n\n[SYSTEM: EMBEDDED]\n', 'utf-8');
-    }
-  } catch (e) { /* File not found or unreadable */ }
+  // Include Agent Report if it exists and hasn't been embedded yet
+  let agentReport = null;
+  const reportPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.md');
+  const lockPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.lock');
+  try {
+    // Use atomic directory creation as a lock to prevent race conditions
+    await fs.mkdir(lockPath);
+    const reportContent = await fs.readFile(reportPath, 'utf-8');
+    
+    if (!reportContent.includes('[SYSTEM: EMBEDDED]')) {
+      agentReport = reportContent;
+
+      // Immediately mark as embedded to release the race window
+      await fs.appendFile(reportPath, '\n\n[SYSTEM: EMBEDDED]\n', 'utf-8');
+
+      // Auto-Journaling: prepend agent report to JOURNAL.md
+      const journalPath = path.join(repoPath, '.eck', 'JOURNAL.md');
+      try {
+        const dateStr = new Date().toISOString().split('T')[0];
+        const journalEntry = `## ${dateStr} — Agent Report\n\n${reportContent.trim()}\n`;
+
+        let existingJournal = '';
+        try {
+          existingJournal = await fs.readFile(journalPath, 'utf-8');
+        } catch (e) { /* might not exist */ }
+
+        const insertPos = existingJournal.indexOf('\n## ');
+        if (insertPos !== -1) {
+          const newJournal = existingJournal.slice(0, insertPos) + '\n\n' + journalEntry + existingJournal.slice(insertPos);
+          await fs.writeFile(journalPath, newJournal, 'utf-8');
+        } else {
+          await fs.writeFile(journalPath, (existingJournal ? existingJournal + '\n\n' : '') + journalEntry + '\n', 'utf-8');
+        }
+      } catch (je) {
+        console.warn('Could not auto-update JOURNAL.md', je.message);
+      }
+    }
+    await fs.rmdir(lockPath);
+  } catch (e) { 
+    // File not found or locked by another process
+    try { await fs.rmdir(lockPath); } catch (_) {} 
+  }
 
   const cleanDirsToIgnore = (config.dirsToIgnore || []).map(d => d.replace(/\/$/, ''));
 
-  for (const filePath of changedFiles) {
-    const normalizedPath = filePath.replace(/\\/g, '/');
-
-    // Skip hidden paths (.idea/, .vscode/, etc.) — mirrors createSnapshot.js
-    if (isHiddenPath(normalizedPath)) continue;
-
-    // Skip binary files — mirrors createSnapshot.js
-    if (isBinaryPath(filePath)) continue;
-
-    const pathParts = normalizedPath.split('/');
-    let isIgnoredDir = false;
-    for (let i = 0; i < pathParts.length - 1; i++) {
-      if (cleanDirsToIgnore.includes(pathParts[i])) {
-        isIgnoredDir = true;
-        break;
-      }
-    }
-    if (isIgnoredDir) continue;
-
-    const fileExt = path.extname(filePath);
-    // Use matchesPattern (glob support) instead of exact includes() — mirrors createSnapshot.js
-    if (config.filesToIgnore && matchesPattern(normalizedPath, config.filesToIgnore)) continue;
-    if (fileExt && config.extensionsToIgnore?.includes(fileExt)) continue;
-    if (gitignore.ignores(normalizedPath)) continue;
-
-    try {
-      const fullPath = path.join(repoPath, filePath);
-      const content = await readFileWithSizeCheck(fullPath, parseSize(config.maxFileSize));
-      contentOutput += `--- File: /${normalizedPath} ---\n\n${content}\n\n`;
-      fileList.push(`- ${normalizedPath}`);
-      includedCount++;
-    } catch (e) { /* Skip */ }
-  }
+  for (const filePath of changedFiles) {
+    const normalizedPath = filePath.replace(/\\/g, '/');
+
+    // Skip hidden paths (.idea/, .vscode/, etc.) — mirrors createSnapshot.js
+    if (isHiddenPath(normalizedPath)) continue;
+
+    // Skip binary files — mirrors createSnapshot.js
+    if (isBinaryPath(filePath)) continue;
+
+    const pathParts = normalizedPath.split('/');
+    let isIgnoredDir = false;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      if (cleanDirsToIgnore.includes(pathParts[i])) {
+        isIgnoredDir = true;
+        break;
+      }
+    }
+    if (isIgnoredDir) continue;
+
+    const fileExt = path.extname(filePath);
+    // Use matchesPattern (glob support) instead of exact includes() — mirrors createSnapshot.js
+    if (config.filesToIgnore && matchesPattern(normalizedPath, config.filesToIgnore)) continue;
+    if (fileExt && config.extensionsToIgnore?.includes(fileExt)) continue;
+    if (gitignore.ignores(normalizedPath)) continue;
+
+    try {
+      const fullPath = path.join(repoPath, filePath);
+
+      // Explicitly check if file was deleted
+      try {
+        await fs.access(fullPath);
+      } catch (accessErr) {
+        contentOutput += `--- File: /${normalizedPath} ---\n\n[FILE DELETED]\n\n`;
+        fileList.push(`- ${normalizedPath} (Deleted)`);
+        includedCount++;
+        continue;
+      }
+
+      const content = await readFileWithSizeCheck(fullPath, parseSize(config.maxFileSize));
+      contentOutput += `--- File: /${normalizedPath} ---\n\n${content}\n\n`;
+      fileList.push(`- ${normalizedPath} (Modified/Added)`);
+      includedCount++;
+    } catch (e) { /* Skip */ }
+  }
 
   // Load Template
   const templatePath = path.join(__dirname, '../../templates/update-prompt.template.md');
@@ -122,17 +166,22 @@ export async function updateSnapshot(repoPath, options) {
     }
 
     // Auto-commit any uncommitted changes so they appear in the diff
-    const didCommit = await autoCommit(repoPath);
-    if (didCommit) {
-      spinner.info('Auto-committed uncommitted changes.');
-      spinner.start('Generating update snapshot...');
+    let didCommit = false;
+    if (!options.fail) {
+      didCommit = await autoCommit(repoPath);
+      if (didCommit) {
+        spinner.info('Auto-committed uncommitted changes.');
+      }
+    } else {
+      spinner.info('Fail flag passed: skipping auto-commit.');
     }
+    spinner.start('Generating update snapshot...');
 
-    const changedFiles = await getChangedFiles(repoPath, anchor);
-    if (changedFiles.length === 0) {
-      spinner.succeed('No changes detected since last full snapshot.');
-      return;
-    }
+    const changedFiles = await getChangedFiles(repoPath, anchor, options.fail);
+    if (changedFiles.length === 0) {
+      spinner.succeed('No changes detected since last full snapshot.');
+      return;
+    }
 
     const setupConfig = await loadSetupConfig();
     let config = { ...setupConfig.fileFiltering, ...setupConfig.performance, ...options };
@@ -216,7 +265,7 @@ export async function updateSnapshot(repoPath, options) {
 }
 
 // New Silent/JSON command for Agents
-export async function updateSnapshotJson(repoPath) {
+export async function updateSnapshotJson(repoPath, options = {}) {
   try {
     const anchor = await getGitAnchor(repoPath);
     if (!anchor) {
@@ -225,9 +274,11 @@ export async function updateSnapshotJson(repoPath) {
     }
 
     // Auto-commit any uncommitted changes
-    await autoCommit(repoPath);
+    if (!options.fail) {
+      await autoCommit(repoPath);
+    }
 
-    const changedFiles = await getChangedFiles(repoPath, anchor);
+    const changedFiles = await getChangedFiles(repoPath, anchor, !!options.fail);
     if (changedFiles.length === 0) {
       console.log(JSON.stringify({ status: "no_changes", message: "No changes detected" }));
       return;
@@ -294,15 +345,16 @@ export async function updateSnapshotJson(repoPath) {
     }
     // --------------------------------------------
 
-    console.log(JSON.stringify({
-      status: "success",
-      snapshot_file: `.eck/snapshots/${outputFilename}`,
-      files_count: includedCount,
-      timestamp: timestamp
-    }));
-
-    // Auto-push telemetry (fire and forget so it doesn't break JSON output)
-    pushTelemetry(repoPath, true).catch(() => {});
+    console.log(JSON.stringify({
+      status: "success",
+      snapshot_file: `.eck/snapshots/${outputFilename}`,
+      files_count: includedCount,
+      timestamp: timestamp
+    }));
+
+    // Auto-push telemetry and sync weights (fire and forget so it doesn't break JSON output)
+    pushTelemetry(repoPath, true).catch(() => {});
+    syncTokenWeights(true).catch(() => {});
 
   } catch (error) {
     console.log(JSON.stringify({ status: "error", message: error.message }));

package/src/templates/opencode/coder.template.md

@@ -4,18 +4,25 @@
 You are an Expert Developer. The architecture is already decided. Your job is to **execute**, **fix**, and **polish**.
 
 ## DEFINITION OF DONE (CRITICAL)
-When the task is complete:
-1. **WRITE** your report to \`.eck/lastsnapshot/AnswerToSA.md\` (overwrite, not append). Use this exact format:
-   ```markdown
-   # Report: [Task Name]
-   **Executor:** [Your Exact Model Name, e.g., GLM-4.7 (OpenCode)]
-   **Status:** [SUCCESS / BLOCKED / FAILED]
-   **Changes:**
-   - Modified X
-   ```
-2. **Use the \`eck_finish_task\` tool** to commit and sync context.
-   - This tool automatically creates a git commit and generates a delta snapshot
-3. **DO NOT** use raw git commands for the final commit.
+When task is complete, you must report back and sync context.
+
+**OPTION A: Using MCP Tool (Recommended)**
+Call the \`eck_finish_task\` tool. Pass your detailed markdown report into the \`status\` argument.
+- The tool will automatically write the report to \`AnswerToSA.md\`, commit, and generate a snapshot.
+- **DO NOT** manually write to \`AnswerToSA.md\` with your file editing tools (it will fail safety checks).
+- **WARNING: USE ONLY ONCE.** Do not use \`eck_finish_task\` for intermediate testing. It spams snapshot history.
+
+**OPTION B: Manual CLI (Fallback)**
+If the MCP tool is unavailable:
+1. **READ** \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED by safety rules before overwriting).
+2. **WRITE** your report to that file.
+3. Run \`eck-snapshot update\` in terminal.
+
+## PROJECT CONTEXT (.eck DIRECTORY)
+The `.eck/` directory contains critical project documentation. **Before starting your task, you MUST:**
+1. List the files in the `.eck/` directory.
+2. Read any files that might be relevant to your task based on their names (e.g., `CONTEXT.md`, `TECH_DEBT.md`, `OPERATIONS.md`).
+3. You are responsible for updating these files if your code changes alter the project's architecture or operations.
 
 ## CONTEXT
 - The GLM ZAI swarm might have struggled or produced code that needs refinement.
@@ -23,7 +30,9 @@ When the task is complete:
 - You have full permission to edit files directly.
 
 ## WORKFLOW
-1.  Read the code.
-2.  Fix the bugs / Implement the feature.
-3.  Verify functionality (Run tests!).
-4.  **Loop:** If verification fails, fix it immediately. Do not ask for permission.
+1.  Check the `.eck/RUNTIME_STATE.md` and verify actual running processes.
+2.  Read the code. If the Architect's hypothesis is wrong, discard it and find the real bug.
+3.  Fix the bugs / Implement the feature.
+4.  Verify functionality manually via browser/curl/logs/DB checks.
+5.  **Loop:** If verification fails, fix it immediately. Do not ask for permission.
+6.  **Blocked?** Use the `eck_fail_task` tool to abort safely without committing broken code.