@renseiai/agentfactory 0.8.0

package/dist/src/governor/event-types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Governor Event Types
+ *
+ * Discriminated union of events that flow through the GovernorEventBus.
+ * Events are produced by webhooks (real-time) and poll sweeps (periodic),
+ * then consumed by the EventDrivenGovernor for decision-making.
+ */
+import type { GovernorIssue } from './governor-types.js';
+/**
+ * Fired when an issue's workflow status changes (e.g., Backlog → Started).
+ * Typically produced by webhook `issue-updated` or a poll sweep diff.
+ */
+export interface IssueStatusChangedEvent {
+    type: 'issue-status-changed';
+    issueId: string;
+    issue: GovernorIssue;
+    previousStatus?: string;
+    newStatus: string;
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    /** Where this event originated */
+    source: EventSource;
+}
+/**
+ * Fired when a comment is added to an issue.
+ * Used for parsing human override directives (HOLD, RESUME, PRIORITY, etc.).
+ */
+export interface CommentAddedEvent {
+    type: 'comment-added';
+    issueId: string;
+    issue: GovernorIssue;
+    commentId: string;
+    commentBody: string;
+    userId?: string;
+    userName?: string;
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    source: EventSource;
+}
+/**
+ * Fired when an agent session completes (success or failure).
+ * Allows the Governor to re-evaluate the issue immediately.
+ */
+export interface SessionCompletedEvent {
+    type: 'session-completed';
+    issueId: string;
+    issue: GovernorIssue;
+    sessionId: string;
+    outcome: 'success' | 'failure';
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    source: EventSource;
+}
+/**
+ * Emitted by periodic poll sweeps. Contains a full snapshot of a single
+ * issue so the Governor can evaluate it without an extra API call.
+ */
+export interface PollSnapshotEvent {
+    type: 'poll-snapshot';
+    issueId: string;
+    issue: GovernorIssue;
+    project: string;
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    source: EventSource;
+}
+export type EventSource = 'webhook' | 'poll' | 'manual';
+export type GovernorEvent = IssueStatusChangedEvent | CommentAddedEvent | SessionCompletedEvent | PollSnapshotEvent;
+/**
+ * Generate a deduplication key for an event.
+ * Same issue at the same status = duplicate within the dedup window.
+ */
+export declare function eventDedupKey(event: GovernorEvent): string;
+/**
+ * Create a GovernorEvent timestamp (ISO-8601 now).
+ */
+export declare function eventTimestamp(): string;
+//# sourceMappingURL=event-types.d.ts.map

package/dist/src/governor/event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../../src/governor/event-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAMxD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,sBAAsB,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,GAAG,SAAS,CAAA;IAC9B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAMD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAMvD,MAAM,MAAM,aAAa,GACrB,uBAAuB,GACvB,iBAAiB,GACjB,qBAAqB,GACrB,iBAAiB,CAAA;AAMrB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAW1D;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/src/governor/event-types.js

@@ -0,0 +1,32 @@
+/**
+ * Governor Event Types
+ *
+ * Discriminated union of events that flow through the GovernorEventBus.
+ * Events are produced by webhooks (real-time) and poll sweeps (periodic),
+ * then consumed by the EventDrivenGovernor for decision-making.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Generate a deduplication key for an event.
+ * Same issue at the same status = duplicate within the dedup window.
+ */
+export function eventDedupKey(event) {
+    switch (event.type) {
+        case 'issue-status-changed':
+            return `${event.issueId}:${event.newStatus}`;
+        case 'comment-added':
+            return `${event.issueId}:comment:${event.commentId}`;
+        case 'session-completed':
+            return `${event.issueId}:session:${event.sessionId}`;
+        case 'poll-snapshot':
+            return `${event.issueId}:${event.issue.status}`;
+    }
+}
+/**
+ * Create a GovernorEvent timestamp (ISO-8601 now).
+ */
+export function eventTimestamp() {
+    return new Date().toISOString();
+}

package/dist/src/governor/governor-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Governor Types
+ *
+ * Core type definitions for the Workflow Governor scan loop.
+ * The Governor periodically scans Linear projects and dispatches
+ * agent work based on issue status and configuration.
+ */
+import type { TopOfFunnelConfig } from './top-of-funnel.js';
+/**
+ * Actions the Governor can take for a given issue.
+ *
+ * Each action maps to an agent work type or special handling:
+ * - trigger-research: Dispatch a research agent (Icebox, sparse description)
+ * - trigger-backlog-creation: Dispatch a backlog-creation agent (Icebox, well-researched)
+ * - trigger-development: Dispatch a development agent (Backlog)
+ * - trigger-qa: Dispatch a QA agent (Finished)
+ * - trigger-acceptance: Dispatch an acceptance agent (Delivered)
+ * - trigger-refinement: Dispatch a refinement agent (Rejected)
+ * - decompose: Trigger task decomposition (escalation strategy)
+ * - escalate-human: Create a human escalation touchpoint
+ * - none: No action needed
+ */
+export type GovernorAction = 'trigger-research' | 'trigger-backlog-creation' | 'trigger-development' | 'trigger-qa' | 'trigger-acceptance' | 'trigger-refinement' | 'decompose' | 'escalate-human' | 'none';
+/**
+ * Configuration for the Workflow Governor scan loop.
+ */
+export interface GovernorConfig {
+    /** Projects to scan */
+    projects: string[];
+    /** Scan interval in milliseconds (default: 60000) */
+    scanIntervalMs: number;
+    /** Maximum concurrent dispatches per scan (default: 3) */
+    maxConcurrentDispatches: number;
+    /** Enable auto-research from Icebox (default: true) */
+    enableAutoResearch: boolean;
+    /** Enable auto-backlog-creation from Icebox (default: true) */
+    enableAutoBacklogCreation: boolean;
+    /** Enable auto-development from Backlog (default: true) */
+    enableAutoDevelopment: boolean;
+    /** Enable auto-QA from Finished (default: true) */
+    enableAutoQA: boolean;
+    /** Enable auto-acceptance from Delivered (default: true) */
+    enableAutoAcceptance: boolean;
+    /** Human response timeout in milliseconds (default: 4 hours) */
+    humanResponseTimeoutMs: number;
+    /** Top-of-funnel configuration overrides */
+    topOfFunnel?: Partial<TopOfFunnelConfig>;
+}
+/**
+ * Sensible defaults for the Governor configuration.
+ */
+export declare const DEFAULT_GOVERNOR_CONFIG: GovernorConfig;
+/**
+ * Result of a single project scan pass.
+ */
+export interface ScanResult {
+    project: string;
+    scannedIssues: number;
+    actionsDispatched: number;
+    skippedReasons: Map<string, string>;
+    errors: Array<{
+        issueId: string;
+        error: string;
+    }>;
+}
+/**
+ * Minimal issue representation used by the Governor.
+ * Intentionally decoupled from the Linear SDK types so the Governor
+ * can be tested and used with any issue source.
+ */
+export interface GovernorIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    status: string;
+    labels: string[];
+    createdAt: number;
+    parentId?: string;
+    project?: string;
+}
+//# sourceMappingURL=governor-types.d.ts.map

package/dist/src/governor/governor-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governor-types.d.ts","sourceRoot":"","sources":["../../../src/governor/governor-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAM3D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,GACrB,YAAY,GACZ,oBAAoB,GACpB,oBAAoB,GACpB,WAAW,GACX,gBAAgB,GAChB,MAAM,CAAA;AAMV;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAA;IACtB,0DAA0D;IAC1D,uBAAuB,EAAE,MAAM,CAAA;IAC/B,uDAAuD;IACvD,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,yBAAyB,EAAE,OAAO,CAAA;IAClC,2DAA2D;IAC3D,qBAAqB,EAAE,OAAO,CAAA;IAC9B,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAA;IACrB,4DAA4D;IAC5D,oBAAoB,EAAE,OAAO,CAAA;IAC7B,gEAAgE;IAChE,sBAAsB,EAAE,MAAM,CAAA;IAC9B,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACzC;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAUrC,CAAA;AAMD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD;AAMD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB"}

package/dist/src/governor/governor-types.js

@@ -0,0 +1,21 @@
+/**
+ * Governor Types
+ *
+ * Core type definitions for the Workflow Governor scan loop.
+ * The Governor periodically scans Linear projects and dispatches
+ * agent work based on issue status and configuration.
+ */
+/**
+ * Sensible defaults for the Governor configuration.
+ */
+export const DEFAULT_GOVERNOR_CONFIG = {
+    projects: [],
+    scanIntervalMs: 60_000,
+    maxConcurrentDispatches: 3,
+    enableAutoResearch: false,
+    enableAutoBacklogCreation: false,
+    enableAutoDevelopment: true,
+    enableAutoQA: true,
+    enableAutoAcceptance: true,
+    humanResponseTimeoutMs: 4 * 60 * 60 * 1000, // 4 hours
+};

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

@@ -0,0 +1,100 @@
+/**
+ * Workflow Governor
+ *
+ * Periodically scans Linear projects and dispatches agent work based on
+ * issue status and configuration. The Governor is the central scheduler
+ * that replaces webhook-driven execution with a polling-based model.
+ *
+ * The Governor is designed with dependency injection so it can be tested
+ * without any external services (Linear, Redis, etc.).
+ */
+import type { GovernorAction, GovernorConfig, GovernorIssue, ScanResult } from './governor-types.js';
+import type { OverridePriority } from './override-parser.js';
+/**
+ * Abstract dependencies that the Governor needs to interact with
+ * external systems. Callers inject these at construction time.
+ *
+ * This design keeps the Governor testable and decoupled from
+ * concrete implementations (Linear SDK, Redis, etc.).
+ */
+export interface GovernorDependencies {
+    /** List non-terminal issues for a project */
+    listIssues: (project: string) => Promise<GovernorIssue[]>;
+    /** Check if an issue has an active agent session */
+    hasActiveSession: (issueId: string) => Promise<boolean>;
+    /** Check if an issue is within cooldown (e.g., just failed QA) */
+    isWithinCooldown: (issueId: string) => Promise<boolean>;
+    /** Check if an issue is a parent (has sub-issues) */
+    isParentIssue: (issueId: string) => Promise<boolean>;
+    /** Check if an issue has a HOLD override active */
+    isHeld: (issueId: string) => Promise<boolean>;
+    /** Get the PRIORITY override for an issue (high > medium > low) */
+    getOverridePriority: (issueId: string) => Promise<OverridePriority | null>;
+    /** Get the workflow escalation strategy for an issue */
+    getWorkflowStrategy: (issueId: string) => Promise<string | undefined>;
+    /** Check if the research phase has been completed for an issue */
+    isResearchCompleted: (issueId: string) => Promise<boolean>;
+    /** Check if the backlog-creation phase has been completed for an issue */
+    isBacklogCreationCompleted: (issueId: string) => Promise<boolean>;
+    /** Count completed agent sessions for an issue (for circuit breaker) */
+    getCompletedSessionCount: (issueId: string) => Promise<number>;
+    /** Dispatch work for an issue with a specific action */
+    dispatchWork: (issue: GovernorIssue, action: GovernorAction) => Promise<void>;
+}
+/**
+ * The Workflow Governor scans projects on a configurable interval,
+ * evaluates each issue against the decision engine, and dispatches
+ * agent work for actionable issues.
+ */
+export interface WorkflowGovernorCallbacks {
+    onScanComplete?: (results: ScanResult[]) => void | Promise<void>;
+}
+export declare class WorkflowGovernor {
+    private readonly config;
+    private readonly deps;
+    private readonly callbacks;
+    private intervalHandle;
+    private running;
+    private scanning;
+    constructor(config: Partial<GovernorConfig>, deps: GovernorDependencies, callbacks?: WorkflowGovernorCallbacks);
+    /**
+     * Start the scan loop. Runs `scanOnce()` immediately, then repeats
+     * on the configured interval.
+     */
+    start(): void;
+    /**
+     * Stop the scan loop gracefully. If a scan is in progress it will
+     * finish before the Governor is fully stopped.
+     */
+    stop(): void;
+    /**
+     * Check if the Governor is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Run a single scan pass across all configured projects.
+     *
+     * For each project:
+     * 1. List all non-terminal issues
+     * 2. Gather context for each issue (active session, cooldown, etc.)
+     * 3. Run the decision engine
+     * 4. Dispatch actions up to `maxConcurrentDispatches`
+     *
+     * Returns an array of ScanResult (one per project).
+     */
+    scanOnce(): Promise<ScanResult[]>;
+    /**
+     * Scan a single project and dispatch actions.
+     *
+     * Issues are evaluated in two passes:
+     * 1. Evaluate all issues to determine actions and gather priority overrides
+     * 2. Sort actionable issues by PRIORITY override (high > medium > low > none)
+     *    and dispatch up to `maxConcurrentDispatches`
+     */
+    private scanProject;
+    /**
+     * Gather context for a single issue and run it through the decision engine.
+     */
+    private evaluateIssue;
+}
+//# sourceMappingURL=governor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../../src/governor/governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACb,UAAU,EACX,MAAM,qBAAqB,CAAA;AAG5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAsC5D;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;IACzD,oDAAoD;IACpD,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACvD,kEAAkE;IAClE,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACvD,qDAAqD;IACrD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACpD,mDAAmD;IACnD,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7C,mEAAmE;IACnE,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAC1E,wDAAwD;IACxD,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACrE,kEAAkE;IAClE,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1D,0EAA0E;IAC1E,0BAA0B,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACjE,wEAAwE;IACxE,wBAAwB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9D,wDAAwD;IACxD,YAAY,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9E;AAMD;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjE;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,SAAS,CAAC,EAAE,yBAAyB;IAU9G;;;OAGG;IACH,KAAK,IAAI,IAAI;IAuBb;;;OAGG;IACH,IAAI,IAAI,IAAI;IAgBZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAQpB;;;;;;;;;;OAUG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IA4BvC;;;;;;;OAOG;YACW,WAAW;IA2GzB;;OAEG;YACW,aAAa;CAqC5B"}

package/dist/src/governor/governor.js

@@ -0,0 +1,262 @@
+/**
+ * Workflow Governor
+ *
+ * Periodically scans Linear projects and dispatches agent work based on
+ * issue status and configuration. The Governor is the central scheduler
+ * that replaces webhook-driven execution with a polling-based model.
+ *
+ * The Governor is designed with dependency injection so it can be tested
+ * without any external services (Linear, Redis, etc.).
+ */
+import { DEFAULT_GOVERNOR_CONFIG } from './governor-types.js';
+import { decideAction } from './decision-engine.js';
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+const log = {
+    info: (msg, data) => console.log(`[governor] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[governor] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[governor] ${msg}`, data ? JSON.stringify(data) : ''),
+    debug: (_msg, _data) => { },
+};
+// ---------------------------------------------------------------------------
+// Priority ordering
+// ---------------------------------------------------------------------------
+/** Map priority to a sort weight (lower = higher priority = dispatched first) */
+function priorityWeight(priority) {
+    switch (priority) {
+        case 'high':
+            return 0;
+        case 'medium':
+            return 1;
+        case 'low':
+            return 2;
+        default:
+            return 3;
+    }
+}
+export class WorkflowGovernor {
+    config;
+    deps;
+    callbacks;
+    intervalHandle = null;
+    running = false;
+    scanning = false;
+    constructor(config, deps, callbacks) {
+        this.config = { ...DEFAULT_GOVERNOR_CONFIG, ...config };
+        this.deps = deps;
+        this.callbacks = callbacks ?? {};
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Start the scan loop. Runs `scanOnce()` immediately, then repeats
+     * on the configured interval.
+     */
+    start() {
+        if (this.running) {
+            log.warn('Governor is already running');
+            return;
+        }
+        this.running = true;
+        log.info('Governor started', {
+            projects: this.config.projects,
+            scanIntervalMs: this.config.scanIntervalMs,
+            maxConcurrentDispatches: this.config.maxConcurrentDispatches,
+        });
+        // Run the first scan immediately (fire and forget — errors logged internally)
+        void this.scanOnce();
+        // Schedule subsequent scans
+        this.intervalHandle = setInterval(() => {
+            void this.scanOnce();
+        }, this.config.scanIntervalMs);
+    }
+    /**
+     * Stop the scan loop gracefully. If a scan is in progress it will
+     * finish before the Governor is fully stopped.
+     */
+    stop() {
+        if (!this.running) {
+            log.warn('Governor is not running');
+            return;
+        }
+        this.running = false;
+        if (this.intervalHandle !== null) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = null;
+        }
+        log.info('Governor stopped');
+    }
+    /**
+     * Check if the Governor is running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    // -------------------------------------------------------------------------
+    // Scan
+    // -------------------------------------------------------------------------
+    /**
+     * Run a single scan pass across all configured projects.
+     *
+     * For each project:
+     * 1. List all non-terminal issues
+     * 2. Gather context for each issue (active session, cooldown, etc.)
+     * 3. Run the decision engine
+     * 4. Dispatch actions up to `maxConcurrentDispatches`
+     *
+     * Returns an array of ScanResult (one per project).
+     */
+    async scanOnce() {
+        // Guard against overlapping scans
+        if (this.scanning) {
+            log.debug('Scan already in progress, skipping');
+            return [];
+        }
+        this.scanning = true;
+        const results = [];
+        try {
+            for (const project of this.config.projects) {
+                const result = await this.scanProject(project);
+                results.push(result);
+            }
+        }
+        finally {
+            this.scanning = false;
+        }
+        await this.callbacks.onScanComplete?.(results);
+        return results;
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    /**
+     * Scan a single project and dispatch actions.
+     *
+     * Issues are evaluated in two passes:
+     * 1. Evaluate all issues to determine actions and gather priority overrides
+     * 2. Sort actionable issues by PRIORITY override (high > medium > low > none)
+     *    and dispatch up to `maxConcurrentDispatches`
+     */
+    async scanProject(project) {
+        const result = {
+            project,
+            scannedIssues: 0,
+            actionsDispatched: 0,
+            skippedReasons: new Map(),
+            errors: [],
+        };
+        let issues;
+        try {
+            issues = await this.deps.listIssues(project);
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            log.error('Failed to list issues for project', { project, error: errorMsg });
+            result.errors.push({ issueId: `project:${project}`, error: errorMsg });
+            return result;
+        }
+        result.scannedIssues = issues.length;
+        log.info('Scanning project', {
+            project,
+            issueCount: issues.length,
+        });
+        // Pass 1: Evaluate all issues and gather priority overrides
+        const actionable = [];
+        for (const issue of issues) {
+            try {
+                const [decision, priority] = await Promise.all([
+                    this.evaluateIssue(issue),
+                    this.deps.getOverridePriority(issue.id),
+                ]);
+                if (decision.action === 'none') {
+                    result.skippedReasons.set(issue.identifier, decision.reason);
+                    continue;
+                }
+                actionable.push({
+                    issue,
+                    action: decision.action,
+                    reason: decision.reason,
+                    priority,
+                });
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                log.error('Error evaluating issue', {
+                    issueIdentifier: issue.identifier,
+                    error: errorMsg,
+                });
+                result.errors.push({ issueId: issue.identifier, error: errorMsg });
+            }
+        }
+        // Pass 2: Sort by priority override (high > medium > low > none)
+        actionable.sort((a, b) => priorityWeight(a.priority) - priorityWeight(b.priority));
+        // Pass 3: Dispatch up to the limit
+        for (const item of actionable) {
+            if (result.actionsDispatched >= this.config.maxConcurrentDispatches) {
+                log.info('Dispatch limit reached', {
+                    project,
+                    limit: this.config.maxConcurrentDispatches,
+                    dispatched: result.actionsDispatched,
+                });
+                break;
+            }
+            try {
+                await this.deps.dispatchWork(item.issue, item.action);
+                result.actionsDispatched++;
+                log.info('Dispatched action', {
+                    issueIdentifier: item.issue.identifier,
+                    action: item.action,
+                    reason: item.reason,
+                    priority: item.priority ?? 'none',
+                });
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                log.error('Error dispatching issue', {
+                    issueIdentifier: item.issue.identifier,
+                    error: errorMsg,
+                });
+                result.errors.push({ issueId: item.issue.identifier, error: errorMsg });
+            }
+        }
+        log.info('Project scan complete', {
+            project,
+            scanned: result.scannedIssues,
+            dispatched: result.actionsDispatched,
+            skipped: result.skippedReasons.size,
+            errors: result.errors.length,
+        });
+        return result;
+    }
+    /**
+     * Gather context for a single issue and run it through the decision engine.
+     */
+    async evaluateIssue(issue) {
+        // Gather all context in parallel for efficiency
+        const [hasActiveSession, isWithinCooldown, isParentIssue, isHeld, workflowStrategy, researchCompleted, backlogCreationCompleted, completedSessionCount,] = await Promise.all([
+            this.deps.hasActiveSession(issue.id),
+            this.deps.isWithinCooldown(issue.id),
+            this.deps.isParentIssue(issue.id),
+            this.deps.isHeld(issue.id),
+            this.deps.getWorkflowStrategy(issue.id),
+            this.deps.isResearchCompleted(issue.id),
+            this.deps.isBacklogCreationCompleted(issue.id),
+            this.deps.getCompletedSessionCount(issue.id),
+        ]);
+        const ctx = {
+            issue,
+            config: this.config,
+            hasActiveSession,
+            isHeld,
+            isWithinCooldown,
+            isParentIssue,
+            workflowStrategy,
+            researchCompleted,
+            backlogCreationCompleted,
+            completedSessionCount,
+        };
+        return decideAction(ctx);
+    }
+}

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

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

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

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