pulse-framework-cli 0.4.2 → 0.4.4

package/dist/commands/doctor.js

@@ -66,7 +66,7 @@ function registerDoctorCommand(program) {
             }
         }
         // ════════════════════════════════════════════════════════════════════════
-        // Preset-Verletzungen explizit hinzufügen
+        // Add preset limit violations explicitly
         // ════════════════════════════════════════════════════════════════════════
         const scope = (0, briefing_js_1.calculateScopeCheck)(config, scan.stats);
         if (scope.exceeded) {

package/dist/commands/reset.js

@@ -38,7 +38,7 @@ function registerResetCommand(program) {
             }
         }
         // ══════════════════════════════════════════════════════════════════════
-        // Zeige betroffene Commits
+        // Show affected commits
         // ══════════════════════════════════════════════════════════════════════
         const recentLog = await (0, git_js_1.gitLogOneline)(repoRoot, numCommits + 2);
         const logLines = recentLog.split("\n").filter((l) => l.trim());
@@ -57,7 +57,7 @@ function registerResetCommand(program) {
         // eslint-disable-next-line no-console
         console.log("");
         // ══════════════════════════════════════════════════════════════════════
-        // Reset-Modus wählen
+        // Choose reset mode
         // ══════════════════════════════════════════════════════════════════════
         let mode = "mixed";
         if (opts.soft) {
@@ -75,7 +75,7 @@ function registerResetCommand(program) {
             mode = await (0, input_js_1.promptSelect)("Reset mode", choices, "mixed");
         }
         // ══════════════════════════════════════════════════════════════════════
-        // Letzte Bestätigung bei Hard Reset
+        // Final confirmation for hard reset
         // ══════════════════════════════════════════════════════════════════════
         if (mode === "hard" && !opts.yes) {
             // eslint-disable-next-line no-console
@@ -88,7 +88,7 @@ function registerResetCommand(program) {
             }
         }
         // ══════════════════════════════════════════════════════════════════════
-        // Git Reset ausführen
+        // Execute git reset
         // ══════════════════════════════════════════════════════════════════════
         const resetArg = `HEAD~${numCommits}`;
         const modeArg = mode === "mixed" ? "" : `--${mode}`;
@@ -102,14 +102,14 @@ function registerResetCommand(program) {
             process.exit(1);
         }
         // ══════════════════════════════════════════════════════════════════════
-        // Erfolgsmeldung
+        // Success message
         // ══════════════════════════════════════════════════════════════════════
         const newLog = await (0, git_js_1.gitLogOneline)(repoRoot, 1);
         // eslint-disable-next-line no-console
         console.log(`✅ Reset successful!`);
         // eslint-disable-next-line no-console
         console.log(`📍 New HEAD: ${newLog}\n`);
-        // Hinweise
+        // Tips
         if (mode === "soft" || mode === "mixed") {
             // eslint-disable-next-line no-console
             console.log(`💡 Tip: Changes are still there.`);

package/dist/commands/run.js

@@ -46,15 +46,15 @@ function registerRunCommand(program) {
     program
         .command("run")
         .description("Combined workflow: Start → Watch → Checkpoints → Review")
-        .option("-t, --template <id>", "Vorlage: feature, bugfix, refactor, concept, analyze, review")
+        .option("-t, --template <id>", "Template: feature, bugfix, refactor, concept, analyze, review")
         .option("--minutes <n>", "Minutes between checkpoint reminders")
         .option("--no-watch", "Don't start watcher")
-        .option("--action <text>", "ACTION direkt angeben")
-        .option("-C, --clipboard", "Prompt in Zwischenablage kopieren")
+        .option("--action <text>", "Provide ACTION directly")
+        .option("-C, --clipboard", "Copy prompt to clipboard")
         .action(async (opts) => {
         const repoRoot = await (0, paths_js_1.findRepoRoot)(process.cwd());
         if (!repoRoot)
-            throw new Error("Nicht in einem Git-Repository.");
+            throw new Error("Not in a git repository.");
         const [state, config] = await Promise.all([(0, artifacts_js_1.loadState)(repoRoot), (0, config_js_1.loadConfig)(repoRoot)]);
         // Use preset checkpoint interval if not specified
         const minutes = opts.minutes
@@ -76,17 +76,17 @@ function registerRunCommand(program) {
         // ════════════════════════════════════════════════════════════════════════
         // eslint-disable-next-line no-console
         console.log(`━━━ PHASE 1: Prompt ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
-        // Template auswählen
+        // Select template
         let template = opts.template ? (0, prompts_js_1.getTemplateById)(opts.template) : undefined;
         if (!template && !opts.action) {
             const choices = prompts_js_1.PROMPT_TEMPLATES.map((t) => ({
                 value: t.id,
                 label: `${t.name} - ${t.description}`,
             }));
-            const selectedId = await (0, input_js_1.promptSelect)("📋 Vorlage wählen", choices, "feature");
+            const selectedId = await (0, input_js_1.promptSelect)("📋 Choose template", choices, "feature");
             template = (0, prompts_js_1.getTemplateById)(selectedId);
         }
-        // 6-Elemente sammeln
+        // Collect the 6 elements
         const el = {
             role: template?.defaults.role,
             context: template?.defaults.context,
@@ -95,14 +95,14 @@ function registerRunCommand(program) {
         };
         const layer = template?.layer ?? state.profile;
         if (!el.action?.trim()) {
-            el.action = await (0, input_js_1.promptText)("⚡ ACTION (Was soll gemacht werden?)", "");
+            el.action = await (0, input_js_1.promptText)("⚡ ACTION (what should be built?)", "");
         }
         if (!el.context?.trim()) {
-            el.context = await (0, input_js_1.promptText)("📍 KONTEXT (Projekt, Stack)", "");
+            el.context = await (0, input_js_1.promptText)("📍 CONTEXT (project, stack)", "");
         }
-        // Prompt generieren
+        // Generate prompt
         const prompt = (0, prompts_js_1.renderSixElementPrompt)(layer, el);
-        // Artefakt speichern
+        // Save artifact
         const ts = (0, artifacts_js_1.timestampId)();
         const filename = `${ts}-run.md`;
         const content = [
@@ -110,7 +110,7 @@ function registerRunCommand(program) {
             ``,
             `- Profile: **${presetProfile}**`,
             `- Layer: **${layer}**`,
-            template ? `- Vorlage: **${template.name}**` : "",
+            template ? `- Template: **${template.name}**` : "",
             `- Checkpoint interval: **${minutes} min**`,
             ``,
             `## Prompt`,
@@ -126,7 +126,7 @@ function registerRunCommand(program) {
         // eslint-disable-next-line no-console
         console.log(`✅ Template: ${template?.name ?? "custom"}`);
         // eslint-disable-next-line no-console
-        console.log(`✅ Artefakt: ${artifactPath}`);
+        console.log(`✅ Artifact: ${artifactPath}`);
         // Clipboard
         if (opts.clipboard) {
             const clipMsg = await (0, clipboard_js_1.copyAndNotify)(prompt);
@@ -148,19 +148,19 @@ function registerRunCommand(program) {
         // ════════════════════════════════════════════════════════════════════════
         if (opts.watch === false) {
             // eslint-disable-next-line no-console
-            console.log(`━━━ PHASE 2: Übersprungen ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+            console.log(`━━━ PHASE 2: Skipped ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
             // eslint-disable-next-line no-console
             console.log("Watcher not started (--no-watch).\n");
             // eslint-disable-next-line no-console
             console.log("💡 Next steps:");
             // eslint-disable-next-line no-console
-            console.log("   1. Prompt in Cursor einfügen");
+            console.log("   1. Paste the prompt into Cursor");
             // eslint-disable-next-line no-console
-            console.log("   2. `pulse checkpoint` alle 5-10 Min");
+            console.log("   2. Run `pulse checkpoint` every 5-10 min");
             // eslint-disable-next-line no-console
-            console.log("   3. Bei Problemen: `pulse escalate`");
+            console.log("   3. If stuck: `pulse escalate`");
             // eslint-disable-next-line no-console
-            console.log("   4. Am Ende: `pulse review`\n");
+            console.log("   4. At the end: `pulse review`\n");
             return;
         }
         // eslint-disable-next-line no-console
@@ -170,12 +170,12 @@ function registerRunCommand(program) {
         // eslint-disable-next-line no-console
         console.log(`📍 Watcher running... (Ctrl+C to stop)\n`);
         // eslint-disable-next-line no-console
-        console.log(`   1. Kopiere den Prompt oben in Cursor`);
+        console.log(`   1. Paste the prompt above into Cursor`);
         // eslint-disable-next-line no-console
-        console.log(`   2. Arbeite los`);
+        console.log(`   2. Start working`);
         // eslint-disable-next-line no-console
-        console.log(`   3. Ctrl+C wenn fertig\n`);
-        await (0, notifications_js_1.notify)(config.notifications, "Pulse Run gestartet", `Checkpoint reminder every ${minutes} min. Ctrl+C to exit.`);
+        console.log(`   3. Ctrl+C when done\n`);
+        await (0, notifications_js_1.notify)(config.notifications, "Pulse Run started", `Checkpoint reminder every ${minutes} min. Ctrl+C to exit.`);
         // Update state
         state.lastCheckpointAt = new Date().toISOString();
         await (0, artifacts_js_1.saveState)(repoRoot, state);
@@ -200,11 +200,11 @@ function registerRunCommand(program) {
                 // eslint-disable-next-line no-console
                 console.log(`└${"─".repeat(58)}┘`);
                 // eslint-disable-next-line no-console
-                console.log(`   Zeit: ${new Date().toLocaleTimeString()}`);
+                console.log(`   Time: ${new Date().toLocaleTimeString()}`);
                 // eslint-disable-next-line no-console
-                console.log(`   Status: Uncommitted Changes vorhanden`);
+                console.log(`   Status: uncommitted changes present`);
                 // eslint-disable-next-line no-console
-                console.log(`   → pulse checkpoint -m 'deine message'\n`);
+                console.log(`   → pulse checkpoint -m 'your message'\n`);
             }
             else {
                 // eslint-disable-next-line no-console
@@ -217,15 +217,15 @@ function registerRunCommand(program) {
         const cleanup = async (signal) => {
             clearInterval(interval);
             // eslint-disable-next-line no-console
-            console.log(`\n\n━━━ PHASE 3: Abschluss ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+            console.log(`\n\n━━━ PHASE 3: Wrap-up ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
             // eslint-disable-next-line no-console
-            console.log(`🛑 ${signal} empfangen - Beende Pulse Run...\n`);
+            console.log(`🛑 Received ${signal} - stopping Pulse Run...\n`);
             // Check final status
             const status = await (0, git_js_1.gitStatusPorcelain)(repoRoot);
             const dirty = status.trim().length > 0;
             if (dirty) {
                 // eslint-disable-next-line no-console
-                console.log("📝 Uncommitted Changes gefunden:\n");
+                console.log("📝 Uncommitted changes found:\n");
                 const stat = await (0, git_js_1.gitDiffStat)(repoRoot);
                 // eslint-disable-next-line no-console
                 console.log(stat);
@@ -243,25 +243,25 @@ function registerRunCommand(program) {
             }
             else {
                 // eslint-disable-next-line no-console
-                console.log("✨ Keine uncommitted Changes.\n");
+                console.log("✨ No uncommitted changes.\n");
             }
             // Offer review
             const doReview = await (0, input_js_1.promptConfirm)("Create review?", dirty);
             if (doReview) {
                 // eslint-disable-next-line no-console
-                console.log("\n💡 Führe aus: pulse review\n");
+                console.log("\n💡 Run: pulse review\n");
             }
             // Summary
             // eslint-disable-next-line no-console
             console.log(`┌${"─".repeat(58)}┐`);
             // eslint-disable-next-line no-console
-            console.log(`│ 👋 Pulse Run beendet${" ".repeat(37)}│`);
+            console.log(`│ 👋 Pulse Run finished${" ".repeat(35)}│`);
             // eslint-disable-next-line no-console
             console.log(`│                                                          │`);
             // eslint-disable-next-line no-console
             console.log(`│ Checkpoints: ${checkpointCount}${" ".repeat(43 - String(checkpointCount).length)}│`);
             // eslint-disable-next-line no-console
-            console.log(`│ Artefakt: .pulse/pulses/${filename}${" ".repeat(Math.max(0, 32 - filename.length))}│`);
+            console.log(`│ Artifact: .pulse/pulses/${filename}${" ".repeat(Math.max(0, 32 - filename.length))}│`);
             // eslint-disable-next-line no-console
             console.log(`└${"─".repeat(58)}┘\n`);
             process.exit(0);

package/dist/hooks/install.js

@@ -75,13 +75,39 @@ fi
 `, "utf8");
     await ensureExecutable(postCommit);
     await promises_1.default.writeFile(prePush, `#!/bin/sh
-set -e
-
 # Pulse safeguard: never push without explicit permission.
 # Allow push explicitly by running:
 #   PULSE_ALLOW_PUSH=1 git push ...
 
-pulse doctor --hook pre-push
+if [ "$PULSE_SKIP_HOOKS" = "1" ]; then
+  exit 0
+fi
+
+if [ "$PULSE_ALLOW_PUSH" != "1" ]; then
+  echo "PULSE safeguard: push blocked. Set PULSE_ALLOW_PUSH=1 for an explicit push."
+  exit 1
+fi
+
+# Run doctor check if pulse CLI is available
+if command -v pulse >/dev/null 2>&1; then
+  pulse doctor --hook pre-push
+  EXIT_CODE=$?
+elif command -v pulse-framework >/dev/null 2>&1; then
+  pulse-framework doctor --hook pre-push
+  EXIT_CODE=$?
+else
+  EXIT_CODE=0
+fi
+
+# Only block on CRITICAL (exit 2), allow warnings (exit 1) - consistent with pre-commit
+if [ $EXIT_CODE -eq 2 ]; then
+  echo ""
+  echo "❌ Push blocked by PULSE (critical findings)"
+  echo "   Fix issues or use: PULSE_SKIP_HOOKS=1 git push ..."
+  exit 2
+fi
+
+exit 0
 `, "utf8");
     await ensureExecutable(prePush);
     // eslint-disable-next-line no-console

package/dist/lib/input.js

@@ -37,7 +37,7 @@ async function promptSelect(label, choices, defaultValue) {
         });
         // eslint-disable-next-line no-console
         console.log("");
-        const ans = await rl.question("Nummer wählen: ");
+        const ans = await rl.question("Enter number: ");
         const num = parseInt(ans.trim(), 10);
         if (num >= 1 && num <= choices.length) {
             const choice = choices[num - 1];
@@ -65,12 +65,13 @@ async function promptSelect(label, choices, defaultValue) {
 async function promptConfirm(label, defaultYes = false) {
     const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const hint = defaultYes ? "(J/n)" : "(j/N)";
+        const hint = defaultYes ? "(Y/n)" : "(y/N)";
         const ans = await rl.question(`${label} ${hint}: `);
         const v = ans.trim().toLowerCase();
-        if (v === "j" || v === "y" || v === "ja" || v === "yes")
+        // Accept a few common variants (English + legacy German inputs)
+        if (v === "y" || v === "yes" || v === "j" || v === "ja")
             return true;
-        if (v === "n" || v === "nein" || v === "no")
+        if (v === "n" || v === "no" || v === "nein")
             return false;
         return defaultYes;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-framework-cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Pulse Framework CLI – Guardrails, checkpoints, and escalation for AI-assisted development.",
   "author": "Manuel Fuß <kontakt@manuel-fuss.de>",
   "license": "MIT",

package/templates/.cursorrules

@@ -154,6 +154,52 @@
 # 4. ESTIMATE the effort:
 #    "Estimated effort: [X] minutes. Should I start?"
 
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 🔧 MCP TOOL TRIGGERS (WHEN TO CALL)                                         │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# pulse_status   → FIRST action of every response
+# pulse_doctor   → AFTER any file edit/create/delete
+# pulse_checkpoint → WHEN >10 min since last checkpoint (just do it)
+# pulse_run      → WHEN user gives multi-step task (>3 steps)
+# pulse_escalate → WHEN 2-3 failed attempts OR error you don't understand
+# pulse_correct  → WHEN user says "wrong", "not what I meant", "stop"
+# pulse_review   → BEFORE saying "done", creating PR, or merging
+# pulse_learn    → AFTER solving a non-trivial problem (document what worked!)
+# pulse_reset    → WHEN pulse_doctor shows loop signal
+
+# IMPORTANT: Call these ACTIVELY, not just when user asks!
+# - After success: pulse_learn (build knowledge)
+# - Before "done": pulse_review (final check)
+# - On problems: pulse_escalate (don't keep trying)
+
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ 📝 CHANGELOG PROTOCOL (MANDATORY)                                           │
+# └─────────────────────────────────────────────────────────────────────────────┘
+
+# EVERY significant change MUST be documented in CHANGELOG.md
+#
+# WHEN to update:
+# - New feature added
+# - Bug fixed
+# - Breaking change
+# - Behavior changed
+# - After each session with multiple changes
+#
+# FORMAT (Keep a Changelog style):
+# ## [version] (YYYY-MM-DD)
+# ### Added - for new features
+# ### Changed - for changes in existing functionality
+# ### Fixed - for bug fixes
+# ### Removed - for removed features
+# ### Security - for security fixes
+#
+# IMPORTANT:
+# - Update CHANGELOG.md BEFORE committing significant changes
+# - Include specific details (what, why)
+# - Reference issue numbers if applicable
+# - Keep the project alive with good documentation!
+
 # ┌─────────────────────────────────────────────────────────────────────────────┐
 # │ 📦 PULSE PUBLISHING PROTOCOL                                               │
 # └─────────────────────────────────────────────────────────────────────────────┘

package/templates/cursor/pulse.mdc

@@ -53,18 +53,22 @@ WHEN: pulse_status shows >10 min since checkpoint
 WHAT: "Should I create a checkpoint?"
 ```
 
-## 🔴 AUTOMATIC ACTIONS
-
-| Situation | Action |
-|-----------|--------|
-| Start of response | → `pulse_status` (once) |
-| Code changed | → `pulse_doctor` |
-| >10 min since checkpoint | → Recommend checkpoint |
-| >15 min since checkpoint | → **Checkpoint URGENT** |
-| >30 min autonomous | → **STOP + ask user** |
-| 2-3 failed attempts | → **STOP + `pulse_escalate`** |
-| DELETE operation | → **Get user confirmation** |
-| Loop detected | → **STOP + `pulse_escalate`** |
+## 🔴 AUTOMATIC ACTIONS (MANDATORY)
+
+| Situation | Action | Example |
+|-----------|--------|---------|
+| Start of response | → `pulse_status` | Every message |
+| Code changed | → `pulse_doctor` | After any edit/create/delete |
+| >10 min since checkpoint | → `pulse_checkpoint` | Just do it, don't ask |
+| >30 min autonomous | → **STOP + ask user** | "I've been working 30 min, should I continue?" |
+| 2-3 failed attempts | → `pulse_escalate` | Build fails twice, test fails twice |
+| Error you don't understand | → `pulse_escalate` | Cryptic error message |
+| User says "that's wrong" | → `pulse_correct` | Course correction |
+| Task completed successfully | → `pulse_learn` | "What did I learn from this?" |
+| Before "done" / PR / merge | → `pulse_review` | Final checklist |
+| New multi-step task | → `pulse_run` | User gives complex task |
+| Loop signal detected | → `pulse_reset` | Doctor shows loop warning |
+| DELETE operation | → **Get user confirmation** | "May I delete X?" |
 
 ## 🔴 SAFEGUARDS (non-negotiable)
 
@@ -103,19 +107,29 @@ After 2-3 failed attempts:
    - Error message
 3. **WAIT** for user instruction
 
-## MCP Tools
+## After Success (IMPORTANT!)
 
-| Tool | When |
-|------|------|
-| `pulse_status` | **Once per response** (at start) |
-| `pulse_doctor` | **After code changes** |
-| `pulse_checkpoint` | After 5-10 min / on recommendation |
-| `pulse_run` | At start of new tasks |
-| `pulse_escalate` | On problems, loop |
-| `pulse_correct` | On course correction |
-| `pulse_review` | At end / before merge |
-| `pulse_learn` | After solved problems |
-| `pulse_reset` | On loop, reset |
+When you successfully solve a non-trivial problem:
+
+1. **Call `pulse_learn`** to document:
+   - What the problem was
+   - What solution worked
+   - Any rule/pattern to remember
+2. This builds institutional knowledge for future sessions
+
+## MCP Tools - WHEN TO CALL
+
+| Tool | Trigger (MANDATORY) |
+|------|---------------------|
+| `pulse_status` | **FIRST action** of every response |
+| `pulse_doctor` | **AFTER** any file edit/create/delete |
+| `pulse_checkpoint` | **WHEN** >10 min since last checkpoint |
+| `pulse_run` | **WHEN** user gives multi-step task (>3 steps) |
+| `pulse_escalate` | **WHEN** 2-3 failed attempts OR error you don't understand |
+| `pulse_correct` | **WHEN** user says "wrong", "not what I meant", "stop" |
+| `pulse_review` | **BEFORE** saying "done", creating PR, or merging |
+| `pulse_learn` | **AFTER** solving a non-trivial problem (document what worked) |
+| `pulse_reset` | **WHEN** `pulse_doctor` shows loop signal |
 
 ## Example Flow
 
@@ -142,3 +156,4 @@ Agent:
 - Call the tools ACTIVELY, not only when user asks
 - When uncertain: STOP and ASK
 - The safeguards ALWAYS apply, even if user argues against them
+- **ALWAYS update CHANGELOG.md** after significant changes (features, fixes, changes)