edsger 0.75.1 → 0.77.0

package/dist/phases/api-docs/mcp-server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * In-process MCP server exposing a single api-docs tool:
+ *
+ *   - submit_api_docs  capture the generated API reference (Markdown + an
+ *                      optional OpenAPI document + summary + endpoint count)
+ *
+ * Unlike the recipes toolkit (which commits each mutation as it goes) the
+ * api-docs artifact is a single document, so the tool just captures into an
+ * in-memory buffer. The orchestrator persists the captured artifact and flips
+ * the run row to success once the agent's turn ends — a clean all-or-nothing
+ * write that can't leave a half-written reference behind.
+ */
+import { z } from 'zod';
+import { type ApiDocsArtifact } from './types.js';
+export interface ApiDocsCaptureState {
+    captured: ApiDocsArtifact | null;
+}
+export declare function createApiDocsCaptureState(): ApiDocsCaptureState;
+export declare function createSubmitApiDocsTool(capture: ApiDocsCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    markdown: z.ZodString;
+    summary: z.ZodString;
+    endpoint_count: z.ZodNumber;
+    openapi_json: z.ZodOptional<z.ZodString>;
+}>;
+export declare function createApiDocsMcpServer(capture: ApiDocsCaptureState): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/api-docs/mcp-server.js

@@ -0,0 +1,82 @@
+/**
+ * In-process MCP server exposing a single api-docs tool:
+ *
+ *   - submit_api_docs  capture the generated API reference (Markdown + an
+ *                      optional OpenAPI document + summary + endpoint count)
+ *
+ * Unlike the recipes toolkit (which commits each mutation as it goes) the
+ * api-docs artifact is a single document, so the tool just captures into an
+ * in-memory buffer. The orchestrator persists the captured artifact and flips
+ * the run row to success once the agent's turn ends — a clean all-or-nothing
+ * write that can't leave a half-written reference behind.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { API_DOCS_MARKDOWN_MAX, API_DOCS_SUMMARY_MAX, } from './types.js';
+export function createApiDocsCaptureState() {
+    return { captured: null };
+}
+function textError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+function textOk(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+export function createSubmitApiDocsTool(capture) {
+    return tool('submit_api_docs', 'Submit the final API reference for this repository. Call this exactly once, at the end, after you have explored the codebase. Provide a Markdown reference (always) and, when the repo exposes an HTTP API, a complete OpenAPI 3.x document as a JSON string.', {
+        markdown: z
+            .string()
+            .min(1)
+            .max(API_DOCS_MARKDOWN_MAX)
+            .describe('The human-readable API reference in Markdown. Document each endpoint / exported interface: method + path (or signature), purpose, parameters, request/response shapes, auth, and an example where useful.'),
+        summary: z
+            .string()
+            .min(1)
+            .max(API_DOCS_SUMMARY_MAX)
+            .describe('One-paragraph overview of the API surface (what it exposes and how it is consumed).'),
+        endpoint_count: z
+            .number()
+            .int()
+            .min(0)
+            .describe('How many distinct endpoints / operations the reference documents (0 if the repo exposes no callable API surface).'),
+        openapi_json: z
+            .string()
+            .optional()
+            .describe('A complete OpenAPI 3.x document serialized as a JSON string. Omit when the repository exposes no HTTP API (e.g. a library or CLI).'),
+    }, async (args) => {
+        let openapi = null;
+        if (args.openapi_json && args.openapi_json.trim()) {
+            try {
+                const parsed = JSON.parse(args.openapi_json);
+                if (typeof parsed !== 'object' ||
+                    parsed === null ||
+                    Array.isArray(parsed)) {
+                    return textError('openapi_json must be a JSON object (an OpenAPI document), not an array or scalar.');
+                }
+                openapi = parsed;
+            }
+            catch (error) {
+                return textError(`openapi_json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        capture.captured = {
+            openapi,
+            markdown: args.markdown,
+            summary: args.summary.trim(),
+            endpointCount: args.endpoint_count,
+        };
+        return textOk(`API docs captured (${args.endpoint_count} endpoint${args.endpoint_count === 1 ? '' : 's'}${openapi ? ', with OpenAPI spec' : ''}). You can end your turn now.`);
+    });
+}
+export function createApiDocsMcpServer(capture) {
+    return createSdkMcpServer({
+        name: 'api-docs',
+        version: '1.0.0',
+        tools: [createSubmitApiDocsTool(capture)],
+    });
+}

package/dist/phases/api-docs/prompts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Prompts for the api-docs phase.
+ *
+ * Agent's job: explore the cloned repository, work out what API surface it
+ * exposes (HTTP/REST routes, RPC handlers, edge functions, exported SDK
+ * functions, CLI commands — whatever the repo actually offers), and produce
+ * an API reference. Output is submitted via the single `submit_api_docs` MCP
+ * tool — no fenced JSON, no chat summary.
+ */
+export interface ApiDocsPromptContext {
+    repoName: string;
+    repoDescription?: string;
+    guidance?: string;
+}
+export declare function createApiDocsSystemPrompt(): string;
+export declare function createApiDocsUserPrompt(ctx: ApiDocsPromptContext): string;

package/dist/phases/api-docs/prompts.js

@@ -0,0 +1,65 @@
+/**
+ * Prompts for the api-docs phase.
+ *
+ * Agent's job: explore the cloned repository, work out what API surface it
+ * exposes (HTTP/REST routes, RPC handlers, edge functions, exported SDK
+ * functions, CLI commands — whatever the repo actually offers), and produce
+ * an API reference. Output is submitted via the single `submit_api_docs` MCP
+ * tool — no fenced JSON, no chat summary.
+ */
+export function createApiDocsSystemPrompt() {
+    return `You are a senior engineer writing the API reference for a codebase.
+
+The current working directory is a fresh clone of the repository. Use Glob/Grep/Read (and Bash for git/log when helpful) to explore it before writing anything.
+
+## Step 1 — Determine the API surface
+
+Repositories expose their API in different ways. Figure out which apply here (a repo may have more than one):
+- **HTTP / REST** — route definitions, controllers, request handlers (Express/Fastify/Next.js route handlers, Flask/FastAPI/Django, Spring, Go net/http, etc.).
+- **Action-routed / RPC functions** — e.g. serverless / edge functions dispatched by an \`action\` field on the body, gRPC services, tRPC routers.
+- **Library / SDK** — the public, exported functions/classes other code imports. Document the exported surface, not internal helpers.
+- **CLI** — the commands and flags the tool exposes.
+
+Do NOT assume it is REST. Read the code and document what is actually there.
+
+## Step 2 — Produce two artifacts
+
+1. **Markdown reference (always).** A clear, navigable reference. For each endpoint / operation / exported function document: its identifier (method + path, or signature), purpose, parameters (name, type, required, description), request body and response shapes, auth/permissions, and a short example where it helps. Group by resource/module. Note relative file paths so readers can jump to the source.
+
+2. **OpenAPI 3.x document (only when the repo exposes an HTTP API).** A complete, spec-valid OpenAPI document covering the HTTP endpoints — paths, methods, parameters, requestBody/response schemas under \`components.schemas\`, and security schemes. Omit this entirely for pure libraries or CLIs (there is nothing meaningful to put in an OpenAPI \`paths\` object).
+
+## Output protocol
+
+Submit your result with the \`submit_api_docs\` MCP tool — call it EXACTLY ONCE at the end:
+
+- \`markdown\` — the full Markdown reference.
+- \`summary\` — one paragraph describing the API surface.
+- \`endpoint_count\` — the number of distinct endpoints/operations you documented (0 for a non-callable surface).
+- \`openapi_json\` — the OpenAPI document as a JSON string, or omit it when there is no HTTP API.
+
+Do NOT paste the reference into chat. Do NOT wrap it in fenced code blocks in a message. Explore, then call the tool, then end your turn.
+
+## Rules
+
+- Ground everything in the actual source. Don't invent endpoints, parameters, or response fields. If something is ambiguous, describe what the code does and say so.
+- Keep the Markdown focused on the externally-callable surface. Don't document private/internal helpers as if they were API.
+- Prefer accuracy over completeness padding: a small repo gets a short, correct reference.`;
+}
+export function createApiDocsUserPrompt(ctx) {
+    const lines = [];
+    lines.push(`# Repository: ${ctx.repoName}`);
+    if (ctx.repoDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(ctx.repoDescription);
+    }
+    if (ctx.guidance && ctx.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(ctx.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repository, determine what API surface it exposes, and write its API reference. Then call `submit_api_docs` exactly once with the Markdown reference, a one-paragraph summary, the endpoint count, and (only if the repo exposes an HTTP API) the OpenAPI document as a JSON string. End your turn after submitting.');
+    return lines.join('\n');
+}

package/dist/phases/api-docs/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shapes the api-docs MCP tool accepts. The Zod schema lives in mcp-server.ts;
+ * these plain TS types are what the orchestrator / persistence helpers consume.
+ *
+ * Defensive caps mirror the DB CHECK constraints from
+ * 20260605000000_create_api_doc_runs.sql so the MCP tool can reject oversized
+ * output with an actionable message instead of a Postgres constraint violation.
+ */
+/** A spec-compliant OpenAPI document. Kept loose — the agent owns the shape. */
+export type OpenApiSpec = Record<string, unknown>;
+export interface ApiDocsArtifact {
+    /** Parsed OpenAPI document, or null when the repo exposes no HTTP API. */
+    openapi: OpenApiSpec | null;
+    /** Human-readable Markdown API reference (always produced). */
+    markdown: string;
+    /** One-paragraph overview for the tab header. */
+    summary: string;
+    /** Number of documented endpoints/operations (0 for non-HTTP surfaces). */
+    endpointCount: number;
+}
+export declare const API_DOCS_MARKDOWN_MAX = 200000;
+export declare const API_DOCS_SUMMARY_MAX = 1000;

package/dist/phases/api-docs/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shapes the api-docs MCP tool accepts. The Zod schema lives in mcp-server.ts;
+ * these plain TS types are what the orchestrator / persistence helpers consume.
+ *
+ * Defensive caps mirror the DB CHECK constraints from
+ * 20260605000000_create_api_doc_runs.sql so the MCP tool can reject oversized
+ * output with an actionable message instead of a Postgres constraint violation.
+ */
+export const API_DOCS_MARKDOWN_MAX = 200_000;
+export const API_DOCS_SUMMARY_MAX = 1000;

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

@@ -9,7 +9,10 @@
  * phases share the same workspace + state pattern.
  */
 export interface FindArchitectureOptions {
-    productId: string;
+    /** Product scope. Provide this OR repoId (repo-scoped scan). */
+    productId?: string;
+    /** Repository scope: scan a bare `repositories` row with no product. */
+    repoId?: string;
     githubToken: string;
     owner: string;
     repo: string;

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

@@ -12,8 +12,11 @@ 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 { resolveScanBase } from '../find-shared/baseline.js';
+import { resolveCustomRules } from '../find-shared/custom-rules.js';
 import { detectDefaultBranch, gitRevParse, isAncestor, listChangedPaths, } from '../find-shared/git.js';
-import { createIssue, fetchOpenIssues, fetchProductBasics, } from '../find-shared/mcp.js';
+import { createIssue, fetchOpenIssues, fetchOpenIssuesByRepo, fetchProductBasics, fetchRepositoryBasics, } from '../find-shared/mcp.js';
+import { resolveStackRulePacks } from '../find-shared/rule-config.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { createFindArchitectureSystemPrompt, createFindArchitectureUserPrompt, } from './prompts.js';
 import { acquireFindArchitectureLock, loadFindArchitectureState, updateFindArchitectureState, } from './state.js';
@@ -33,31 +36,35 @@ const MAX_TURNS = 200;
  */
 // 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);
+    const { productId, repoId, githubToken, owner, repo, full, maxFiles, verbose, } = options;
+    // State/lock/workspace are keyed by an opaque scope id so product and repo
+    // scans never collide; repo keys are prefixed to namespace them clearly.
+    const scopeId = productId ?? `repo-${repoId}`;
+    const scopeLabel = productId ? `product ${productId}` : `repository ${repoId}`;
+    logInfo(`Starting architecture scan for ${scopeLabel} (${owner}/${repo})`);
+    const lock = acquireFindArchitectureLock(scopeId);
     if (!lock) {
-        logWarning(`Another architecture scan is already in progress for product ${productId}; skipping.`);
+        logWarning(`Another architecture scan is already in progress for ${scopeLabel}; skipping.`);
         return {
             status: 'error',
-            message: 'Another architecture scan is already in progress for this product',
+            message: 'Another architecture scan is already in progress for this scope',
         };
     }
     let repoPath;
     let scanSucceeded = false;
     try {
-        updateFindArchitectureState(productId, {
+        updateFindArchitectureState(scopeId, {
             lastAttemptedAt: new Date().toISOString(),
         });
         const workspaceRoot = ensureWorkspaceDir();
-        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        const repoKey = `${WORKSPACE_KEY}-${scopeId}`;
         ({ 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;
+        const state = loadFindArchitectureState(scopeId);
+        const baseSha = await resolveScanBase({ productId, repoId }, { full, lastScannedSha: state.lastScannedCommitSha });
         let scope = 'full';
         let changedPaths;
         if (baseSha && baseSha !== headSha) {
@@ -68,7 +75,7 @@ export async function scanForArchitecture(options) {
                 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, {
+                    updateFindArchitectureState(scopeId, {
                         lastScannedCommitSha: headSha,
                         lastScannedAt: new Date().toISOString(),
                         lastError: undefined,
@@ -89,7 +96,7 @@ export async function scanForArchitecture(options) {
         }
         else if (baseSha === headSha) {
             logSuccess('HEAD unchanged since last scan; nothing to do.');
-            updateFindArchitectureState(productId, {
+            updateFindArchitectureState(scopeId, {
                 lastScannedAt: new Date().toISOString(),
                 lastError: undefined,
             });
@@ -102,10 +109,19 @@ export async function scanForArchitecture(options) {
                 issuesCreated: 0,
             };
         }
-        const product = await fetchProductBasics(productId);
-        const existingIssues = await fetchOpenIssues(productId);
+        const product = productId
+            ? await fetchProductBasics(productId)
+            : await fetchRepositoryBasics(repoId);
+        const existingIssues = productId
+            ? await fetchOpenIssues(productId)
+            : await fetchOpenIssuesByRepo(repoId);
         logInfo(`Loaded ${existingIssues.length} existing issues for dedup context`);
-        const systemPrompt = createFindArchitectureSystemPrompt();
+        const rulePacks = await resolveStackRulePacks(repoPath, {
+            productId,
+            repoId,
+        });
+        const customRules = await resolveCustomRules({ productId, repoId }, 'architecture');
+        const systemPrompt = createFindArchitectureSystemPrompt(rulePacks, customRules);
         const userPrompt = createFindArchitectureUserPrompt({
             productName: product.name,
             productDescription: product.description,
@@ -157,7 +173,7 @@ export async function scanForArchitecture(options) {
         }
         if (!scanResult) {
             const msg = 'Audit failed: could not parse a scan_result from the agent';
-            updateFindArchitectureState(productId, { lastError: msg });
+            updateFindArchitectureState(scopeId, { lastError: msg });
             return {
                 status: 'error',
                 message: msg,
@@ -168,18 +184,20 @@ export async function scanForArchitecture(options) {
         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);
+        // CLI suggestion argument: a productId positional, or the --repo-id flag.
+        const scopeArg = productId ?? `--repo-id ${repoId}`;
+        logDeferred(deferredBugs, 'find-bugs', scopeArg);
+        logDeferred(deferredFeatures, 'find-features', scopeArg);
+        logDeferred(deferredSmells, 'find-smells', scopeArg);
         let created = 0;
         for (const finding of findings) {
-            const issueId = await createIssueForFinding(productId, finding);
+            const issueId = await createIssueForFinding({ productId, repoId }, finding);
             if (issueId) {
                 created++;
                 logSuccess(`Filed issue ${issueId}: ${finding.title}`);
             }
         }
-        updateFindArchitectureState(productId, {
+        updateFindArchitectureState(scopeId, {
             lastScannedCommitSha: headSha,
             lastScannedAt: new Date().toISOString(),
             lastError: undefined,
@@ -200,7 +218,7 @@ export async function scanForArchitecture(options) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logError(`Architecture scan failed: ${errorMessage}`);
-        updateFindArchitectureState(productId, { lastError: errorMessage });
+        updateFindArchitectureState(scopeId, { lastError: errorMessage });
         return {
             status: 'error',
             message: `Architecture scan failed: ${errorMessage}`,
@@ -213,21 +231,23 @@ export async function scanForArchitecture(options) {
         lock.release();
     }
 }
-function logDeferred(deferred, siblingPhase, productId) {
+function logDeferred(deferred, siblingPhase, scopeArg) {
     if (deferred.length === 0) {
         return;
     }
-    logInfo(`${deferred.length} finding(s) deferred to ${siblingPhase} — run \`edsger ${siblingPhase} ${productId}\` to pick them up:`);
+    logInfo(`${deferred.length} finding(s) deferred to ${siblingPhase} — run \`edsger ${siblingPhase} ${scopeArg}\` 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) {
+async function createIssueForFinding(scope, finding) {
     return createIssue({
-        productId,
+        productId: scope.productId,
+        repoId: scope.repoId,
         title: finding.title,
         description: formatIssueDescription(finding),
+        source: 'quality',
     });
 }
 function formatIssueDescription(finding) {

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

@@ -12,7 +12,8 @@
  *     multiple files: module boundaries, layering, coupling, cycles, missing
  *     or duplicated abstractions, responsibility creep, cross-cutting concerns.
  */
-export declare function createFindArchitectureSystemPrompt(): string;
+import { type RulePack } from '../find-shared/rule-packs.js';
+export declare function createFindArchitectureSystemPrompt(packs?: RulePack[], customRules?: string): string;
 export interface FindArchitectureUserPromptParams {
     productName: string;
     productDescription?: string;

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

@@ -12,7 +12,8 @@
  *     multiple files: module boundaries, layering, coupling, cycles, missing
  *     or duplicated abstractions, responsibility creep, cross-cutting concerns.
  */
-export function createFindArchitectureSystemPrompt() {
+import { renderRulePacks } from '../find-shared/rule-packs.js';
+export function createFindArchitectureSystemPrompt(packs = [], customRules = '') {
     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**:
@@ -26,7 +27,7 @@ export function createFindArchitectureSystemPrompt() {
 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
+11. **Scalability shape**: data-flow / control-flow patterns that won't survive the next obvious axis of growth${renderRulePacks(packs, 'architecture')}${customRules}
 
 **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\`.**

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

@@ -4,7 +4,10 @@
  * incremental, scoped to commits since the previous successful scan.
  */
 export interface FindBugsOptions {
-    productId: string;
+    /** Product scope. Provide this OR repoId (repo-scoped scan). */
+    productId?: string;
+    /** Repository scope: scan a bare `repositories` row with no product. */
+    repoId?: string;
     githubToken: string;
     owner: string;
     repo: string;

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

@@ -7,8 +7,9 @@ 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 { resolveScanBase } from '../find-shared/baseline.js';
 import { detectDefaultBranch, gitRevParse, isAncestor, listChangedPaths, } from '../find-shared/git.js';
-import { createIssue, fetchOpenIssues, fetchProductBasics, } from '../find-shared/mcp.js';
+import { createIssue, fetchOpenIssues, fetchOpenIssuesByRepo, fetchProductBasics, fetchRepositoryBasics, } from '../find-shared/mcp.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { createFindBugsSystemPrompt, createFindBugsUserPrompt, } from './prompts.js';
 import { acquireFindBugsLock, loadFindBugsState, updateFindBugsState, } from './state.js';
@@ -32,34 +33,40 @@ const MAX_TURNS = 200;
  */
 // eslint-disable-next-line complexity
 export async function scanForBugs(options) {
-    const { productId, githubToken, owner, repo, full, maxFiles, verbose } = options;
-    logInfo(`Starting bug scan for product ${productId} (${owner}/${repo})`);
-    const lock = acquireFindBugsLock(productId);
+    const { productId, repoId, githubToken, owner, repo, full, maxFiles, verbose } = options;
+    // State/lock/workspace are keyed by an opaque scope id so product and repo
+    // scans never collide; repo keys are prefixed to namespace them clearly.
+    const scopeId = productId ?? `repo-${repoId}`;
+    const scopeLabel = productId
+        ? `product ${productId}`
+        : `repository ${repoId}`;
+    logInfo(`Starting bug scan for ${scopeLabel} (${owner}/${repo})`);
+    const lock = acquireFindBugsLock(scopeId);
     if (!lock) {
-        logWarning(`Another bug scan is already in progress for product ${productId}; skipping.`);
+        logWarning(`Another bug scan is already in progress for ${scopeLabel}; skipping.`);
         return {
             status: 'error',
-            message: 'Another bug scan is already in progress for this product',
+            message: 'Another bug scan is already in progress for this scope',
         };
     }
     let repoPath;
     let scanSucceeded = false;
     try {
-        updateFindBugsState(productId, {
+        updateFindBugsState(scopeId, {
             lastAttemptedAt: new Date().toISOString(),
         });
         const workspaceRoot = ensureWorkspaceDir();
         // 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 repoKey = `${WORKSPACE_KEY}-${scopeId}`;
         ({ 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 = loadFindBugsState(productId);
-        const baseSha = full ? undefined : state.lastScannedCommitSha;
+        const state = loadFindBugsState(scopeId);
+        const baseSha = await resolveScanBase({ productId, repoId }, { full, lastScannedSha: state.lastScannedCommitSha });
         let scope = 'full';
         let changedPaths;
         if (baseSha && baseSha !== headSha) {
@@ -70,7 +77,7 @@ export async function scanForBugs(options) {
                 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.');
-                    updateFindBugsState(productId, {
+                    updateFindBugsState(scopeId, {
                         lastScannedCommitSha: headSha,
                         lastScannedAt: new Date().toISOString(),
                         lastError: undefined,
@@ -100,8 +107,12 @@ export async function scanForBugs(options) {
                 issuesCreated: 0,
             };
         }
-        const product = await fetchProductBasics(productId);
-        const existingIssues = await fetchOpenIssues(productId);
+        const product = productId
+            ? await fetchProductBasics(productId)
+            : await fetchRepositoryBasics(repoId);
+        const existingIssues = productId
+            ? await fetchOpenIssues(productId)
+            : await fetchOpenIssuesByRepo(repoId);
         logInfo(`Loaded ${existingIssues.length} existing issues for dedup context`);
         const systemPrompt = createFindBugsSystemPrompt();
         const userPrompt = createFindBugsUserPrompt({
@@ -155,7 +166,7 @@ export async function scanForBugs(options) {
         }
         if (!scanResult) {
             const msg = 'Audit failed: could not parse a scan_result from the agent';
-            updateFindBugsState(productId, { lastError: msg });
+            updateFindBugsState(scopeId, { lastError: msg });
             return {
                 status: 'error',
                 message: msg,
@@ -165,13 +176,13 @@ export async function scanForBugs(options) {
         logInfo(`Audit produced ${bugs.length} candidate bugs. ${summary}`);
         let created = 0;
         for (const bug of bugs) {
-            const issueId = await createIssueForBug(productId, bug);
+            const issueId = await createIssueForBug({ productId, repoId }, bug);
             if (issueId) {
                 created++;
                 logSuccess(`Filed issue ${issueId}: ${bug.title}`);
             }
         }
-        updateFindBugsState(productId, {
+        updateFindBugsState(scopeId, {
             lastScannedCommitSha: headSha,
             lastScannedAt: new Date().toISOString(),
             lastError: undefined,
@@ -189,7 +200,7 @@ export async function scanForBugs(options) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logError(`Bug scan failed: ${errorMessage}`);
-        updateFindBugsState(productId, { lastError: errorMessage });
+        updateFindBugsState(scopeId, { lastError: errorMessage });
         return {
             status: 'error',
             message: `Bug scan failed: ${errorMessage}`,
@@ -202,11 +213,13 @@ export async function scanForBugs(options) {
         lock.release();
     }
 }
-async function createIssueForBug(productId, bug) {
+async function createIssueForBug(scope, bug) {
     return createIssue({
-        productId,
+        productId: scope.productId,
+        repoId: scope.repoId,
         title: bug.title,
         description: formatIssueDescription(bug),
+        source: 'quality',
     });
 }
 function formatIssueDescription(bug) {

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

@@ -0,0 +1,45 @@
+/**
+ * Server-side scan baseline, shared across the find-* phases.
+ *
+ * A baseline pins a commit as the "everything before here is acknowledged"
+ * floor for a scope. On a fresh scan (no machine-local scan-state cursor) the
+ * find-* scanners use it as the diff base so only findings in code changed
+ * since the baseline are reported — the "only new" view DCM-style baselines
+ * provide — instead of re-filing the entire pre-existing backlog.
+ *
+ * Read here via the user's supabase session; written from the desktop app
+ * (services/db/quality-baselines.ts). Stored in `quality_scan_baselines`.
+ */
+export interface ScanScope {
+    productId?: string;
+    repoId?: string;
+}
+/**
+ * Resolve the diff base for a scan, given the explicit `--full` flag, the
+ * machine-local last-scanned cursor, and the server baseline. Pure + exported
+ * for testing.
+ *
+ * - `--full` always wins → undefined (scan everything, ignore baseline).
+ * - otherwise prefer the local cursor (normal incremental), falling back to
+ *   the baseline so a fresh checkout still suppresses the pre-existing backlog.
+ */
+export declare function resolveScanBaseSha(opts: {
+    full?: boolean;
+    lastScannedSha?: string;
+    baselineSha?: string | null;
+}): string | undefined;
+/**
+ * Fetch the pinned baseline commit for a scope, or null if none is set / no
+ * session is available. Never throws — a baseline read failure must not abort
+ * a scan (it just degrades to a full scan).
+ */
+export declare function getScanBaseline(scope: ScanScope): Promise<string | null>;
+/**
+ * Fetch the baseline and resolve the scan's diff base in one call, logging when
+ * the baseline floor is applied on a fresh checkout. Shared by every find-*
+ * phase so the baseline wiring lives in one place.
+ */
+export declare function resolveScanBase(scope: ScanScope, opts: {
+    full?: boolean;
+    lastScannedSha?: string;
+}): Promise<string | undefined>;