edsger 0.50.0 → 0.52.0

package/dist/phases/find-features/index.js

@@ -0,0 +1,279 @@
+/**
+ * Find-features phase: synthesise opportunities from user feedback +
+ * intelligence reports + the codebase, and file each one as an issue.
+ *
+ * The repo is cloned and the model runs with Read/Grep/Glob available so it
+ * can **verify existing functionality before proposing a new feature**. Many
+ * "obvious" feature asks ("add CSV export") turn out to be discoverability
+ * issues on something already shipped — the model needs to see the code to
+ * avoid those mistakes.
+ *
+ * Time-windowed on the PM data side (last N days of feedback) rather than
+ * diff-incremental on the repo side — we don't care what changed in the
+ * code, we care what exists there.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { callMcpEndpoint } from '../../api/mcp-client.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cloneIssueRepo, ensureWorkspaceDir, syncRepoToRef, } from '../../workspace/workspace-manager.js';
+import { detectDefaultBranch } from '../find-shared/git.js';
+import { createIssue, fetchOpenIssues, fetchProductBasics, } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createFindFeaturesSystemPrompt, createFindFeaturesUserPrompt, } from './prompts.js';
+import { acquireFindFeaturesLock, updateFindFeaturesState } from './state.js';
+import { isDiscoveryResult, } from './types.js';
+/**
+ * Upper bound on turns for the in-CLI Claude session.
+ *
+ * Feature discovery is primarily synthesis (cluster feedback, compare to
+ * intel, rank) but the model now also spot-checks the codebase to avoid
+ * proposing features that already exist. 150 turns leaves room for 5-10
+ * targeted Read/Grep passes per candidate without being an open-ended audit.
+ */
+const MAX_TURNS = 150;
+const WORKSPACE_KEY = 'find-features';
+const DEFAULT_SINCE = '90d';
+const DEFAULT_MIN_CLUSTER = 3;
+const DEFAULT_MAX_SUGGESTIONS = 10;
+// eslint-disable-next-line complexity
+export async function scanForFeatures(options) {
+    const { productId, githubToken, owner, repo, since = DEFAULT_SINCE, minClusterSize = DEFAULT_MIN_CLUSTER, maxSuggestions = DEFAULT_MAX_SUGGESTIONS, focusReportId, verbose, } = options;
+    logInfo(`Starting feature discovery for product ${productId} (${owner}/${repo})`);
+    const lock = acquireFindFeaturesLock(productId);
+    if (!lock) {
+        logWarning(`Another feature discovery run is already in progress for product ${productId}; skipping.`);
+        return {
+            status: 'error',
+            message: 'Another feature discovery run is already in progress for this product',
+        };
+    }
+    try {
+        updateFindFeaturesState(productId, {
+            lastAttemptedAt: new Date().toISOString(),
+        });
+        // Clone / refresh the repo so the model can verify existing functionality
+        // before proposing new features. Same workspace pattern as find-bugs —
+        // one reusable clone per product, keyed by WORKSPACE_KEY.
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        const cloned = cloneIssueRepo(workspaceRoot, repoKey, owner, repo, githubToken);
+        const { repoPath } = cloned;
+        const branch = options.branch ?? detectDefaultBranch(repoPath);
+        logInfo(`Syncing ${owner}/${repo} to branch ${branch}`);
+        syncRepoToRef(repoPath, { branch }, githubToken);
+        const sinceIso = resolveSinceIso(since);
+        const product = await fetchProductBasics(productId);
+        const [feedbacks, intelligenceReports, existingIssues] = await Promise.all([
+            fetchFeedbacks(productId, sinceIso),
+            fetchIntelligenceReports(productId, focusReportId),
+            fetchOpenIssues(productId),
+        ]);
+        logInfo(`Loaded ${feedbacks.length} feedbacks (since ${since}), ${intelligenceReports.length} reports, ${existingIssues.length} open issues`);
+        const codeOnlyMode = feedbacks.length === 0 && intelligenceReports.length === 0;
+        if (codeOnlyMode) {
+            logInfo('No feedback or intelligence reports in scope — running code-only analysis on the repo.');
+        }
+        const systemPrompt = createFindFeaturesSystemPrompt({ codeOnlyMode });
+        const userPrompt = createFindFeaturesUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            feedbacks,
+            intelligenceReports,
+            existingIssues: existingIssues.map((i) => ({
+                id: i.id,
+                name: i.name,
+                description: i.description,
+            })),
+            minClusterSize,
+            maxSuggestions,
+            sinceWindow: since,
+            focusReportId,
+            codeOnlyMode,
+        });
+        let lastAssistantResponse = '';
+        let discoveryResult = null;
+        logInfo('Running Claude opportunity synthesis...');
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+            },
+        })) {
+            if (message.type === 'assistant') {
+                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            const responseText = message.subtype === 'success'
+                ? message.result || lastAssistantResponse
+                : lastAssistantResponse;
+            const parsed = tryExtractResult(responseText, 'discovery_result');
+            if (isDiscoveryResult(parsed)) {
+                discoveryResult = parsed;
+            }
+            else if (message.subtype !== 'success') {
+                logError(`Synthesis incomplete: ${message.subtype}`);
+            }
+        }
+        if (!discoveryResult) {
+            const msg = 'Synthesis failed: could not parse a discovery_result from the agent';
+            updateFindFeaturesState(productId, { lastError: msg });
+            return { status: 'error', message: msg };
+        }
+        const { summary, opportunities } = discoveryResult;
+        logInfo(`Synthesis produced ${opportunities.length} opportunities. ${summary}`);
+        let created = 0;
+        for (const opp of opportunities) {
+            const issueId = await createIssueForOpportunity(productId, opp);
+            if (issueId) {
+                created++;
+                logSuccess(`Filed issue ${issueId}: ${opp.title}`);
+            }
+        }
+        // The previous schema captured `lastSeenFeedbackId / lastSeenReportId /
+        // lastScannedCommitSha` here, but the reader side never used them — kept
+        // it lean and only persist the run-status fields the worker actually
+        // reads on retry. See find-features/state.ts for the schema rationale.
+        updateFindFeaturesState(productId, {
+            lastRunAt: new Date().toISOString(),
+            lastError: undefined,
+        });
+        return {
+            status: 'success',
+            message: `Filed ${created} of ${opportunities.length} opportunities`,
+            opportunitiesFound: opportunities.length,
+            issuesCreated: created,
+            summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Feature discovery failed: ${errorMessage}`);
+        updateFindFeaturesState(productId, { lastError: errorMessage });
+        return {
+            status: 'error',
+            message: `Feature discovery failed: ${errorMessage}`,
+        };
+    }
+    finally {
+        lock.release();
+    }
+}
+/**
+ * Convert a user-friendly "since" value (e.g. "30d", "12h", ISO timestamp) to
+ * an ISO string usable as a lower bound. Falls back to 90 days ago on parse
+ * failure — better to over-fetch than silently skip half the signal.
+ */
+const DURATION_UNIT_MS = {
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+    w: 7 * 24 * 60 * 60 * 1000,
+};
+export function resolveSinceIso(since) {
+    const now = Date.now();
+    const durationMatch = /^(\d+)([dhw])$/.exec(since.trim());
+    if (durationMatch) {
+        const n = parseInt(durationMatch[1], 10);
+        const unit = durationMatch[2];
+        const ms = n * (DURATION_UNIT_MS[unit] ?? DURATION_UNIT_MS.d);
+        return new Date(now - ms).toISOString();
+    }
+    const ts = Date.parse(since);
+    if (!Number.isNaN(ts)) {
+        return new Date(ts).toISOString();
+    }
+    return new Date(now - 90 * 24 * 60 * 60 * 1000).toISOString();
+}
+async function fetchFeedbacks(productId, sinceIso) {
+    try {
+        // `product_user_feedbacks/list_for_product` queries the
+        // product_user_feedbacks table — the *external user* feedback surface
+        // (submitted via the public feedback page, no auth). Schema: title +
+        // description + category (bug | feature_request | improvement |
+        // question | other) + status + priority. Server-side filter on
+        // `since` keeps the response size bounded.
+        //
+        // NOT to be confused with `feedbacks/list_for_product`, which returns
+        // Claude-Code phase feedback and is an internal-workflow artefact.
+        const result = (await callMcpEndpoint('product_user_feedbacks/list_for_product', {
+            product_id: productId,
+            since: sinceIso,
+        }));
+        const rows = result.feedbacks || [];
+        return rows.map((f) => ({
+            id: f.id,
+            body: f.title ? `${f.title}\n${f.description}`.trim() : f.description,
+            category: f.category,
+            createdAt: f.created_at,
+        }));
+    }
+    catch (error) {
+        logWarning(`Could not load user feedbacks: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+async function fetchIntelligenceReports(productId, focusReportId) {
+    try {
+        // `intelligence_reports` schema (20260327000000_create_intelligence.sql:69):
+        // id, product_id, report_type, title, summary, full_report, …, created_at.
+        const result = (await callMcpEndpoint('intelligence/reports/list', {
+            product_id: productId,
+        }));
+        let reports = result.reports || [];
+        if (focusReportId) {
+            // If focused, put the focus report first and keep 5 others for context.
+            const focus = reports.filter((r) => r.id === focusReportId);
+            const rest = reports.filter((r) => r.id !== focusReportId).slice(0, 5);
+            reports = [...focus, ...rest];
+        }
+        else {
+            reports = reports.slice(0, 10);
+        }
+        return reports.map((r) => ({
+            id: r.id,
+            title: r.title,
+            summary: r.summary,
+            createdAt: r.created_at,
+        }));
+    }
+    catch (error) {
+        logWarning(`Could not load intelligence reports: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+async function createIssueForOpportunity(productId, opp) {
+    return createIssue({
+        productId,
+        title: opp.title,
+        description: formatIssueDescription(opp),
+    });
+}
+function formatIssueDescription(opp) {
+    const evidenceLine = opp.supporting_evidence_ids.length > 0
+        ? opp.supporting_evidence_ids.join(', ')
+        : '(none provided — review manually)';
+    const lines = [
+        `**Source**: feature-discovery`,
+        `**Confidence**: ${opp.confidence}`,
+        `**Signal**: ${opp.source}`,
+        `**User outcome**: ${opp.user_outcome}`,
+        `**Supporting evidence**: ${evidenceLine}`,
+        '',
+        opp.description,
+        '',
+        '---',
+        '_Filed automatically by `edsger find-features`._',
+    ];
+    return lines.join('\n');
+}

package/dist/phases/find-features/prompts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Prompts for the find-features phase. The agent runs with cwd=repo checkout
+ * and has Read/Grep/Glob available — it's expected to consult the codebase
+ * to verify an idea isn't already shipped before proposing it. That check
+ * catches the most common failure mode of feature-discovery: surfacing
+ * "opportunities" that are really just discoverability issues on existing
+ * functionality.
+ */
+export interface FindFeaturesSystemPromptParams {
+    /** True when no feedback/reports were available; agent must derive opportunities purely from code. */
+    codeOnlyMode?: boolean;
+}
+export declare function createFindFeaturesSystemPrompt(params?: FindFeaturesSystemPromptParams): string;
+export interface FindFeaturesUserPromptParams {
+    productName: string;
+    productDescription?: string;
+    feedbacks: {
+        id: string;
+        body: string;
+        category?: string;
+        createdAt?: string;
+    }[];
+    intelligenceReports: {
+        id: string;
+        title: string;
+        summary?: string;
+        createdAt?: string;
+    }[];
+    existingIssues: {
+        id: string;
+        name: string;
+        description?: string;
+    }[];
+    minClusterSize: number;
+    maxSuggestions: number;
+    /** Upper bound on the feedback window this run considers (human readable). */
+    sinceWindow: string;
+    /** Optional narrowing to a specific intelligence report's context. */
+    focusReportId?: string;
+    /** True when the run has no feedback/reports and must analyse the codebase only. */
+    codeOnlyMode?: boolean;
+}
+export declare function createFindFeaturesUserPrompt(params: FindFeaturesUserPromptParams): string;

package/dist/phases/find-features/prompts.js

@@ -0,0 +1,138 @@
+/**
+ * Prompts for the find-features phase. The agent runs with cwd=repo checkout
+ * and has Read/Grep/Glob available — it's expected to consult the codebase
+ * to verify an idea isn't already shipped before proposing it. That check
+ * catches the most common failure mode of feature-discovery: surfacing
+ * "opportunities" that are really just discoverability issues on existing
+ * functionality.
+ */
+export function createFindFeaturesSystemPrompt(params = {}) {
+    const { codeOnlyMode = false } = params;
+    const evidenceClause = codeOnlyMode
+        ? `2. **Evidence from the codebase** — since no user feedback or reports are available this run, opportunities must be grounded in concrete observations of the code: half-finished flows, TODO/FIXME clusters, obvious gaps next to existing functionality, missing standard capabilities for this kind of product. Cite file paths (e.g. \`src/foo/bar.ts:42\`) as your evidence in \`supporting_evidence_ids\`.`
+        : `2. **Evidence beyond one voice** — backed by multiple feedbacks, a competitor gap, or a measurable trend. Cite specific IDs.`;
+    return `You are a senior product manager synthesising **opportunities worth building** for a product. You are reading user feedback, competitive intelligence, and the product's current codebase, then picking the few ideas with the strongest evidence.${codeOnlyMode
+        ? '\n\nThis run has **no user feedback and no intelligence reports** in scope. Derive opportunities purely from the codebase: look for half-built flows, TODO/FIXME clusters, missing standard capabilities, and natural extensions of existing features. Cite file paths as evidence.'
+        : ''}
+
+You have read-only access to the repository via Read/Grep/Glob. Use it — the single most common failure mode of this role is proposing a feature that already exists but is badly discoverable. Before filing an opportunity, grep the code for the feature you're about to propose; if it's already implemented, either reframe the opportunity as a discoverability fix or drop it.
+
+**What counts as an opportunity worth filing**:
+1. **Clear user outcome** — you can articulate in one sentence what changes for the user.
+${evidenceClause}
+3. **Feasible in this product's shape** — adjacent to existing workflows, not a pivot. Verify against the code.
+4. **Not already in the backlog** — cross-check the existing-issues list; skip anything that overlaps, even if the wording differs.
+5. **Not already in the code** — grep before you file. If the feature exists but is hidden, the opportunity is "improve discoverability of X", not "add X".
+
+**What does NOT count** (skip these — they cost product velocity for little signal):
+- Nice-to-haves with no evidence ("would be cool if…")
+- Pure refactors or tech debt (those are issues, not opportunities)
+- Things that belong in support docs, not in the product
+- "We should do X like CompetitorY" with no evidence any user wants X
+- Generic platform expansions ("add a mobile app", "add an API") unless specific evidence supports it
+- Features that already exist in the code — check before filing
+
+**Discipline**:
+- Prefer **fewer**, **better-evidenced** ideas over a long list. Ten mediocre suggestions dilute the good ones.
+- Each opportunity must cite \`supporting_evidence_ids\` — feedback IDs, report IDs, ${codeOnlyMode ? 'or **file paths** (e.g. `src/foo/bar.ts:42`) when running in code-only mode' : 'or, when no PM signal exists, file paths in the form `src/foo/bar.ts:42`'}. Zero evidence = you're speculating; cut it.
+- Confidence rubric${codeOnlyMode ? ' (code-only mode)' : ''}:
+  - high   = ${codeOnlyMode ? 'a half-finished flow with multiple TODOs **or** an obvious gap next to existing functionality with clear product framing' : '3+ independent user signals **or** a clear competitor parity gap backed by a report'}
+  - medium = ${codeOnlyMode ? 'a noticeable gap or natural extension supported by 2+ code references' : '2 signals, or a strong theme in one report'}
+  - low    = ${codeOnlyMode ? 'a single thoughtful code observation that still deserves surfacing' : 'a single thoughtful signal that still deserves surfacing'}
+- **Deduplication**: skip findings that overlap any existing open issue. Be conservative — rephrased overlap is still overlap.
+- **Verification**: for each candidate, grep the repo for the functionality. Note in the opportunity description what you checked and why you're confident it's genuinely missing.
+
+**CRITICAL — Output Format**:
+End your response with a single JSON code block in this exact shape:
+
+\`\`\`json
+{
+  "discovery_result": {
+    "summary": "Reviewed N feedbacks and M reports; surfacing K opportunities.",
+    "analyzed_through": "<ISO timestamp of the most recent signal considered>",
+    "opportunities": [
+      {
+        "title": "Short, action-oriented title under 80 chars",
+        "description": "## Opportunity\\nPlain-language pitch.\\n\\n## Evidence\\n- feedback:abc123 — quote\\n- report:def456 — key finding\\n\\n## Why now\\nTiming rationale (trend, blocker unblocking, etc).\\n\\n## Rough scope\\nOne paragraph on what building it looks like.",
+        "user_outcome": "The user can now X without having to Y.",
+        "confidence": "medium",
+        "source": "user_feedback",
+        "supporting_evidence_ids": ["abc123", "def456"],
+        "dedup_signature": "invoice-bulk-csv-export"
+      }
+    ]
+  }
+}
+\`\`\`
+
+If nothing meets the bar, emit the JSON with an empty \`opportunities\` array and a summary that says so plainly.`;
+}
+export function createFindFeaturesUserPrompt(params) {
+    const { productName, productDescription, feedbacks, intelligenceReports, existingIssues, minClusterSize, maxSuggestions, sinceWindow, focusReportId, codeOnlyMode = false, } = params;
+    const productBlock = productDescription
+        ? `**Product**: ${productName}\n${productDescription}`
+        : `**Product**: ${productName}`;
+    const feedbackBlock = feedbacks.length === 0
+        ? 'No user feedback available in the current window.'
+        : `**User feedback** (${feedbacks.length} items, window: ${sinceWindow}):\n${feedbacks
+            .slice(0, 300)
+            .map((f) => `- [${f.id}] ${f.category ? `[${f.category}] ` : ''}${f.createdAt ? `(${f.createdAt.slice(0, 10)}) ` : ''}${truncate(f.body, 300)}`)
+            .join('\n')}${feedbacks.length > 300 ? `\n…and ${feedbacks.length - 300} more.` : ''}`;
+    const focusBlock = focusReportId
+        ? `\n**Focus**: report id \`${focusReportId}\` — prioritise opportunities implied by this specific report.`
+        : '';
+    const reportsBlock = intelligenceReports.length === 0
+        ? 'No intelligence reports available.'
+        : `**Intelligence reports** (${intelligenceReports.length}):\n${intelligenceReports
+            .slice(0, 30)
+            .map((r) => `- [${r.id}] ${r.title}${r.summary ? `\n  ${truncate(r.summary, 200)}` : ''}`)
+            .join('\n')}`;
+    const issuesBlock = existingIssues.length === 0
+        ? 'No existing open issues — any opportunity you surface is new.'
+        : `**Existing open issues** (${existingIssues.length}) — skip overlaps:\n${existingIssues
+            .slice(0, 200)
+            .map((i) => `- [${i.id}] ${i.name}${i.description ? `\n  ${truncate(i.description, 160)}` : ''}`)
+            .join('\n')}`;
+    return `${productBlock}
+
+${feedbackBlock}${focusBlock}
+
+${reportsBlock}
+
+${issuesBlock}
+
+## Budget and discipline
+- Surface **at most ${maxSuggestions} opportunities**. Rank by confidence + evidence strength; drop the weakest.
+- A "theme" needs at least ${minClusterSize} independent feedback mentions to count as high-confidence (solo mentions may still appear at low confidence if they're specific and concrete).
+
+${codeOnlyMode
+        ? `## How to work (code-only mode — no feedback or reports this run)
+1. Orient: Glob top-level source dirs, Read the README and any docs/ index, list the main routes/screens/commands. Goal: build a one-paragraph mental model of what the product already does.
+2. Identify candidate gaps from the code itself:
+   - Half-finished flows (UI exists but handler is a stub, route returns 501, TODO/FIXME clusters).
+   - Standard capabilities a product of this shape would normally have but doesn't (search, export, filtering, bulk actions, audit logs, settings, empty-state guidance, error recovery).
+   - Natural extensions of existing features (one-off where a list/multi version is the obvious next step).
+   - Inconsistencies (feature available in one entity but not its peers).
+3. For each candidate: (a) cross-check the existing-issues list for overlap, (b) grep more carefully to confirm the gap is real, not just code you missed.
+4. Rank by signal strength. Keep at most ${maxSuggestions}; cut hard. Skip pure refactors and tech debt.
+5. For each survivor: write a clear user outcome, cite **file paths** in \`supporting_evidence_ids\` (e.g. \`src/exports/index.ts:42\`), set \`source\` to \`code_analysis\`, and pick a confidence level honestly using the code-only rubric.
+6. Produce the final JSON described in the system prompt. If nothing meets the bar, emit an empty \`opportunities\` array with a summary that says so plainly.
+
+Begin.`
+        : `## How to work
+1. Start with a lightweight orientation pass on the repo: Glob for top-level source dirs, Read the README and any docs/ index, grep for obvious domain concepts. Goal: know what the product already does before you synthesise what it should do.
+2. Scan feedbacks. Group by theme. Note which themes have ≥${minClusterSize} mentions.
+3. Scan intelligence reports. Note any gaps, trends, or competitor parity points.
+4. For each candidate theme: (a) check the existing-issues list for overlap, (b) **grep the code** to verify the feature isn't already implemented. If found in code but users don't seem to know, reframe as a discoverability opportunity instead of a net-new feature.
+5. Rank the survivors. Keep the top ${maxSuggestions} with the strongest evidence.
+6. For each: write a clear user outcome, cite evidence IDs, pick a confidence level honestly. In the description's "Rough scope" section, note what you verified in code (e.g. "confirmed no CSV export code path under src/exports/").
+7. Produce the final JSON described in the system prompt.
+
+Begin.`}`;
+}
+function truncate(s, n) {
+    if (s.length <= n) {
+        return s;
+    }
+    return `${s.slice(0, n)}…`;
+}

package/dist/phases/find-features/state.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-product discovery state for find-features. Storage at
+ * `~/.edsger/find-features-state/<productId>.json`.
+ *
+ * Tracks only run-status fields (last successful run, last attempt, last
+ * error) — feature discovery uses a time-based "since" window passed at
+ * call time, so there's no per-run cursor to persist. The earlier schema
+ * captured `lastSeenFeedbackId / lastSeenReportId / lastScannedCommitSha`
+ * but they were never read; trimmed in favour of a leaner schema. If a
+ * future run wants to skip already-clustered material, restore them and
+ * wire the read side at the same time.
+ *
+ * File layout + lock semantics shared via createScanStateModule.
+ */
+import { type LockHandle } from '../find-shared/scan-state.js';
+export type { LockHandle };
+export interface FindFeaturesState {
+    lastRunAt?: string;
+    lastAttemptedAt?: string;
+    lastError?: string;
+}
+export declare const loadFindFeaturesState: (productId: string) => FindFeaturesState;
+export declare const saveFindFeaturesState: (productId: string, state: FindFeaturesState) => void;
+export declare const updateFindFeaturesState: (productId: string, patch: Partial<FindFeaturesState>) => FindFeaturesState;
+export declare const acquireFindFeaturesLock: (productId: string, staleAfterMs?: number) => LockHandle | null;

package/dist/phases/find-features/state.js

@@ -0,0 +1,22 @@
+/**
+ * Per-product discovery state for find-features. Storage at
+ * `~/.edsger/find-features-state/<productId>.json`.
+ *
+ * Tracks only run-status fields (last successful run, last attempt, last
+ * error) — feature discovery uses a time-based "since" window passed at
+ * call time, so there's no per-run cursor to persist. The earlier schema
+ * captured `lastSeenFeedbackId / lastSeenReportId / lastScannedCommitSha`
+ * but they were never read; trimmed in favour of a leaner schema. If a
+ * future run wants to skip already-clustered material, restore them and
+ * wire the read side at the same time.
+ *
+ * File layout + lock semantics shared via createScanStateModule.
+ */
+import { createScanStateModule, } from '../find-shared/scan-state.js';
+const m = createScanStateModule({
+    dirName: 'find-features-state',
+});
+export const loadFindFeaturesState = m.load;
+export const saveFindFeaturesState = m.save;
+export const updateFindFeaturesState = m.update;
+export const acquireFindFeaturesLock = m.acquireLock;

package/dist/phases/find-features/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Types for the find-features phase.
+ */
+export type OpportunityConfidence = 'high' | 'medium' | 'low';
+export type OpportunitySource = 'user_feedback' | 'competitor_gap' | 'market_trend' | 'adjacent_workflow' | 'code_analysis' | 'other';
+export interface FeatureOpportunity {
+    /** Short, action-oriented title (e.g. "Add bulk CSV export for invoices"). */
+    title: string;
+    /** Structured markdown body — see prompt for the required sections. */
+    description: string;
+    /** One-line hypothesis of the user outcome the feature unlocks. */
+    user_outcome: string;
+    /** Rough confidence; keeps the agent honest about evidence strength. */
+    confidence: OpportunityConfidence;
+    /** What signal surfaced this idea. */
+    source: OpportunitySource;
+    /** Specific evidence IDs (feedback IDs, report IDs) backing the idea. */
+    supporting_evidence_ids: string[];
+    /** Free-form stable slug for logging/audit. Not used for dedup persistence. */
+    dedup_signature?: string;
+}
+export interface DiscoveryResult {
+    summary: string;
+    analyzed_through: string;
+    opportunities: FeatureOpportunity[];
+}
+export declare function isDiscoveryResult(value: unknown): value is DiscoveryResult;

package/dist/phases/find-features/types.js

@@ -0,0 +1,16 @@
+/**
+ * Types for the find-features phase.
+ */
+export function isDiscoveryResult(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    return (typeof v.summary === 'string' &&
+        Array.isArray(v.opportunities) &&
+        v.opportunities.every((o) => o &&
+            typeof o === 'object' &&
+            typeof o.title === 'string' &&
+            typeof o.description === 'string' &&
+            typeof o.user_outcome === 'string'));
+}

package/dist/phases/find-shared/git.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Git helpers shared by the find-* phases (find-bugs, find-features,
+ * find-smells). All three clone a product's repo, sync to a branch, and need
+ * the same low-level rev/diff queries — keep them here so behaviour stays in
+ * lock-step.
+ *
+ * Read-only on the working tree; safe to call against any cwd that is a git
+ * repo.
+ */
+export declare function gitRevParse(repoPath: string, ref: string): string;
+/**
+ * Resolve the remote's default branch (e.g. "main", "master", "trunk") via the
+ * symbolic ref `refs/remotes/origin/HEAD`. Falls back to "main" if the ref is
+ * missing — the caller will surface a sync error if that's wrong.
+ */
+export declare function detectDefaultBranch(repoPath: string): string;
+/**
+ * True iff `ancestor` is reachable from `descendant` (i.e. `descendant`
+ * contains all of `ancestor`'s history). Used by incremental scans to decide
+ * whether a previously-scanned commit is still part of HEAD's history before
+ * trusting a `git diff base..head`.
+ */
+export declare function isAncestor(repoPath: string, ancestor: string, descendant: string): boolean;
+export declare function listChangedPaths(repoPath: string, baseSha: string, headSha: string): string[];

package/dist/phases/find-shared/git.js

@@ -0,0 +1,60 @@
+/**
+ * Git helpers shared by the find-* phases (find-bugs, find-features,
+ * find-smells). All three clone a product's repo, sync to a branch, and need
+ * the same low-level rev/diff queries — keep them here so behaviour stays in
+ * lock-step.
+ *
+ * Read-only on the working tree; safe to call against any cwd that is a git
+ * repo.
+ */
+import { execFileSync } from 'child_process';
+export function gitRevParse(repoPath, ref) {
+    return execFileSync('git', ['rev-parse', ref], {
+        cwd: repoPath,
+        encoding: 'utf-8',
+    }).trim();
+}
+/**
+ * Resolve the remote's default branch (e.g. "main", "master", "trunk") via the
+ * symbolic ref `refs/remotes/origin/HEAD`. Falls back to "main" if the ref is
+ * missing — the caller will surface a sync error if that's wrong.
+ */
+export function detectDefaultBranch(repoPath) {
+    try {
+        const ref = execFileSync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd: repoPath, encoding: 'utf-8' }).trim();
+        return ref.replace(/^origin\//, '');
+    }
+    catch {
+        return 'main';
+    }
+}
+/**
+ * True iff `ancestor` is reachable from `descendant` (i.e. `descendant`
+ * contains all of `ancestor`'s history). Used by incremental scans to decide
+ * whether a previously-scanned commit is still part of HEAD's history before
+ * trusting a `git diff base..head`.
+ */
+export function isAncestor(repoPath, ancestor, descendant) {
+    try {
+        execFileSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+            cwd: repoPath,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function listChangedPaths(repoPath, baseSha, headSha) {
+    try {
+        const out = execFileSync('git', ['diff', '--name-only', `${baseSha}..${headSha}`], { cwd: repoPath, encoding: 'utf-8' });
+        return out
+            .split('\n')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    catch {
+        return [];
+    }
+}