edsger 0.51.0 → 0.53.0

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

@@ -6,14 +6,20 @@
  * "opportunities" that are really just discoverability issues on existing
  * functionality.
  */
-export function createFindFeaturesSystemPrompt() {
-    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.
+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.
-2. **Evidence beyond one voice** — backed by multiple feedbacks, a competitor gap, or a measurable trend. Cite specific IDs.
+${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".
@@ -28,11 +34,11 @@ You have read-only access to the repository via Read/Grep/Glob. Use it — the s
 
 **Discipline**:
 - Prefer **fewer**, **better-evidenced** ideas over a long list. Ten mediocre suggestions dilute the good ones.
-- Each opportunity must cite \`supporting_evidence_ids\` — the feedback IDs or report IDs that support it. Zero IDs = you're speculating; cut it.
-- Confidence rubric:
-  - high   = 3+ independent user signals **or** a clear competitor parity gap backed by a report
-  - medium = 2 signals, or a strong theme in one report
-  - low    = a single thoughtful signal that still deserves surfacing
+- 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.
 
@@ -62,7 +68,7 @@ End your response with a single JSON code block in this exact shape:
 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, } = params;
+    const { productName, productDescription, feedbacks, intelligenceReports, existingIssues, minClusterSize, maxSuggestions, sinceWindow, focusReportId, codeOnlyMode = false, } = params;
     const productBlock = productDescription
         ? `**Product**: ${productName}\n${productDescription}`
         : `**Product**: ${productName}`;
@@ -99,7 +105,21 @@ ${issuesBlock}
 - 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).
 
-## How to work
+${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.
@@ -108,7 +128,7 @@ ${issuesBlock}
 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.`;
+Begin.`}`;
 }
 function truncate(s, n) {
     if (s.length <= n) {

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

@@ -1,29 +1,25 @@
 /**
- * Per-product discovery state persisted under
+ * Per-product discovery state for find-features. Storage at
  * `~/.edsger/find-features-state/<productId>.json`.
  *
- * Unlike find-bugs (which tracks a commit sha for diff-based incremental
- * scans), feature discovery is time-based: we record when we last ran and
- * what the most-recent feedback we'd seen was, so the next run can focus on
- * genuinely new material instead of re-clustering the same themes.
+ * 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.
  *
- * Also shares the same atomic-write + exclusive-lock machinery as find-bugs.
+ * 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;
-    /** Most recent feedback id seen by the previous successful run. */
-    lastSeenFeedbackId?: string;
-    /** Most recent intelligence report id seen. */
-    lastSeenReportId?: string;
-    /** HEAD sha of the repo when the last successful run read it. Metadata only. */
-    lastScannedCommitSha?: string;
 }
-export declare function loadFindFeaturesState(productId: string): FindFeaturesState;
-export declare function saveFindFeaturesState(productId: string, state: FindFeaturesState): void;
-export declare function updateFindFeaturesState(productId: string, patch: Partial<FindFeaturesState>): FindFeaturesState;
-export interface LockHandle {
-    release: () => void;
-}
-export declare function acquireFindFeaturesLock(productId: string, staleAfterMs?: number): LockHandle | null;
+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

@@ -1,94 +1,22 @@
 /**
- * Per-product discovery state persisted under
+ * Per-product discovery state for find-features. Storage at
  * `~/.edsger/find-features-state/<productId>.json`.
  *
- * Unlike find-bugs (which tracks a commit sha for diff-based incremental
- * scans), feature discovery is time-based: we record when we last ran and
- * what the most-recent feedback we'd seen was, so the next run can focus on
- * genuinely new material instead of re-clustering the same themes.
+ * 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.
  *
- * Also shares the same atomic-write + exclusive-lock machinery as find-bugs.
+ * File layout + lock semantics shared via createScanStateModule.
  */
-import { existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'fs';
-import { homedir } from 'os';
-import { join } from 'path';
-function stateDir() {
-    return join(homedir(), '.edsger', 'find-features-state');
-}
-function safeProductId(productId) {
-    return productId.replace(/[^a-zA-Z0-9_-]/g, '_');
-}
-function statePath(productId) {
-    return join(stateDir(), `${safeProductId(productId)}.json`);
-}
-function lockPath(productId) {
-    return join(stateDir(), `${safeProductId(productId)}.lock`);
-}
-function ensureStateDir() {
-    const dir = stateDir();
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    return dir;
-}
-export function loadFindFeaturesState(productId) {
-    const p = statePath(productId);
-    if (!existsSync(p)) {
-        return {};
-    }
-    try {
-        const raw = readFileSync(p, 'utf-8');
-        const parsed = JSON.parse(raw);
-        return parsed && typeof parsed === 'object' ? parsed : {};
-    }
-    catch {
-        return {};
-    }
-}
-export function saveFindFeaturesState(productId, state) {
-    ensureStateDir();
-    const finalPath = statePath(productId);
-    const tmpPath = `${finalPath}.${process.pid}.tmp`;
-    writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
-    renameSync(tmpPath, finalPath);
-}
-export function updateFindFeaturesState(productId, patch) {
-    const merged = { ...loadFindFeaturesState(productId), ...patch };
-    saveFindFeaturesState(productId, merged);
-    return merged;
-}
-export function acquireFindFeaturesLock(productId, staleAfterMs = 60 * 60 * 1000) {
-    ensureStateDir();
-    const lock = lockPath(productId);
-    if (existsSync(lock)) {
-        try {
-            const raw = readFileSync(lock, 'utf-8');
-            const parsed = JSON.parse(raw);
-            const age = Date.now() - new Date(parsed.acquiredAt ?? 0).getTime();
-            if (age < staleAfterMs) {
-                return null;
-            }
-            rmSync(lock, { force: true });
-        }
-        catch {
-            rmSync(lock, { force: true });
-        }
-    }
-    try {
-        const fd = openSync(lock, 'wx');
-        writeFileSync(fd, JSON.stringify({ acquiredAt: new Date().toISOString(), pid: process.pid }));
-        return {
-            release: () => {
-                try {
-                    unlinkSync(lock);
-                }
-                catch {
-                    // already gone
-                }
-            },
-        };
-    }
-    catch {
-        return null;
-    }
-}
+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

@@ -2,7 +2,7 @@
  * Types for the find-features phase.
  */
 export type OpportunityConfidence = 'high' | 'medium' | 'low';
-export type OpportunitySource = 'user_feedback' | 'competitor_gap' | 'market_trend' | 'adjacent_workflow' | 'other';
+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;

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 [];
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * MCP helpers shared by find-bugs / find-features / find-smells.
+ *
+ * All three load a product's basics (name, description) for prompt context,
+ * pull the open-issue list for dedup, and file findings via `issues/create`.
+ * Centralising the calls means a schema change in MCP only needs touching one
+ * place, and the per-phase orchestrators stay focused on their own logic.
+ */
+import { type IssueInfo } from '../../types/issues.js';
+export interface ProductBasics {
+    name: string;
+    description?: string;
+}
+export declare function fetchProductBasics(productId: string): Promise<ProductBasics>;
+/**
+ * Fetch the product's open issues for dedup context. Filters out terminal
+ * statuses (shipped/archived/closed/...) since those can't conflict with new
+ * findings the agent might surface.
+ */
+export declare function fetchOpenIssues(productId: string): Promise<IssueInfo[]>;
+export declare function isTerminalStatus(status: string): boolean;
+export interface CreateIssueInput {
+    productId: string;
+    /** Issue title for `name`. */
+    title: string;
+    /** Already-formatted markdown body. The caller decides the layout. */
+    description: string;
+}
+/**
+ * File a new issue via MCP. Returns the new issue id, or null if MCP returned
+ * an error / unexpected shape (already logged).
+ */
+export declare function createIssue(input: CreateIssueInput): Promise<string | null>;

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

@@ -0,0 +1,69 @@
+/**
+ * MCP helpers shared by find-bugs / find-features / find-smells.
+ *
+ * All three load a product's basics (name, description) for prompt context,
+ * pull the open-issue list for dedup, and file findings via `issues/create`.
+ * Centralising the calls means a schema change in MCP only needs touching one
+ * place, and the per-phase orchestrators stay focused on their own logic.
+ */
+import { callMcpEndpoint } from '../../api/mcp-client.js';
+import { logError, logWarning } from '../../utils/logger.js';
+export async function fetchProductBasics(productId) {
+    try {
+        const result = (await callMcpEndpoint('resources/read', {
+            uri: `product://${productId}`,
+        }));
+        const text = result.contents?.[0]?.text || '{}';
+        const parsed = JSON.parse(text);
+        return {
+            name: parsed.name || productId,
+            description: parsed.description,
+        };
+    }
+    catch {
+        return { name: productId };
+    }
+}
+/**
+ * Fetch the product's open issues for dedup context. Filters out terminal
+ * statuses (shipped/archived/closed/...) since those can't conflict with new
+ * findings the agent might surface.
+ */
+export async function fetchOpenIssues(productId) {
+    try {
+        const result = (await callMcpEndpoint('issues/list', {
+            product_id: productId,
+        }));
+        const all = result.issues || [];
+        return all.filter((i) => !isTerminalStatus(i.status));
+    }
+    catch (error) {
+        logWarning(`Could not load existing issues for dedup: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+export function isTerminalStatus(status) {
+    return (status === 'shipped' ||
+        status === 'archived' ||
+        status === 'cancelled' ||
+        status === 'closed' ||
+        status === 'completed');
+}
+/**
+ * File a new issue via MCP. Returns the new issue id, or null if MCP returned
+ * an error / unexpected shape (already logged).
+ */
+export async function createIssue(input) {
+    try {
+        const result = (await callMcpEndpoint('issues/create', {
+            product_id: input.productId,
+            name: input.title,
+            description: input.description,
+        }));
+        return result.issue?.id || result.id || null;
+    }
+    catch (error) {
+        logError(`Failed to create issue for "${input.title}": ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}

package/dist/phases/find-shared/scan-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-product scan state, generic across the find-* phases. Each phase has
+ * its own state schema (find-bugs tracks a commit sha, find-features tracks
+ * the most-recent-seen feedback id, etc.) so the type is parametric, but the
+ * file layout, atomic-write, and lock semantics are identical and live here.
+ *
+ * Storage layout: `~/.edsger/<dirName>/<productId>.json` plus a sibling
+ * `.lock` file. The lockfile uses O_EXCL so concurrent acquirers race on the
+ * filesystem, not on application code — atomic on local POSIX filesystems
+ * (good enough; the workspace clone is also machine-local).
+ *
+ * Known limitation: state is machine-local. A scan started on machine A and
+ * next on machine B will look like a first run.
+ */
+export interface LockHandle {
+    release: () => void;
+}
+export interface ScanStateModule<T extends object> {
+    load: (productId: string) => T;
+    save: (productId: string, state: T) => void;
+    /** Merge `patch` into the stored state. Fields not mentioned are preserved. */
+    update: (productId: string, patch: Partial<T>) => T;
+    /**
+     * Acquire an exclusive lock for this product's state. Returns null if held.
+     * Stale locks older than `staleAfterMs` (default 1h) are reclaimed.
+     */
+    acquireLock: (productId: string, staleAfterMs?: number) => LockHandle | null;
+}
+export interface CreateScanStateModuleOptions {
+    /** Subdirectory under ~/.edsger/. Example: 'find-bugs-state'. */
+    dirName: string;
+}
+export declare function createScanStateModule<T extends object>(opts: CreateScanStateModuleOptions): ScanStateModule<T>;

package/dist/phases/find-shared/scan-state.js

@@ -0,0 +1,112 @@
+/**
+ * Per-product scan state, generic across the find-* phases. Each phase has
+ * its own state schema (find-bugs tracks a commit sha, find-features tracks
+ * the most-recent-seen feedback id, etc.) so the type is parametric, but the
+ * file layout, atomic-write, and lock semantics are identical and live here.
+ *
+ * Storage layout: `~/.edsger/<dirName>/<productId>.json` plus a sibling
+ * `.lock` file. The lockfile uses O_EXCL so concurrent acquirers race on the
+ * filesystem, not on application code — atomic on local POSIX filesystems
+ * (good enough; the workspace clone is also machine-local).
+ *
+ * Known limitation: state is machine-local. A scan started on machine A and
+ * next on machine B will look like a first run.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const DEFAULT_STALE_AFTER_MS = 60 * 60 * 1000;
+export function createScanStateModule(opts) {
+    const { dirName } = opts;
+    // Resolve at call time, not module-load time, so test setups that swap
+    // process.env.HOME between cases see the change.
+    function stateDir() {
+        return join(homedir(), '.edsger', dirName);
+    }
+    function safeProductId(productId) {
+        return productId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    }
+    function statePath(productId) {
+        return join(stateDir(), `${safeProductId(productId)}.json`);
+    }
+    function lockPath(productId) {
+        return join(stateDir(), `${safeProductId(productId)}.lock`);
+    }
+    function ensureStateDir() {
+        const dir = stateDir();
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    function load(productId) {
+        const p = statePath(productId);
+        if (!existsSync(p)) {
+            return {};
+        }
+        try {
+            const raw = readFileSync(p, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Atomic write: stage to a tempfile, then rename. */
+    function save(productId, state) {
+        ensureStateDir();
+        const finalPath = statePath(productId);
+        const tmpPath = `${finalPath}.${process.pid}.tmp`;
+        writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+        renameSync(tmpPath, finalPath);
+    }
+    function update(productId, patch) {
+        const merged = { ...load(productId), ...patch };
+        save(productId, merged);
+        return merged;
+    }
+    function acquireLock(productId, staleAfterMs = DEFAULT_STALE_AFTER_MS) {
+        ensureStateDir();
+        const lock = lockPath(productId);
+        if (existsSync(lock)) {
+            try {
+                const raw = readFileSync(lock, 'utf-8');
+                const parsed = JSON.parse(raw);
+                const age = Date.now() - new Date(parsed.acquiredAt ?? 0).getTime();
+                if (age < staleAfterMs) {
+                    return null;
+                }
+                // Stale or corrupt — reclaim. Only reachable if a previous run died
+                // without releasing (SIGKILL, OOM).
+                rmSync(lock, { force: true });
+            }
+            catch {
+                rmSync(lock, { force: true });
+            }
+        }
+        try {
+            // `flag: 'wx'` = open with O_CREAT | O_EXCL — atomic against a racing
+            // peer, and writeFileSync(path, ...) closes the fd internally so no
+            // manual closeSync is needed (vs. the openSync + writeFileSync(fd)
+            // form, which leaks the fd).
+            writeFileSync(lock, JSON.stringify({
+                acquiredAt: new Date().toISOString(),
+                pid: process.pid,
+            }), { flag: 'wx' });
+            return {
+                release: () => {
+                    try {
+                        unlinkSync(lock);
+                    }
+                    catch {
+                        // Already gone — fine.
+                    }
+                },
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    return { load, save, update, acquireLock };
+}

package/dist/phases/find-smells/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Find-smells phase: clone the product's repo, ask Claude to audit code for
+ * code smells (refactor candidates, perf cliffs, dead code, etc.), and file
+ * each new finding as an issue. Subsequent runs are incremental, scoped to
+ * commits since the previous successful scan.
+ *
+ * Companion to find-bugs (real defects) and find-features (missing user
+ * capability). The three phases share the same workspace + state pattern.
+ */
+import { type SmellCategory } from './types.js';
+export interface FindSmellsOptions {
+    productId: string;
+    githubToken: string;
+    owner: string;
+    repo: string;
+    /** Force a full scan even if previous-scan state exists. */
+    full?: boolean;
+    /** Branch to scan; defaults to the repo's default branch. */
+    branch?: string;
+    /** Upper bound on files the auditor may Read. Keeps token cost predictable. */
+    maxFiles?: number;
+    /**
+     * Optional category filter. Agent is asked to honour it via the prompt
+     * AND its output is re-filtered after parsing — both are required because
+     * the agent can't be trusted to obey perfectly.
+     */
+    categories?: SmellCategory[];
+    verbose?: boolean;
+}
+export interface FindSmellsResult {
+    status: 'success' | 'error';
+    message: string;
+    scannedCommitSha?: string;
+    smellsFound?: number;
+    issuesCreated?: number;
+    /** Findings the agent passed off to find-bugs (not filed by this run). */
+    deferredToBugs?: number;
+    /** Findings the agent passed off to find-features (not filed by this run). */
+    deferredToFeatures?: number;
+    summary?: string;
+}
+/** Single source of truth — referenced by the CLI help string too. */
+export declare const DEFAULT_MAX_FILES = 200;
+/**
+ * Scan a product's repository for code smells and file each new finding as an issue.
+ */
+export declare function scanForSmells(options: FindSmellsOptions): Promise<FindSmellsResult>;