@lumenflow/agent 1.0.0

package/dist/feedback-promote-core.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Feedback Promote Core Logic (WU-1599)
+ *
+ * Generates draft WU specs from feedback patterns and promotes them to actual WUs.
+ * Tracks incident-to-WU mappings in feedback-index.ndjson.
+ *
+ * @see {@link tools/__tests__/feedback-promote.test.mjs} - Tests
+ * @see {@link tools/feedback-promote.mjs} - CLI entry point
+ */
+/**
+ * Directory for draft WU specs
+ */
+export declare const DRAFT_DIRECTORY = ".beacon/feedback-drafts";
+/**
+ * Path to feedback index (incident-to-WU mappings)
+ */
+export declare const FEEDBACK_INDEX_PATH = ".beacon/feedback-index.ndjson";
+/**
+ * Feedback index entry status
+ */
+export declare const FEEDBACK_STATUS: {
+    PENDING_RESOLUTION: string;
+    RESOLVED: string;
+    WONT_FIX: string;
+};
+/**
+ * Pattern example structure
+ */
+interface PatternExample {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * Pattern structure from feedback:review
+ */
+interface Pattern {
+    title: string;
+    category?: string;
+    frequency?: number;
+    score?: number;
+    firstSeen?: string;
+    lastSeen?: string;
+    examples?: PatternExample[];
+}
+/**
+ * Draft WU spec structure
+ */
+interface DraftSpec {
+    title: string;
+    lane: string;
+    description: string;
+    acceptance: string[];
+    source_incidents: string[];
+    pattern_metadata: {
+        frequency: number | undefined;
+        category: string | undefined;
+        score: number | undefined;
+        firstSeen: string | undefined;
+        lastSeen: string | undefined;
+    };
+    filePath?: string;
+}
+/**
+ * Options for generating a draft
+ */
+interface GenerateDraftOptions {
+    writeFile?: boolean;
+}
+/**
+ * Generate draft WU spec from a pattern
+ *
+ * @param baseDir - Base directory
+ * @param pattern - Pattern from feedback:review
+ * @param options - Options
+ * @returns Draft WU spec
+ */
+export declare function generateDraft(baseDir: string, pattern: Pattern, options?: GenerateDraftOptions): Promise<DraftSpec>;
+/**
+ * Load all draft files from .beacon/feedback-drafts/
+ *
+ * @param baseDir - Base directory
+ * @returns Array of draft objects with filePath
+ */
+export declare function loadDrafts(baseDir: string): Promise<DraftSpec[]>;
+/**
+ * Options for promoting a draft
+ */
+interface PromoteDraftOptions {
+    dryRun?: boolean;
+    wuIdOverride?: string;
+    removeDraft?: boolean;
+}
+/**
+ * Result of promoting a draft
+ */
+interface PromoteDraftResult {
+    success: boolean;
+    wuId: string;
+    command: string;
+    draft?: DraftSpec;
+    error?: string;
+    draftRemoved?: boolean;
+}
+/**
+ * Promote a draft to a WU via wu:create
+ *
+ * @param baseDir - Base directory
+ * @param draft - Draft object
+ * @param options - Options
+ * @returns Result with success, wuId, command
+ */
+export declare function promoteDraft(baseDir: string, draft: DraftSpec, options?: PromoteDraftOptions): Promise<PromoteDraftResult>;
+/**
+ * Feedback index entry
+ */
+interface FeedbackIndexEntry {
+    incident_id: string;
+    wu_id: string;
+    status: string;
+    timestamp: string;
+}
+/**
+ * Update feedback index with incident-to-WU mappings
+ *
+ * @param baseDir - Base directory
+ * @param wuId - WU ID
+ * @param incidentIds - Array of incident IDs
+ */
+export declare function updateFeedbackIndex(baseDir: string, wuId: string, incidentIds: string[]): Promise<void>;
+/**
+ * Load feedback index entries
+ *
+ * @param baseDir - Base directory
+ * @returns Array of index entries
+ */
+export declare function loadFeedbackIndex(baseDir: string): Promise<FeedbackIndexEntry[]>;
+export {};

package/dist/feedback-promote-core.js

@@ -0,0 +1,337 @@
+/**
+ * Feedback Promote Core Logic (WU-1599)
+ *
+ * Generates draft WU specs from feedback patterns and promotes them to actual WUs.
+ * Tracks incident-to-WU mappings in feedback-index.ndjson.
+ *
+ * @see {@link tools/__tests__/feedback-promote.test.mjs} - Tests
+ * @see {@link tools/feedback-promote.mjs} - CLI entry point
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { stringifyYAML, parseYAML } from '@lumenflow/core/lib/wu-yaml.js';
+/**
+ * Directory for draft WU specs
+ */
+export const DRAFT_DIRECTORY = '.beacon/feedback-drafts';
+/**
+ * Path to feedback index (incident-to-WU mappings)
+ */
+export const FEEDBACK_INDEX_PATH = '.beacon/feedback-index.ndjson';
+/**
+ * Feedback index entry status
+ */
+export const FEEDBACK_STATUS = {
+    PENDING_RESOLUTION: 'pending_resolution',
+    RESOLVED: 'resolved',
+    WONT_FIX: 'wont_fix',
+};
+/**
+ * Lane constants for DRY compliance
+ */
+const LANES = {
+    OPERATIONS_TOOLING: 'Operations: Tooling',
+    OPERATIONS_DOCUMENTATION: 'Operations: Documentation',
+    OPERATIONS_SECURITY: 'Operations: Security',
+    OPERATIONS_COMPLIANCE: 'Operations: Compliance',
+    OPERATIONS: 'Operations',
+    CORE_SYSTEMS: 'Core Systems',
+    EXPERIENCE: 'Experience',
+    INTELLIGENCE: 'Intelligence',
+};
+/**
+ * Lane inference mapping from category to suggested lane
+ */
+const CATEGORY_TO_LANE = {
+    test: LANES.OPERATIONS_TOOLING,
+    tooling: LANES.OPERATIONS_TOOLING,
+    docs: LANES.OPERATIONS_DOCUMENTATION,
+    documentation: LANES.OPERATIONS_DOCUMENTATION,
+    infrastructure: LANES.CORE_SYSTEMS,
+    database: LANES.CORE_SYSTEMS,
+    api: LANES.CORE_SYSTEMS,
+    ui: LANES.EXPERIENCE,
+    frontend: LANES.EXPERIENCE,
+    ux: LANES.EXPERIENCE,
+    llm: LANES.INTELLIGENCE,
+    prompt: LANES.INTELLIGENCE,
+    ai: LANES.INTELLIGENCE,
+    security: LANES.OPERATIONS_SECURITY,
+    compliance: LANES.OPERATIONS_COMPLIANCE,
+    uncategorized: LANES.OPERATIONS,
+};
+/**
+ * Infer lane from pattern category
+ *
+ * @param category - Pattern category
+ * @returns Suggested lane
+ */
+function inferLane(category) {
+    const normalizedCategory = (category ?? 'uncategorized').toLowerCase();
+    // Safe lookup using Object.hasOwn to prevent prototype pollution
+    if (Object.hasOwn(CATEGORY_TO_LANE, normalizedCategory)) {
+        // eslint-disable-next-line security/detect-object-injection -- Safe: hasOwn validates key exists
+        return CATEGORY_TO_LANE[normalizedCategory];
+    }
+    return CATEGORY_TO_LANE.uncategorized;
+}
+/**
+ * Generate description from pattern
+ *
+ * @param pattern - Pattern object
+ * @returns Description with Context/Problem/Solution structure
+ */
+function generateDescription(pattern) {
+    const frequency = pattern.frequency ?? 1;
+    const category = pattern.category ?? 'uncategorized';
+    const firstSeen = pattern.firstSeen
+        ? new Date(pattern.firstSeen).toISOString().slice(0, 10)
+        : 'unknown';
+    const lastSeen = pattern.lastSeen
+        ? new Date(pattern.lastSeen).toISOString().slice(0, 10)
+        : 'unknown';
+    return [
+        `Context: Pattern detected from ${frequency} incident(s) in category "${category}". First seen: ${firstSeen}, last seen: ${lastSeen}.`,
+        '',
+        `Problem: ${pattern.title}`,
+        '',
+        'Solution: [To be defined by implementer]',
+    ].join('\n');
+}
+/**
+ * Generate acceptance criteria from pattern
+ *
+ * @param pattern - Pattern object
+ * @returns Acceptance criteria
+ */
+function generateAcceptance(pattern) {
+    return [
+        'Root cause identified and documented',
+        'Fix implemented',
+        'Tests pass (pnpm gates)',
+        `No recurrence of "${pattern.title}" pattern`,
+    ];
+}
+/**
+ * Generate draft WU spec from a pattern
+ *
+ * @param baseDir - Base directory
+ * @param pattern - Pattern from feedback:review
+ * @param options - Options
+ * @returns Draft WU spec
+ */
+export async function generateDraft(baseDir, pattern, options = {}) {
+    const { writeFile: shouldWrite = false } = options;
+    const draft = {
+        title: pattern.title,
+        lane: inferLane(pattern.category),
+        description: generateDescription(pattern),
+        acceptance: generateAcceptance(pattern),
+        source_incidents: (pattern.examples ?? []).map((e) => e.id),
+        pattern_metadata: {
+            frequency: pattern.frequency,
+            category: pattern.category,
+            score: pattern.score,
+            firstSeen: pattern.firstSeen,
+            lastSeen: pattern.lastSeen,
+        },
+    };
+    if (shouldWrite) {
+        const draftsDir = path.join(baseDir, DRAFT_DIRECTORY);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+        await fs.mkdir(draftsDir, { recursive: true });
+        const timestamp = Date.now();
+        const filename = `draft-${timestamp}.yaml`;
+        const filePath = path.join(draftsDir, filename);
+        const yamlContent = stringifyYAML(draft, { lineWidth: 100 });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes draft file
+        await fs.writeFile(filePath, yamlContent, 'utf8');
+        draft.filePath = path.join(DRAFT_DIRECTORY, filename);
+    }
+    return draft;
+}
+/**
+ * Load all draft files from .beacon/feedback-drafts/
+ *
+ * @param baseDir - Base directory
+ * @returns Array of draft objects with filePath
+ */
+export async function loadDrafts(baseDir) {
+    const draftsDir = path.join(baseDir, DRAFT_DIRECTORY);
+    let files;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known directory
+        files = await fs.readdir(draftsDir);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    const yamlFiles = files.filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
+    const drafts = [];
+    for (const file of yamlFiles) {
+        const filePath = path.join(draftsDir, file);
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads draft files
+            const content = await fs.readFile(filePath, 'utf8');
+            // Parse YAML or JSON content
+            let draft;
+            try {
+                // Try JSON first (for test files that might use JSON.stringify)
+                draft = JSON.parse(content);
+            }
+            catch {
+                // Fall back to YAML parsing
+                draft = parseYAML(content);
+            }
+            draft.filePath = path.join(DRAFT_DIRECTORY, file);
+            drafts.push(draft);
+        }
+        catch (err) {
+            // Skip malformed files
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            console.warn(`Warning: Could not load draft ${file}: ${errorMessage}`);
+        }
+    }
+    return drafts;
+}
+/**
+ * Promote a draft to a WU via wu:create
+ *
+ * @param baseDir - Base directory
+ * @param draft - Draft object
+ * @param options - Options
+ * @returns Result with success, wuId, command
+ */
+export async function promoteDraft(baseDir, draft, options = {}) {
+    const { dryRun = false, wuIdOverride, removeDraft = false } = options;
+    // Generate WU ID if not provided
+    const wuId = wuIdOverride ?? `WU-${Date.now()}`;
+    // Build wu:create command
+    const command = buildWuCreateCommand(wuId, draft);
+    const result = {
+        success: true,
+        wuId,
+        command,
+        draft,
+    };
+    if (!dryRun) {
+        // Execute wu:create command
+        const { execSync } = await import('node:child_process');
+        try {
+            execSync(command, { cwd: baseDir, stdio: 'pipe' });
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                success: false,
+                wuId,
+                command,
+                error: errorMessage,
+            };
+        }
+        // Update feedback index with incident mappings
+        if (draft.source_incidents && draft.source_incidents.length > 0) {
+            await updateFeedbackIndex(baseDir, wuId, draft.source_incidents);
+        }
+    }
+    // Remove draft file if requested
+    if (removeDraft && draft.filePath) {
+        const absolutePath = draft.filePath.startsWith('/')
+            ? draft.filePath
+            : path.join(baseDir, draft.filePath);
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool removes draft file
+            await fs.unlink(absolutePath);
+            result.draftRemoved = true;
+        }
+        catch (err) {
+            // Ignore errors if file doesn't exist
+            if (err instanceof Error && 'code' in err && err.code !== 'ENOENT') {
+                console.warn(`Warning: Could not remove draft ${draft.filePath}: ${err.message}`);
+            }
+            result.draftRemoved = true; // Mark as removed even if it didn't exist
+        }
+    }
+    return result;
+}
+/**
+ * Build wu:create command from draft
+ *
+ * @param wuId - WU ID
+ * @param draft - Draft object
+ * @returns Command string
+ */
+function buildWuCreateCommand(wuId, draft) {
+    const parts = ['pnpm wu:create'];
+    parts.push(`--id ${wuId}`);
+    parts.push(`--lane "${draft.lane}"`);
+    parts.push(`--title "${draft.title.replace(/"/g, '\\"')}"`);
+    if (draft.description) {
+        parts.push(`--description "${draft.description.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`);
+    }
+    if (draft.acceptance && draft.acceptance.length > 0) {
+        for (const criterion of draft.acceptance) {
+            parts.push(`--acceptance "${criterion.replace(/"/g, '\\"')}"`);
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * Update feedback index with incident-to-WU mappings
+ *
+ * @param baseDir - Base directory
+ * @param wuId - WU ID
+ * @param incidentIds - Array of incident IDs
+ */
+export async function updateFeedbackIndex(baseDir, wuId, incidentIds) {
+    const indexPath = path.join(baseDir, FEEDBACK_INDEX_PATH);
+    const timestamp = new Date().toISOString();
+    // Ensure directory exists
+    const indexDir = path.dirname(indexPath);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+    await fs.mkdir(indexDir, { recursive: true });
+    // Build NDJSON entries
+    const entries = incidentIds.map((incidentId) => ({
+        incident_id: incidentId,
+        wu_id: wuId,
+        status: FEEDBACK_STATUS.PENDING_RESOLUTION,
+        timestamp,
+    }));
+    const content = `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`;
+    // Append to index file
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes index file
+    await fs.appendFile(indexPath, content, 'utf8');
+}
+/**
+ * Load feedback index entries
+ *
+ * @param baseDir - Base directory
+ * @returns Array of index entries
+ */
+export async function loadFeedbackIndex(baseDir) {
+    const indexPath = path.join(baseDir, FEEDBACK_INDEX_PATH);
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads index file
+        const content = await fs.readFile(indexPath, 'utf8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        return lines
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+}

package/dist/feedback-review-core.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Feedback Review Core Logic (WU-1598)
+ *
+ * Aggregates .beacon/incidents/*.ndjson and .beacon/memory/memory.jsonl,
+ * clusters by title similarity, scores patterns (frequency x severity x recency),
+ * and outputs prioritised patterns for human review.
+ *
+ * @see {@link tools/__tests__/feedback-review.test.mjs} - Tests
+ * @see {@link tools/feedback-review.mjs} - CLI entry point
+ */
+import { INCIDENT_SEVERITY } from '@lumenflow/core/lib/wu-constants.js';
+/**
+ * Severity weights for scoring
+ *
+ * Higher severity = higher weight in scoring formula
+ */
+export declare const SEVERITY_WEIGHTS: {
+    [INCIDENT_SEVERITY.BLOCKER]: number;
+    [INCIDENT_SEVERITY.MAJOR]: number;
+    [INCIDENT_SEVERITY.MINOR]: number;
+    [INCIDENT_SEVERITY.INFO]: number;
+};
+/**
+ * Node with ID and optional title/content
+ */
+interface NodeWithTitle {
+    id: string;
+    title?: string;
+    content?: string;
+    category?: string;
+    severity?: string;
+    created_at?: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    type?: string;
+    tags?: string[];
+}
+/**
+ * Cluster of nodes grouped by title similarity
+ */
+interface Cluster {
+    title: string;
+    nodes: NodeWithTitle[];
+    category: string;
+}
+/**
+ * Cluster nodes by title similarity
+ *
+ * Uses simple greedy clustering with Jaccard similarity.
+ *
+ * @param nodes - Nodes to cluster
+ * @param threshold - Similarity threshold
+ * @returns Array of cluster objects
+ */
+export declare function clusterByTitle(nodes: NodeWithTitle[], threshold?: number): Cluster[];
+/**
+ * Score a pattern cluster
+ *
+ * Formula: frequency x average_severity x recency_factor
+ *
+ * @param cluster - Cluster with nodes
+ * @returns Score value
+ */
+export declare function scorePattern(cluster: Cluster): number;
+/**
+ * Options for reviewing feedback
+ */
+interface ReviewOptions {
+    since?: string;
+    minFrequency?: number;
+    category?: string;
+    json?: boolean;
+}
+/**
+ * Pattern example for output
+ */
+interface PatternExample {
+    id: string;
+    severity: string | undefined;
+    source: string | undefined;
+}
+/**
+ * Pattern in review result
+ */
+interface ReviewPattern {
+    title: string;
+    frequency: number;
+    category: string;
+    score: number;
+    firstSeen: string | undefined;
+    lastSeen: string | undefined;
+    examples: PatternExample[];
+}
+/**
+ * Review result
+ */
+interface ReviewResult {
+    success: boolean;
+    patterns: ReviewPattern[];
+    summary: {
+        totalNodes: number;
+        totalClusters: number;
+        topCategory: string | null;
+    };
+}
+/**
+ * Review feedback from incidents and memory nodes
+ *
+ * Main entry point for feedback review logic.
+ *
+ * @param baseDir - Base directory containing .beacon
+ * @param options - Review options
+ * @returns Review result
+ */
+export declare function reviewFeedback(baseDir: string, options?: ReviewOptions): Promise<ReviewResult>;
+export {};