edsger 0.54.0 → 0.55.0

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

@@ -0,0 +1,248 @@
+/**
+ * Find-architecture phase: clone the product's repo, ask Claude to audit the
+ * codebase for architectural problems and improvement opportunities, 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), find-features (missing user
+ * capability), and find-smells (local code-level improvements). All four
+ * phases share the same workspace + state pattern.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, syncRepoToRef, } from '../../workspace/workspace-manager.js';
+import { detectDefaultBranch, gitRevParse, isAncestor, listChangedPaths, } 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 { createFindArchitectureSystemPrompt, createFindArchitectureUserPrompt, } from './prompts.js';
+import { acquireFindArchitectureLock, loadFindArchitectureState, updateFindArchitectureState, } from './state.js';
+import { isScanResult, } from './types.js';
+const WORKSPACE_KEY = 'find-architecture';
+/** Single source of truth — referenced by the CLI help string too. */
+export const DEFAULT_MAX_FILES = 200;
+/**
+ * Upper bound on turns for the in-CLI Claude session. Architectural audits
+ * traverse imports and follow boundaries across the repo, so they need at
+ * least as much headroom as find-bugs / find-smells.
+ */
+const MAX_TURNS = 200;
+/**
+ * Scan a product's repository for architectural concerns and file each new
+ * finding as an issue.
+ */
+// eslint-disable-next-line complexity
+export async function scanForArchitecture(options) {
+    const { productId, githubToken, owner, repo, full, maxFiles, verbose } = options;
+    logInfo(`Starting architecture scan for product ${productId} (${owner}/${repo})`);
+    const lock = acquireFindArchitectureLock(productId);
+    if (!lock) {
+        logWarning(`Another architecture scan is already in progress for product ${productId}; skipping.`);
+        return {
+            status: 'error',
+            message: 'Another architecture scan is already in progress for this product',
+        };
+    }
+    let repoPath;
+    let scanSucceeded = false;
+    try {
+        updateFindArchitectureState(productId, {
+            lastAttemptedAt: new Date().toISOString(),
+        });
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, owner, repo, githubToken));
+        const branch = options.branch ?? detectDefaultBranch(repoPath);
+        logInfo(`Syncing ${owner}/${repo} to branch ${branch}`);
+        syncRepoToRef(repoPath, { branch }, githubToken);
+        const headSha = gitRevParse(repoPath, 'HEAD');
+        const state = loadFindArchitectureState(productId);
+        const baseSha = full ? undefined : state.lastScannedCommitSha;
+        let scope = 'full';
+        let changedPaths;
+        if (baseSha && baseSha !== headSha) {
+            const sameTree = isAncestor(repoPath, baseSha, headSha);
+            if (sameTree) {
+                scope = 'incremental';
+                changedPaths = listChangedPaths(repoPath, baseSha, headSha);
+                logInfo(`Incremental scan: ${changedPaths.length} files changed since ${baseSha.slice(0, 8)}`);
+                if (changedPaths.length === 0) {
+                    logSuccess('No code changes since last scan; nothing to do.');
+                    updateFindArchitectureState(productId, {
+                        lastScannedCommitSha: headSha,
+                        lastScannedAt: new Date().toISOString(),
+                        lastError: undefined,
+                    });
+                    scanSucceeded = true;
+                    return {
+                        status: 'success',
+                        message: 'No changes since last scan',
+                        scannedCommitSha: headSha,
+                        findingsFound: 0,
+                        issuesCreated: 0,
+                    };
+                }
+            }
+            else {
+                logWarning(`Last scanned sha ${baseSha.slice(0, 8)} not reachable from HEAD; falling back to full scan.`);
+            }
+        }
+        else if (baseSha === headSha) {
+            logSuccess('HEAD unchanged since last scan; nothing to do.');
+            updateFindArchitectureState(productId, {
+                lastScannedAt: new Date().toISOString(),
+                lastError: undefined,
+            });
+            scanSucceeded = true;
+            return {
+                status: 'success',
+                message: 'HEAD unchanged since last scan',
+                scannedCommitSha: headSha,
+                findingsFound: 0,
+                issuesCreated: 0,
+            };
+        }
+        const product = await fetchProductBasics(productId);
+        const existingIssues = await fetchOpenIssues(productId);
+        logInfo(`Loaded ${existingIssues.length} existing issues for dedup context`);
+        const systemPrompt = createFindArchitectureSystemPrompt();
+        const userPrompt = createFindArchitectureUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            scope,
+            baseSha,
+            headSha,
+            changedPaths,
+            maxFiles: maxFiles ?? DEFAULT_MAX_FILES,
+            existingIssues: existingIssues.map((i) => ({
+                id: i.id,
+                name: i.name,
+                description: i.description,
+            })),
+        });
+        let lastAssistantResponse = '';
+        let scanResult = null;
+        logInfo('Running Claude architecture audit...');
+        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, 'scan_result');
+            if (isScanResult(parsed)) {
+                scanResult = parsed;
+            }
+            else if (message.subtype !== 'success') {
+                logError(`Audit incomplete: ${message.subtype}`);
+            }
+        }
+        if (!scanResult) {
+            const msg = 'Audit failed: could not parse a scan_result from the agent';
+            updateFindArchitectureState(productId, { lastError: msg });
+            return {
+                status: 'error',
+                message: msg,
+            };
+        }
+        const { summary, findings } = scanResult;
+        logInfo(`Audit produced ${findings.length} candidate findings. ${summary}`);
+        const deferredBugs = scanResult.deferred_to_bugs ?? [];
+        const deferredFeatures = scanResult.deferred_to_features ?? [];
+        const deferredSmells = scanResult.deferred_to_smells ?? [];
+        logDeferred(deferredBugs, 'find-bugs', productId);
+        logDeferred(deferredFeatures, 'find-features', productId);
+        logDeferred(deferredSmells, 'find-smells', productId);
+        let created = 0;
+        for (const finding of findings) {
+            const issueId = await createIssueForFinding(productId, finding);
+            if (issueId) {
+                created++;
+                logSuccess(`Filed issue ${issueId}: ${finding.title}`);
+            }
+        }
+        updateFindArchitectureState(productId, {
+            lastScannedCommitSha: headSha,
+            lastScannedAt: new Date().toISOString(),
+            lastError: undefined,
+        });
+        scanSucceeded = true;
+        return {
+            status: 'success',
+            message: `Filed ${created} of ${findings.length} candidate architecture findings (${deferredBugs.length} deferred to bugs, ${deferredFeatures.length} to features, ${deferredSmells.length} to smells)`,
+            scannedCommitSha: headSha,
+            findingsFound: findings.length,
+            issuesCreated: created,
+            deferredToBugs: deferredBugs.length,
+            deferredToFeatures: deferredFeatures.length,
+            deferredToSmells: deferredSmells.length,
+            summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Architecture scan failed: ${errorMessage}`);
+        updateFindArchitectureState(productId, { lastError: errorMessage });
+        return {
+            status: 'error',
+            message: `Architecture scan failed: ${errorMessage}`,
+        };
+    }
+    finally {
+        if (scanSucceeded) {
+            cleanupIssueRepo(repoPath);
+        }
+        lock.release();
+    }
+}
+function logDeferred(deferred, siblingPhase, productId) {
+    if (deferred.length === 0) {
+        return;
+    }
+    logInfo(`${deferred.length} finding(s) deferred to ${siblingPhase} — run \`edsger ${siblingPhase} ${productId}\` to pick them up:`);
+    for (const d of deferred) {
+        const loc = d.file ? ` (${d.file}${d.line ? `:${d.line}` : ''})` : '';
+        logInfo(`  • ${d.title}${loc} — ${d.reason}`);
+    }
+}
+async function createIssueForFinding(productId, finding) {
+    return createIssue({
+        productId,
+        title: finding.title,
+        description: formatIssueDescription(finding),
+    });
+}
+function formatIssueDescription(finding) {
+    const location = finding.line
+        ? `${finding.file}:${finding.line}`
+        : finding.file;
+    const lines = [
+        `**Severity**: ${finding.severity}`,
+        `**Concern**: ${finding.concern}`,
+        `**Location**: \`${location}\``,
+    ];
+    if (finding.related_files && finding.related_files.length > 0) {
+        lines.push(`**Related**: ${finding.related_files.map((f) => `\`${f}\``).join(', ')}`);
+    }
+    lines.push('', finding.description, '', '---');
+    lines.push('_Filed automatically by `edsger find-architecture`._');
+    return lines.join('\n');
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Prompts for the find-architecture phase. The agent runs with cwd=repo
+ * checkout and has Read/Grep/Glob/Bash available — it explores the code
+ * itself rather than receiving a pre-baked diff.
+ *
+ * Boundary against neighbouring phases:
+ *   - find-bugs handles real defects (security, correctness, races, etc.)
+ *   - find-features handles missing user-facing capability
+ *   - find-smells handles local code-level improvements (refactor, dead code,
+ *     readability, perf cliffs, type-safety gaps in a single function/file)
+ *   - find-architecture (this phase) handles structural problems that span
+ *     multiple files: module boundaries, layering, coupling, cycles, missing
+ *     or duplicated abstractions, responsibility creep, cross-cutting concerns.
+ */
+export declare function createFindArchitectureSystemPrompt(): string;
+export interface FindArchitectureUserPromptParams {
+    productName: string;
+    productDescription?: string;
+    scope: 'full' | 'incremental';
+    baseSha?: string;
+    headSha: string;
+    changedPaths?: string[];
+    existingIssues: {
+        id: string;
+        name: string;
+        description?: string;
+    }[];
+    /** Upper bound on files the auditor may Read. Keeps token cost predictable. */
+    maxFiles?: number;
+}
+export declare function createFindArchitectureUserPrompt(params: FindArchitectureUserPromptParams): string;

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

@@ -0,0 +1,128 @@
+/**
+ * Prompts for the find-architecture phase. The agent runs with cwd=repo
+ * checkout and has Read/Grep/Glob/Bash available — it explores the code
+ * itself rather than receiving a pre-baked diff.
+ *
+ * Boundary against neighbouring phases:
+ *   - find-bugs handles real defects (security, correctness, races, etc.)
+ *   - find-features handles missing user-facing capability
+ *   - find-smells handles local code-level improvements (refactor, dead code,
+ *     readability, perf cliffs, type-safety gaps in a single function/file)
+ *   - find-architecture (this phase) handles structural problems that span
+ *     multiple files: module boundaries, layering, coupling, cycles, missing
+ *     or duplicated abstractions, responsibility creep, cross-cutting concerns.
+ */
+export function createFindArchitectureSystemPrompt() {
+    return `You are a senior staff engineer auditing a codebase for **architectural problems and improvement opportunities**. You have read-only access via Read/Grep/Glob and may run shallow Bash queries (e.g. \`git log\`, \`wc -l\`, \`grep\`) to navigate.
+
+**What counts as an architectural finding worth filing**:
+1. **Layering violations**: lower layers reaching into upper layers, UI directly hitting persistence, infrastructure leaking into domain
+2. **Coupling**: modules that know too much about each other's internals, leaky abstractions, pervasive shared mutable state
+3. **Cohesion**: modules that mix unrelated responsibilities; "god" files/services that have grown into multiple things
+4. **Cyclic dependencies**: import cycles between modules / packages
+5. **Boundary problems**: unclear public API surfaces, internal-only types exported, missing seams that make testing hard
+6. **Duplicated abstractions**: two parallel implementations of the same concept (two HTTP clients, two auth flows, two cache layers)
+7. **Missing abstraction**: same orchestration pattern hand-rolled in N call sites, no shared helper / interface
+8. **Responsibility creep**: a service / component that started focused and now does five things
+9. **Cross-cutting concerns**: logging, auth, retries, error handling implemented inconsistently across modules
+10. **Inconsistency**: same problem solved different ways in different parts of the codebase, drifting conventions
+11. **Scalability shape**: data-flow / control-flow patterns that won't survive the next obvious axis of growth
+
+**What does NOT count** (skip these — wrong tool):
+- Real bugs (security holes, logic errors, races, data corruption) — those belong in \`edsger find-bugs\`. **Don't drop them silently — list them in \`deferred_to_bugs\`.**
+- Missing user-facing features or workflows — those belong in \`edsger find-features\`. **List them in \`deferred_to_features\`.**
+- Local code smells confined to a single function/file (refactor candidates, dead code, type-safety gaps, readability issues) — those belong in \`edsger find-smells\`. **List them in \`deferred_to_smells\`.**
+- Pure style / formatting / lint issues
+- Hypothetical future-scaling concerns with no current evidence
+- "Could be more idiomatic" rewrites with no concrete benefit
+
+**Discipline**:
+- Be concrete: cite the exact files, modules, or import paths involved. If you flag a cycle, name every file in the cycle. If you flag a layering violation, quote the offending import line.
+- Architectural findings span multiple files almost by definition — use \`related_files\` to enumerate them. The \`file\` field should be the most useful single anchor for a reader.
+- Be conservative: if you can't articulate the *concrete cost* of the current shape (testability blocked, change-amplification, repeated bugs in the same area, slow onboarding), skip it.
+- Severity rubric:
+  - high = actively blocking work (cycles preventing builds, coupling causing repeated regressions, missing seams blocking testing the team is clearly trying to do)
+  - medium = clear structural improvement that pays back across many future changes
+  - low = directional nudge; only file if the fix is small and obvious
+- **Deduplication**: you will be given the list of existing open issues. Skip any finding that overlaps. Better to under-report than spam duplicates.
+
+**CRITICAL — Output Format**:
+End your response with a single JSON code block in this exact shape:
+
+\`\`\`json
+{
+  "scan_result": {
+    "summary": "Reviewed N files / M modules in <scope>; found X architectural findings (Y high, Z medium).",
+    "scanned_commit_sha": "<the HEAD sha you scanned>",
+    "findings": [
+      {
+        "title": "Short, action-oriented title (under 80 chars)",
+        "description": "## What\\nWhat the architectural problem is, with the offending imports/snippets quoted.\\n\\n## Why it matters\\nConcrete cost of the current shape (testability, change-amplification, regression history, onboarding friction).\\n\\n## Suggested change\\nA specific structural change — extracted module, inverted dependency, new boundary, etc.",
+        "file": "relative/path/from/repo/root.ts",
+        "line": 42,
+        "related_files": ["other/file/in/the/cycle.ts", "another/layer/violator.ts"],
+        "severity": "medium",
+        "concern": "layering",
+        "dedup_signature": "ui-layer-imports-db-client"
+      }
+    ],
+    "deferred_to_bugs": [
+      { "title": "...", "reason": "...", "file": "...", "line": 100 }
+    ],
+    "deferred_to_features": [
+      { "title": "...", "reason": "...", "file": "..." }
+    ],
+    "deferred_to_smells": [
+      { "title": "...", "reason": "...", "file": "..." }
+    ]
+  }
+}
+\`\`\`
+
+If you find nothing worth filing, still emit the JSON with an empty \`findings\` array. The \`deferred_to_*\` arrays are optional — omit them or send \`[]\` if there's nothing to hand off.`;
+}
+export function createFindArchitectureUserPrompt(params) {
+    const { productName, productDescription, scope, baseSha, headSha, changedPaths, existingIssues, maxFiles, } = params;
+    const productBlock = productDescription
+        ? `**Product**: ${productName}\n${productDescription}`
+        : `**Product**: ${productName}`;
+    const scopeBlock = scope === 'incremental' && baseSha
+        ? `**Scope**: incremental scan focused on changes between ${baseSha} and ${headSha}, but architectural findings are inherently structural — feel free to follow imports out of the diff to confirm boundaries / cycles. Use \`git diff --name-only ${baseSha}..${headSha}\` to enumerate the entry points.`
+        : `**Scope**: full repository scan at ${headSha}. Use Glob to enumerate source modules. Skip vendored code, build output, generated files, lockfiles, and \`node_modules\`. Map out the top-level module structure first, then drill into suspected hotspots.`;
+    const filesHint = changedPaths && changedPaths.length > 0
+        ? `\n**Changed files in this range** (${changedPaths.length}):\n${changedPaths
+            .slice(0, 200)
+            .map((p) => `- ${p}`)
+            .join('\n')}${changedPaths.length > 200 ? `\n…and ${changedPaths.length - 200} more.` : ''}`
+        : '';
+    const issuesBlock = existingIssues.length === 0
+        ? 'No existing open issues for this product — every finding is new.'
+        : `**Existing open issues** (${existingIssues.length}) — skip findings that overlap with any of these:\n${existingIssues
+            .map((i) => `- [${i.id}] ${i.name}${i.description ? `\n  ${truncate(i.description, 200)}` : ''}`)
+            .join('\n')}`;
+    const budgetBlock = typeof maxFiles === 'number' && maxFiles > 0
+        ? `\n**Budget**: Read at most ${maxFiles} files. Prioritise top-level module entry points, package boundaries, shared infrastructure (clients, services, framework glue), and files most-imported by the rest of the repo. If the scope is larger than the budget, stop when you hit it and report truncation in \`summary\`.`
+        : '';
+    return `${productBlock}
+
+${scopeBlock}${filesHint}${budgetBlock}
+
+${issuesBlock}
+
+## How to work
+
+1. Map the top-level module structure first (\`ls\`, \`Glob\` on top-level dirs). Identify the natural layers / boundaries the codebase is trying to maintain.
+2. For each suspected concern (layering violation, cycle, coupling hotspot, duplicated abstraction, responsibility creep), follow imports / call sites with Grep + Read to confirm before filing.
+3. When you suspect a structural issue, articulate the *concrete cost* of the current shape. If you can't name the cost, drop it.
+4. If something looks like a real bug, a missing user feature, or a local code smell — drop it from this scan and route it via the appropriate \`deferred_to_*\` array.
+5. Cross-check every candidate against the existing issues list. Drop overlaps.
+6. 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-architecture/state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Per-product scan state for find-architecture. Storage at
+ * `~/.edsger/find-architecture-state/<productId>.json`.
+ *
+ * Same schema shape as find-smells / find-bugs (incremental sha tracking) —
+ * file/lock machinery shared via createScanStateModule. Kept as a sibling
+ * state file so an architecture scan can run alongside other find-* scans
+ * without contending on the same lock.
+ */
+import { type LockHandle } from '../find-shared/scan-state.js';
+export type { LockHandle };
+export interface FindArchitectureState {
+    lastScannedCommitSha?: string;
+    lastScannedAt?: string;
+    lastAttemptedAt?: string;
+    lastError?: string;
+}
+export declare const loadFindArchitectureState: (productId: string) => FindArchitectureState;
+export declare const saveFindArchitectureState: (productId: string, state: FindArchitectureState) => void;
+export declare const updateFindArchitectureState: (productId: string, patch: Partial<FindArchitectureState>) => FindArchitectureState;
+export declare const acquireFindArchitectureLock: (productId: string, staleAfterMs?: number) => LockHandle | null;

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

@@ -0,0 +1,17 @@
+/**
+ * Per-product scan state for find-architecture. Storage at
+ * `~/.edsger/find-architecture-state/<productId>.json`.
+ *
+ * Same schema shape as find-smells / find-bugs (incremental sha tracking) —
+ * file/lock machinery shared via createScanStateModule. Kept as a sibling
+ * state file so an architecture scan can run alongside other find-* scans
+ * without contending on the same lock.
+ */
+import { createScanStateModule, } from '../find-shared/scan-state.js';
+const m = createScanStateModule({
+    dirName: 'find-architecture-state',
+});
+export const loadFindArchitectureState = m.load;
+export const saveFindArchitectureState = m.save;
+export const updateFindArchitectureState = m.update;
+export const acquireFindArchitectureLock = m.acquireLock;

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

@@ -0,0 +1,55 @@
+/**
+ * Types for the find-architecture phase.
+ *
+ * Where find-smells covers local "the code would be better if changed" findings
+ * (refactor candidates, dead code, perf cliffs, etc.), this phase zooms out to
+ * **architectural** problems and improvements — module boundaries, layering,
+ * coupling, dependency direction, responsibility creep, missing or duplicated
+ * abstractions, cross-cutting concerns. Findings span multiple files by nature.
+ */
+export type ArchitectureSeverity = 'high' | 'medium' | 'low';
+/**
+ * Authoritative list of allowed concern types. Kept as a `const` array so the
+ * type and the runtime whitelist can never drift apart.
+ */
+export declare const ARCHITECTURE_CONCERNS: readonly ["layering", "coupling", "cohesion", "cyclic_dependency", "boundary", "duplication", "missing_abstraction", "responsibility_creep", "cross_cutting", "inconsistency", "scalability", "other"];
+export type ArchitectureConcern = (typeof ARCHITECTURE_CONCERNS)[number];
+export declare function isArchitectureConcern(value: unknown): value is ArchitectureConcern;
+export interface ArchitectureFinding {
+    title: string;
+    description: string;
+    /** Primary anchor file or module path. */
+    file: string;
+    /** Optional line in the primary file. */
+    line?: number;
+    /** Other files involved in the finding (cycle members, layer crossers, etc.). */
+    related_files?: string[];
+    severity: ArchitectureSeverity;
+    concern: ArchitectureConcern;
+    /** Stable signature for log/audit; not used for storage dedup. */
+    dedup_signature?: string;
+}
+/**
+ * A finding the agent saw but is handing off to a sibling phase rather than
+ * filing as an architecture issue. Surfaced in the run log so the user knows
+ * the work wasn't silently lost.
+ */
+export interface DeferredFinding {
+    title: string;
+    reason: string;
+    file?: string;
+    line?: number;
+}
+export declare function isDeferredFinding(value: unknown): value is DeferredFinding;
+export interface ScanResult {
+    summary: string;
+    scanned_commit_sha?: string;
+    findings: ArchitectureFinding[];
+    /** Findings the agent thinks belong in `edsger find-bugs`. */
+    deferred_to_bugs?: DeferredFinding[];
+    /** Findings the agent thinks belong in `edsger find-features`. */
+    deferred_to_features?: DeferredFinding[];
+    /** Findings the agent thinks belong in `edsger find-smells`. */
+    deferred_to_smells?: DeferredFinding[];
+}
+export declare function isScanResult(value: unknown): value is ScanResult;

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

@@ -0,0 +1,69 @@
+/**
+ * Types for the find-architecture phase.
+ *
+ * Where find-smells covers local "the code would be better if changed" findings
+ * (refactor candidates, dead code, perf cliffs, etc.), this phase zooms out to
+ * **architectural** problems and improvements — module boundaries, layering,
+ * coupling, dependency direction, responsibility creep, missing or duplicated
+ * abstractions, cross-cutting concerns. Findings span multiple files by nature.
+ */
+/**
+ * Authoritative list of allowed concern types. Kept as a `const` array so the
+ * type and the runtime whitelist can never drift apart.
+ */
+export const ARCHITECTURE_CONCERNS = [
+    'layering',
+    'coupling',
+    'cohesion',
+    'cyclic_dependency',
+    'boundary',
+    'duplication',
+    'missing_abstraction',
+    'responsibility_creep',
+    'cross_cutting',
+    'inconsistency',
+    'scalability',
+    'other',
+];
+export function isArchitectureConcern(value) {
+    return (typeof value === 'string' &&
+        ARCHITECTURE_CONCERNS.includes(value));
+}
+export function isDeferredFinding(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    return typeof v.title === 'string' && typeof v.reason === 'string';
+}
+export function isScanResult(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    if (typeof v.summary !== 'string' || !Array.isArray(v.findings)) {
+        return false;
+    }
+    const findingsOk = v.findings.every((f) => f &&
+        typeof f === 'object' &&
+        typeof f.title === 'string' &&
+        typeof f.description === 'string' &&
+        typeof f.file === 'string');
+    if (!findingsOk) {
+        return false;
+    }
+    for (const key of [
+        'deferred_to_bugs',
+        'deferred_to_features',
+        'deferred_to_smells',
+    ]) {
+        const arr = v[key];
+        if (arr === undefined) {
+            continue;
+        }
+        if (!Array.isArray(arr) || !arr.every(isDeferredFinding)) {
+            return false;
+        }
+    }
+    return true;
+}

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

@@ -6,7 +6,7 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
 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 { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, syncRepoToRef, } from '../../workspace/workspace-manager.js';
 import { detectDefaultBranch, gitRevParse, isAncestor, listChangedPaths, } from '../find-shared/git.js';
 import { createIssue, fetchOpenIssues, fetchProductBasics, } from '../find-shared/mcp.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
@@ -42,15 +42,18 @@ export async function scanForBugs(options) {
             message: 'Another bug scan is already in progress for this product',
         };
     }
+    let repoPath;
+    let scanSucceeded = false;
     try {
         updateFindBugsState(productId, {
             lastAttemptedAt: new Date().toISOString(),
         });
         const workspaceRoot = ensureWorkspaceDir();
-        // Reuse a single workspace per product so incremental scans don't re-clone.
+        // Each run re-clones into a per-product directory and removes it on
+        // success. Incremental scope is recovered from the persisted state file
+        // (~/.edsger/find-bugs-state/<productId>.json), not from the workspace.
         const repoKey = `${WORKSPACE_KEY}-${productId}`;
-        const cloned = cloneIssueRepo(workspaceRoot, repoKey, owner, repo, githubToken);
-        const { repoPath } = cloned;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, owner, repo, githubToken));
         const branch = options.branch ?? detectDefaultBranch(repoPath);
         logInfo(`Syncing ${owner}/${repo} to branch ${branch}`);
         syncRepoToRef(repoPath, { branch }, githubToken);
@@ -72,6 +75,7 @@ export async function scanForBugs(options) {
                         lastScannedAt: new Date().toISOString(),
                         lastError: undefined,
                     });
+                    scanSucceeded = true;
                     return {
                         status: 'success',
                         message: 'No changes since last scan',
@@ -87,6 +91,7 @@ export async function scanForBugs(options) {
         }
         else if (baseSha === headSha) {
             logSuccess('HEAD unchanged since last scan; nothing to do.');
+            scanSucceeded = true;
             return {
                 status: 'success',
                 message: 'HEAD unchanged since last scan',
@@ -171,6 +176,7 @@ export async function scanForBugs(options) {
             lastScannedAt: new Date().toISOString(),
             lastError: undefined,
         });
+        scanSucceeded = true;
         return {
             status: 'success',
             message: `Filed ${created} of ${bugs.length} candidate bugs`,
@@ -190,6 +196,9 @@ export async function scanForBugs(options) {
         };
     }
     finally {
+        if (scanSucceeded) {
+            cleanupIssueRepo(repoPath);
+        }
         lock.release();
     }
 }