@xelth/eck-snapshot 5.9.0 → 6.0.0

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)`);
+}

package/src/utils/fileUtils.js

@@ -11,56 +11,86 @@ import { minimatch } from 'minimatch';
 /**
  * Scanner for detecting and redacting secrets (API keys, tokens)
  */
-export const SecretScanner = {
-  patterns: [
-    // Service-specific patterns
-    { name: 'GitHub Token', regex: /gh[pous]_[a-zA-Z0-9]{36}/g },
-    { name: 'AWS Access Key', regex: /(?:AKIA|ASIA)[0-9A-Z]{16}/g },
-    { name: 'OpenAI API Key', regex: /sk-[a-zA-Z0-9]{32,}/g },
-    { name: 'Stripe Secret Key', regex: /sk_live_[0-9a-zA-Z]{24}/g },
-    { name: 'Google API Key', regex: /AIza[0-9A-Za-z\-_]{35}/g },
-    { name: 'Slack Token', regex: /xox[baprs]-[0-9a-zA-Z\-]{10,}/g },
-    { name: 'NPM Token', regex: /npm_[a-zA-Z0-9]{36}/g },
-    { name: 'Private Key', regex: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g },
-    // Generic high-entropy patterns near sensitive keywords
-    {
-      name: 'Generic Secret',
-      regex: /(?:api[_-]?key|secret|password|token|auth|pwd|credential)\s*[:=]\s*["']([a-zA-Z0-9\-_.]{16,})["']/gi
-    }
-  ],
-
-  /**
-   * Scans content and replaces detected secrets with a placeholder
-   * @param {string} content - File content to scan
-   * @param {string} filePath - Path for logging context
-   * @returns {{content: string, found: string[]}} Redacted content and list of found secret types
-   */
-  redact(content, filePath) {
-    let redactedContent = content;
-    const foundSecrets = [];
-
-    for (const pattern of this.patterns) {
-      // Reset regex lastIndex for global patterns
-      pattern.regex.lastIndex = 0;
-
-      const matches = [...content.matchAll(pattern.regex)];
-      if (matches.length > 0) {
-        for (const match of matches) {
-          // For generic pattern, use captured group; for specific patterns, use full match
-          const secretValue = match[1] || match[0];
-          const placeholder = `[REDACTED_${pattern.name.replace(/\s+/g, '_').toUpperCase()}]`;
-          redactedContent = redactedContent.replace(secretValue, placeholder);
-          foundSecrets.push(pattern.name);
-        }
-      }
-    }
-
-    return {
-      content: redactedContent,
-      found: [...new Set(foundSecrets)]
-    };
-  }
-};
+export const SecretScanner = {
+  patterns: [
+    // Service-specific patterns
+    { name: 'GitHub Token', regex: /gh[pous]_[a-zA-Z0-9]{36}/g },
+    { name: 'AWS Access Key', regex: /(?:AKIA|ASIA)[0-9A-Z]{16}/g },
+    { name: 'OpenAI API Key', regex: /sk-[a-zA-Z0-9]{32,}/g },
+    { name: 'Stripe Secret Key', regex: /sk_live_[0-9a-zA-Z]{24}/g },
+    { name: 'Google API Key', regex: /AIza[0-9A-Za-z\-_]{35}/g },
+    { name: 'Slack Token', regex: /xox[baprs]-[0-9a-zA-Z\-]{10,}/g },
+    { name: 'NPM Token', regex: /npm_[a-zA-Z0-9]{36}/g },
+    { name: 'Private Key', regex: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g },
+    // Generic high-entropy patterns near sensitive keywords
+    {
+      name: 'Generic Secret',
+      regex: /(?:api[_-]?key|secret|password|token|auth|pwd|credential)\s*[:=]\s*["']([a-zA-Z0-9\-_.]{16,})["']/gi
+    }
+  ],
+
+  /**
+   * Calculates Shannon Entropy of a string
+   */
+  calculateEntropy(str) {
+    const len = str.length;
+    const frequencies = Array.from(str).reduce((freq, c) => {
+      freq[c] = (freq[c] || 0) + 1;
+      return freq;
+    }, {});
+    return Object.values(frequencies).reduce((sum, f) => {
+      const p = f / len;
+      return sum - (p * Math.log2(p));
+    }, 0);
+  },
+
+  /**
+   * Scans content and replaces detected secrets with a placeholder
+   * @param {string} content - File content to scan
+   * @param {string} filePath - Path for logging context
+   * @returns {{content: string, found: string[]}} Redacted content and list of found secret types
+   */
+  redact(content, filePath) {
+    let redactedContent = content;
+    const foundSecrets = [];
+
+    for (const pattern of this.patterns) {
+      // Reset regex lastIndex for global patterns
+      pattern.regex.lastIndex = 0;
+
+      const matches = [...content.matchAll(pattern.regex)];
+      if (matches.length > 0) {
+        for (const match of matches) {
+          // For generic pattern, use captured group; for specific patterns, use full match
+          const secretValue = match[1] || match[0];
+          const placeholder = `[REDACTED_${pattern.name.replace(/\s+/g, '_').toUpperCase()}]`;
+          redactedContent = redactedContent.replace(secretValue, placeholder);
+          foundSecrets.push(pattern.name);
+        }
+      }
+    }
+
+    // Second pass: Shannon Entropy check for arbitrary hardcoded secrets
+    // Look for long strings assigned to variable names that might be keys
+    const entropyRegex = /(?:const|let|var|set|export|define)\s+([A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Za-z0-9_]*)\s*=\s*["']([a-zA-Z0-9+/=_-]{20,128})["']/gi;
+    const entropyMatches = [...redactedContent.matchAll(entropyRegex)];
+    
+    for (const match of entropyMatches) {
+      const secretValue = match[2];
+      // Check entropy - random base64 usually has entropy > 4.5
+      if (this.calculateEntropy(secretValue) > 4.5 && !secretValue.includes('REDACTED')) {
+        const placeholder = `[REDACTED_HIGH_ENTROPY_SECRET]`;
+        redactedContent = redactedContent.replace(secretValue, placeholder);
+        foundSecrets.push('High Entropy Secret');
+      }
+    }
+
+    return {
+      content: redactedContent,
+      found: [...new Set(foundSecrets)]
+    };
+  }
+};
 
 export function parseSize(sizeStr) {
   const units = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
@@ -838,15 +868,16 @@ export async function applyProfileFilter(allFiles, profileString, repoPath) {
 export async function initializeEckManifest(projectPath) {
   const eckDir = path.join(projectPath, '.eck');
 
-  // Load setup configuration to check AI generation settings
-  let aiGenerationEnabled = false;
-  try {
-    const setupConfig = await loadSetupConfig();
-    aiGenerationEnabled = setupConfig?.aiInstructions?.manifestInitialization?.aiGenerationEnabled ?? false;
-  } catch (error) {
-    // If setup config fails to load, default to disabled
-    console.warn(`   ⚠️ Could not load setup config: ${error.message}. AI generation disabled.`);
-  }
+  // Load setup configuration to check AI generation settings and project context
+  let aiGenerationEnabled = false;
+  let setupConfig = null;
+  try {
+    setupConfig = await loadSetupConfig();
+    aiGenerationEnabled = setupConfig?.aiInstructions?.manifestInitialization?.aiGenerationEnabled ?? false;
+  } catch (error) {
+    // If setup config fails to load, default to disabled
+    console.warn(`   ⚠️ Could not load setup config: ${error.message}. AI generation disabled.`);
+  }
 
   try {
     // Check if .eck directory already exists and has all required files
@@ -894,33 +925,38 @@ export async function initializeEckManifest(projectPath) {
       delete staticFacts.allDetections;
     }
     
-    const staticFactsJson = JSON.stringify(staticFacts, null, 2);
-    // --- END NEW LOGIC ---
-    
-    // 3. Define smarter templates and prompts with "STUB NOTICES"
+    const staticFactsJson = JSON.stringify(staticFacts, null, 2);
+    // --- END NEW LOGIC ---
+
+    // Extract Context from setup.json if available
+    const projName = setupConfig?.projectContext?.name || staticFacts.type || 'project';
+    const projType = setupConfig?.projectContext?.type || staticFacts.type || 'unknown';
+    const projStack = setupConfig?.projectContext?.architecture?.stack?.join(', ') || 'TBD';
+    const projAi = setupConfig?.projectContext?.architecture?.aiIntegration || 'None';
+    
+    // 3. Define smarter templates and prompts using setup.json context
     const templateConfigs = {
-      'ENVIRONMENT.md': {
-        prompt: `Generate raw YAML for .eck/ENVIRONMENT.md based on these project facts:\n${staticFactsJson}\nInclude project_type, runtime, and agent_id: local_dev. NO markdown fences.`,
-        fallback: `project_type: ${staticFacts.type || 'unknown'}
-# [STUB: ENVIRONMENT.MD]
-# ARCHITECT: Task Coder to verify environment variables.
-# CODER: Scan project for .env files or config files and fill this. Remove this stub notice.
-agent_id: local_dev
-`
+      'ENVIRONMENT.md': {
+        prompt: `Generate raw YAML for .eck/ENVIRONMENT.md based on these project facts:\n${staticFactsJson}\nInclude project_type, runtime, and agent_id: local_dev. NO markdown fences.`,
+        fallback: `project_type: ${projType}
+agent_id: local_dev
+# Generated from setup.json
+`
       },
-      'CONTEXT.md': {
-        prompt: `Analyze these project files and dependencies:\n${staticFactsJson}\nGenerate a professional # Project Overview in Markdown. Describe the actual architecture and purpose of this specific project. Be technical and concise. Start with '# Project Overview'.`,
-        fallback: `# [STUB: CONTEXT.MD]
-
-## 🚨 ATTENTION ARCHITECT & CODER
-**ARCHITECT:** This file is EMPTY. You MUST prioritize a task for the Coder to analyze the source code and define the Project Overview, Architecture, and Key Technologies.
-**CODER:** Use your tools to read the code, write the real content, and DELETE this entire stub header.
-
-## Description
-(Placeholder: A ${staticFacts.type || 'project'} project)
-
-## Architecture
-(Placeholder: TBD)`
+      'CONTEXT.md': {
+        prompt: `Analyze these project files and dependencies:\n${staticFactsJson}\nGenerate a professional # Project Overview in Markdown. Describe the actual architecture and purpose of this specific project. Be technical and concise. Start with '# Project Overview'.`,
+        fallback: `# Project Overview
+
+## Description
+Project name: ${projName}
+Type: ${projType}
+AI Integration: ${projAi}
+
+## Architecture
+Stack: ${projStack}
+
+*(Auto-generated from setup.json)*
+`
       },
       'OPERATIONS.md': {
         prompt: `Look at the dependencies and files:\n${staticFactsJson}\nGenerate a Markdown guide for common operations (Setup, Run, Test, Build) using the correct commands for this tech stack. Start with '# Common Operations'.`,
@@ -938,11 +974,40 @@ ${staticFacts.type === 'nodejs' ? 'npm install' : 'TBD'}`
 
 **ARCHITECT:** Set a real roadmap based on user goals. **CODER:** Remove this stub marker once a real goal is added.`
       },
-      'TECH_DEBT.md': {
-        prompt: `Given this is a ${staticFacts.type} project, list 2-3 common technical debt items. Start with '# Technical Debt'.`,
-        fallback: `# [STUB: TECH_DEBT.MD]
-
-**CODER:** Scan for TODOs/FIXMEs or structural issues and list them here. Remove this stub marker.`
+      'TECH_DEBT.md': {
+        prompt: `Given this is a ${staticFacts.type} project, list 2-3 common technical debt items. Start with '# Technical Debt'.`,
+        fallback: `# [STUB: TECH_DEBT.MD]
+
+**CODER:** Scan for TODOs/FIXMEs or structural issues and list them here. Remove this stub marker.`
+      },
+      'DEPLOY_CHECKLIST.md': {
+        prompt: `Based on the project type (${staticFacts.type}), generate a pre-deployment checklist. Start with '# Deployment Checklist'.`,
+        fallback: `# [STUB: DEPLOY_CHECKLIST.MD]
+
+## 🚨 ATTENTION CODER
+Verify required build steps before deployment.
+
+## Pre-Deployment Checklist
+- [ ] Verify all tests pass
+- [ ] Build assets (e.g., npm run build)
+- [ ] Check environment variables
+
+**CODER:** Update this checklist with actual build/deploy steps for this project.`
+      },
+      'RUNTIME_STATE.md': {
+        prompt: `Based on the project type (${staticFacts.type}), generate a template for RUNTIME_STATE.md. Start with '# Runtime State'.`,
+        fallback: `# Runtime State
+
+## 🚨 ATTENTION CODER
+Always check this file and verify the actual runtime state (ports, running processes, env variables) BEFORE writing code. Update this file if ports or access methods change.
+
+- **Server:** e.g., running on port 3210
+- **Services:** e.g., Scraper running on port 3211
+- **Auth:** e.g., admin@local / password
+- **Verification Commands:**
+  - \`pm2 ls\`
+  - \`curl http://localhost:3210/health\`
+`
       },
       'JOURNAL.md': {
         fallback: `# Development Journal

package/src/utils/gitUtils.js

@@ -25,14 +25,18 @@ export async function getGitAnchor(repoPath) {
   }
 }
 
-export async function getChangedFiles(repoPath, anchorHash) {
-  try {
-    const { stdout } = await execa('git', ['diff', '--name-only', anchorHash, 'HEAD'], { cwd: repoPath });
-    return stdout.split('\n').filter(Boolean);
-  } catch (e) {
-    throw new Error(`Failed to get git diff: ${e.message}`);
-  }
-}
+export async function getChangedFiles(repoPath, anchorHash, includeWorkingTree = false) {
+  try {
+    const args = ['diff', '--name-only', anchorHash];
+    if (!includeWorkingTree) {
+      args.push('HEAD');
+    }
+    const { stdout } = await execa('git', args, { cwd: repoPath });
+    return stdout.split('\n').filter(Boolean);
+  } catch (e) {
+    throw new Error(`Failed to get git diff: ${e.message}`);
+  }
+}
 
 export async function getGitDiffOutput(repoPath, anchorHash, excludeFiles = []) {
   try {

package/src/utils/opencodeAgentsGenerator.js

@@ -1,5 +1,9 @@
 import fs from 'fs/promises';
 import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 /**
  * Generates AGENTS.md for OpenCode integration (GLM Z.AI ecosystem only)
@@ -30,11 +34,12 @@ export async function generateOpenCodeAgents(repoPath, mode, tree, confidentialF
       color: '#10a37f'
     };
 
-    const templatePath = path.join(repoPath, '..', '..', 'src', 'templates', 'opencode', 'junior-architect.template.md');
+    const templatePath = path.join(__dirname, '..', 'templates', 'opencode', 'junior-architect.template.md');
     try {
       let templateContent = await fs.readFile(templatePath, 'utf-8');
       body = templateContent.replace('{{tree}}', tree);
     } catch (error) {
+      console.warn(`⚠️ Could not load JAZ template from ${templatePath}: ${error.message}`);
       body = `# 🧠 ROLE: Swarm Orchestrator (GLM-4.7)\n\nDirectory:\n\`\`\`\n${tree}\n\`\`\``;
     }
   } else {
@@ -48,10 +53,11 @@ export async function generateOpenCodeAgents(repoPath, mode, tree, confidentialF
       color: '#44BA81'
     };
 
-    const templatePath = path.join(repoPath, '..', '..', 'src', 'templates', 'opencode', 'coder.template.md');
+    const templatePath = path.join(__dirname, '..', 'templates', 'opencode', 'coder.template.md');
     try {
       body = await fs.readFile(templatePath, 'utf-8');
     } catch (error) {
+      console.warn(`⚠️ Could not load Coder template from ${templatePath}: ${error.message}`);
       body = `# 🛠️ ROLE: Expert Developer`;
     }
   }