@phuetz/code-buddy 0.1.25 → 0.1.26

package/dist/agent/lessons-tracker.js

@@ -0,0 +1,234 @@
+/**
+ * Lessons Tracker — Self-improvement loop for recurring patterns
+ *
+ * Maintains a persistent `lessons.md` in `.codebuddy/lessons.md` (project)
+ * and `~/.codebuddy/lessons.md` (global). On every agent turn the active
+ * lessons are injected BEFORE the todo suffix (stable rules before recency
+ * bias), so the model internalises learned patterns across sessions.
+ *
+ * The agent calls `lessons_add` to capture a new lesson after a correction;
+ * `lessons_search` to find relevant lessons before similar tasks.
+ *
+ * Categories follow a structured taxonomy:
+ *  PATTERN — "What went wrong → correct approach"
+ *  RULE    — Invariant to always follow (e.g. "run tests before marking done")
+ *  CONTEXT — Project/domain-specific facts (e.g. "this repo uses ESM imports")
+ *  INSIGHT — Non-obvious observation useful for future tasks
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// ============================================================================
+// Singleton registry (one tracker per working directory)
+// ============================================================================
+const registry = new Map();
+export function getLessonsTracker(workDir = process.cwd()) {
+    const key = path.resolve(workDir);
+    if (!registry.has(key)) {
+        registry.set(key, new LessonsTracker(key));
+    }
+    return registry.get(key);
+}
+// ============================================================================
+// LessonsTracker
+// ============================================================================
+export class LessonsTracker {
+    workDir;
+    projectPath;
+    globalPath;
+    items = [];
+    loaded = false;
+    constructor(workDir) {
+        this.workDir = workDir;
+        const projectDir = path.join(workDir, '.codebuddy');
+        this.projectPath = path.join(projectDir, 'lessons.md');
+        this.globalPath = path.join(os.homedir(), '.codebuddy', 'lessons.md');
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        const globalItems = this.loadFile(this.globalPath);
+        const projectItems = this.loadFile(this.projectPath);
+        // Merge: project overrides global for duplicate ids
+        const byId = new Map();
+        for (const item of [...globalItems, ...projectItems]) {
+            byId.set(item.id, item);
+        }
+        this.items = Array.from(byId.values());
+    }
+    save() {
+        this.load();
+        // Save to project path only (global is managed manually or by `lessons_add --global`)
+        try {
+            const dir = path.dirname(this.projectPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(this.projectPath, this.serialise(), 'utf-8');
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    add(category, content, source = 'manual', context) {
+        this.load();
+        const item = {
+            id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),
+            category,
+            content,
+            context,
+            createdAt: Date.now(),
+            source,
+        };
+        this.items.push(item);
+        this.save();
+        return item;
+    }
+    remove(id) {
+        this.load();
+        const idx = this.items.findIndex(i => i.id === id);
+        if (idx === -1)
+            return false;
+        this.items.splice(idx, 1);
+        this.save();
+        return true;
+    }
+    clearByCategory(category) {
+        this.load();
+        const before = this.items.length;
+        this.items = category
+            ? this.items.filter(i => i.category !== category)
+            : [];
+        this.save();
+        return before - this.items.length;
+    }
+    list(category) {
+        this.load();
+        return category ? this.items.filter(i => i.category === category) : this.items;
+    }
+    search(query, category) {
+        this.load();
+        const q = query.toLowerCase();
+        return this.items.filter(item => {
+            if (category && item.category !== category)
+                return false;
+            return (item.content.toLowerCase().includes(q) ||
+                (item.context?.toLowerCase().includes(q) ?? false));
+        });
+    }
+    /**
+     * Build the per-turn context block injected BEFORE the todo suffix.
+     * Returns null when there are no lessons (avoids noisy injections).
+     */
+    buildContextBlock() {
+        this.load();
+        if (this.items.length === 0)
+            return null;
+        const lines = [
+            '<lessons_context>',
+            '## Active Lessons (apply to this turn)',
+            '',
+        ];
+        const grouped = new Map();
+        for (const item of this.items) {
+            const arr = grouped.get(item.category) ?? [];
+            arr.push(item);
+            grouped.set(item.category, arr);
+        }
+        const order = ['RULE', 'PATTERN', 'CONTEXT', 'INSIGHT'];
+        for (const cat of order) {
+            const catItems = grouped.get(cat);
+            if (!catItems || catItems.length === 0)
+                continue;
+            for (const item of catItems) {
+                const ctx = item.context ? ` _(${item.context})_` : '';
+                lines.push(`**[${item.category}]**${ctx} ${item.content}`);
+            }
+        }
+        lines.push('</lessons_context>');
+        return lines.join('\n');
+    }
+    // --------------------------------------------------------------------------
+    // Markdown serialisation / parsing
+    // --------------------------------------------------------------------------
+    serialise() {
+        const lines = [
+            '# Lessons Learned',
+            `<!-- auto-generated by Code Buddy — last updated ${new Date().toISOString()} -->`,
+            '',
+        ];
+        const grouped = new Map();
+        for (const item of this.items) {
+            const arr = grouped.get(item.category) ?? [];
+            arr.push(item);
+            grouped.set(item.category, arr);
+        }
+        const order = ['PATTERN', 'RULE', 'CONTEXT', 'INSIGHT'];
+        for (const cat of order) {
+            const catItems = grouped.get(cat);
+            if (!catItems || catItems.length === 0)
+                continue;
+            lines.push(`## ${cat}`);
+            for (const item of catItems) {
+                const date = new Date(item.createdAt).toISOString().slice(0, 10);
+                const ctx = item.context ? `:${item.context}` : '';
+                lines.push(`- [${item.id}] ${item.content} <!-- ${date} ${item.source}${ctx} -->`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    loadFile(filePath) {
+        if (!fs.existsSync(filePath))
+            return [];
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            return this.parseMd(content);
+        }
+        catch {
+            return [];
+        }
+    }
+    parseMd(content) {
+        const items = [];
+        let currentCategory = 'INSIGHT';
+        for (const rawLine of content.split('\n')) {
+            // Category header: ## PATTERN
+            const catMatch = rawLine.match(/^## (PATTERN|RULE|CONTEXT|INSIGHT)\s*$/);
+            if (catMatch) {
+                currentCategory = catMatch[1];
+                continue;
+            }
+            // Item: - [id] content <!-- date source:context -->
+            const itemMatch = rawLine.match(/^- \[([^\]]+)\] (.+?) <!-- ([^\s]+) ([^\s:]+)(?::([^-]+))? -->/);
+            if (itemMatch) {
+                items.push({
+                    id: itemMatch[1],
+                    content: itemMatch[2].trim(),
+                    category: currentCategory,
+                    createdAt: new Date(itemMatch[3]).getTime() || 0,
+                    source: itemMatch[4] ?? 'manual',
+                    context: itemMatch[5]?.trim() || undefined,
+                });
+                continue;
+            }
+            // Plain item fallback: - content
+            const plainMatch = rawLine.match(/^- (.+)/);
+            if (plainMatch) {
+                items.push({
+                    id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),
+                    content: plainMatch[1].trim(),
+                    category: currentCategory,
+                    createdAt: 0,
+                    source: 'manual',
+                });
+            }
+        }
+        return items;
+    }
+}
+//# sourceMappingURL=lessons-tracker.js.map

package/dist/agent/lessons-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons-tracker.js","sourceRoot":"","sources":["../../src/agent/lessons-tracker.ts"],"names":[],"mappings":"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"}

package/dist/agent/message-queue.d.ts

@@ -9,7 +9,7 @@
  * - collect: Messages are batched into a single string for the next turn
  */
 import { EventEmitter } from 'events';
-export type MessageQueueMode = 'steer' | 'followup' | 'collect';
+export type MessageQueueMode = 'steer' | 'followup' | 'collect' | 'steer-backlog';
 export interface QueuedMessage {
     /** Message content */
     content: string;
@@ -18,10 +18,33 @@ export interface QueuedMessage {
     /** When the message was enqueued */
     timestamp: Date;
 }
+export interface MessageQueueOptions {
+    /**
+     * Wait for this many ms of silence before starting a followup turn.
+     * Prevents rapid "continue continue" bursts from spamming turns.
+     * Default: 1000 ms.
+     */
+    debounceMs?: number;
+    /**
+     * Maximum queued messages before overflow handling kicks in.
+     * Default: 20.
+     */
+    cap?: number;
+    /**
+     * How to handle overflow when `cap` is exceeded.
+     * 'drop'      — silently drop the oldest message
+     * 'summarize' — replace the queue with a single synthetic bullet-list prompt
+     * Default: 'drop'.
+     */
+    drop?: 'drop' | 'summarize';
+}
 export declare class MessageQueue extends EventEmitter {
     private mode;
     private queue;
     private processing;
+    private opts;
+    private debounceTimer;
+    constructor(options?: MessageQueueOptions);
     /**
      * Set the queue mode
      */
@@ -31,9 +54,23 @@ export declare class MessageQueue extends EventEmitter {
      */
     getMode(): MessageQueueMode;
     /**
-     * Enqueue a message
+     * Enqueue a message.
+     * Handles debounce (followup mode), cap enforcement with overflow policy,
+     * and steer-backlog mode.
      */
     enqueue(msg: QueuedMessage): void;
+    /**
+     * Collapse all queued messages + incoming overflow into a single synthetic prompt.
+     */
+    private _summarizeOverflow;
+    /**
+     * Update queue options at runtime (e.g. from /queue steer debounce:2s cap:25)
+     */
+    configure(options: Partial<MessageQueueOptions>): void;
+    /**
+     * Get current queue options
+     */
+    getOptions(): Readonly<Required<MessageQueueOptions>>;
     /**
      * Check if a steering message is available (steer mode)
      */

package/dist/agent/message-queue.js

@@ -16,6 +16,16 @@ export class MessageQueue extends EventEmitter {
     mode = 'followup';
     queue = [];
     processing = false;
+    opts;
+    debounceTimer = null;
+    constructor(options = {}) {
+        super();
+        this.opts = {
+            debounceMs: options.debounceMs ?? 1000,
+            cap: options.cap ?? 20,
+            drop: options.drop ?? 'drop',
+        };
+    }
     /**
      * Set the queue mode
      */
@@ -30,14 +40,69 @@ export class MessageQueue extends EventEmitter {
         return this.mode;
     }
     /**
-     * Enqueue a message
+     * Enqueue a message.
+     * Handles debounce (followup mode), cap enforcement with overflow policy,
+     * and steer-backlog mode.
      */
     enqueue(msg) {
+        // Enforce capacity cap
+        if (this.queue.length >= this.opts.cap) {
+            if (this.opts.drop === 'summarize') {
+                this._summarizeOverflow(msg);
+                return;
+            }
+            else {
+                // Drop oldest
+                this.queue.shift();
+            }
+        }
         this.queue.push(msg);
         this.emit('message-enqueued', msg);
-        if (this.mode === 'steer' && this.processing) {
+        if ((this.mode === 'steer' || this.mode === 'steer-backlog') && this.processing) {
             this.emit('steering-available');
         }
+        // Debounce: reset timer on each new message in followup/collect mode
+        if ((this.mode === 'followup' || this.mode === 'collect') && !this.processing) {
+            if (this.debounceTimer)
+                clearTimeout(this.debounceTimer);
+            this.debounceTimer = setTimeout(() => {
+                this.debounceTimer = null;
+                this.emit('debounce-ready');
+            }, this.opts.debounceMs);
+        }
+    }
+    /**
+     * Collapse all queued messages + incoming overflow into a single synthetic prompt.
+     */
+    _summarizeOverflow(incoming) {
+        const all = [...this.queue, incoming];
+        this.queue = [];
+        const bullets = all.map(m => `- [${m.source}] ${m.content}`).join('\n');
+        const synthetic = {
+            content: `Multiple queued messages (summarized due to overflow):\n${bullets}`,
+            source: 'queue-summary',
+            timestamp: new Date(),
+        };
+        this.queue.push(synthetic);
+        this.emit('message-enqueued', synthetic);
+        this.emit('overflow-summarized', { count: all.length });
+    }
+    /**
+     * Update queue options at runtime (e.g. from /queue steer debounce:2s cap:25)
+     */
+    configure(options) {
+        if (options.debounceMs !== undefined)
+            this.opts.debounceMs = options.debounceMs;
+        if (options.cap !== undefined)
+            this.opts.cap = options.cap;
+        if (options.drop !== undefined)
+            this.opts.drop = options.drop;
+    }
+    /**
+     * Get current queue options
+     */
+    getOptions() {
+        return { ...this.opts };
     }
     /**
      * Check if a steering message is available (steer mode)

package/dist/agent/message-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"message-queue.js","sourceRoot":"","sources":["../../src/agent/message-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAiBtC,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,MAAM,OAAO,YAAa,SAAQ,YAAY;IACpC,IAAI,GAAqB,UAAU,CAAC;IACpC,KAAK,GAAoB,EAAE,CAAC;IAC5B,UAAU,GAAG,KAAK,CAAC;IAE3B;;OAEG;IACH,OAAO,CAAC,IAAsB;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,GAAkB;QACxB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;QAEnC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,sBAAsB;QACpB,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK;aACxB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACtC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,eAAe;QACb,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,aAAa;QACX,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF"}
+{"version":3,"file":"message-queue.js","sourceRoot":"","sources":["../../src/agent/message-queue.ts"],"names":[],"mappings":"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"}

package/dist/agent/middleware/index.d.ts

@@ -12,3 +12,4 @@ export { CostLimitMiddleware } from './cost-limit.js';
 export { ContextWarningMiddleware } from './context-warning.js';
 export { AutoObservationMiddleware } from './auto-observation.js';
 export type { AutoObservationConfig } from './auto-observation.js';
+export { WorkflowGuardMiddleware } from './workflow-guard.js';

package/dist/agent/middleware/index.js

@@ -10,4 +10,5 @@ export { TurnLimitMiddleware } from './turn-limit.js';
 export { CostLimitMiddleware } from './cost-limit.js';
 export { ContextWarningMiddleware } from './context-warning.js';
 export { AutoObservationMiddleware } from './auto-observation.js';
+export { WorkflowGuardMiddleware } from './workflow-guard.js';
 //# sourceMappingURL=index.js.map

package/dist/agent/middleware/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/agent/middleware/workflow-guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Workflow Guard Middleware
+ *
+ * Detects tasks that require planning before acting (priority 45).
+ * When the first user message contains 3+ distinct action verbs AND
+ * there is no existing PLAN.md, emits a `steer` hint suggesting
+ * the agent create a plan before diving into implementation.
+ *
+ * This resolves the plan-first vs bug-fix tension:
+ * - Single-file fixes with 1-2 verbs: proceed directly
+ * - Multi-verb, multi-file tasks: steer toward plan init
+ *
+ * Priority 45 — runs after cost-limit (10) and turn-limit (10),
+ * but before most business logic middlewares (100+).
+ */
+import type { ConversationMiddleware, MiddlewareContext, MiddlewareResult } from './types.js';
+export declare class WorkflowGuardMiddleware implements ConversationMiddleware {
+    readonly name = "workflow-guard";
+    readonly priority = 45;
+    beforeTurn(context: MiddlewareContext): MiddlewareResult;
+}

package/dist/agent/middleware/workflow-guard.js

@@ -0,0 +1,94 @@
+/**
+ * Workflow Guard Middleware
+ *
+ * Detects tasks that require planning before acting (priority 45).
+ * When the first user message contains 3+ distinct action verbs AND
+ * there is no existing PLAN.md, emits a `steer` hint suggesting
+ * the agent create a plan before diving into implementation.
+ *
+ * This resolves the plan-first vs bug-fix tension:
+ * - Single-file fixes with 1-2 verbs: proceed directly
+ * - Multi-verb, multi-file tasks: steer toward plan init
+ *
+ * Priority 45 — runs after cost-limit (10) and turn-limit (10),
+ * but before most business logic middlewares (100+).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+// Action verbs that indicate non-trivial scope
+const ACTION_VERBS = new Set([
+    'create', 'add', 'implement', 'build', 'write',
+    'fix', 'repair', 'resolve', 'debug', 'patch',
+    'update', 'change', 'modify', 'edit', 'refactor',
+    'test', 'verify', 'validate', 'check',
+    'deploy', 'release', 'publish', 'push',
+    'remove', 'delete', 'drop', 'clean',
+    'migrate', 'upgrade', 'downgrade',
+    'integrate', 'connect', 'setup', 'configure',
+    'optimise', 'optimize', 'improve', 'enhance',
+    'document', 'explain', 'analyse', 'analyze',
+]);
+function countDistinctActionVerbs(text) {
+    const words = text.toLowerCase().match(/\b\w+\b/g) ?? [];
+    const found = new Set();
+    for (const word of words) {
+        // Check base form and common conjugations
+        if (ACTION_VERBS.has(word))
+            found.add(word);
+        // Strip trailing 's' for 3rd person singular (creates → create)
+        else if (word.endsWith('s') && ACTION_VERBS.has(word.slice(0, -1)))
+            found.add(word.slice(0, -1));
+        // Strip 'ing' (creating → create)
+        else if (word.endsWith('ing') && ACTION_VERBS.has(word.slice(0, -3)))
+            found.add(word.slice(0, -3));
+        // Strip 'ed' (created → create)
+        else if (word.endsWith('ed') && ACTION_VERBS.has(word.slice(0, -2)))
+            found.add(word.slice(0, -2));
+    }
+    return found.size;
+}
+function hasPlanFile(cwd) {
+    return (fs.existsSync(path.join(cwd, 'PLAN.md')) ||
+        fs.existsSync(path.join(cwd, '.codebuddy', 'PLAN.md')));
+}
+export class WorkflowGuardMiddleware {
+    name = 'workflow-guard';
+    priority = 45;
+    beforeTurn(context) {
+        // Only trigger on the very first turn (round 0) of a session
+        if (context.toolRound !== 0) {
+            return { action: 'continue' };
+        }
+        // Extract last user message
+        const lastUser = [...context.messages]
+            .reverse()
+            .find(m => m.role === 'user');
+        if (!lastUser)
+            return { action: 'continue' };
+        const text = typeof lastUser.content === 'string'
+            ? lastUser.content
+            : Array.isArray(lastUser.content)
+                ? lastUser.content.map((c) => {
+                    if (typeof c === 'object' && c !== null && 'text' in c) {
+                        return c.text;
+                    }
+                    return '';
+                }).join(' ')
+                : '';
+        const verbCount = countDistinctActionVerbs(text);
+        // Trigger if 3+ distinct action verbs and no plan file exists
+        if (verbCount >= 3 && !hasPlanFile(process.cwd())) {
+            return {
+                action: 'warn',
+                message: [
+                    `[workflow-guard] This task involves ${verbCount} distinct actions.`,
+                    'Consider initialising a plan first: call the `plan` tool with action="init"',
+                    'or create PLAN.md to break the work into verifiable steps before acting.',
+                    'Proceeding without a plan — but be mindful of the Verification Contract.',
+                ].join(' '),
+            };
+        }
+        return { action: 'continue' };
+    }
+}
+//# sourceMappingURL=workflow-guard.js.map

package/dist/agent/middleware/workflow-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-guard.js","sourceRoot":"","sources":["../../../src/agent/middleware/workflow-guard.ts"],"names":[],"mappings":"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"}

package/dist/agent/repo-profiler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RepoProfiler
+ *
+ * Scans the current repository to detect language, framework, package manager,
+ * and build/test commands. Produces a compact contextPack string injected into
+ * the agent system prompt to give it awareness of project conventions.
+ *
+ * Result is cached in .codebuddy/repoProfile.json and invalidated when
+ * package.json (or equivalent) changes.
+ */
+export interface RepoProfile {
+    detectedAt: string;
+    languages: string[];
+    framework?: string;
+    packageManager?: 'npm' | 'pnpm' | 'yarn' | 'poetry' | 'pip' | 'cargo' | 'dotnet' | 'go';
+    commands: {
+        test?: string;
+        lint?: string;
+        format?: string;
+        build?: string;
+    };
+    directories: {
+        src?: string;
+        tests?: string;
+        docs?: string;
+    };
+    conventions: {
+        naming?: string;
+        lintRules?: string[];
+    };
+    /** Compact string injected into agent system prompt */
+    contextPack: string;
+    /** mtime of the primary config file used for cache invalidation */
+    _configMtime?: number;
+}
+/**
+ * Profiles a repository to produce structured metadata.
+ */
+export declare class RepoProfiler {
+    private cwd;
+    private cachePath;
+    constructor(cwd?: string);
+    /**
+     * Get or compute the repo profile.
+     * Uses cached result if the primary config file hasn't changed.
+     */
+    getProfile(): Promise<RepoProfile>;
+    /**
+     * Force recompute (ignores cache).
+     */
+    refresh(): Promise<RepoProfile>;
+    private computeProfile;
+    private buildContextPack;
+    private loadCache;
+    private isCacheStale;
+    private saveCache;
+    private exists;
+    private mtime;
+    private glob;
+}
+export declare function getRepoProfiler(cwd?: string): RepoProfiler;