archbyte 0.2.8 → 0.3.0

package/dist/agents/pipeline/agents/component-identifier.js

@@ -3,10 +3,19 @@
 import { extractJSON } from "../response-parser.js";
 import { getPrompt } from "../../prompts.js";
 import "../../prompt-data.js";
-function formatFileTree(ctx) {
+function formatFileTree(ctx, affectedPaths) {
     // Show directories + key files only (not all 1000+ files) to stay within context limits
     const lines = [];
-    const MAX_LINES = 300;
+    const MAX_LINES = affectedPaths ? 150 : 300;
+    function isAffectedSubtree(dirPath) {
+        if (!affectedPaths)
+            return true;
+        for (const p of affectedPaths) {
+            if (p.startsWith(dirPath + "/") || dirPath.startsWith(p + "/") || dirPath === p)
+                return true;
+        }
+        return false;
+    }
     function walk(entries, indent) {
         for (const e of entries) {
             if (lines.length >= MAX_LINES)
@@ -14,6 +23,11 @@ function formatFileTree(ctx) {
             if (e.type === "directory") {
                 const fileCount = e.children?.filter((c) => c.type === "file").length ?? 0;
                 const dirCount = e.children?.filter((c) => c.type === "directory").length ?? 0;
+                if (affectedPaths && indent >= 1 && !isAffectedSubtree(e.path)) {
+                    // Collapse unchanged directories
+                    lines.push(`${"  ".repeat(indent)}${e.path}/ ... (${fileCount} files, unchanged)`);
+                    continue;
+                }
                 lines.push(`${"  ".repeat(indent)}${e.path}/ (${fileCount} files, ${dirCount} dirs)`);
                 if (e.children)
                     walk(e.children, indent + 1);
@@ -48,8 +62,49 @@ export const componentIdentifier = {
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/component-identifier");
         const incremental = priorResults?.["__incremental__"];
-        const fileTree = formatFileTree(ctx);
-        const configs = formatConfigs(ctx);
+        // Build set of affected paths for tree filtering
+        let affectedPaths;
+        if (incremental) {
+            affectedPaths = new Set();
+            // Include paths of affected components
+            for (const compId of incremental.affectedComponents) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedPaths.add(comp.path);
+            }
+            // Include paths of neighbor components
+            for (const compId of incremental.neighborComponents) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedPaths.add(comp.path);
+            }
+            // Include directories of changed files
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedPaths.add(dir);
+            }
+        }
+        const fileTree = formatFileTree(ctx, affectedPaths);
+        // Filter configs: in incremental mode, only include configs from affected dirs + root configs
+        let configs;
+        if (incremental && affectedPaths) {
+            const filteredConfigs = ctx.codeSamples.configFiles.filter((cf) => {
+                const dir = cf.path.includes("/") ? cf.path.substring(0, cf.path.lastIndexOf("/")) : ".";
+                // Always include root configs
+                if (!cf.path.includes("/"))
+                    return true;
+                // Include configs from affected directories
+                for (const p of affectedPaths) {
+                    if (dir.startsWith(p) || p.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            configs = filteredConfigs.map((cf) => `--- ${cf.path} ---\n${cf.content}`).join("\n\n");
+        }
+        else {
+            configs = formatConfigs(ctx);
+        }
         const structureInfo = [
             `Project: ${ctx.structure.projectName || "(unknown)"}`,
             `Language: ${ctx.structure.language}`,
@@ -62,9 +117,13 @@ export const componentIdentifier = {
         const docNotes = ctx.docs.architectureNotes.length > 0
             ? `\n\nArchitecture notes from docs:\n${ctx.docs.architectureNotes.join("\n")}`
             : "";
-        const dockerInfo = ctx.infra.docker.composeFile
-            ? `\n\nDocker Compose services:\n${ctx.infra.docker.services.map((s) => `- ${s.name}${s.image ? ` (image: ${s.image})` : ""}${s.buildContext ? ` (build: ${s.buildContext})` : ""}${s.dependsOn?.length ? ` depends_on: ${s.dependsOn.join(", ")}` : ""}`).join("\n")}`
-            : "";
+        // In incremental mode, only include Docker info if infra files changed
+        let dockerInfo = "";
+        if (ctx.infra.docker.composeFile) {
+            if (!incremental || incremental.categories.infraFiles.length > 0) {
+                dockerInfo = `\n\nDocker Compose services:\n${ctx.infra.docker.services.map((s) => `- ${s.name}${s.image ? ` (image: ${s.image})` : ""}${s.buildContext ? ` (build: ${s.buildContext})` : ""}${s.dependsOn?.length ? ` depends_on: ${s.dependsOn.join(", ")}` : ""}`).join("\n")}`;
+            }
+        }
         let incrementalInfo = "";
         if (incremental) {
             const existing = Object.entries(incremental.existingSpec.components)
@@ -76,7 +135,7 @@ ${existing}
 Changed files: ${incremental.changedFiles.join(", ")}
 Affected components: ${incremental.affectedComponents.length > 0 ? incremental.affectedComponents.join(", ") : "none (check for new components)"}
 
-IMPORTANT: Return ALL components — both existing unaffected ones AND updated/new ones. Only re-analyze components whose paths overlap with the changed files.`;
+IMPORTANT: Return ALL components — both existing unaffected ones AND updated/new ones. Focus: re-evaluate components in [${[...new Set([...incremental.affectedComponents, ...incremental.neighborComponents])].join(", ")}]. Return other components as-is.`;
         }
         const user = `Analyze this project and identify ALL architecturally significant components.
 

package/dist/agents/pipeline/agents/connection-mapper.js

@@ -47,10 +47,36 @@ export const connectionMapper = {
                 parts.push(`- ${ar.method} ${ar.path} (${ar.handlerFile})`);
             }
         }
-        // Import map
-        const importEntries = Object.entries(ctx.codeSamples.importMap);
+        // Import map — filter to affected + neighbor component dirs in incremental mode
+        const incremental = priorResults?.["__incremental__"];
+        let affectedDirs;
+        if (incremental) {
+            affectedDirs = new Set();
+            for (const compId of [...incremental.affectedComponents, ...incremental.neighborComponents]) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedDirs.add(comp.path);
+            }
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedDirs.add(dir);
+            }
+        }
+        let importEntries = Object.entries(ctx.codeSamples.importMap);
+        if (affectedDirs && affectedDirs.size > 0) {
+            importEntries = importEntries.filter(([file]) => {
+                const dir = file.includes("/") ? file.substring(0, file.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+        }
         if (importEntries.length > 0) {
-            parts.push(`\n## Import Graph (${importEntries.length} files)`);
+            const totalEntries = Object.keys(ctx.codeSamples.importMap).length;
+            const label = affectedDirs ? `${importEntries.length} of ${totalEntries} files, filtered to affected dirs` : `${totalEntries} files`;
+            parts.push(`\n## Import Graph (${label})`);
             // Summarize by directory to keep it concise
             const dirImports = {};
             for (const [file, imports] of importEntries) {
@@ -69,8 +95,8 @@ export const connectionMapper = {
                 }
             }
         }
-        // Docker depends_on
-        if (ctx.infra.docker.composeFile) {
+        // Docker depends_on — only if infra changed (or full scan)
+        if (ctx.infra.docker.composeFile && (!incremental || incremental.categories.infraFiles.length > 0)) {
             const deps = ctx.infra.docker.services
                 .filter((s) => s.dependsOn?.length)
                 .map((s) => `${s.name} → ${s.dependsOn.join(", ")}`);
@@ -78,15 +104,14 @@ export const connectionMapper = {
                 parts.push(`\n## Docker depends_on\n${deps.join("\n")}`);
             }
         }
-        // Kubernetes resources
-        if (ctx.infra.kubernetes.resources.length > 0) {
+        // Kubernetes resources — only if infra changed (or full scan)
+        if (ctx.infra.kubernetes.resources.length > 0 && (!incremental || incremental.categories.infraFiles.length > 0)) {
             parts.push("\n## Kubernetes Resources");
             for (const r of ctx.infra.kubernetes.resources) {
                 parts.push(`- ${r.kind}: ${r.name}${r.namespace ? ` (ns=${r.namespace})` : ""}`);
             }
         }
         // Incremental context
-        const incremental = priorResults?.["__incremental__"];
         if (incremental) {
             const existingConns = incremental.existingSpec.connections
                 .map((c) => `- ${c.from} → ${c.to} (${c.type}${c.async ? ", async" : ""}): ${c.description}`)

package/dist/agents/pipeline/agents/flow-detector.js

@@ -11,6 +11,20 @@ export const flowDetector = {
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/flow-detector");
         const incremental = priorResults?.["__incremental__"];
+        // Build set of affected directories for filtering
+        let affectedDirs;
+        if (incremental) {
+            affectedDirs = new Set();
+            for (const compId of [...incremental.affectedComponents, ...incremental.neighborComponents]) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedDirs.add(comp.path);
+            }
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedDirs.add(dir);
+            }
+        }
         const parts = [];
         // Event patterns from static scanner
         if (ctx.events.hasEDA) {
@@ -18,8 +32,23 @@ export const flowDetector = {
             for (const p of ctx.events.patterns) {
                 parts.push(`  Technology: ${p.technology} (dep: ${p.dependency})`);
             }
-            parts.push("\nEvent occurrences in code:");
-            for (const e of ctx.events.events.slice(0, 30)) {
+            // Filter events to affected directories in incremental mode
+            let events = ctx.events.events;
+            if (affectedDirs && affectedDirs.size > 0) {
+                events = events.filter((e) => {
+                    const dir = e.file.includes("/") ? e.file.substring(0, e.file.lastIndexOf("/")) : ".";
+                    for (const ad of affectedDirs) {
+                        if (dir.startsWith(ad) || ad.startsWith(dir))
+                            return true;
+                    }
+                    return false;
+                });
+                parts.push(`\nEvent occurrences in affected files (${events.length} of ${ctx.events.events.length} total):`);
+            }
+            else {
+                parts.push("\nEvent occurrences in code:");
+            }
+            for (const e of events.slice(0, 30)) {
                 parts.push(`  [${e.type}] ${e.file}: ${e.pattern}`);
             }
         }
@@ -33,24 +62,48 @@ export const flowDetector = {
                 parts.push(`  ${ep.method} ${ep.path} — ${ep.description}`);
             }
         }
-        // Route file samples
-        const routeSamples = ctx.codeSamples.samples.filter((s) => s.category === "route-file");
+        // Route file samples — filter to affected directories in incremental mode
+        let routeSamples = ctx.codeSamples.samples.filter((s) => s.category === "route-file");
+        if (affectedDirs && affectedDirs.size > 0) {
+            const filtered = routeSamples.filter((s) => {
+                const dir = s.path.includes("/") ? s.path.substring(0, s.path.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            if (filtered.length > 0)
+                routeSamples = filtered;
+        }
         if (routeSamples.length > 0) {
             parts.push("\nRoute file excerpts:");
             for (const s of routeSamples.slice(0, 5)) {
                 parts.push(`\n--- ${s.path} ---\n${s.excerpt}`);
             }
         }
-        // Entry points for context
-        const entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        // Entry points — filter to affected directories in incremental mode
+        let entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        if (affectedDirs && affectedDirs.size > 0) {
+            const filtered = entrySamples.filter((s) => {
+                const dir = s.path.includes("/") ? s.path.substring(0, s.path.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            if (filtered.length > 0)
+                entrySamples = filtered;
+        }
         if (entrySamples.length > 0) {
             parts.push("\nEntry point excerpts:");
             for (const s of entrySamples.slice(0, 3)) {
                 parts.push(`\n--- ${s.path} ---\n${s.excerpt}`);
             }
         }
-        // Docker info for queue/broker identification
-        if (ctx.infra.docker.composeFile) {
+        // Docker info for queue/broker identification — only if event-related files changed
+        if (ctx.infra.docker.composeFile && (!incremental || incremental.categories.eventFiles.length > 0 || incremental.categories.infraFiles.length > 0)) {
             const queueServices = ctx.infra.docker.services.filter((s) => {
                 const img = (s.image ?? "").toLowerCase();
                 return img.includes("rabbit") || img.includes("kafka") || img.includes("redis") ||

package/dist/agents/pipeline/agents/service-describer.js

@@ -11,6 +11,22 @@ export const serviceDescriber = {
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/service-describer");
         const incremental = priorResults?.["__incremental__"];
+        // Build affected dirs for filtering
+        let affectedDirs;
+        if (incremental) {
+            affectedDirs = new Set();
+            for (const compId of [...incremental.affectedComponents, ...incremental.neighborComponents]) {
+                const comp = incremental.existingSpec.components[compId];
+                if (comp?.path)
+                    affectedDirs.add(comp.path);
+            }
+            for (const f of incremental.changedFiles) {
+                const dir = f.includes("/") ? f.substring(0, f.lastIndexOf("/")) : ".";
+                affectedDirs.add(dir);
+            }
+        }
+        const hasInfraChanges = incremental ? incremental.categories.infraFiles.length > 0 : true;
+        const hasConfigChanges = incremental ? incremental.categories.configFiles.length > 0 : true;
         const parts = [];
         // Structure info
         parts.push(`Project: ${ctx.structure.projectName || "(unknown)"}`);
@@ -24,8 +40,8 @@ export const serviceDescriber = {
         if (ctx.docs.externalDependencies.length > 0) {
             parts.push(`\nExternal dependencies mentioned: ${ctx.docs.externalDependencies.join(", ")}`);
         }
-        // Docker services
-        if (ctx.infra.docker.composeFile) {
+        // Docker services — only include if infra/config files changed (or full scan)
+        if (ctx.infra.docker.composeFile && (hasInfraChanges || hasConfigChanges)) {
             const svcInfo = ctx.infra.docker.services.map((s) => {
                 const details = [s.name];
                 if (s.image)
@@ -40,22 +56,34 @@ export const serviceDescriber = {
             });
             parts.push(`\nDocker services:\n${svcInfo.join("\n")}`);
         }
-        // Env vars
-        if (ctx.envs.environments.length > 0) {
+        // Env vars — only include if infra/config files changed (or full scan)
+        if (ctx.envs.environments.length > 0 && (hasInfraChanges || hasConfigChanges)) {
             for (const env of ctx.envs.environments) {
                 parts.push(`\nEnv file "${env.name}" variables: ${env.variables.join(", ")}`);
             }
         }
-        // Code samples (entry points)
-        const entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        // Code samples (entry points) — filter to affected dirs in incremental mode
+        let entrySamples = ctx.codeSamples.samples.filter((s) => s.category === "entry-point");
+        if (affectedDirs && affectedDirs.size > 0) {
+            const filtered = entrySamples.filter((s) => {
+                const dir = s.path.includes("/") ? s.path.substring(0, s.path.lastIndexOf("/")) : ".";
+                for (const ad of affectedDirs) {
+                    if (dir.startsWith(ad) || ad.startsWith(dir))
+                        return true;
+                }
+                return false;
+            });
+            if (filtered.length > 0)
+                entrySamples = filtered;
+        }
         if (entrySamples.length > 0) {
             parts.push("\nEntry point excerpts:");
             for (const s of entrySamples.slice(0, 5)) {
                 parts.push(`\n--- ${s.path} ---\n${s.excerpt}`);
             }
         }
-        // Cloud info
-        if (ctx.infra.cloud.provider) {
+        // Cloud info — only if infra changed (or full scan)
+        if (ctx.infra.cloud.provider && hasInfraChanges) {
             parts.push(`\nCloud: ${ctx.infra.cloud.provider}, services: ${ctx.infra.cloud.services.join(", ")}`);
         }
         // Incremental context

package/dist/agents/pipeline/agents/validator.js

@@ -10,15 +10,36 @@ export const validator = {
     phase: "sequential",
     buildPrompt(ctx, priorResults) {
         const system = getPrompt("pipeline/validator");
+        const incremental = priorResults?.["__incremental__"];
+        // Build set of relevant component IDs for filtering
+        let relevantComponents;
+        if (incremental) {
+            relevantComponents = new Set([...incremental.affectedComponents, ...incremental.neighborComponents]);
+        }
         const parts = [];
-        // Components
+        // Components — in incremental mode, show affected + neighbors in full, others as summary
         const components = priorResults?.["component-identifier"];
         if (components?.components) {
-            parts.push("## Components");
-            for (const c of components.components) {
-                parts.push(`- ${c.id}: ${c.name} (type=${c.type}, layer=${c.layer}, path=${c.path})`);
-                parts.push(`  description: ${c.description || "(none)"}`);
-                parts.push(`  tech: [${(c.technologies || []).join(", ")}]`);
+            if (relevantComponents && relevantComponents.size > 0) {
+                const relevant = components.components.filter((c) => relevantComponents.has(c.id));
+                const others = components.components.length - relevant.length;
+                parts.push("## Components (affected + neighbors)");
+                for (const c of relevant) {
+                    parts.push(`- ${c.id}: ${c.name} (type=${c.type}, layer=${c.layer}, path=${c.path})`);
+                    parts.push(`  description: ${c.description || "(none)"}`);
+                    parts.push(`  tech: [${(c.technologies || []).join(", ")}]`);
+                }
+                if (others > 0) {
+                    parts.push(`\n(${others} other unchanged components omitted)`);
+                }
+            }
+            else {
+                parts.push("## Components");
+                for (const c of components.components) {
+                    parts.push(`- ${c.id}: ${c.name} (type=${c.type}, layer=${c.layer}, path=${c.path})`);
+                    parts.push(`  description: ${c.description || "(none)"}`);
+                    parts.push(`  tech: [${(c.technologies || []).join(", ")}]`);
+                }
             }
         }
         // Services
@@ -35,11 +56,19 @@ export const validator = {
                 parts.push(`- ${svc.id}: ${svc.name} (${svc.type}) — ${svc.description}`);
             }
         }
-        // Connections
+        // Connections — in incremental mode, only show connections involving affected/neighbor components
         const connections = priorResults?.["connection-mapper"];
         if (connections?.connections) {
-            parts.push("\n## Connections");
-            for (const c of connections.connections) {
+            let conns = connections.connections;
+            if (relevantComponents && relevantComponents.size > 0) {
+                conns = conns.filter((c) => relevantComponents.has(c.from) || relevantComponents.has(c.to));
+                const omitted = connections.connections.length - conns.length;
+                parts.push(`\n## Connections (involving affected components${omitted > 0 ? `, ${omitted} others omitted` : ""})`);
+            }
+            else {
+                parts.push("\n## Connections");
+            }
+            for (const c of conns) {
                 parts.push(`- ${c.from} → ${c.to} (${c.type}) ${c.async ? "[async]" : ""}: ${c.description}`);
             }
         }

package/dist/agents/pipeline/index.d.ts

@@ -11,4 +11,5 @@ export declare function runPipeline(ctx: StaticContext, provider: LLMProvider, c
         input: number;
         output: number;
     };
+    skippedAgents?: string[];
 }>;

package/dist/agents/pipeline/index.js

@@ -15,6 +15,79 @@ function isAuthError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return /401|authentication_error|invalid.*api.?key|unauthorized|invalid.*key/i.test(msg);
 }
+/**
+ * Determine if an agent can be skipped based on what changed.
+ * Returns a skip reason string if skippable, or null if the agent must run.
+ */
+function shouldSkipAgent(agentId, inc) {
+    // Never skip if there are unmapped files — potential new components
+    if (inc.hasUnmappedFiles)
+        return null;
+    const cat = inc.categories;
+    const hasInfra = cat.infraFiles.length > 0;
+    const hasConfig = cat.configFiles.length > 0;
+    const hasEntryPoints = cat.entryPoints.length > 0;
+    const hasRoutes = cat.routeFiles.length > 0;
+    const hasEvents = cat.eventFiles.length > 0;
+    switch (agentId) {
+        case "service-describer":
+            // Skip when no infra/config/entry-point changes
+            if (!hasInfra && !hasConfig && !hasEntryPoints) {
+                return "no infra/config/entry-point changes";
+            }
+            return null;
+        case "flow-detector":
+            // Skip when no route/event/entry-point changes
+            if (!hasRoutes && !hasEvents && !hasEntryPoints) {
+                return "no route/event/entry-point changes";
+            }
+            return null;
+        case "validator":
+            // Skip when ≤1 affected component and no infra changes
+            if (inc.affectedComponents.length <= 1 && !hasInfra) {
+                return `only ${inc.affectedComponents.length} component affected, no infra changes`;
+            }
+            return null;
+        // component-identifier and connection-mapper never skip
+        default:
+            return null;
+    }
+}
+/** Build fallback data for a skipped agent from existing spec */
+function getFallbackData(agentId, inc) {
+    switch (agentId) {
+        case "service-describer": {
+            const dbs = Object.entries(inc.existingSpec.databases).map(([id, d]) => ({
+                id, name: d.name, type: d.type, description: d.description, usedBy: [],
+            }));
+            const exts = Object.entries(inc.existingSpec["external-services"]).map(([id, s]) => ({
+                id, name: s.name, type: s.type, description: s.description, usedBy: [],
+            }));
+            return {
+                projectDescription: "",
+                primaryLanguage: "",
+                databases: dbs,
+                externalServices: exts,
+            };
+        }
+        case "flow-detector":
+            return {
+                eventConnections: [],
+                apiRoutes: [],
+            };
+        case "validator":
+            return {
+                componentTypeCorrections: {},
+                componentDescriptions: {},
+                addedConnections: [],
+                removedConnectionKeys: [],
+                confidence: 0.8,
+                issues: [],
+            };
+        default:
+            return null;
+    }
+}
 /**
  * Run the multi-agent pipeline: 3 parallel fast agents → 2 sequential agents.
  * Each agent gets a single chat() call with pre-collected static context.
@@ -22,6 +95,7 @@ function isAuthError(err) {
 export async function runPipeline(ctx, provider, config, onProgress, incrementalContext) {
     const agentResults = {};
     const agentMeta = [];
+    const skippedAgents = [];
     // Pass incremental context to agents via priorResults
     if (incrementalContext) {
         agentResults["__incremental__"] = incrementalContext;
@@ -30,10 +104,27 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     onProgress?.(`Phase 1: Running ${PARALLEL_AGENTS.length} agents in parallel...`);
     // Pass agentResults to parallel agents too (contains __incremental__ if set)
     const parallelPrior = incrementalContext ? agentResults : undefined;
-    const parallelResults = await Promise.allSettled(PARALLEL_AGENTS.map((agent) => runAgent(agent, ctx, provider, config, parallelPrior, onProgress)));
+    // Check for agent skipping
+    const parallelTasks = PARALLEL_AGENTS.map((agent) => ({
+        agent,
+        skipReason: incrementalContext ? shouldSkipAgent(agent.id, incrementalContext) : null,
+    }));
+    const parallelResults = await Promise.allSettled(parallelTasks.map(({ agent, skipReason }) => {
+        if (skipReason) {
+            // Skip this agent — use fallback data
+            skippedAgents.push(agent.id);
+            onProgress?.(`  ${agent.name}: skipped (${skipReason})`);
+            const fallback = getFallbackData(agent.id, incrementalContext);
+            agentResults[agent.id] = fallback;
+            return Promise.resolve(null);
+        }
+        return runAgent(agent, ctx, provider, config, parallelPrior, onProgress);
+    }));
     let authFailed = false;
-    for (let i = 0; i < PARALLEL_AGENTS.length; i++) {
-        const agent = PARALLEL_AGENTS[i];
+    for (let i = 0; i < parallelTasks.length; i++) {
+        const { agent, skipReason } = parallelTasks[i];
+        if (skipReason)
+            continue; // Already handled
         const result = parallelResults[i];
         if (result.status === "fulfilled" && result.value) {
             agentResults[agent.id] = result.value.data;
@@ -55,6 +146,15 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     // === Phase 2: Sequential agents ===
     onProgress?.(`Phase 2: Running ${SEQUENTIAL_AGENTS.length} agents sequentially...`);
     for (const agent of SEQUENTIAL_AGENTS) {
+        // Check for agent skipping
+        const skipReason = incrementalContext ? shouldSkipAgent(agent.id, incrementalContext) : null;
+        if (skipReason) {
+            skippedAgents.push(agent.id);
+            onProgress?.(`  ${agent.name}: skipped (${skipReason})`);
+            const fallback = getFallbackData(agent.id, incrementalContext);
+            agentResults[agent.id] = fallback;
+            continue;
+        }
         try {
             const result = await runAgent(agent, ctx, provider, config, agentResults, onProgress);
             if (result) {
@@ -82,13 +182,29 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     if (merged.validation.repairs.length > 0) {
         onProgress?.(`Applied ${merged.validation.repairs.length} deterministic repair(s)`);
     }
-    // Log token usage
+    // Log per-agent + total token usage
     const totalInput = agentMeta.reduce((s, a) => s + (a.tokenUsage?.input ?? 0), 0);
     const totalOutput = agentMeta.reduce((s, a) => s + (a.tokenUsage?.output ?? 0), 0);
-    if (totalInput > 0) {
-        onProgress?.(`Token usage: ${totalInput} in / ${totalOutput} out`);
+    if (totalInput > 0 || skippedAgents.length > 0) {
+        // Log to stderr so progress bar doesn't clobber it
+        console.error("\n  Token usage breakdown:");
+        for (const a of agentMeta) {
+            const inp = a.tokenUsage?.input ?? 0;
+            const out = a.tokenUsage?.output ?? 0;
+            const dur = (a.duration / 1000).toFixed(1);
+            console.error(`    ${a.agentId.padEnd(22)} ${String(inp).padStart(6)} in  ${String(out).padStart(6)} out  ${dur}s`);
+        }
+        for (const id of skippedAgents) {
+            console.error(`    ${id.padEnd(22)}      0 in       0 out  SKIPPED`);
+        }
+        console.error(`    ${"TOTAL".padEnd(22)} ${String(totalInput).padStart(6)} in  ${String(totalOutput).padStart(6)} out`);
+        if (skippedAgents.length > 0) {
+            console.error(`    Skipped ${skippedAgents.length} agent(s): ${skippedAgents.join(", ")}`);
+        }
+        console.error();
+        onProgress?.(`Token usage: ${totalInput} in / ${totalOutput} out${skippedAgents.length > 0 ? ` (${skippedAgents.length} skipped)` : ""}`);
     }
-    return { ...merged, tokenUsage: { input: totalInput, output: totalOutput } };
+    return { ...merged, tokenUsage: { input: totalInput, output: totalOutput }, skippedAgents: skippedAgents.length > 0 ? skippedAgents : undefined };
 }
 // Agents that produce large structured output (lists of components/connections) need more tokens
 const MAX_TOKENS = {

package/dist/agents/pipeline/types.d.ts

@@ -82,6 +82,14 @@ export interface ValidatorOutput {
     confidence: number;
     issues: string[];
 }
+export interface CategorizedChanges {
+    entryPoints: string[];
+    routeFiles: string[];
+    configFiles: string[];
+    infraFiles: string[];
+    eventFiles: string[];
+    sourceFiles: string[];
+}
 export interface IncrementalContext {
     existingSpec: {
         components: Record<string, {
@@ -123,6 +131,9 @@ export interface IncrementalContext {
     };
     changedFiles: string[];
     affectedComponents: string[];
+    categories: CategorizedChanges;
+    neighborComponents: string[];
+    hasUnmappedFiles: boolean;
 }
 export interface PipelineAgentResult {
     agentId: string;

package/dist/agents/providers/openai.js

@@ -7,12 +7,12 @@ export class OpenAIProvider {
     }
     async chat(params) {
         const messages = [
-            { role: "system", content: params.system },
+            { role: "developer", content: params.system },
             ...params.messages.map((m) => this.toOpenAIMessage(m)),
         ];
         const response = await this.client.chat.completions.create({
-            model: params.model ?? "gpt-4o",
-            max_tokens: params.maxTokens ?? 8192,
+            model: params.model ?? "gpt-5.2",
+            max_completion_tokens: params.maxTokens ?? 8192,
             messages,
             ...(params.tools?.length
                 ? {
@@ -54,12 +54,12 @@ export class OpenAIProvider {
     }
     async *stream(params) {
         const messages = [
-            { role: "system", content: params.system },
+            { role: "developer", content: params.system },
             ...params.messages.map((m) => this.toOpenAIMessage(m)),
         ];
         const stream = await this.client.chat.completions.create({
-            model: params.model ?? "gpt-4o",
-            max_tokens: params.maxTokens ?? 8192,
+            model: params.model ?? "gpt-5.2",
+            max_completion_tokens: params.maxTokens ?? 8192,
             messages,
             stream: true,
             ...(params.tools?.length