@renseiai/agentfactory 0.8.0

package/dist/src/governor/platform-adapter.js

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export {};

package/dist/src/governor/processing-state.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Processing State Tracker
+ *
+ * Tracks which top-of-funnel processing phases have been completed for each
+ * issue to prevent re-processing. The core package defines the types and the
+ * storage adapter interface; concrete implementations live in packages/server
+ * (e.g., RedisProcessingStateStorage).
+ */
+/**
+ * Processing phases tracked by the top-of-funnel governor.
+ */
+export type ProcessingPhase = 'research' | 'backlog-creation';
+/**
+ * Record of a completed processing phase for an issue.
+ */
+export interface ProcessingRecord {
+    issueId: string;
+    phase: ProcessingPhase;
+    completedAt: number;
+    sessionId?: string;
+}
+/**
+ * Storage adapter for persisting processing state.
+ *
+ * Implementations must be idempotent — calling `markPhaseCompleted` twice
+ * for the same issue+phase is a no-op (overwrites with the latest data).
+ *
+ * See `RedisProcessingStateStorage` in `packages/server` for the Redis-backed
+ * implementation.
+ */
+export interface ProcessingStateStorage {
+    /**
+     * Check whether a given phase has already been completed for an issue.
+     */
+    isPhaseCompleted(issueId: string, phase: ProcessingPhase): Promise<boolean>;
+    /**
+     * Mark a phase as completed for an issue.
+     * If the phase was already marked, this overwrites the record.
+     */
+    markPhaseCompleted(issueId: string, phase: ProcessingPhase, sessionId?: string): Promise<void>;
+    /**
+     * Clear a phase completion record for an issue.
+     * Useful when an issue is re-opened or moved back to Icebox.
+     */
+    clearPhase(issueId: string, phase: ProcessingPhase): Promise<void>;
+    /**
+     * Retrieve the processing record for a phase, if it exists.
+     */
+    getPhaseRecord(issueId: string, phase: ProcessingPhase): Promise<ProcessingRecord | null>;
+}
+/**
+ * Simple in-memory implementation of `ProcessingStateStorage`.
+ * Suitable for tests and single-process local development; not shared across
+ * processes.
+ */
+export declare class InMemoryProcessingStateStorage implements ProcessingStateStorage {
+    private store;
+    private key;
+    isPhaseCompleted(issueId: string, phase: ProcessingPhase): Promise<boolean>;
+    markPhaseCompleted(issueId: string, phase: ProcessingPhase, sessionId?: string): Promise<void>;
+    clearPhase(issueId: string, phase: ProcessingPhase): Promise<void>;
+    getPhaseRecord(issueId: string, phase: ProcessingPhase): Promise<ProcessingRecord | null>;
+    /** Clear all records (useful in tests). */
+    clear(): void;
+}
+//# sourceMappingURL=processing-state.d.ts.map

package/dist/src/governor/processing-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing-state.d.ts","sourceRoot":"","sources":["../../../src/governor/processing-state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,kBAAkB,CAAA;AAE7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,eAAe,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE3E;;;OAGG;IACH,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElE;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CACpC;AAMD;;;;GAIG;AACH,qBAAa,8BAA+B,YAAW,sBAAsB;IAC3E,OAAO,CAAC,KAAK,CAAsC;IAEnD,OAAO,CAAC,GAAG;IAIL,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,OAAO,CAAC;IAIb,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IASV,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAInC,2CAA2C;IAC3C,KAAK,IAAI,IAAI;CAGd"}

package/dist/src/governor/processing-state.js

@@ -0,0 +1,43 @@
+/**
+ * Processing State Tracker
+ *
+ * Tracks which top-of-funnel processing phases have been completed for each
+ * issue to prevent re-processing. The core package defines the types and the
+ * storage adapter interface; concrete implementations live in packages/server
+ * (e.g., RedisProcessingStateStorage).
+ */
+// ---------------------------------------------------------------------------
+// In-memory implementation (for testing and local development)
+// ---------------------------------------------------------------------------
+/**
+ * Simple in-memory implementation of `ProcessingStateStorage`.
+ * Suitable for tests and single-process local development; not shared across
+ * processes.
+ */
+export class InMemoryProcessingStateStorage {
+    store = new Map();
+    key(issueId, phase) {
+        return `${issueId}:${phase}`;
+    }
+    async isPhaseCompleted(issueId, phase) {
+        return this.store.has(this.key(issueId, phase));
+    }
+    async markPhaseCompleted(issueId, phase, sessionId) {
+        this.store.set(this.key(issueId, phase), {
+            issueId,
+            phase,
+            completedAt: Date.now(),
+            sessionId,
+        });
+    }
+    async clearPhase(issueId, phase) {
+        this.store.delete(this.key(issueId, phase));
+    }
+    async getPhaseRecord(issueId, phase) {
+        return this.store.get(this.key(issueId, phase)) ?? null;
+    }
+    /** Clear all records (useful in tests). */
+    clear() {
+        this.store.clear();
+    }
+}

package/dist/src/governor/processing-state.test.d.ts

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

package/dist/src/governor/processing-state.test.d.ts.map

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

package/dist/src/governor/processing-state.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryProcessingStateStorage, } from './processing-state.js';
+// ---------------------------------------------------------------------------
+// ProcessingStateStorage interface contract tests
+// ---------------------------------------------------------------------------
+// These tests exercise the interface through the InMemoryProcessingStateStorage
+// implementation but validate the contract that any implementation must honour.
+describe('ProcessingStateStorage (InMemoryProcessingStateStorage)', () => {
+    let storage;
+    beforeEach(() => {
+        storage = new InMemoryProcessingStateStorage();
+    });
+    // -- isPhaseCompleted --
+    it('returns false for a phase that has not been completed', async () => {
+        const completed = await storage.isPhaseCompleted('issue-1', 'research');
+        expect(completed).toBe(false);
+    });
+    it('returns true after marking a phase as completed', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research');
+        const completed = await storage.isPhaseCompleted('issue-1', 'research');
+        expect(completed).toBe(true);
+    });
+    // -- markPhaseCompleted --
+    it('records a phase completion with optional sessionId', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research', 'session-abc');
+        const record = await storage.getPhaseRecord('issue-1', 'research');
+        expect(record).not.toBeNull();
+        expect(record.issueId).toBe('issue-1');
+        expect(record.phase).toBe('research');
+        expect(record.sessionId).toBe('session-abc');
+        expect(record.completedAt).toBeGreaterThan(0);
+    });
+    it('is idempotent — re-marking overwrites the record', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research', 'session-1');
+        const first = await storage.getPhaseRecord('issue-1', 'research');
+        await storage.markPhaseCompleted('issue-1', 'research', 'session-2');
+        const second = await storage.getPhaseRecord('issue-1', 'research');
+        expect(second.sessionId).toBe('session-2');
+        expect(second.completedAt).toBeGreaterThanOrEqual(first.completedAt);
+    });
+    // -- clearPhase --
+    it('clears a completed phase', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research');
+        expect(await storage.isPhaseCompleted('issue-1', 'research')).toBe(true);
+        await storage.clearPhase('issue-1', 'research');
+        expect(await storage.isPhaseCompleted('issue-1', 'research')).toBe(false);
+    });
+    it('clearing an already-absent phase is a no-op', async () => {
+        // Should not throw
+        await storage.clearPhase('issue-1', 'research');
+        expect(await storage.isPhaseCompleted('issue-1', 'research')).toBe(false);
+    });
+    // -- getPhaseRecord --
+    it('returns null for an absent record', async () => {
+        const record = await storage.getPhaseRecord('issue-1', 'backlog-creation');
+        expect(record).toBeNull();
+    });
+    it('returns the stored record', async () => {
+        await storage.markPhaseCompleted('issue-1', 'backlog-creation', 'sess-x');
+        const record = await storage.getPhaseRecord('issue-1', 'backlog-creation');
+        expect(record).toEqual(expect.objectContaining({
+            issueId: 'issue-1',
+            phase: 'backlog-creation',
+            sessionId: 'sess-x',
+        }));
+    });
+    // -- Phase isolation --
+    it('different phases for the same issue are independent', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research');
+        expect(await storage.isPhaseCompleted('issue-1', 'research')).toBe(true);
+        expect(await storage.isPhaseCompleted('issue-1', 'backlog-creation')).toBe(false);
+    });
+    it('same phase for different issues are independent', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research');
+        expect(await storage.isPhaseCompleted('issue-1', 'research')).toBe(true);
+        expect(await storage.isPhaseCompleted('issue-2', 'research')).toBe(false);
+    });
+    // -- All phases --
+    it('supports both defined processing phases', async () => {
+        const phases = ['research', 'backlog-creation'];
+        for (const phase of phases) {
+            await storage.markPhaseCompleted('issue-x', phase, `sess-${phase}`);
+            expect(await storage.isPhaseCompleted('issue-x', phase)).toBe(true);
+            const record = await storage.getPhaseRecord('issue-x', phase);
+            expect(record.phase).toBe(phase);
+        }
+    });
+    // -- InMemory-specific: clear all --
+    it('clear() removes all records', async () => {
+        await storage.markPhaseCompleted('issue-1', 'research');
+        await storage.markPhaseCompleted('issue-2', 'backlog-creation');
+        storage.clear();
+        expect(await storage.isPhaseCompleted('issue-1', 'research')).toBe(false);
+        expect(await storage.isPhaseCompleted('issue-2', 'backlog-creation')).toBe(false);
+    });
+});

package/dist/src/governor/top-of-funnel.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Top-of-Funnel Triggers
+ *
+ * Heuristics and trigger logic for auto-research and auto-backlog-creation.
+ * Issues in "Icebox" are evaluated to determine whether they need research
+ * (fleshing out requirements, acceptance criteria, technical approach) or
+ * are already well-researched and ready for backlog creation (decomposition
+ * into sub-issues, estimation, etc.).
+ *
+ * All functions are pure — no side effects, no network calls.
+ */
+/**
+ * Configuration for the top-of-funnel governor heuristics.
+ */
+export interface TopOfFunnelConfig {
+    /** Minimum time in Icebox before triggering research (ms). Default: 1 hour */
+    iceboxResearchDelayMs: number;
+    /** Minimum description length to consider "well-researched". Default: 200 */
+    minResearchedDescriptionLength: number;
+    /** Headers that indicate a well-researched issue */
+    researchedHeaders: string[];
+    /** Labels that explicitly request research */
+    researchRequestLabels: string[];
+    /** Whether auto-research is enabled. Default: true */
+    enableAutoResearch: boolean;
+    /** Whether auto-backlog-creation is enabled. Default: true */
+    enableAutoBacklogCreation: boolean;
+}
+/**
+ * Sensible defaults for the top-of-funnel configuration.
+ */
+export declare const DEFAULT_TOP_OF_FUNNEL_CONFIG: TopOfFunnelConfig;
+/**
+ * Minimal issue information needed by the top-of-funnel evaluator.
+ */
+export interface IssueInfo {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    status: string;
+    labels: string[];
+    createdAt: number;
+    parentId?: string;
+}
+/**
+ * Discriminated union describing the action the governor should take for an
+ * Icebox issue.
+ */
+export type TopOfFunnelAction = {
+    type: 'trigger-research';
+    issueId: string;
+    reason: string;
+} | {
+    type: 'trigger-backlog-creation';
+    issueId: string;
+    reason: string;
+} | {
+    type: 'none';
+    issueId: string;
+    reason: string;
+};
+/**
+ * External state the caller supplies so the evaluator can avoid re-processing.
+ */
+export interface TopOfFunnelContext {
+    /** Whether there is already an active agent session for this issue */
+    hasActiveSession: boolean;
+    /** Whether the issue is held (e.g., awaiting human input) */
+    isHeld: boolean;
+    /** Whether the research phase was already completed */
+    researchCompleted: boolean;
+    /** Whether the backlog-creation phase was already completed */
+    backlogCreationCompleted: boolean;
+    /** Whether the issue is a parent/coordinator issue */
+    isParentIssue: boolean;
+}
+/**
+ * Check whether an issue description appears well-researched.
+ *
+ * Heuristic:
+ *  - The description must meet a minimum character length **and**
+ *  - Contain at least one of the recognised structured headers.
+ */
+export declare function isWellResearched(description: string | undefined, config?: TopOfFunnelConfig): boolean;
+/**
+ * Check whether an issue needs research.
+ *
+ * Criteria (all must hold):
+ *  1. Issue is in "Icebox" status
+ *  2. Description is **not** well-researched (short / missing headers) **or**
+ *     the issue carries a research-request label
+ *  3. The issue has been in Icebox for longer than the configured delay
+ *  4. The issue is not a parent/coordinator issue
+ *
+ * Note: active-session and hold checks are done in `determineTopOfFunnelAction`
+ * so that callers who just want the heuristic can use this function standalone.
+ */
+export declare function needsResearch(issue: IssueInfo, config?: TopOfFunnelConfig): boolean;
+/**
+ * Check whether an issue is ready for backlog creation.
+ *
+ * Criteria (all must hold):
+ *  1. Issue is in "Icebox" status
+ *  2. Description **is** well-researched (meets length + header heuristic)
+ *  3. The issue is not a parent/coordinator issue
+ *
+ * The `researchCompleted` flag is checked in `determineTopOfFunnelAction`.
+ */
+export declare function isReadyForBacklogCreation(issue: IssueInfo, config?: TopOfFunnelConfig): boolean;
+/**
+ * Determine the top-of-funnel action for an Icebox issue.
+ *
+ * Uses workflow / processing state to avoid re-processing issues that have
+ * already been through research or backlog creation.
+ */
+export declare function determineTopOfFunnelAction(issue: IssueInfo, config: TopOfFunnelConfig, context: TopOfFunnelContext): TopOfFunnelAction;
+//# sourceMappingURL=top-of-funnel.d.ts.map

package/dist/src/governor/top-of-funnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"top-of-funnel.d.ts","sourceRoot":"","sources":["../../../src/governor/top-of-funnel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,qBAAqB,EAAE,MAAM,CAAA;IAC7B,6EAA6E;IAC7E,8BAA8B,EAAE,MAAM,CAAA;IACtC,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,8CAA8C;IAC9C,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,sDAAsD;IACtD,kBAAkB,EAAE,OAAO,CAAA;IAC3B,8DAA8D;IAC9D,yBAAyB,EAAE,OAAO,CAAA;CACnC;AAED;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,iBAa1C,CAAA;AAMD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,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;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAMrD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAA;IACzB,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAA;IACf,uDAAuD;IACvD,iBAAiB,EAAE,OAAO,CAAA;IAC1B,+DAA+D;IAC/D,wBAAwB,EAAE,OAAO,CAAA;IACjC,sDAAsD;IACtD,aAAa,EAAE,OAAO,CAAA;CACvB;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,GAAE,iBAAgD,GACvD,OAAO,CAWT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,EAChB,MAAM,GAAE,iBAAgD,GACvD,OAAO,CAiBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,EAChB,MAAM,GAAE,iBAAgD,GACvD,OAAO,CAOT;AAMD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CA0FnB"}

package/dist/src/governor/top-of-funnel.js

@@ -0,0 +1,168 @@
+/**
+ * Top-of-Funnel Triggers
+ *
+ * Heuristics and trigger logic for auto-research and auto-backlog-creation.
+ * Issues in "Icebox" are evaluated to determine whether they need research
+ * (fleshing out requirements, acceptance criteria, technical approach) or
+ * are already well-researched and ready for backlog creation (decomposition
+ * into sub-issues, estimation, etc.).
+ *
+ * All functions are pure — no side effects, no network calls.
+ */
+/**
+ * Sensible defaults for the top-of-funnel configuration.
+ */
+export const DEFAULT_TOP_OF_FUNNEL_CONFIG = {
+    iceboxResearchDelayMs: 60 * 60 * 1000, // 1 hour
+    minResearchedDescriptionLength: 200,
+    researchedHeaders: [
+        '## Acceptance Criteria',
+        '## Technical Approach',
+        '## Summary',
+        '## Design',
+        '## Requirements',
+    ],
+    researchRequestLabels: ['Needs Research'],
+    enableAutoResearch: false,
+    enableAutoBacklogCreation: false,
+};
+// ---------------------------------------------------------------------------
+// Pure evaluation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Check whether an issue description appears well-researched.
+ *
+ * Heuristic:
+ *  - The description must meet a minimum character length **and**
+ *  - Contain at least one of the recognised structured headers.
+ */
+export function isWellResearched(description, config = DEFAULT_TOP_OF_FUNNEL_CONFIG) {
+    if (!description)
+        return false;
+    const meetsLengthThreshold = description.length >= config.minResearchedDescriptionLength;
+    const hasStructuredHeader = config.researchedHeaders.some((header) => description.includes(header));
+    return meetsLengthThreshold && hasStructuredHeader;
+}
+/**
+ * Check whether an issue needs research.
+ *
+ * Criteria (all must hold):
+ *  1. Issue is in "Icebox" status
+ *  2. Description is **not** well-researched (short / missing headers) **or**
+ *     the issue carries a research-request label
+ *  3. The issue has been in Icebox for longer than the configured delay
+ *  4. The issue is not a parent/coordinator issue
+ *
+ * Note: active-session and hold checks are done in `determineTopOfFunnelAction`
+ * so that callers who just want the heuristic can use this function standalone.
+ */
+export function needsResearch(issue, config = DEFAULT_TOP_OF_FUNNEL_CONFIG) {
+    if (issue.status !== 'Icebox')
+        return false;
+    // Parent issues use coordination, not individual research
+    if (issue.parentId !== undefined)
+        return false;
+    const ageMs = Date.now() - issue.createdAt;
+    if (ageMs < config.iceboxResearchDelayMs)
+        return false;
+    // Explicit research-request label always triggers research
+    const hasResearchLabel = issue.labels.some((label) => config.researchRequestLabels.includes(label));
+    if (hasResearchLabel)
+        return true;
+    // Otherwise, only if the description is not well-researched
+    return !isWellResearched(issue.description, config);
+}
+/**
+ * Check whether an issue is ready for backlog creation.
+ *
+ * Criteria (all must hold):
+ *  1. Issue is in "Icebox" status
+ *  2. Description **is** well-researched (meets length + header heuristic)
+ *  3. The issue is not a parent/coordinator issue
+ *
+ * The `researchCompleted` flag is checked in `determineTopOfFunnelAction`.
+ */
+export function isReadyForBacklogCreation(issue, config = DEFAULT_TOP_OF_FUNNEL_CONFIG) {
+    if (issue.status !== 'Icebox')
+        return false;
+    // Parent issues use coordination, not individual backlog creation
+    if (issue.parentId !== undefined)
+        return false;
+    return isWellResearched(issue.description, config);
+}
+// ---------------------------------------------------------------------------
+// Main decision function
+// ---------------------------------------------------------------------------
+/**
+ * Determine the top-of-funnel action for an Icebox issue.
+ *
+ * Uses workflow / processing state to avoid re-processing issues that have
+ * already been through research or backlog creation.
+ */
+export function determineTopOfFunnelAction(issue, config, context) {
+    const none = (reason) => ({
+        type: 'none',
+        issueId: issue.id,
+        reason,
+    });
+    // --- Guard rails ---
+    if (issue.status !== 'Icebox') {
+        return none('Issue is not in Icebox status');
+    }
+    if (context.hasActiveSession) {
+        return none('Issue already has an active agent session');
+    }
+    if (context.isHeld) {
+        return none('Issue is held (awaiting human input)');
+    }
+    if (context.isParentIssue) {
+        return none('Parent/coordinator issues are handled via coordination workflow');
+    }
+    // --- Research evaluation ---
+    if (config.enableAutoResearch && !context.researchCompleted) {
+        const hasResearchLabel = issue.labels.some((label) => config.researchRequestLabels.includes(label));
+        const descriptionNeedsResearch = !isWellResearched(issue.description, config);
+        if (hasResearchLabel || descriptionNeedsResearch) {
+            const ageMs = Date.now() - issue.createdAt;
+            if (ageMs >= config.iceboxResearchDelayMs) {
+                const reason = hasResearchLabel
+                    ? `Issue has research-request label: ${issue.labels.filter((l) => config.researchRequestLabels.includes(l)).join(', ')}`
+                    : 'Issue description lacks sufficient detail or structured headers';
+                return {
+                    type: 'trigger-research',
+                    issueId: issue.id,
+                    reason,
+                };
+            }
+            return none(`Issue needs research but has not been in Icebox long enough (${Math.round(ageMs / 1000)}s < ${Math.round(config.iceboxResearchDelayMs / 1000)}s)`);
+        }
+    }
+    if (!config.enableAutoResearch && !context.researchCompleted) {
+        // Auto-research is disabled; if the description is sparse we still skip
+        // backlog creation since research hasn't been done.
+        if (!isWellResearched(issue.description, config)) {
+            return none('Auto-research is disabled and issue description is not well-researched');
+        }
+    }
+    // --- Backlog-creation evaluation ---
+    if (config.enableAutoBacklogCreation && !context.backlogCreationCompleted) {
+        if (isWellResearched(issue.description, config)) {
+            return {
+                type: 'trigger-backlog-creation',
+                issueId: issue.id,
+                reason: 'Issue is well-researched and ready for backlog creation',
+            };
+        }
+    }
+    // --- Fallthrough ---
+    if (context.researchCompleted && context.backlogCreationCompleted) {
+        return none('Both research and backlog-creation phases already completed');
+    }
+    if (context.backlogCreationCompleted) {
+        return none('Backlog-creation phase already completed');
+    }
+    if (!config.enableAutoBacklogCreation) {
+        return none('Auto-backlog-creation is disabled');
+    }
+    return none('No top-of-funnel action needed');
+}

package/dist/src/governor/top-of-funnel.test.d.ts

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

package/dist/src/governor/top-of-funnel.test.d.ts.map

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