pulse-framework-cli 0.4.1

package/dist/lib/scanner.js

@@ -0,0 +1,413 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanDiff = scanDiff;
+exports.detectLoopSignals = detectLoopSignals;
+const node_path_1 = __importDefault(require("node:path"));
+function scanDiff(config, input) {
+    const findings = [];
+    const num = parseNumstat(input.diffNumstat);
+    const deletedFiles = parseDeletedFiles(input.diffNameStatus);
+    const touchedFiles = num.map((n) => n.file);
+    const stats = {
+        filesChanged: touchedFiles.length,
+        linesAdded: num.reduce((a, n) => a + n.added, 0),
+        linesDeleted: num.reduce((a, n) => a + n.deleted, 0),
+        deletedFiles,
+        touchedFiles,
+    };
+    // --- Critical: secrets ---
+    const secretHits = matchAny(config.patterns.secret, input.diffText);
+    if (secretHits.length) {
+        findings.push({
+            severity: "critical",
+            code: "SECRETS",
+            message: `Possible secrets found in diff (${secretHits.length} hit(s)).`,
+            details: secretHits.slice(0, 5).join("\n"),
+        });
+    }
+    // --- Warn: production URLs ---
+    const prodUrlHits = matchAny(config.patterns.prodUrl, input.diffText).filter((m) => !m.includes("localhost") && !m.includes("127.0.0.1"));
+    if (prodUrlHits.length) {
+        findings.push({
+            severity: config.enforcement === "strict" ? "critical" : "warn",
+            code: "PROD_URL",
+            message: `Production/external URL(s) detected in diff (${prodUrlHits.length} hit(s)). Prefer env vars.`,
+            details: prodUrlHits.slice(0, 5).join("\n"),
+        });
+    }
+    // --- Critical/Warn: mass deletes (DELETE safeguard) ---
+    if (deletedFiles.length) {
+        findings.push({
+            severity: config.enforcement === "advisory" ? "warn" : "critical",
+            code: "MASS_DELETE",
+            message: `File deletion detected (${deletedFiles.length} file(s)). DELETE requires explicit confirmation.`,
+            details: deletedFiles.slice(0, 10).join("\n"),
+        });
+    }
+    else if (stats.linesDeleted >= config.thresholds.warnMaxDeletions) {
+        findings.push({
+            severity: "warn",
+            code: "MASS_DELETE",
+            message: `High deletions in diff (${stats.linesDeleted}). Consider smaller milestones / checkpoint.`,
+        });
+    }
+    // --- Warn: big changeset (red flag: too much at once) ---
+    if (stats.filesChanged >= config.thresholds.warnMaxFilesChanged ||
+        stats.linesAdded + stats.linesDeleted >= config.thresholds.warnMaxLinesChanged) {
+        findings.push({
+            severity: "warn",
+            code: "BIG_CHANGESET",
+            message: `Large changeset (files=${stats.filesChanged}, lines=${stats.linesAdded + stats.linesDeleted}). Consider smaller milestones.`,
+            details: input.diffStat || undefined,
+        });
+    }
+    // --- Warn: dependencies changed (unknown deps) ---
+    const depsTouched = touchedFiles.some((f) => ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"].includes(node_path_1.default.basename(f)));
+    if (depsTouched) {
+        // Parse NEW dependencies from diff
+        const newDeps = extractNewDependencies(input.diffText);
+        if (newDeps.length > 0) {
+            findings.push({
+                severity: "warn",
+                code: "UNKNOWN_DEPS",
+                message: `New dependencies detected (${newDeps.length}): Do you know these?`,
+                details: newDeps.slice(0, 10).map((d) => `  + ${d.name}${d.version ? ` @ ${d.version}` : ""}`).join("\n"),
+            });
+        }
+        else {
+            findings.push({
+                severity: "warn",
+                code: "UNKNOWN_DEPS",
+                message: "Dependency/lockfile change detected. Check if changes are intended.",
+            });
+        }
+    }
+    // --- Warn: console.log / debug leftovers ---
+    const consoleHits = simpleLineHits(input.diffText, /^\+\s*console\.log\(/gm, 5);
+    if (consoleHits.length) {
+        findings.push({
+            severity: "warn",
+            code: "CONSOLE_LOG",
+            message: "console.log detected in added lines. Remove debug output before merging.",
+            details: consoleHits.join("\n"),
+        });
+    }
+    // --- Warn: commented-out code (very heuristic) ---
+    const commentedHits = simpleLineHits(input.diffText, /^\+\s*\/\/\s*(if|for|while|return|const|let|function|class)\b/gim, 5);
+    if (commentedHits.length) {
+        findings.push({
+            severity: "warn",
+            code: "COMMENTED_CODE",
+            message: "Commented-out code detected in added lines. Prefer deleting or tracking via issue.",
+            details: commentedHits.join("\n"),
+        });
+    }
+    // --- Warn: TODO without issue ref ---
+    const todoHits = simpleLineHits(input.diffText, /^\+\s*\/\/\s*TODO\b(?!.*#\d+)(?!.*CU-)(?!.*JIRA-)/gim, 5);
+    if (todoHits.length) {
+        findings.push({
+            severity: "warn",
+            code: "TODO_NO_ISSUE",
+            message: "TODO comment without issue reference detected. Add ticket reference to avoid orphan TODOs.",
+            details: todoHits.join("\n"),
+        });
+    }
+    return { findings, stats };
+}
+/**
+ * Extract NEW dependencies from git diff of package.json
+ * Looks for added lines with "package": "version" pattern
+ */
+function extractNewDependencies(diffText) {
+    const deps = [];
+    const seen = new Set();
+    // Match added lines in package.json that look like dependencies
+    // Pattern: +    "package-name": "^1.2.3"
+    const depLineRegex = /^\+\s*"(@?[\w\-./]+)"\s*:\s*"([^"]+)"/gm;
+    let match;
+    while ((match = depLineRegex.exec(diffText)) !== null) {
+        const name = match[1] ?? "";
+        const version = match[2] ?? "";
+        // Skip common non-dependency fields
+        if (isNonDependencyField(name))
+            continue;
+        // Skip if it looks like a lockfile internal entry
+        if (name.startsWith("node_modules/"))
+            continue;
+        // Must look like a valid npm package name
+        // - Starts with @ (scoped) or a letter
+        // - Contains only valid chars
+        // - Version looks like a semver range
+        if (!isValidPackageName(name))
+            continue;
+        if (!isValidVersionRange(version))
+            continue;
+        // Dedupe
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        deps.push({ name, version });
+    }
+    return deps;
+}
+/**
+ * Check if name looks like a valid npm package name
+ */
+function isValidPackageName(name) {
+    // Scoped packages: @scope/name
+    if (name.startsWith("@")) {
+        return /^@[\w-]+\/[\w.-]+$/.test(name);
+    }
+    // Regular packages: name or name-with-dashes
+    return /^[a-z][\w.-]*$/.test(name);
+}
+/**
+ * Check if version looks like a semver range
+ */
+function isValidVersionRange(version) {
+    // Common patterns: ^1.0.0, ~1.0.0, >=1.0.0, 1.0.0, *, latest
+    // Also: npm:package@version, workspace:*
+    if (version === "*" || version === "latest" || version === "next")
+        return true;
+    if (version.startsWith("npm:"))
+        return true;
+    if (version.startsWith("workspace:"))
+        return true;
+    if (/^[\^~>=<]?\d/.test(version))
+        return true;
+    return false;
+}
+/**
+ * Check if a field name is a common package.json field (not a dependency)
+ */
+function isNonDependencyField(name) {
+    const nonDepFields = [
+        // package.json fields
+        "name", "version", "description", "main", "module", "types", "typings",
+        "scripts", "bin", "files", "repository", "keywords", "author", "license",
+        "bugs", "homepage", "engines", "private", "workspaces", "publishConfig",
+        "type", "exports", "imports", "sideEffects", "browserslist", "eslintConfig",
+        "prettier", "jest", "mocha", "nyc", "lint-staged", "husky", "config",
+        "peerDependenciesMeta", "bundleDependencies", "optionalDependencies",
+        "overrides", "resolutions", "packageManager", "volta", "directories",
+        // Script names
+        "dev", "build", "start", "test", "lint", "format", "clean", "watch",
+        "preinstall", "postinstall", "prepublish", "prepare",
+        // Lock file internal fields
+        "resolved", "integrity", "dev", "optional", "requires", "dependencies",
+        "node", "npm", "funding", "hasInstallScript", "hasShrinkwrap", "deprecated",
+        "peer", "engines", "os", "cpu", "libc", "bin", "license",
+        // Common config field values
+        "preset", "extends", "plugins", "rules", "env", "globals", "parser",
+        "parserOptions", "settings", "ignorePatterns",
+    ];
+    // Also skip if it looks like a version range or URL
+    if (/^[\d^~<>=*]/.test(name))
+        return true;
+    if (name.startsWith("http"))
+        return true;
+    if (name.startsWith("git"))
+        return true;
+    if (name.startsWith("file:"))
+        return true;
+    if (name.startsWith("npm:"))
+        return true;
+    return nonDepFields.includes(name);
+}
+function matchAny(patterns, text) {
+    const out = [];
+    for (const p of patterns) {
+        try {
+            const re = new RegExp(p, "g");
+            const m = text.match(re);
+            if (m)
+                out.push(...m.slice(0, 5));
+        }
+        catch {
+            // ignore invalid patterns
+        }
+    }
+    // de-dupe
+    return [...new Set(out)];
+}
+function simpleLineHits(text, re, limit) {
+    const hits = [];
+    let m;
+    while ((m = re.exec(text)) && hits.length < limit) {
+        hits.push(m[0]);
+    }
+    return hits;
+}
+function parseDeletedFiles(nameStatus) {
+    const files = [];
+    for (const line of nameStatus.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const [status, file] = trimmed.split(/\s+/);
+        if (status === "D" && file)
+            files.push(file);
+    }
+    return files;
+}
+function parseNumstat(numstat) {
+    const rows = [];
+    for (const line of numstat.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const parts = trimmed.split("\t");
+        if (parts.length < 3)
+            continue;
+        const [a, d, file] = parts;
+        const added = a === "-" ? 0 : Number(a);
+        const deleted = d === "-" ? 0 : Number(d);
+        rows.push({ added: Number.isFinite(added) ? added : 0, deleted: Number.isFinite(deleted) ? deleted : 0, file: file ?? "" });
+    }
+    return rows;
+}
+/**
+ * Analyze git log for loop signals
+ * @param gitLog Output from `git log --oneline -n 15`
+ * @param gitLogWithFiles Output from `git log --name-only --oneline -n 15`
+ */
+function detectLoopSignals(gitLog, gitLogWithFiles) {
+    const signals = [];
+    const lines = gitLog.split("\n").filter((l) => l.trim());
+    const messages = lines.map((l) => l.replace(/^[a-f0-9]+\s+/, "").toLowerCase());
+    // ────────────────────────────────────────────────────────────────────────────
+    // Signal 1: Fix-Chain (multiple "fix" commits in a row)
+    // ────────────────────────────────────────────────────────────────────────────
+    const fixCount = messages.filter((m) => /^fix(\(|:|\s)/i.test(m)).length;
+    if (fixCount >= 3) {
+        signals.push({
+            type: "fix_chain",
+            severity: "warn",
+            message: `Loop signal: ${fixCount}x "fix" commits in last 15 commits. Possible fix-loop.`,
+            details: messages.slice(0, 6).join("\n"),
+        });
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Signal 2: Revert-Pattern (explizite Reverts)
+    // ────────────────────────────────────────────────────────────────────────────
+    const revertCount = messages.filter((m) => /\brevert\b/i.test(m)).length;
+    if (revertCount >= 1) {
+        signals.push({
+            type: "revert",
+            severity: revertCount >= 2 ? "critical" : "warn",
+            message: `Loop signal: ${revertCount}x "revert" found. A↔B toggling possible.`,
+            details: messages.filter((m) => /\brevert\b/i.test(m)).join("\n"),
+        });
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Signal 3: File-Churn (same file changed multiple times in short time)
+    // ────────────────────────────────────────────────────────────────────────────
+    if (gitLogWithFiles) {
+        const fileChanges = parseFileChangesFromLog(gitLogWithFiles);
+        const churnFiles = Object.entries(fileChanges)
+            .filter(([_, count]) => count >= 5)
+            .map(([file, count]) => `${file} (${count}x)`);
+        if (churnFiles.length > 0) {
+            signals.push({
+                type: "churn",
+                severity: "warn",
+                message: `Loop signal: File-Churn - ${churnFiles.length} file(s) changed 5+ times.`,
+                details: churnFiles.slice(0, 5).join("\n"),
+            });
+        }
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Signal 4: Fix without test changes
+    // ────────────────────────────────────────────────────────────────────────────
+    if (gitLogWithFiles) {
+        const fixWithoutTest = detectFixWithoutTest(gitLogWithFiles);
+        if (fixWithoutTest.length >= 2) {
+            signals.push({
+                type: "fix_no_test",
+                severity: "warn",
+                message: `Loop signal: ${fixWithoutTest.length}x "fix" commits without test changes.`,
+                details: fixWithoutTest.slice(0, 3).join("\n"),
+            });
+        }
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Signal 5: Pendulum (similar commit messages repeating)
+    // ────────────────────────────────────────────────────────────────────────────
+    const similarMessages = findSimilarMessages(messages);
+    if (similarMessages.length > 0) {
+        signals.push({
+            type: "pendeln",
+            severity: "critical",
+            message: `Loop signal: Similar commits repeating. Possible diff pendulum.`,
+            details: similarMessages.join("\n"),
+        });
+    }
+    return signals;
+}
+/**
+ * Parse file changes from git log --name-only output
+ */
+function parseFileChangesFromLog(logWithFiles) {
+    const fileCount = {};
+    const lines = logWithFiles.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip commit hashes and empty lines
+        if (!trimmed || /^[a-f0-9]{7,}/.test(trimmed))
+            continue;
+        // Count file occurrences
+        if (trimmed.includes(".") || trimmed.includes("/")) {
+            fileCount[trimmed] = (fileCount[trimmed] ?? 0) + 1;
+        }
+    }
+    return fileCount;
+}
+/**
+ * Detect "fix" commits that don't touch test files
+ */
+function detectFixWithoutTest(logWithFiles) {
+    const results = [];
+    const blocks = logWithFiles.split(/\n(?=[a-f0-9]{7,})/);
+    for (const block of blocks) {
+        const lines = block.split("\n").filter((l) => l.trim());
+        if (lines.length === 0)
+            continue;
+        const firstLine = lines[0] ?? "";
+        const message = firstLine.replace(/^[a-f0-9]+\s+/, "").toLowerCase();
+        // Check if it's a fix commit
+        if (!/^fix(\(|:|\s)/i.test(message))
+            continue;
+        // Check if any files are test files
+        const files = lines.slice(1);
+        const hasTestFile = files.some((f) => /\.(test|spec)\.[jt]sx?$/.test(f) ||
+            /__(tests|test)__/.test(f) ||
+            /\.test\./.test(f));
+        if (!hasTestFile) {
+            results.push(firstLine);
+        }
+    }
+    return results;
+}
+/**
+ * Find similar commit messages that might indicate pendeln
+ */
+function findSimilarMessages(messages) {
+    const similar = [];
+    // Simple: Check for near-identical messages
+    for (let i = 0; i < messages.length - 1; i++) {
+        for (let j = i + 1; j < messages.length; j++) {
+            const m1 = messages[i] ?? "";
+            const m2 = messages[j] ?? "";
+            // Normalize: remove version numbers, timestamps
+            const norm1 = m1.replace(/v?\d+(\.\d+)*/g, "").replace(/\s+/g, " ").trim();
+            const norm2 = m2.replace(/v?\d+(\.\d+)*/g, "").replace(/\s+/g, " ").trim();
+            if (norm1 === norm2 && norm1.length > 10) {
+                similar.push(`"${m1}" ≈ "${m2}"`);
+            }
+        }
+    }
+    return similar;
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,37 @@
+export type PulseLayer = "concept" | "build" | "escalation";
+export type EnforcementMode = "advisory" | "mixed" | "strict";
+export type NotificationMode = "terminal" | "macos" | "both";
+export type ProjectType = "node" | "python" | "unknown";
+export type PresetName = "frontend" | "backend" | "fullstack" | "monorepo" | "custom";
+export type PresetConfig = {
+    warnMaxFilesChanged: number;
+    warnMaxLinesChanged: number;
+    warnMaxDeletions: number;
+    checkpointReminderMinutes: number;
+    extraSecretPatterns?: string[];
+};
+export type PulseConfig = {
+    version: 1;
+    projectType: ProjectType;
+    enforcement: EnforcementMode;
+    notifications: NotificationMode;
+    preset?: PresetName;
+    thresholds: {
+        warnMaxFilesChanged: number;
+        warnMaxLinesChanged: number;
+        warnMaxDeletions: number;
+    };
+    patterns: {
+        secret: string[];
+        prodUrl: string[];
+    };
+    commands: {
+        test?: string;
+    };
+    checkpointReminderMinutes?: number;
+};
+export type PulseState = {
+    version: 1;
+    profile: PulseLayer;
+    lastCheckpointAt?: string;
+};

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pulse-framework-cli",
+  "version": "0.4.1",
+  "description": "Pulse Framework CLI – Guardrails, checkpoints, and escalation for AI-assisted development.",
+  "author": "Manuel Fuß <kontakt@manuel-fuss.de>",
+  "license": "MIT",
+  "homepage": "https://manuel-fuss.de/pulse",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manuelfussTC/PulseFramework"
+  },
+  "keywords": [
+    "pulse",
+    "ai",
+    "cursor",
+    "agent",
+    "guardrails",
+    "checkpoint",
+    "cli"
+  ],
+  "bin": {
+    "pulse": "dist/index.js",
+    "pulse-framework": "dist/index.js"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0"
+  }
+}
+

package/templates/.cursorrules

@@ -0,0 +1,159 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# PULSE FRAMEWORK - AI Agent Rules (v1.1)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Author: Manuel Fuß (kontakt@manuel-fuss.de)
+# Repo: https://github.com/manuelfussTC/PulseFramework
+#
+# These rules apply to YOU, the AI Agent. You MUST follow them.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 🛑 CRITICAL RULE: 30-MINUTE AUTONOMY LIMIT                                  │
+# └─────────────────────────────────────────────────────────────────────────────┘
+#
+# You may work autonomously for a MAXIMUM of 30 minutes. Then you MUST:
+#
+# 1. STOP - No further action without human confirmation
+# 2. SUMMARIZE - What have you done in the last 30 min?
+# 3. ASK - "Should I continue? Here is my current status: [...]"
+#
+# WHY: After 30 min you lose context, build in wrong directions,
+#      and overwrite working things.
+#
+# For EVERY longer task:
+# - Split into 30-min blocks
+# - At the end of each block: Checkpoint + Summary + Question
+# - NEVER "just one more quick thing" after 30 min
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 🔒 5 CRITICAL SAFEGUARDS - NON-NEGOTIABLE                                   │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# SAFEGUARD 1: DELETE LOCK
+# - NEVER delete a non-empty file without explicitly asking:
+#   "CONFIRM DELETION: [filename] - This file contains [X lines]. Delete?"
+# - NEVER "Apply All" on a diff >50 lines without prior summary
+
+# SAFEGUARD 2: GIT PUSH LOCK  
+# - NEVER git push without explicit instruction
+# - Before every push: "Ready to push. Changes: [summary]. Confirm push?"
+
+# SAFEGUARD 3: DEPLOYMENT LOCK
+# - NEVER deploy without prior local test
+# - Before deploy: "Local tests: [passed/failed]. Confirm deploy?"
+
+# SAFEGUARD 4: BREAKING CHANGES
+# - On API changes, schema migrations, config changes:
+#   "⚠️ BREAKING CHANGE: [what changes]. Continue?"
+
+# SAFEGUARD 5: SECRETS
+# - NEVER put secrets, API keys, tokens in code
+# - If you see a secret: "🚨 SECRET FOUND: [masked]. Please move to .env."
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 🔄 LOOP DETECTION - SELF-MONITORING                                         │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# You MUST monitor yourself for loops:
+
+# LOOP TYPE 1: "Is fixed" but not
+# - If you say >2x "now it should work" and it doesn't:
+# - STOP. Say: "I'm stuck in a loop. Here's what I've tried: [...]"
+# - Recommend escalation to a reasoning model
+
+# LOOP TYPE 2: Back-and-forth (A↔B)
+# - If you change something, then undo it, then change it again:
+# - STOP. Say: "I'm toggling between two approaches. Which should I choose?"
+
+# LOOP TYPE 3: Doesn't understand the problem
+# - If you're unsure what the actual problem is:
+# - STOP. Say: "I'm not sure I understand the problem. 
+#   Let me summarize what I understood: [...]"
+
+# LOOP TYPE 4: Too much at once
+# - If the task is too big:
+# - STOP. Say: "This task is too big for one block. 
+#   I suggest: Milestone 1: [...], Milestone 2: [...]"
+
+# LOOP TYPE 5: Verification loop (status/search/status without action)
+# - If you keep running checks without implementing anything (2 cycles):
+# - STOP. Say: "I'm in verification mode. I'll now implement the smallest concrete change."
+# - Then implement ONE minimal change and re-check once.
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 📋 CHECKPOINT PROTOCOL                                                      │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# Every 5-10 minutes (or after every significant change):
+#
+# 1. GIT COMMIT with clear message
+# 2. SHORT SUMMARY: "Checkpoint: [what was done]"
+# 3. NEXT STEP: "Next up: [what comes next]"
+#
+# Commit message format:
+# - feat: New feature
+# - fix: Bug fix  
+# - refactor: Code improvement without functionality change
+# - docs: Documentation
+# - test: Tests
+# - chore: Maintenance
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 🚨 RED FLAGS - STOP IMMEDIATELY                                             │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# If you recognize any of these patterns, STOP IMMEDIATELY and report:
+#
+# 🚩 You no longer understand your own code
+# 🚩 More than 200 lines in one change
+# 🚩 Dependencies you don't know
+# 🚩 Deleted files without explicit confirmation
+# 🚩 Production URLs hardcoded
+# 🚩 console.log/print statements for debugging forgotten
+# 🚩 Commented-out code
+# 🚩 TODO without issue reference
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 📊 ESCALATION                                                               │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# When you need to escalate, ALWAYS provide:
+#
+# 1. PROBLEM SUMMARY
+#    - What was the original task?
+#    - What did I try?
+#    - What doesn't work?
+#
+# 2. CONTEXT
+#    - Relevant code snippets
+#    - Error messages (complete)
+#    - Git history of recent changes
+#
+# 3. HYPOTHESES
+#    - What could be the cause?
+#    - What have I already ruled out?
+#
+# 4. SPECIFIC QUESTION
+#    - What exactly should the reasoning model answer?
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ ✅ START PROTOCOL                                                           │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# For EVERY new task:
+#
+# 1. CONFIRM your understanding:
+#    "I understand the task as follows: [summary]"
+#
+# 2. PLAN before you code:
+#    "My plan: 1. [...] 2. [...] 3. [...]"
+#
+# 3. ASK about uncertainties:
+#    "Before I start: [specific question]"
+#
+# 4. ESTIMATE the effort:
+#    "Estimated effort: [X] minutes. Should I start?"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# END OF RULES - You are now ready. Follow these rules.
+# ═══════════════════════════════════════════════════════════════════════════════