@renseiai/agentfactory 0.8.0

package/dist/src/governor/in-memory-event-bus.js

@@ -0,0 +1,79 @@
+/**
+ * In-Memory Event Bus
+ *
+ * Simple event bus implementation for testing and single-process CLI usage.
+ * Events are stored in a queue and delivered via an async generator.
+ */
+// ---------------------------------------------------------------------------
+// InMemoryEventBus
+// ---------------------------------------------------------------------------
+export class InMemoryEventBus {
+    queue = [];
+    waiters = [];
+    closed = false;
+    idCounter = 0;
+    ackedIds = new Set();
+    async publish(event) {
+        if (this.closed) {
+            throw new Error('Event bus is closed');
+        }
+        const id = `mem-${++this.idCounter}`;
+        const item = { id, event };
+        // If a subscriber is waiting, deliver directly
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter(item);
+        }
+        else {
+            this.queue.push(item);
+        }
+        return id;
+    }
+    async *subscribe() {
+        while (!this.closed) {
+            // Try to pull from the queue
+            const item = this.queue.shift();
+            if (item) {
+                yield item;
+                continue;
+            }
+            // Wait for a new event or close
+            const next = await new Promise((resolve) => {
+                if (this.closed) {
+                    resolve(null);
+                    return;
+                }
+                this.waiters.push(resolve);
+            });
+            if (next === null) {
+                return;
+            }
+            yield next;
+        }
+    }
+    async ack(eventId) {
+        this.ackedIds.add(eventId);
+    }
+    async close() {
+        this.closed = true;
+        // Resolve all waiting subscribers with null to end iteration
+        for (const waiter of this.waiters) {
+            ;
+            waiter(null);
+        }
+        this.waiters = [];
+    }
+    // ---- Test helpers ----
+    /** Check if an event ID has been acknowledged */
+    isAcked(eventId) {
+        return this.ackedIds.has(eventId);
+    }
+    /** Get the number of pending (undelivered) events */
+    get pendingCount() {
+        return this.queue.length;
+    }
+    /** Check if the bus has been closed */
+    get isClosed() {
+        return this.closed;
+    }
+}

package/dist/src/governor/index.d.ts

@@ -0,0 +1,14 @@
+export * from './override-parser.js';
+export * from './human-touchpoints.js';
+export * from './top-of-funnel.js';
+export * from './processing-state.js';
+export * from './governor-types.js';
+export * from './decision-engine.js';
+export * from './governor.js';
+export * from './event-types.js';
+export * from './event-bus.js';
+export * from './in-memory-event-bus.js';
+export * from './event-deduplicator.js';
+export * from './event-driven-governor.js';
+export * from './platform-adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/governor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/governor/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,0BAA0B,CAAA;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uBAAuB,CAAA"}

package/dist/src/governor/index.js

@@ -0,0 +1,13 @@
+export * from './override-parser.js';
+export * from './human-touchpoints.js';
+export * from './top-of-funnel.js';
+export * from './processing-state.js';
+export * from './governor-types.js';
+export * from './decision-engine.js';
+export * from './governor.js';
+export * from './event-types.js';
+export * from './event-bus.js';
+export * from './in-memory-event-bus.js';
+export * from './event-deduplicator.js';
+export * from './event-driven-governor.js';
+export * from './platform-adapter.js';

package/dist/src/governor/override-parser.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Override Parser Module
+ *
+ * Parses issue comments for structured human override directives.
+ * Directives must appear at the start of a comment (case-insensitive)
+ * and only non-bot comments are processed.
+ */
+/**
+ * Supported override directive types
+ */
+export type OverrideDirectiveType = 'hold' | 'resume' | 'skip-qa' | 'decompose' | 'reassign' | 'priority';
+/**
+ * Priority levels for the PRIORITY directive
+ */
+export type OverridePriority = 'high' | 'medium' | 'low';
+/**
+ * A parsed override directive extracted from a comment
+ */
+export interface OverrideDirective {
+    type: OverrideDirectiveType;
+    reason?: string;
+    priority?: OverridePriority;
+    commentId?: string;
+    userId?: string;
+    timestamp: number;
+}
+/**
+ * Information about a comment to be parsed for directives
+ */
+export interface CommentInfo {
+    id: string;
+    body: string;
+    userId: string;
+    isBot: boolean;
+    createdAt: number;
+}
+/**
+ * Parse a single comment for an override directive.
+ *
+ * Rules:
+ * - Bot comments are always ignored (returns null)
+ * - Only the first line of the comment is checked for a directive
+ * - Directives are case-insensitive
+ * - Returns null if no directive is found
+ *
+ * @param comment - The comment to parse
+ * @returns The parsed directive, or null if no directive found
+ */
+export declare function parseOverrideDirective(comment: CommentInfo): OverrideDirective | null;
+/**
+ * Find the most recent override directive from a list of comments.
+ *
+ * Parses all comments (skipping bots) and returns the directive with
+ * the latest timestamp. If no directive is found, returns null.
+ *
+ * @param comments - Array of comments to scan, in any order
+ * @returns The most recent directive, or null if none found
+ */
+export declare function findLatestOverride(comments: CommentInfo[]): OverrideDirective | null;
+//# sourceMappingURL=override-parser.d.ts.map

package/dist/src/governor/override-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"override-parser.d.ts","sourceRoot":"","sources":["../../../src/governor/override-parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAAA;AAEzG;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAA;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,iBAAiB,GAAG,IAAI,CAqCrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,iBAAiB,GAAG,IAAI,CAapF"}

package/dist/src/governor/override-parser.js

@@ -0,0 +1,98 @@
+/**
+ * Override Parser Module
+ *
+ * Parses issue comments for structured human override directives.
+ * Directives must appear at the start of a comment (case-insensitive)
+ * and only non-bot comments are processed.
+ */
+// ============================================
+// Directive Patterns
+// ============================================
+/**
+ * Regex patterns for each directive type.
+ * All patterns are anchored to the start of the comment body (after trimming).
+ * The HOLD pattern captures an optional reason after a dash or em-dash.
+ * The PRIORITY pattern captures the priority level.
+ */
+const DIRECTIVE_PATTERNS = [
+    // HOLD or HOLD — reason or HOLD - reason
+    { type: 'hold', pattern: /^hold(?:\s*[—–-]\s*(.+))?$/i },
+    // RESUME
+    { type: 'resume', pattern: /^resume$/i },
+    // SKIP QA or SKIP-QA
+    { type: 'skip-qa', pattern: /^skip[\s-]+qa$/i },
+    // DECOMPOSE
+    { type: 'decompose', pattern: /^decompose$/i },
+    // REASSIGN
+    { type: 'reassign', pattern: /^reassign$/i },
+    // PRIORITY: high|medium|low
+    { type: 'priority', pattern: /^priority:\s*(high|medium|low)$/i },
+];
+// ============================================
+// Parser Functions
+// ============================================
+/**
+ * Parse a single comment for an override directive.
+ *
+ * Rules:
+ * - Bot comments are always ignored (returns null)
+ * - Only the first line of the comment is checked for a directive
+ * - Directives are case-insensitive
+ * - Returns null if no directive is found
+ *
+ * @param comment - The comment to parse
+ * @returns The parsed directive, or null if no directive found
+ */
+export function parseOverrideDirective(comment) {
+    // Ignore bot comments
+    if (comment.isBot) {
+        return null;
+    }
+    // Take the first line of the comment body, trimmed
+    const firstLine = comment.body.trim().split('\n')[0]?.trim();
+    if (!firstLine) {
+        return null;
+    }
+    for (const { type, pattern } of DIRECTIVE_PATTERNS) {
+        const match = firstLine.match(pattern);
+        if (match) {
+            const directive = {
+                type,
+                commentId: comment.id,
+                userId: comment.userId,
+                timestamp: comment.createdAt,
+            };
+            // Extract reason for HOLD directive
+            if (type === 'hold' && match[1]) {
+                directive.reason = match[1].trim();
+            }
+            // Extract priority level for PRIORITY directive
+            if (type === 'priority' && match[1]) {
+                directive.priority = match[1].toLowerCase();
+            }
+            return directive;
+        }
+    }
+    return null;
+}
+/**
+ * Find the most recent override directive from a list of comments.
+ *
+ * Parses all comments (skipping bots) and returns the directive with
+ * the latest timestamp. If no directive is found, returns null.
+ *
+ * @param comments - Array of comments to scan, in any order
+ * @returns The most recent directive, or null if none found
+ */
+export function findLatestOverride(comments) {
+    let latest = null;
+    for (const comment of comments) {
+        const directive = parseOverrideDirective(comment);
+        if (directive) {
+            if (!latest || directive.timestamp > latest.timestamp) {
+                latest = directive;
+            }
+        }
+    }
+    return latest;
+}

package/dist/src/governor/override-parser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=override-parser.test.d.ts.map

package/dist/src/governor/override-parser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"override-parser.test.d.ts","sourceRoot":"","sources":["../../../src/governor/override-parser.test.ts"],"names":[],"mappings":""}

package/dist/src/governor/override-parser.test.js

@@ -0,0 +1,312 @@
+import { describe, it, expect } from 'vitest';
+import { parseOverrideDirective, findLatestOverride } from './override-parser.js';
+// ============================================
+// Helpers
+// ============================================
+function makeComment(overrides = {}) {
+    return {
+        id: 'comment-1',
+        body: '',
+        userId: 'user-1',
+        isBot: false,
+        createdAt: Date.now(),
+        ...overrides,
+    };
+}
+// ============================================
+// Tests
+// ============================================
+describe('parseOverrideDirective', () => {
+    describe('HOLD directive', () => {
+        it('parses plain HOLD', () => {
+            const comment = makeComment({ body: 'HOLD' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+            expect(result.reason).toBeUndefined();
+        });
+        it('parses HOLD with em-dash reason', () => {
+            const comment = makeComment({ body: 'HOLD — waiting for design review' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+            expect(result.reason).toBe('waiting for design review');
+        });
+        it('parses HOLD with regular dash reason', () => {
+            const comment = makeComment({ body: 'HOLD - need more info' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+            expect(result.reason).toBe('need more info');
+        });
+        it('parses HOLD with en-dash reason', () => {
+            const comment = makeComment({ body: 'HOLD – performance concerns' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+            expect(result.reason).toBe('performance concerns');
+        });
+        it('parses HOLD case-insensitively', () => {
+            const comment = makeComment({ body: 'hold' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+        });
+        it('parses Hold (mixed case)', () => {
+            const comment = makeComment({ body: 'Hold — mixed case' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+            expect(result.reason).toBe('mixed case');
+        });
+    });
+    describe('RESUME directive', () => {
+        it('parses RESUME', () => {
+            const comment = makeComment({ body: 'RESUME' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('resume');
+        });
+        it('parses resume (lowercase)', () => {
+            const comment = makeComment({ body: 'resume' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('resume');
+        });
+    });
+    describe('SKIP QA directive', () => {
+        it('parses SKIP QA', () => {
+            const comment = makeComment({ body: 'SKIP QA' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('skip-qa');
+        });
+        it('parses skip qa (lowercase)', () => {
+            const comment = makeComment({ body: 'skip qa' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('skip-qa');
+        });
+        it('handles extra whitespace between SKIP and QA', () => {
+            const comment = makeComment({ body: 'SKIP   QA' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('skip-qa');
+        });
+        it('parses SKIP-QA (hyphenated)', () => {
+            const comment = makeComment({ body: 'SKIP-QA' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('skip-qa');
+        });
+        it('parses skip-qa (hyphenated lowercase)', () => {
+            const comment = makeComment({ body: 'skip-qa' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('skip-qa');
+        });
+    });
+    describe('DECOMPOSE directive', () => {
+        it('parses DECOMPOSE', () => {
+            const comment = makeComment({ body: 'DECOMPOSE' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('decompose');
+        });
+        it('parses decompose (lowercase)', () => {
+            const comment = makeComment({ body: 'decompose' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('decompose');
+        });
+    });
+    describe('REASSIGN directive', () => {
+        it('parses REASSIGN', () => {
+            const comment = makeComment({ body: 'REASSIGN' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('reassign');
+        });
+        it('parses Reassign (mixed case)', () => {
+            const comment = makeComment({ body: 'Reassign' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('reassign');
+        });
+    });
+    describe('PRIORITY directive', () => {
+        it('parses PRIORITY: high', () => {
+            const comment = makeComment({ body: 'PRIORITY: high' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('priority');
+            expect(result.priority).toBe('high');
+        });
+        it('parses PRIORITY: medium', () => {
+            const comment = makeComment({ body: 'PRIORITY: medium' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('priority');
+            expect(result.priority).toBe('medium');
+        });
+        it('parses PRIORITY: low', () => {
+            const comment = makeComment({ body: 'PRIORITY: low' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('priority');
+            expect(result.priority).toBe('low');
+        });
+        it('parses priority case-insensitively', () => {
+            const comment = makeComment({ body: 'priority: HIGH' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('priority');
+            expect(result.priority).toBe('high');
+        });
+        it('handles extra whitespace after colon', () => {
+            const comment = makeComment({ body: 'PRIORITY:   high' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('priority');
+            expect(result.priority).toBe('high');
+        });
+    });
+    describe('bot filtering', () => {
+        it('ignores bot comments', () => {
+            const comment = makeComment({ body: 'HOLD', isBot: true });
+            const result = parseOverrideDirective(comment);
+            expect(result).toBeNull();
+        });
+        it('ignores bot comments for all directive types', () => {
+            const directives = ['HOLD', 'RESUME', 'SKIP QA', 'DECOMPOSE', 'REASSIGN', 'PRIORITY: high'];
+            for (const body of directives) {
+                const comment = makeComment({ body, isBot: true });
+                const result = parseOverrideDirective(comment);
+                expect(result).toBeNull();
+            }
+        });
+    });
+    describe('no directive found', () => {
+        it('returns null for empty body', () => {
+            const comment = makeComment({ body: '' });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+        it('returns null for regular comment text', () => {
+            const comment = makeComment({ body: 'This looks good, nice work!' });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+        it('returns null for directive-like text not at start', () => {
+            const comment = makeComment({ body: 'I think we should HOLD on this' });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+        it('returns null for unsupported directives', () => {
+            const comment = makeComment({ body: 'CANCEL' });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+        it('returns null for PRIORITY with invalid level', () => {
+            const comment = makeComment({ body: 'PRIORITY: urgent' });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+    });
+    describe('metadata extraction', () => {
+        it('captures commentId and userId', () => {
+            const comment = makeComment({
+                id: 'comment-42',
+                body: 'HOLD',
+                userId: 'user-99',
+                createdAt: 1700000000000,
+            });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.commentId).toBe('comment-42');
+            expect(result.userId).toBe('user-99');
+            expect(result.timestamp).toBe(1700000000000);
+        });
+    });
+    describe('multiline comments', () => {
+        it('only checks the first line for directives', () => {
+            const comment = makeComment({
+                body: 'HOLD — security concern\nThis needs review from the security team.\nPlease check the auth flow.',
+            });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+            expect(result.reason).toBe('security concern');
+        });
+        it('ignores directives on subsequent lines', () => {
+            const comment = makeComment({
+                body: 'Great work on this!\nHOLD\nNot really.',
+            });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+    });
+    describe('whitespace handling', () => {
+        it('trims leading whitespace from body', () => {
+            const comment = makeComment({ body: '  HOLD  ' });
+            const result = parseOverrideDirective(comment);
+            expect(result).not.toBeNull();
+            expect(result.type).toBe('hold');
+        });
+        it('trims whitespace-only body', () => {
+            const comment = makeComment({ body: '   ' });
+            expect(parseOverrideDirective(comment)).toBeNull();
+        });
+    });
+});
+describe('findLatestOverride', () => {
+    it('returns null for empty comment list', () => {
+        expect(findLatestOverride([])).toBeNull();
+    });
+    it('returns null when no comments contain directives', () => {
+        const comments = [
+            makeComment({ body: 'Looks good!' }),
+            makeComment({ body: 'Nice work' }),
+        ];
+        expect(findLatestOverride(comments)).toBeNull();
+    });
+    it('returns the only directive found', () => {
+        const comments = [
+            makeComment({ body: 'Looks good!', createdAt: 1000 }),
+            makeComment({ body: 'HOLD', createdAt: 2000 }),
+            makeComment({ body: 'What about tests?', createdAt: 3000 }),
+        ];
+        const result = findLatestOverride(comments);
+        expect(result).not.toBeNull();
+        expect(result.type).toBe('hold');
+        expect(result.timestamp).toBe(2000);
+    });
+    it('returns the most recent directive when multiple exist', () => {
+        const comments = [
+            makeComment({ id: 'c1', body: 'HOLD', createdAt: 1000 }),
+            makeComment({ id: 'c2', body: 'RESUME', createdAt: 2000 }),
+            makeComment({ id: 'c3', body: 'HOLD — second hold', createdAt: 3000 }),
+        ];
+        const result = findLatestOverride(comments);
+        expect(result).not.toBeNull();
+        expect(result.type).toBe('hold');
+        expect(result.reason).toBe('second hold');
+        expect(result.timestamp).toBe(3000);
+    });
+    it('returns the most recent directive regardless of order', () => {
+        // Comments may be passed in any order
+        const comments = [
+            makeComment({ id: 'c3', body: 'DECOMPOSE', createdAt: 3000 }),
+            makeComment({ id: 'c1', body: 'HOLD', createdAt: 1000 }),
+            makeComment({ id: 'c2', body: 'RESUME', createdAt: 5000 }),
+        ];
+        const result = findLatestOverride(comments);
+        expect(result).not.toBeNull();
+        expect(result.type).toBe('resume');
+        expect(result.timestamp).toBe(5000);
+    });
+    it('skips bot comments when finding latest', () => {
+        const comments = [
+            makeComment({ body: 'HOLD', createdAt: 1000, isBot: false }),
+            makeComment({ body: 'RESUME', createdAt: 2000, isBot: true }),
+        ];
+        const result = findLatestOverride(comments);
+        expect(result).not.toBeNull();
+        expect(result.type).toBe('hold');
+        expect(result.timestamp).toBe(1000);
+    });
+});

package/dist/src/governor/platform-adapter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * PlatformAdapter Interface
+ *
+ * Extends the WorkSchedulingFrontend concept with methods needed by the
+ * EventDrivenGovernor to process webhook events and poll project state.
+ *
+ * Platform adapters (e.g., LinearPlatformAdapter) implement this interface
+ * structurally, translating between platform-native concepts and the
+ * Governor's abstract event/issue types.
+ */
+import type { GovernorEvent } from './event-types.js';
+import type { GovernorIssue } from './governor-types.js';
+/**
+ * Adapter that bridges a project-management platform (Linear, Jira, etc.)
+ * to the Governor's event-driven processing model.
+ *
+ * Responsibilities:
+ * - Convert platform webhook payloads into GovernorEvents
+ * - Scan a project for all non-terminal issues (poll sweep)
+ * - Convert platform-native issue objects to GovernorIssue
+ * - Detect parent/child issue relationships
+ */
+export interface PlatformAdapter {
+    /** Human-readable name of the platform (e.g., 'linear', 'jira'). */
+    readonly name: string;
+    /**
+     * Normalize a raw webhook payload from the platform into one or more
+     * GovernorEvents.
+     *
+     * Returns `null` if the payload type is not recognized or not relevant
+     * to the Governor (e.g., label-only changes, unrelated resource types).
+     *
+     * @param payload - Raw webhook payload from the platform
+     * @returns Array of GovernorEvents, or null if unrecognized
+     */
+    normalizeWebhookEvent(payload: unknown): GovernorEvent[] | null;
+    /**
+     * Fetch all non-terminal issues for the given project.
+     *
+     * Terminal statuses (e.g., Accepted, Canceled, Duplicate) are excluded
+     * so the Governor only evaluates issues that may need action.
+     *
+     * @param project - Project name to scan
+     * @returns Array of GovernorIssue representing active issues
+     */
+    scanProjectIssues(project: string): Promise<GovernorIssue[]>;
+    /**
+     * Convert a platform-native issue object to a GovernorIssue.
+     *
+     * The `native` parameter is typed as `unknown` to keep the interface
+     * platform-agnostic. Implementations should cast to the appropriate
+     * platform SDK type internally.
+     *
+     * @param native - Platform-native issue object
+     * @returns GovernorIssue representation
+     */
+    toGovernorIssue(native: unknown): Promise<GovernorIssue>;
+    /**
+     * Check whether the given issue is a parent issue (has child/sub-issues).
+     *
+     * Parent issues receive special treatment in the Governor: they are
+     * typically managed by a coordinator rather than dispatched directly.
+     *
+     * @param issueId - Issue ID to check
+     * @returns True if the issue has child issues
+     */
+    isParentIssue(issueId: string): Promise<boolean>;
+}
+//# sourceMappingURL=platform-adapter.d.ts.map

package/dist/src/governor/platform-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-adapter.d.ts","sourceRoot":"","sources":["../../../src/governor/platform-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAMxD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;;;OASG;IACH,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,GAAG,IAAI,CAAA;IAE/D;;;;;;;;OAQG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;IAE5D;;;;;;;;;OASG;IACH,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAExD;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACjD"}