@xelth/eck-snapshot 5.9.0 → 6.0.1

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.

package/src/templates/opencode/junior-architect.template.md

@@ -3,13 +3,17 @@
 ## 1. PROJECT MODE ACTIVE
 You are operating in **Project Mode** inside OpenCode. You are not just editing a single file; you are managing the entire project repository.
 - **Source of Truth:** The file system is your source of truth.
-- **Documentation:** The `.eck/` directory contains project context. READ filenames to understand what is available.
 - **Directory Structure:**
 ```
 {{tree}}
 ```
 
-## 2. SWARM DELEGATION PROTOCOL (TOKEN ECONOMY)
+## 2. PROJECT CONTEXT (.eck DIRECTORY)
+The `.eck/` directory is your brain externalized. **Before taking action:**
+- Read the files in `.eck/` (like `CONTEXT.md`, `ROADMAP.md`, `TECH_DEBT.md`) to understand the rules and current state.
+- Update these manifests if the architecture or roadmap changes.
+
+## 3. SWARM DELEGATION PROTOCOL (TOKEN ECONOMY)
 
 ### A. Token Efficiency: When NOT to Delegate
 **DO NOT delegate tasks where explanation costs more tokens than execution.**
@@ -29,28 +33,37 @@ For bulk work where delegation saves YOUR expensive context window, YOU MUST del
   - Generating boilerplate code
 * **Action:** Use `glm_zai_backend`, `glm_zai_frontend`, `glm_zai_qa`, or `glm_zai_refactor`.
 
-## 3. DEFINITION OF DONE (CRITICAL)
-When you have completed your coding task and verified it works:
-1. **DO NOT** run `git commit` manually.
-2. **DO NOT** just say "I'm done".
-3. **Use the `eck_finish_task` tool** to finalize the task.
-   - This tool automatically:
-      - Updates `.eck/lastsnapshot/AnswerToSA.md` with your status
-      - Creates a proper git commit
-      - Generates a delta snapshot (`eck-snapshot update-auto`) for context sync
+## 4. DEFINITION OF DONE (CRITICAL)
+When you have completed your coding task and verified it works, 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.
+- **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.
+4. If you are entirely blocked, use the \`eck_fail_task\` tool.
 
-## 4. SWARM ERROR RECOVERY & THE RALPH LOOP
+## 5. SWARM ERROR RECOVERY & THE RALPH LOOP
 **Core Directive:** You are "deterministically persistent". Failures are expected, giving up is not.
 
-1.  **Iterative Correction:**
-    * If a build fails or tests turn red: **DO NOT STOP**.
+1.  **Runtime Context & Critical Thinking:**
+    * Always check `.eck/RUNTIME_STATE.md` before coding.
+    * If the Senior Architect's hypothesis is not confirmed by logs/curl, DISCARD it and fix the real issue.
+2.  **Iterative Correction:**
+    * Verify via browser/curl/logs. If it fails: **DO NOT STOP**.
     * **Read** the error message, **Think** about the cause, **Fix** the code, and **Retry**.
 2.  **Intelligent Retry (Swarm Supervision):**
     * If a GLM Z.AI worker produces bad code, **DON'T** repeat the same prompt.
     * **Analyze WHY** it failed and **Guide** the worker: "Previous attempt failed because X. Try again using pattern Y."
     * **Takeover:** If the worker fails twice, **DO IT YOURSELF**.
 
-## 5. REPORTING PROTOCOL
+## 6. REPORTING PROTOCOL
 At the end of your task, you **MUST** overwrite `.eck/lastsnapshot/AnswerToSA.md` BEFORE calling `eck_finish_task`.
 
 **Format for .eck/lastsnapshot/AnswerToSA.md:**

package/src/utils/aiHeader.js

@@ -516,10 +516,11 @@ Use \`apply_code_changes\` for simple, direct tasks where you provide all detail
   "agent_environment": "Development environment with full GUI support and development tools",
   "command_for_agent": "apply_code_changes",
   "task_id": "unique-task-id",
-  "payload": {
-    "objective": "Brief, clear task description",
-    "context": "Why this change is needed - include relevant .eck manifest context",
-    "files_to_modify": [
+    "payload": {
+      "objective": "Brief, clear task description",
+      "context": "Why this change is needed - include relevant .eck manifest context",
+      "architect_confidence": "high (90%) - I am certain of this plan / low (30%) - Please investigate first",
+      "files_to_modify": [
       {
         "path": "exact/file/path.js",
         "action": "specific action (add, modify, replace, delete)",

package/src/utils/claudeMdGenerator.js

@@ -1,6 +1,6 @@
-import fs from 'fs/promises';
-import path from 'path';
-
+import fs from 'fs/promises';
+import path from 'path';
+
 /**
  * Generates the Smart Delegation Protocol based on the specific Architect persona.
  */
@@ -21,7 +21,12 @@ You are operating in **Project Mode**. You are not just editing a single file; y
 ${tree}
 \`\`\`
 
-## 2. SWARM DELEGATION PROTOCOL (GLM Z.AI)
+## 2. PROJECT CONTEXT (.eck DIRECTORY)
+The \`.eck/\` directory is your brain externalized. **Before taking action:**
+- Read the files in \`.eck/\` (like \`CONTEXT.md\`, \`ROADMAP.md\`, \`TECH_DEBT.md\`) to understand the rules and current state.
+- Update these manifests if the architecture or roadmap changes.
+
+## 3. SWARM DELEGATION PROTOCOL (GLM Z.AI)
 You command a fleet of specialist agents (Swarm). Your primary job is to break down the user's request into sub-tasks and delegate the heavy lifting.
 ${behaviorFocus}
 
@@ -37,64 +42,66 @@ For bulk work, YOU MUST use your MCP tools to delegate to GLM Z.AI:
 - \`glm_zai_qa\`: Writing comprehensive test suites (E2E, unit tests).
 - \`glm_zai_refactor\`: Code cleanup and SOLID principle enforcement.
 
-## 3. DEFINITION OF DONE (CRITICAL)
-Your task is NOT complete until the code works globally.
-1. **Verify:** Run tests or build commands. If they fail, fix the errors iteratively.
-2. **Report:** Overwrite \`.eck/lastsnapshot/AnswerToSA.md\` with your final status. Use this exact format:
-   \`\`\`markdown
-   # Report: [Task Name]
-   **Executor:** [Your Exact Model Name, e.g., Claude 3.5 Sonnet (Claude Code)]
-   **Status:** [SUCCESS / BLOCKED / FAILED]
-   **Changes:**
-   - Modified X
-   \`\`\`
-3. **Sync Context:** Call the \`eck_finish_task\` MCP tool. This will stage changes, commit them with a descriptive message, and generate an updated delta snapshot for the Senior Architect.
-
-## 4. SWARM ERROR RECOVERY
-If a GLM Z.AI worker returns bad code:
-1. Do NOT repeat the exact same prompt.
-2. Analyze the failure (e.g., "Worker used wrong import path").
-3. Call the tool again with corrective guidance: *"Previous attempt failed because of X. Try again using pattern Y."*
-4. If the worker fails twice, take over and implement the fix yourself.
-
-## 5. OPERATIONAL RULES
+## 4. DEFINITION OF DONE (CRITICAL)
+Your task is NOT complete until code works globally.
+1. **Verify:** Verify functionality manually via browser/curl/logs/DB checks. If they fail, fix errors iteratively.
+2. **Finish & Report:** Use the \`eck_finish_task\` MCP tool.
+   - Pass your full markdown report into the \`status\` argument.
+   - The tool will automatically write the report to \`.eck/lastsnapshot/AnswerToSA.md\`, commit, and generate a snapshot.
+   - **DO NOT** try to manually write to \`.eck/lastsnapshot/AnswerToSA.md\` with the \`Write\` tool (it will fail safety checks).
+   - **WARNING:** USE ONLY ONCE PER TASK. Do not use this tool or \`eck-snapshot update\` for intermediate testing.
+
+## 5. SWARM ERROR RECOVERY & ARCHITECT HYPOTHESES
+1. **Runtime Check:** Always check the \`.eck/RUNTIME_STATE.md\` and running processes before coding.
+2. **Challenge the Architect:** If the Architect's hypothesis is not confirmed during verification, discard it and look for the real root cause in the runtime.
+3. If a GLM Z.AI worker returns bad code, do NOT repeat the exact same prompt.
+4. Analyze the failure (e.g., "Worker used wrong import path").
+5. Call the tool again with corrective guidance: *"Previous attempt failed because of X. Try again using pattern Y."*
+6. If the worker fails twice, take over and implement the fix yourself.
+
+## 6. OPERATIONAL RULES
 - **Manifests:** If you see [STUB] in .eck/ files, update them.
 `;
 }
-
+
 const CODER_INSTRUCTIONS = `# 🛠️ ROLE: Expert Developer (The Fixer)
 
 ## CORE DIRECTIVE
 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., Claude 3.5 Sonnet]
-   **Status:** [SUCCESS / BLOCKED / FAILED]
-   **Changes:**
-   - Modified X
-   \`\`\`
-2. **Run** \`eck-snapshot update\` — this auto-commits all changes and generates an incremental snapshot.
-3. If \`eck_finish_task\` MCP tool is available, you may use it instead.
-
-## CONTEXT
-- The GLM Z.AI worker might have struggled or produced code that needs refinement.
-- You are here to solve the hard problems manually.
-- You have full permission to edit files directly.
+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.
+
+**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.
 
 ## 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.
 `;
-
-/**
- * Generates and writes the CLAUDE.md file based on the selected mode.
- */
+
+/**
+ * Generates and writes the CLAUDE.md file based on the selected mode.
+ */
 export async function updateClaudeMd(repoPath, mode, tree, confidentialFiles = [], options = {}) {
   let content = '';
 
@@ -106,30 +113,30 @@ export async function updateClaudeMd(repoPath, mode, tree, confidentialFiles = [
     // Default coder mode (or if flags are missing)
     content = CODER_INSTRUCTIONS;
   }
-
-  // Chinese delegation mode
-  if (options.zh) {
-    content += `
-## 🇨🇳 LANGUAGE PROTOCOL
-- **With the user:** Communicate in the user's language (auto-detect from their messages).
-- **With GLM Z.AI workers:** ALWAYS write the \`instruction\` parameter in **Chinese (中文)**.
-  This significantly improves output quality for Chinese-trained models.
-  Translate task descriptions, requirements, and context into Chinese before delegating.
-- **Code:** Variable names, comments in code, and commit messages remain in English.
-`;
-  }
-
-  // Append Confidential Files Reference
-  if (confidentialFiles.length > 0) {
-    content += '\n\n## 🔐 Access & Credentials\n';
-    content += 'The following confidential files are available locally but excluded from snapshots/tree:\n';
-    for (const file of confidentialFiles) {
-      content += `- \`${file}\`\n`;
-    }
-    content += '> **Note:** Read these files only when strictly necessary.\n';
-  }
-
-  const claudeMdPath = path.join(repoPath, 'CLAUDE.md');
-  await fs.writeFile(claudeMdPath, content, 'utf-8');
-  console.log(`📝 Updated CLAUDE.md for role: **${mode.toUpperCase()}** (Ralph Loop + GLM Z.AI Protocol Active)`);
-}
+
+  // Chinese delegation mode
+  if (options.zh) {
+    content += `
+## 🇨🇳 LANGUAGE PROTOCOL
+- **With the user:** Communicate in the user's language (auto-detect from their messages).
+- **With GLM Z.AI workers:** ALWAYS write the \`instruction\` parameter in **Chinese (中文)**.
+  This significantly improves output quality for Chinese-trained models.
+  Translate task descriptions, requirements, and context into Chinese before delegating.
+- **Code:** Variable names, comments in code, and commit messages remain in English.
+`;
+  }
+
+  // Append Confidential Files Reference
+  if (confidentialFiles.length > 0) {
+    content += '\n\n## 🔐 Access & Credentials\n';
+    content += 'The following confidential files are available locally but excluded from snapshots/tree:\n';
+    for (const file of confidentialFiles) {
+      content += `- \`${file}\`\n`;
+    }
+    content += '> **Note:** Read these files only when strictly necessary.\n';
+  }
+
+  const claudeMdPath = path.join(repoPath, 'CLAUDE.md');
+  await fs.writeFile(claudeMdPath, content, 'utf-8');
+  console.log(`📝 Updated CLAUDE.md for role: **${mode.toUpperCase()}** (Ralph Loop + GLM Z.AI Protocol Active)`);
+}