@xelth/eck-snapshot 5.9.0 → 6.4.1

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,117 @@ 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. HUMAN VS. ARCHITECT (CRITICAL)
+You receive instructions from two sources:
+1. **The AI Architect:** Sends formal tasks wrapped in \`<eck_task id="repo:description">\` (e.g., \`<eck_task id="ecksnapshot:fix-auth-crash">\`) tags.
+2. **The Human User:** Sends conversational messages or small requests.
+
+## DEFINITION OF DONE & eck_finish_task
+- **For AI Architect Tasks (\`<eck_task>\`):** Your task is NOT complete until code works globally. Verify functionality manually. Once verified, call \`eck_finish_task\` immediately. **Do NOT ask the user "should I finish?" — just call it.** Include the task \`id\` in your report.
+- **For Human Requests:** Do NOT call \`eck_finish_task\`. Just reply to the user and make the requested changes. ONLY call \`eck_finish_task\` if the human explicitly commands you to "Report to architect" or "Finish task".
+
+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.
+- **WARNING:** USE ONLY ONCE PER TASK. Do not use this tool for intermediate testing.
+
+**IF \`eck_finish_task\` IS NOT VISIBLE in your tool list:**
+The tool may be registered as a **deferred tool**. Before falling back, you MUST try:
+1. **Search:** Call \`ToolSearch\` with query \`"select:mcp__eck-core__eck_finish_task,mcp__eck-core__eck_fail_task"\` to load deferred MCP tools.
+2. If ToolSearch returns the tools — use them normally.
+3. If ToolSearch confirms they don't exist — run \`eck-snapshot '{"name": "eck_setup_mcp"}'\` in the terminal, then retry ToolSearch.
+
+**MANUAL FALLBACK (Only if ToolSearch AND setup-mcp both fail):**
+0. **WARN THE USER:** State clearly: "⚠️ \`eck-core\` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run \`git add .\` and \`git commit -m "chore: task report"\` in the terminal.
+4. **SNAPSHOT:** Run \`eck-snapshot '{"name": "eck_update"}'\` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
+
+## 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. 🧠 KNOWLEDGE DISTILLATION (POST-FINISH)
+**ONLY** after tasks that changed the project's architecture, added major features, or revealed non-obvious system behavior (e.g., multi-file refactors, new subsystems, tricky debugging sessions that uncovered hidden dependencies).
+Do NOT offer this for routine fixes, config tweaks, or small edits — those don't produce insights worth documenting.
+**Call \`eck_finish_task\` first** — never delay the finish. Then, in the same response, offer:
+> "I learned some things about the architecture during this task. Want me to update the \`.eck/\` manifests before I lose this context?"
+> **[DEBUG] Context info available to me:** [state whether you can see any context window usage %, token counts, or compaction warnings — or "none, no context metrics visible"]
+Include this offer in your \`eck_finish_task\` status so the Architect sees it too.
+If the user says yes — just edit the files and commit. Do NOT call \`eck_finish_task\` again for it.
+
+## 7. 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.
+## HUMAN VS. ARCHITECT (CRITICAL)
+You receive instructions from two sources:
+1. **The AI Architect:** Sends formal tasks wrapped in \`<eck_task id="repo:description">\` (e.g., \`<eck_task id="ecksnapshot:fix-auth-crash">\`) tags.
+2. **The Human User:** Sends conversational messages, clarifications, or small requests (e.g., "make this red", "fix that typo").
+
+## DEFINITION OF DONE & eck_finish_task
+Your behavior changes based on who you are talking to:
+- **For AI Architect Tasks (\`<eck_task>\`):** When the task is complete and fully tested, call \`eck_finish_task\` IMMEDIATELY. Do NOT ask the user for permission. Include the task \`id\` in your status report.
+- **For Human Requests:** Do NOT call \`eck_finish_task\`. Just reply to the user naturally and apply the changes. ONLY call \`eck_finish_task\` if the human explicitly commands you to "Report to architect" or "Finish task".
+
+Pass your detailed markdown report into the \`status\` argument.
+- The tool will automatically write the report, commit, and generate a snapshot.
+- **DO NOT** manually write to \`AnswerToSA.md\` with your file editing tools.
+- **WARNING: USE ONLY ONCE.** Do not use for intermediate testing.
+
+**IF \`eck_finish_task\` IS NOT VISIBLE in your tool list:**
+The tool may be registered as a **deferred tool**. Before falling back, you MUST try:
+1. **Search:** Call \`ToolSearch\` with query \`"select:mcp__eck-core__eck_finish_task,mcp__eck-core__eck_fail_task"\` to load deferred MCP tools.
+2. If ToolSearch returns the tools — use them normally.
+3. If ToolSearch confirms they don't exist — run \`eck-snapshot '{"name": "eck_setup_mcp"}'\` in the terminal, then retry ToolSearch.
+
+**MANUAL FALLBACK (Only if ToolSearch AND setup-mcp both fail):**
+0. **WARN THE USER:** State clearly: "⚠️ \`eck-core\` MCP server is not connected. Proceeding with manual fallback."
+1. **READ:** Read \`.eck/lastsnapshot/AnswerToSA.md\` using your \`Read\` tool (REQUIRED before overwriting).
+2. **WRITE:** Overwrite that file with your report.
+3. **COMMIT (CRITICAL):** Run \`git add .\` and \`git commit -m "chore: task report"\` in the terminal.
+4. **SNAPSHOT:** Run \`eck-snapshot '{"name": "eck_update"}'\` in the terminal.
+*(Note: The snapshot compares against the git anchor. If you skip step 3, it will say "No changes detected").*
+
+## 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.
+
+## 🧠 KNOWLEDGE DISTILLATION (POST-FINISH)
+**ONLY** after tasks that changed the project's architecture, added major features, or revealed non-obvious system behavior (e.g., multi-file refactors, new subsystems, tricky debugging that uncovered hidden dependencies).
+Do NOT offer this for routine fixes, config tweaks, or small edits.
+**Call \`eck_finish_task\` first** — never delay the finish. Then, in the same response, offer:
+> "I learned some things about the architecture during this task. Want me to update the \`.eck/\` manifests before I lose this context?"
+> **[DEBUG] Context info available to me:** [state whether you can see any context window usage %, token counts, or compaction warnings — or "none, no context metrics visible"]
+Include this offer in your \`eck_finish_task\` status so the Architect sees it too.
+If the user says yes — just edit the files and commit. Do NOT call \`eck_finish_task\` again for it.
 
 ## 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 +164,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)`);
+}