@codeyam/codeyam-cli 0.1.0-staging.50df560 → 0.1.0-staging.5369cbb

package/codeyam-cli/src/utils/__tests__/editorAudit.test.js

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
 import { Kysely, SqliteDialect } from 'kysely';
-import { isComponent, classifyGlossaryEntries, computeAudit, filterGlossaryByChangeStatus, resolveAuditSessionScope, queryScenarioCounts, queryPageScenarioCounts, queryIncompleteEntities, queryMiscategorizedScenarios, queryUnassociatedScenarios, isOnlyIncompleteEntities, isAutoRemediable, identifyScenariosNeedingRecapture, detectDuplicateNames, } from "../editorAudit.js";
+import { isComponent, classifyGlossaryEntries, computeAudit, filterGlossaryByChangeStatus, resolveAuditSessionScope, queryScenarioCounts, queryPageScenarioCounts, queryIncompleteEntities, queryMiscategorizedScenarios, queryUnassociatedScenarios, isOnlyIncompleteEntities, isOnlyPreExistingIncomplete, isAutoRemediable, identifyScenariosNeedingRecapture, detectDuplicateNames, aggregateClientErrorsByComponent, determineTargetedAnalysisPaths, shouldAutoRecapture, } from "../editorAudit.js";
 describe('editorAudit', () => {
     describe('isComponent', () => {
         it('should return true for JSX.Element return type', () => {
@@ -29,6 +29,16 @@ describe('editorAudit', () => {
         it('should return false when returnType is empty string', () => {
             expect(isComponent({ returnType: '' })).toBe(false);
         });
+        it('should return true for page files (index.tsx) even without returnType', () => {
+            expect(isComponent({ filePath: 'app/(tabs)/index.tsx' })).toBe(true);
+        });
+        it('should return true for page.tsx files even without returnType', () => {
+            expect(isComponent({ filePath: 'app/dashboard/page.tsx' })).toBe(true);
+        });
+        it('should return false for non-page files without returnType', () => {
+            expect(isComponent({ filePath: 'app/hooks/useCounter.ts' })).toBe(false);
+            expect(isComponent({ filePath: 'lib/storage.ts' })).toBe(false);
+        });
     });
     describe('classifyGlossaryEntries', () => {
         it('should classify entries with JSX return types as components', () => {
@@ -553,6 +563,142 @@ describe('editorAudit', () => {
             expect(result.summary.componentsOk).toBe(1);
             expect(result.summary.componentsWithErrors).toBe(1);
         });
+        // ── Test case count integration ─────────────────────────────────
+        it('should include testCaseCount when testCaseCounts is provided', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'calculatePrice',
+                        filePath: 'app/lib/pricing.ts',
+                        testFile: 'app/lib/pricing.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'app/lib/pricing.test.ts': true },
+                testResults: {
+                    'app/lib/pricing.test.ts': {
+                        passing: true,
+                        hasEntityNameDescribe: true,
+                    },
+                },
+                testCaseCounts: { calculatePrice: 5 },
+            });
+            expect(result.functions[0].testCaseCount).toBe(5);
+        });
+        it('should not include testCaseCount when testCaseCounts is not provided', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'calculatePrice',
+                        filePath: 'app/lib/pricing.ts',
+                        testFile: 'app/lib/pricing.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'app/lib/pricing.test.ts': true },
+                testResults: {
+                    'app/lib/pricing.test.ts': {
+                        passing: true,
+                        hasEntityNameDescribe: true,
+                    },
+                },
+            });
+            expect(result.functions[0].testCaseCount).toBeUndefined();
+        });
+        it('should count functionsThinCoverage for ok functions with fewer than 3 test cases', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'fnWellTested',
+                        filePath: 'a.ts',
+                        testFile: 'a.test.ts',
+                    },
+                    {
+                        name: 'fnThinCoverage',
+                        filePath: 'b.ts',
+                        testFile: 'b.test.ts',
+                    },
+                    {
+                        name: 'fnAlsoThin',
+                        filePath: 'c.ts',
+                        testFile: 'c.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: {
+                    'a.test.ts': true,
+                    'b.test.ts': true,
+                    'c.test.ts': true,
+                },
+                testResults: {
+                    'a.test.ts': { passing: true, hasEntityNameDescribe: true },
+                    'b.test.ts': { passing: true, hasEntityNameDescribe: true },
+                    'c.test.ts': { passing: true, hasEntityNameDescribe: true },
+                },
+                testCaseCounts: { fnWellTested: 5, fnThinCoverage: 2, fnAlsoThin: 1 },
+            });
+            expect(result.summary.functionsThinCoverage).toBe(2);
+        });
+        it('should not count failing functions in functionsThinCoverage', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'fnFailing',
+                        filePath: 'a.ts',
+                        testFile: 'a.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'a.test.ts': true },
+                testResults: {
+                    'a.test.ts': { passing: false, hasEntityNameDescribe: true },
+                },
+                testCaseCounts: { fnFailing: 1 },
+            });
+            expect(result.summary.functionsThinCoverage).toBe(0);
+        });
+        it('should not block allPassing due to thin test coverage', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'fnThin',
+                        filePath: 'a.ts',
+                        testFile: 'a.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'a.test.ts': true },
+                testResults: {
+                    'a.test.ts': { passing: true, hasEntityNameDescribe: true },
+                },
+                testCaseCounts: { fnThin: 1 },
+            });
+            expect(result.summary.allPassing).toBe(true);
+            expect(result.summary.functionsThinCoverage).toBe(1);
+        });
+        it('should default functionsThinCoverage to 0 when no testCaseCounts provided', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'fn',
+                        filePath: 'a.ts',
+                        testFile: 'a.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'a.test.ts': true },
+                testResults: {
+                    'a.test.ts': { passing: true, hasEntityNameDescribe: true },
+                },
+            });
+            expect(result.summary.functionsThinCoverage).toBe(0);
+        });
     });
     // ── filterGlossaryByChangeStatus ──────────────────────────────────
     describe('filterGlossaryByChangeStatus', () => {
@@ -1466,8 +1612,11 @@ describe('editorAudit', () => {
             expect(auditResult.summary.incompleteEntities).toBeUndefined();
         });
     });
-    // ── queryMiscategorizedScenarios ─────────────────────────────────────
-    describe('queryMiscategorizedScenarios', () => {
+    // ── filterToIncompleteFilePaths ──────────────────────────────────────
+    describe('filterToIncompleteFilePaths', () => {
+        // analyze-imports processes ALL file paths (~120 files) even when only
+        // a few need analysis. This function filters to files that have no
+        // entity with an analysis record.
         let db;
         let rawDb;
         const projectId = 'test-project-id';
@@ -1475,296 +1624,134 @@ describe('editorAudit', () => {
             rawDb = new Database(':memory:');
             db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
             await db.schema
-                .createTable('editor_scenarios')
+                .createTable('analyses')
                 .addColumn('id', 'varchar', (col) => col.primaryKey())
-                .addColumn('project_id', 'varchar', (col) => col.notNull())
-                .addColumn('name', 'varchar', (col) => col.notNull())
-                .addColumn('component_name', 'varchar')
-                .addColumn('component_path', 'varchar')
                 .addColumn('entity_sha', 'varchar')
-                .addColumn('display_name', 'varchar')
-                .addColumn('page_file_path', 'varchar')
-                .addColumn('url', 'varchar')
-                .addColumn('created_at', 'datetime')
-                .addColumn('updated_at', 'datetime')
+                .addColumn('entity_name', 'varchar')
+                .addColumn('project_id', 'varchar')
+                .execute();
+            await db.schema
+                .createTable('entities')
+                .addColumn('sha', 'varchar', (col) => col.primaryKey())
+                .addColumn('name', 'varchar')
+                .addColumn('entity_type', 'varchar')
+                .addColumn('file_path', 'varchar')
                 .execute();
         });
         afterEach(async () => {
             await db.destroy();
         });
-        it('should return empty when all component scenarios use isolation routes', async () => {
-            await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'LibraryCard - Default',
-                component_name: 'LibraryCard',
-                url: '/isolated-components/LibraryCard?s=Default',
-                created_at: '2026-03-17 12:00:00',
-            })
-                .execute();
-            const result = await queryMiscategorizedScenarios(db, projectId, null);
-            expect(result).toEqual([]);
-        });
-        it('should flag component scenarios that use non-isolation URLs', async () => {
-            // This is the bug: "Full Library Page" registered as component_name=LibraryPage
-            // but url=/library — it's pointing at the real page, not an isolation route
+        it('should exclude files that have an entity with an analysis', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            // Entity with analysis — skip
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('entities')
                 .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'Full Library Page',
-                component_name: 'LibraryPage',
-                url: '/library',
-                created_at: '2026-03-17 12:41:40',
+                sha: 'sha-header',
+                name: 'Header',
+                entity_type: 'visual',
+                file_path: 'app/components/Header.tsx',
             })
                 .execute();
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('analyses')
                 .values({
-                id: 'sc-2',
+                id: 'a-1',
+                entity_sha: 'sha-header',
+                entity_name: 'Header',
                 project_id: projectId,
-                name: 'Empty Library Page',
-                component_name: 'LibraryPage',
-                url: '/library',
-                created_at: '2026-03-17 12:41:51',
             })
                 .execute();
-            const result = await queryMiscategorizedScenarios(db, projectId, null);
-            expect(result).toEqual([
-                {
-                    componentName: 'LibraryPage',
-                    scenarioNames: ['Full Library Page', 'Empty Library Page'],
-                    url: '/library',
-                },
-            ]);
-        });
-        it('should not flag page-level scenarios (no component_name)', async () => {
-            // App-level scenarios have no component_name — they're fine with real URLs
+            // Entity without analysis — needs analysis
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('entities')
                 .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'Library with Articles',
-                url: '/',
-                created_at: '2026-03-17 12:25:14',
+                sha: 'sha-rule',
+                name: 'RuleBuilder',
+                entity_type: 'visual',
+                file_path: 'app/components/RuleBuilder.tsx',
             })
                 .execute();
-            const result = await queryMiscategorizedScenarios(db, projectId, null);
-            expect(result).toEqual([]);
-        });
-        it('should group miscategorized scenarios by component and URL', async () => {
-            // Two different components both misusing real URLs
+            const allFilePaths = [
+                'app/components/Header.tsx',
+                'app/components/RuleBuilder.tsx',
+                'app/components/Footer.tsx', // no entity — needs analysis
+            ];
+            const result = await filterToIncompleteFilePaths(db, projectId, allFilePaths);
+            expect(result).toContain('app/components/RuleBuilder.tsx');
+            expect(result).toContain('app/components/Footer.tsx');
+            expect(result).not.toContain('app/components/Header.tsx');
+        });
+        it('should return all file paths when no entities exist yet', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            const filePaths = ['app/Foo.tsx', 'app/Bar.tsx'];
+            const result = await filterToIncompleteFilePaths(db, projectId, filePaths);
+            expect(result).toEqual(filePaths);
+        });
+        it('should return empty when all files have analyzed entities', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('entities')
                 .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'Full Library Page',
-                component_name: 'LibraryPage',
-                url: '/library',
-                created_at: '2026-03-17 12:41:40',
+                sha: 'sha-a',
+                name: 'CompA',
+                entity_type: 'visual',
+                file_path: 'app/CompA.tsx',
             })
                 .execute();
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('analyses')
                 .values({
-                id: 'sc-2',
+                id: 'a-1',
+                entity_sha: 'sha-a',
+                entity_name: 'CompA',
                 project_id: projectId,
-                name: 'Dashboard - Full',
-                component_name: 'Dashboard',
-                url: '/dashboard',
-                created_at: '2026-03-17 12:50:00',
             })
                 .execute();
-            const result = await queryMiscategorizedScenarios(db, projectId, null);
-            expect(result).toHaveLength(2);
-            expect(result.map((r) => r.componentName).sort()).toEqual([
-                'Dashboard',
-                'LibraryPage',
+            const result = await filterToIncompleteFilePaths(db, projectId, [
+                'app/CompA.tsx',
             ]);
+            expect(result).toEqual([]);
         });
-        it('should scope to session when featureStartedAt is provided', async () => {
-            // Old miscategorized scenario — before session
-            await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-old',
-                project_id: projectId,
-                name: 'Old Page',
-                component_name: 'OldComponent',
-                url: '/old',
-                created_at: '2026-03-16 10:00:00',
-            })
-                .execute();
-            // New miscategorized scenario — in session
+        it('should skip files with analysis even without scenarios', async () => {
+            const { filterToIncompleteFilePaths } = require('../editorAudit');
+            // Entity with analysis but NO scenarios — still complete
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('entities')
                 .values({
-                id: 'sc-new',
-                project_id: projectId,
-                name: 'Full Library Page',
-                component_name: 'LibraryPage',
-                url: '/library',
-                created_at: '2026-03-17 12:41:40',
+                sha: 'sha-util',
+                name: 'utils',
+                entity_type: 'library',
+                file_path: 'app/lib/utils.ts',
             })
                 .execute();
-            const result = await queryMiscategorizedScenarios(db, projectId, '2026-03-17T11:58:55.562Z');
-            expect(result).toHaveLength(1);
-            expect(result[0].componentName).toBe('LibraryPage');
-        });
-        it('should not flag component scenarios with null URL', async () => {
             await db
-                .insertInto('editor_scenarios')
+                .insertInto('analyses')
                 .values({
-                id: 'sc-1',
+                id: 'a-1',
+                entity_sha: 'sha-util',
+                entity_name: 'utils',
                 project_id: projectId,
-                name: 'NoUrl - Default',
-                component_name: 'NoUrl',
-                created_at: '2026-03-17 12:00:00',
             })
                 .execute();
-            const result = await queryMiscategorizedScenarios(db, projectId, null);
+            const result = await filterToIncompleteFilePaths(db, projectId, [
+                'app/lib/utils.ts',
+            ]);
             expect(result).toEqual([]);
         });
     });
-    // ── isOnlyIncompleteEntities ─────────────────────────────────────────
-    describe('isOnlyIncompleteEntities', () => {
-        it('should return true when incompleteEntities is the only failure', () => {
-            expect(isOnlyIncompleteEntities({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                incompleteEntities: 3,
-                allPassing: false,
-            })).toBe(true);
-        });
-        it('should return false when there are also missing components', () => {
-            expect(isOnlyIncompleteEntities({
-                componentsMissing: 1,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                incompleteEntities: 2,
-                allPassing: false,
-            })).toBe(false);
-        });
-        it('should return false when there are also failing tests', () => {
-            expect(isOnlyIncompleteEntities({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 1,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                incompleteEntities: 2,
-                allPassing: false,
-            })).toBe(false);
-        });
-        it('should return false when there are also missing glossary entries', () => {
-            expect(isOnlyIncompleteEntities({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 1,
-                incompleteEntities: 2,
-                allPassing: false,
-            })).toBe(false);
-        });
-        it('should return true even when incompleteEntities is 0 (no failures at all)', () => {
-            // Edge case: all zeros means nothing is failing
-            expect(isOnlyIncompleteEntities({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                incompleteEntities: 0,
-                allPassing: true,
-            })).toBe(true);
-        });
-        it('should return false when there are also miscategorized scenarios', () => {
-            expect(isOnlyIncompleteEntities({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                miscategorizedScenarios: 1,
-                incompleteEntities: 2,
-                allPassing: false,
-            })).toBe(false);
-        });
-        it('should handle missing fields gracefully', () => {
-            // Summary from older API version might not have all fields
-            expect(isOnlyIncompleteEntities({
-                incompleteEntities: 2,
-                allPassing: false,
-            })).toBe(true);
-        });
-    });
-    // ── isAutoRemediable ─────────────────────────────────────────────────
-    describe('isAutoRemediable', () => {
-        it('should return true on first attempt when only incomplete entities', () => {
-            const result = isAutoRemediable({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                miscategorizedScenarios: 0,
-                incompleteEntities: 3,
-                allPassing: false,
-            }, false);
-            expect(result).toBe(true);
-        });
-        it('should return false on second attempt (already tried once)', () => {
-            // This is the key fix: if we already tried analyze-imports and
-            // entities are STILL incomplete, don't try again — report the failure
-            const result = isAutoRemediable({
-                componentsMissing: 0,
-                componentsWithErrors: 0,
-                functionsFailing: 0,
-                functionsNameMismatch: 0,
-                functionsMissing: 0,
-                missingFromGlossary: 0,
-                miscategorizedScenarios: 0,
-                incompleteEntities: 3,
-                allPassing: false,
-            }, true);
-            expect(result).toBe(false);
-        });
-        it('should return false when there are other failures besides incomplete entities', () => {
-            const result = isAutoRemediable({
-                componentsMissing: 1,
-                incompleteEntities: 3,
-                allPassing: false,
-            }, false);
-            expect(result).toBe(false);
-        });
-        it('should return false when there are no incomplete entities', () => {
-            const result = isAutoRemediable({
-                componentsMissing: 1,
-                allPassing: false,
-            }, false);
-            expect(result).toBe(false);
-        });
-    });
-    // ── queryIncompleteEntities ─────────────────────────────────────────
-    describe('queryIncompleteEntities', () => {
+    // ── phantom entity SHAs ─────────────────────────────────────────────
+    describe('queryIncompleteEntities with phantom entity SHAs', () => {
+        // Root cause of the Margo/reader step-blocking bug:
+        // Scenarios registered without component_path got a phantom entity_sha
+        // computed from component_name alone. These SHAs have NO entity record
+        // in the entities table and NO analyses. syncScenarioEntityShas can't
+        // fix them (it skips scenarios without component_path). So they remain
+        // "incomplete" forever, blocking step progression.
+        //
+        // Fix: queryIncompleteEntities should not report scenarios whose
+        // entity_sha has no entity record — these are orphaned data, not
+        // fixable by running analyze-imports.
         let db;
         let rawDb;
         const projectId = 'test-project-id';
@@ -1803,123 +1790,154 @@ describe('editorAudit', () => {
         afterEach(async () => {
             await db.destroy();
         });
-        it('should return empty when all scenario entity SHAs have analyses', async () => {
-            // Entity with analysis
+        it('should not report scenarios with phantom entity SHAs (no entity record exists)', async () => {
+            // Real entity — has an entity record, analyses, and scenarios. Complete.
             await db
                 .insertInto('entities')
                 .values({
-                sha: 'sha-header',
-                name: 'Header',
+                sha: 'sha-real',
+                name: 'RuleBuilder',
                 entity_type: 'visual',
-                file_path: 'src/Header.tsx',
+                file_path: 'app/components/RuleBuilder.tsx',
             })
                 .execute();
             await db
                 .insertInto('analyses')
                 .values({
                 id: 'a-1',
-                entity_sha: 'sha-header',
-                entity_name: 'Header',
+                entity_sha: 'sha-real',
+                entity_name: 'RuleBuilder',
                 project_id: projectId,
             })
                 .execute();
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-1',
+                id: 'sc-good',
                 project_id: projectId,
-                name: 'Header - Default',
-                component_name: 'Header',
-                entity_sha: 'sha-header',
+                name: 'RuleBuilder - Empty',
+                component_name: 'RuleBuilder',
+                component_path: 'app/components/RuleBuilder.tsx',
+                entity_sha: 'sha-real',
                 created_at: '2026-03-16 23:00:00',
             })
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([]);
+            // Phantom entity — scenario points to a SHA that doesn't exist
+            // in the entities table (registered without component_path).
+            // No entity record, no analyses, unfixable by analyze-imports.
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-phantom',
+                project_id: projectId,
+                name: 'Empty',
+                component_name: 'RuleBuilder',
+                component_path: null,
+                entity_sha: 'sha-phantom-no-entity-record',
+                created_at: '2026-03-16 22:00:00',
+            })
+                .execute();
+            const incomplete = await queryIncompleteEntities(db, projectId, null);
+            // Should NOT report phantom SHAs as incomplete — they can't be fixed
+            // by running analyze-imports (no entity record exists to resolve).
+            expect(incomplete).toHaveLength(0);
         });
-        it('should return entities with scenarios but no analyses', async () => {
-            // Entity WITHOUT analysis
+        it('should still report real incomplete entities (entity exists but no analysis)', async () => {
+            // Real entity without analysis — this IS a legitimate incomplete entity
             await db
                 .insertInto('entities')
                 .values({
-                sha: 'sha-chips',
-                name: 'CollectionChips',
+                sha: 'sha-noanalysis',
+                name: 'Footer',
                 entity_type: 'visual',
-                file_path: 'src/components/CollectionChips.tsx',
+                file_path: 'app/components/Footer.tsx',
             })
                 .execute();
-            // Scenario referencing that entity
             await db
                 .insertInto('editor_scenarios')
                 .values({
                 id: 'sc-1',
                 project_id: projectId,
-                name: 'CollectionChips - Default',
-                component_name: 'CollectionChips',
-                entity_sha: 'sha-chips',
+                name: 'Footer - Default',
+                component_name: 'Footer',
+                component_path: 'app/components/Footer.tsx',
+                entity_sha: 'sha-noanalysis',
                 created_at: '2026-03-16 23:00:00',
             })
                 .execute();
+            // Phantom scenario (shouldn't affect results)
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-2',
+                id: 'sc-phantom',
                 project_id: projectId,
-                name: 'CollectionChips - Many',
-                component_name: 'CollectionChips',
-                entity_sha: 'sha-chips',
-                created_at: '2026-03-16 23:01:00',
+                name: 'Footer - Alt',
+                component_name: 'Footer',
+                component_path: null,
+                entity_sha: 'sha-phantom-does-not-exist',
+                created_at: '2026-03-16 22:00:00',
             })
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-chips',
-                    name: 'CollectionChips',
-                    scenarioCount: 2,
-                    preExisting: false,
-                },
-            ]);
+            const incomplete = await queryIncompleteEntities(db, projectId, null);
+            // Should report Footer (real entity, no analysis) but NOT the phantom
+            expect(incomplete).toHaveLength(1);
+            expect(incomplete[0].name).toBe('Footer');
+            expect(incomplete[0].entitySha).toBe('sha-noanalysis');
         });
-        it('should only return entities without analyses, not those with analyses', async () => {
-            // Entity WITH analysis (Header)
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-header',
-                name: 'Header',
-                entity_type: 'visual',
-                file_path: 'src/Header.tsx',
-            })
+    });
+    // ── queryMiscategorizedScenarios ─────────────────────────────────────
+    describe('queryMiscategorizedScenarios', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('editor_scenarios')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('project_id', 'varchar', (col) => col.notNull())
+                .addColumn('name', 'varchar', (col) => col.notNull())
+                .addColumn('component_name', 'varchar')
+                .addColumn('component_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', 'varchar')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('url', 'varchar')
+                .addColumn('created_at', 'datetime')
+                .addColumn('updated_at', 'datetime')
                 .execute();
+        });
+        afterEach(async () => {
+            await db.destroy();
+        });
+        it('should return empty when all component scenarios use isolation routes', async () => {
             await db
-                .insertInto('analyses')
+                .insertInto('editor_scenarios')
                 .values({
-                id: 'a-1',
-                entity_sha: 'sha-header',
-                entity_name: 'Header',
+                id: 'sc-1',
                 project_id: projectId,
+                name: 'LibraryCard - Default',
+                component_name: 'LibraryCard',
+                url: '/isolated-components/LibraryCard?s=Default',
+                created_at: '2026-03-17 12:00:00',
             })
                 .execute();
+            const result = await queryMiscategorizedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should flag component scenarios that use non-isolation URLs', async () => {
+            // This is the bug: "Full Library Page" registered as component_name=LibraryPage
+            // but url=/library — it's pointing at the real page, not an isolation route
             await db
                 .insertInto('editor_scenarios')
                 .values({
                 id: 'sc-1',
                 project_id: projectId,
-                name: 'Header - Default',
-                component_name: 'Header',
-                entity_sha: 'sha-header',
-                created_at: '2026-03-16 23:00:00',
-            })
-                .execute();
-            // Entity WITHOUT analysis (CollectionPicker)
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-picker',
-                name: 'CollectionPicker',
-                entity_type: 'visual',
-                file_path: 'src/components/CollectionPicker.tsx',
+                name: 'Full Library Page',
+                component_name: 'LibraryPage',
+                url: '/library',
+                created_at: '2026-03-17 12:41:40',
             })
                 .execute();
             await db
@@ -1927,490 +1945,907 @@ describe('editorAudit', () => {
                 .values({
                 id: 'sc-2',
                 project_id: projectId,
-                name: 'CollectionPicker - Default',
-                component_name: 'CollectionPicker',
-                entity_sha: 'sha-picker',
-                created_at: '2026-03-16 23:00:00',
+                name: 'Empty Library Page',
+                component_name: 'LibraryPage',
+                url: '/library',
+                created_at: '2026-03-17 12:41:51',
             })
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, null);
+            const result = await queryMiscategorizedScenarios(db, projectId, null);
             expect(result).toEqual([
                 {
-                    entitySha: 'sha-picker',
-                    name: 'CollectionPicker',
-                    scenarioCount: 1,
-                    preExisting: false,
+                    componentName: 'LibraryPage',
+                    scenarioNames: ['Full Library Page', 'Empty Library Page'],
+                    url: '/library',
                 },
             ]);
         });
-        it('should return both pre-session and in-session entities with preExisting flags', async () => {
-            // Entity without analysis, scenario created BEFORE session
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-old',
-                name: 'OldComponent',
-                entity_type: 'visual',
-                file_path: 'src/OldComponent.tsx',
-            })
-                .execute();
+        it('should not flag page-level scenarios (no component_name)', async () => {
+            // App-level scenarios have no component_name — they're fine with real URLs
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-old',
+                id: 'sc-1',
                 project_id: projectId,
-                name: 'OldComponent - Default',
-                component_name: 'OldComponent',
-                entity_sha: 'sha-old',
-                created_at: '2026-03-16 20:00:00',
-            })
-                .execute();
-            // Entity without analysis, scenario created DURING session
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-new',
-                name: 'NewComponent',
-                entity_type: 'visual',
-                file_path: 'src/NewComponent.tsx',
+                name: 'Library with Articles',
+                url: '/',
+                created_at: '2026-03-17 12:25:14',
             })
                 .execute();
+            const result = await queryMiscategorizedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should group miscategorized scenarios by component and URL', async () => {
+            // Two different components both misusing real URLs
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-new',
+                id: 'sc-1',
                 project_id: projectId,
-                name: 'NewComponent - Default',
-                component_name: 'NewComponent',
-                entity_sha: 'sha-new',
-                created_at: '2026-03-16 23:10:00',
-            })
-                .execute();
-            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
-            // Both should be returned — OldComponent is preExisting, NewComponent is not
-            expect(result).toEqual(expect.arrayContaining([
-                {
-                    entitySha: 'sha-old',
-                    name: 'OldComponent',
-                    scenarioCount: 1,
-                    preExisting: true,
-                },
-                {
-                    entitySha: 'sha-new',
-                    name: 'NewComponent',
-                    scenarioCount: 1,
-                    preExisting: false,
-                },
-            ]));
-            expect(result).toHaveLength(2);
-        });
-        it('should flag preExisting: false when scenario was updated in session even if created before', async () => {
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-updated',
-                name: 'UpdatedComponent',
-                entity_type: 'visual',
-                file_path: 'src/Updated.tsx',
+                name: 'Full Library Page',
+                component_name: 'LibraryPage',
+                url: '/library',
+                created_at: '2026-03-17 12:41:40',
             })
                 .execute();
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-updated',
+                id: 'sc-2',
                 project_id: projectId,
-                name: 'UpdatedComponent - Default',
-                component_name: 'UpdatedComponent',
-                entity_sha: 'sha-updated',
-                created_at: '2026-03-16 20:00:00',
-                updated_at: '2026-03-16 23:20:00', // Updated in session
+                name: 'Dashboard - Full',
+                component_name: 'Dashboard',
+                url: '/dashboard',
+                created_at: '2026-03-17 12:50:00',
             })
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-updated',
-                    name: 'UpdatedComponent',
-                    scenarioCount: 1,
-                    preExisting: false,
-                },
+            const result = await queryMiscategorizedScenarios(db, projectId, null);
+            expect(result).toHaveLength(2);
+            expect(result.map((r) => r.componentName).sort()).toEqual([
+                'Dashboard',
+                'LibraryPage',
             ]);
         });
-        it('should skip scenarios with null entity_sha', async () => {
+        it('should scope to session when featureStartedAt is provided', async () => {
+            // Old miscategorized scenario — before session
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-null',
-                project_id: projectId,
-                name: 'Orphan Scenario',
-                component_name: 'Orphan',
-                created_at: '2026-03-16 23:00:00',
-            })
-                .execute();
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([]);
-        });
-        it('should return empty when there are no scenarios', async () => {
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([]);
-        });
-        it('should not flag entities when a sibling version (same name+filePath) has analyses', async () => {
-            // Old entity version WITH analysis
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-btn-v1',
-                name: 'OpenLibraryButton',
-                entity_type: 'visual',
-                file_path: 'src/components/OpenLibraryButton.tsx',
-            })
-                .execute();
-            await db
-                .insertInto('analyses')
-                .values({
-                id: 'a-btn-v1',
-                entity_sha: 'sha-btn-v1',
-                entity_name: 'OpenLibraryButton',
+                id: 'sc-old',
                 project_id: projectId,
+                name: 'Old Page',
+                component_name: 'OldComponent',
+                url: '/old',
+                created_at: '2026-03-16 10:00:00',
             })
                 .execute();
-            // New entity version WITHOUT analysis (created by file watcher)
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-btn-v2',
-                name: 'OpenLibraryButton',
-                entity_type: 'visual',
-                file_path: 'src/components/OpenLibraryButton.tsx',
-            })
-                .execute();
-            // Scenario points to the NEW version (backfilled after file watcher)
+            // New miscategorized scenario — in session
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-btn',
+                id: 'sc-new',
                 project_id: projectId,
-                name: 'OpenLibraryButton - Default',
-                component_name: 'OpenLibraryButton',
-                entity_sha: 'sha-btn-v2',
-                created_at: '2026-03-16 23:00:00',
+                name: 'Full Library Page',
+                component_name: 'LibraryPage',
+                url: '/library',
+                created_at: '2026-03-17 12:41:40',
             })
                 .execute();
-            // Should NOT flag as incomplete — sibling version has analyses
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([]);
+            const result = await queryMiscategorizedScenarios(db, projectId, '2026-03-17T11:58:55.562Z');
+            expect(result).toHaveLength(1);
+            expect(result[0].componentName).toBe('LibraryPage');
         });
-        it('should flag entity when sibling has analyses but different filePath (extracted component)', async () => {
-            // Old entity version WITH analysis at ORIGINAL file path
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-card-v1',
-                name: 'TaskCard',
-                entity_type: 'visual',
-                file_path: 'app/page.tsx',
-            })
-                .execute();
-            await db
-                .insertInto('analyses')
-                .values({
-                id: 'a-card-v1',
-                entity_sha: 'sha-card-v1',
-                entity_name: 'TaskCard',
-                project_id: projectId,
-            })
-                .execute();
-            // New entity version WITHOUT analysis at EXTRACTED file path
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-card-v2',
-                name: 'TaskCard',
-                entity_type: 'visual',
-                file_path: 'app/components/TaskCard.tsx',
-            })
-                .execute();
-            // Scenario points to the new version (synced by syncScenarioEntityShas)
+        it('should not flag component scenarios with null URL', async () => {
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-card',
+                id: 'sc-1',
                 project_id: projectId,
-                name: 'TaskCard - Default',
-                component_name: 'TaskCard',
-                entity_sha: 'sha-card-v2',
-                created_at: '2026-03-16 23:00:00',
+                name: 'NoUrl - Default',
+                component_name: 'NoUrl',
+                created_at: '2026-03-17 12:00:00',
             })
                 .execute();
-            // SHOULD flag as incomplete — sibling has analyses but at a different filePath,
-            // so getAllEntities() won't inherit (it matches by name+filePath)
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-card-v2',
-                    name: 'TaskCard',
-                    scenarioCount: 1,
-                    preExisting: false,
-                },
-            ]);
+            const result = await queryMiscategorizedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
         });
-        it('should still flag entities when no sibling version has analyses', async () => {
-            // Only one version, no analyses
-            await db
-                .insertInto('entities')
-                .values({
-                sha: 'sha-icon',
-                name: 'ExternalLinkIcon',
-                entity_type: 'visual',
-                file_path: 'src/components/ExternalLinkIcon.tsx',
-            })
-                .execute();
-            await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-icon',
-                project_id: projectId,
-                name: 'ExternalLinkIcon - Default',
-                component_name: 'ExternalLinkIcon',
-                entity_sha: 'sha-icon',
-                created_at: '2026-03-16 23:00:00',
-            })
-                .execute();
-            // Should flag as incomplete — no version has analyses
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-icon',
-                    name: 'ExternalLinkIcon',
-                    scenarioCount: 1,
-                    preExisting: false,
-                },
-            ]);
+    });
+    // ── isOnlyIncompleteEntities ─────────────────────────────────────────
+    describe('isOnlyIncompleteEntities', () => {
+        it('should return true when incompleteEntities is the only failure', () => {
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                incompleteEntities: 3,
+                allPassing: false,
+            })).toBe(true);
         });
-        it('should use entity name from entities table, falling back to component_name', async () => {
-            // Scenario has entity_sha but entity record doesn't exist
-            await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'Ghost - Default',
-                component_name: 'GhostComponent',
-                entity_sha: 'sha-ghost',
-                created_at: '2026-03-16 23:00:00',
-            })
+        it('should return false when there are also missing components', () => {
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 1,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                incompleteEntities: 2,
+                allPassing: false,
+            })).toBe(false);
+        });
+        it('should return false when there are also failing tests', () => {
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 1,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                incompleteEntities: 2,
+                allPassing: false,
+            })).toBe(false);
+        });
+        it('should return false when there are also missing glossary entries', () => {
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 1,
+                incompleteEntities: 2,
+                allPassing: false,
+            })).toBe(false);
+        });
+        it('should return true even when incompleteEntities is 0 (no failures at all)', () => {
+            // Edge case: all zeros means nothing is failing
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                incompleteEntities: 0,
+                allPassing: true,
+            })).toBe(true);
+        });
+        it('should return false when there are also miscategorized scenarios', () => {
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 1,
+                incompleteEntities: 2,
+                allPassing: false,
+            })).toBe(false);
+        });
+        it('should handle missing fields gracefully', () => {
+            // Summary from older API version might not have all fields
+            expect(isOnlyIncompleteEntities({
+                incompleteEntities: 2,
+                allPassing: false,
+            })).toBe(true);
+        });
+        it('should return false when there are also runner errors', () => {
+            // functionsRunnerError means the test runner crashed — a real failure
+            // that cannot be fixed by entity SHA backfill or analyze-imports.
+            // If this returns true, checkAuditGate would attempt a useless backfill
+            // instead of reporting the runner error, and isOnlyPreExistingIncomplete
+            // could let the gate pass entirely.
+            expect(isOnlyIncompleteEntities({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsRunnerError: 2,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                incompleteEntities: 1,
+                allPassing: false,
+            })).toBe(false);
+        });
+    });
+    // ── isAutoRemediable ─────────────────────────────────────────────────
+    describe('isAutoRemediable', () => {
+        // isAutoRemediable always returns false — the audit never triggers
+        // full analyze-imports inline. It takes minutes on large projects.
+        // Only lightweight backfill is acceptable during audit.
+        it('should return false even on first attempt with only incomplete entities', () => {
+            const result = isAutoRemediable({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 0,
+                incompleteEntities: 3,
+                allPassing: false,
+            }, false);
+            expect(result).toBe(false);
+        });
+        it('should return false on second attempt', () => {
+            const result = isAutoRemediable({
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 0,
+                incompleteEntities: 3,
+                allPassing: false,
+            }, true);
+            expect(result).toBe(false);
+        });
+        it('should return false when there are other failures besides incomplete entities', () => {
+            const result = isAutoRemediable({
+                componentsMissing: 1,
+                incompleteEntities: 3,
+                allPassing: false,
+            }, false);
+            expect(result).toBe(false);
+        });
+        it('should return false when there are no incomplete entities', () => {
+            const result = isAutoRemediable({
+                componentsMissing: 1,
+                allPassing: false,
+            }, false);
+            expect(result).toBe(false);
+        });
+    });
+    // ── queryIncompleteEntities ─────────────────────────────────────────
+    describe('queryIncompleteEntities', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('editor_scenarios')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('project_id', 'varchar', (col) => col.notNull())
+                .addColumn('name', 'varchar', (col) => col.notNull())
+                .addColumn('component_name', 'varchar')
+                .addColumn('component_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', 'varchar')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('url', 'varchar')
+                .addColumn('created_at', 'datetime')
+                .addColumn('updated_at', 'datetime')
+                .execute();
+            await db.schema
+                .createTable('analyses')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('entity_name', 'varchar')
+                .addColumn('project_id', 'varchar')
+                .execute();
+            await db.schema
+                .createTable('entities')
+                .addColumn('sha', 'varchar', (col) => col.primaryKey())
+                .addColumn('name', 'varchar')
+                .addColumn('entity_type', 'varchar')
+                .addColumn('file_path', 'varchar')
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, null);
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-ghost',
-                    name: 'GhostComponent',
-                    scenarioCount: 1,
-                    preExisting: false,
-                },
-            ]);
         });
-        it('should detect incomplete entity whose scenario predates the session', async () => {
-            // Entity with no analyses, scenario created BEFORE session
+        afterEach(async () => {
+            await db.destroy();
+        });
+        it('should return empty when all scenario entity SHAs have analyses', async () => {
+            // Entity with analysis
             await db
                 .insertInto('entities')
                 .values({
-                sha: 'sha-preexisting',
-                name: 'PreExistingComponent',
+                sha: 'sha-header',
+                name: 'Header',
                 entity_type: 'visual',
-                file_path: 'src/PreExistingComponent.tsx',
+                file_path: 'src/Header.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-1',
+                entity_sha: 'sha-header',
+                entity_name: 'Header',
+                project_id: projectId,
             })
                 .execute();
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-preexisting',
+                id: 'sc-1',
                 project_id: projectId,
-                name: 'PreExistingComponent - Default',
-                component_name: 'PreExistingComponent',
-                entity_sha: 'sha-preexisting',
-                created_at: '2026-03-16 20:00:00',
-                updated_at: '2026-03-16 20:00:00',
+                name: 'Header - Default',
+                component_name: 'Header',
+                entity_sha: 'sha-header',
+                created_at: '2026-03-16 23:00:00',
             })
                 .execute();
-            // Session started well after scenario was created/updated
-            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
-            // Should still be detected — the old time filter would have excluded it
-            expect(result).toEqual([
-                {
-                    entitySha: 'sha-preexisting',
-                    name: 'PreExistingComponent',
-                    scenarioCount: 1,
-                    preExisting: true,
-                },
-            ]);
+            const result = await queryIncompleteEntities(db, projectId, null);
+            expect(result).toEqual([]);
         });
-        it('should flag preExisting: true when all scenarios predate the session', async () => {
+        it('should return entities with scenarios but no analyses', async () => {
+            // Entity WITHOUT analysis
             await db
                 .insertInto('entities')
                 .values({
-                sha: 'sha-old-entity',
-                name: 'OldEntity',
+                sha: 'sha-chips',
+                name: 'CollectionChips',
                 entity_type: 'visual',
-                file_path: 'src/OldEntity.tsx',
+                file_path: 'src/components/CollectionChips.tsx',
             })
                 .execute();
-            // Two scenarios, both before session
+            // Scenario referencing that entity
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-old-1',
+                id: 'sc-1',
                 project_id: projectId,
-                name: 'OldEntity - Default',
-                component_name: 'OldEntity',
-                entity_sha: 'sha-old-entity',
-                created_at: '2026-03-16 19:00:00',
-                updated_at: '2026-03-16 19:00:00',
+                name: 'CollectionChips - Default',
+                component_name: 'CollectionChips',
+                entity_sha: 'sha-chips',
+                created_at: '2026-03-16 23:00:00',
             })
                 .execute();
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-old-2',
+                id: 'sc-2',
                 project_id: projectId,
-                name: 'OldEntity - Hover',
-                component_name: 'OldEntity',
-                entity_sha: 'sha-old-entity',
-                created_at: '2026-03-16 19:30:00',
-                updated_at: '2026-03-16 19:30:00',
+                name: 'CollectionChips - Many',
+                component_name: 'CollectionChips',
+                entity_sha: 'sha-chips',
+                created_at: '2026-03-16 23:01:00',
             })
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            const result = await queryIncompleteEntities(db, projectId, null);
             expect(result).toEqual([
                 {
-                    entitySha: 'sha-old-entity',
-                    name: 'OldEntity',
+                    entitySha: 'sha-chips',
+                    name: 'CollectionChips',
                     scenarioCount: 2,
-                    preExisting: true,
+                    preExisting: false,
                 },
             ]);
         });
-        it('should flag preExisting: false when scenario is from the current session', async () => {
+        it('should only return entities without analyses, not those with analyses', async () => {
+            // Entity WITH analysis (Header)
             await db
                 .insertInto('entities')
                 .values({
-                sha: 'sha-session-entity',
-                name: 'SessionEntity',
+                sha: 'sha-header',
+                name: 'Header',
                 entity_type: 'visual',
-                file_path: 'src/SessionEntity.tsx',
+                file_path: 'src/Header.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-1',
+                entity_sha: 'sha-header',
+                entity_name: 'Header',
+                project_id: projectId,
             })
                 .execute();
             await db
                 .insertInto('editor_scenarios')
                 .values({
-                id: 'sc-session',
+                id: 'sc-1',
                 project_id: projectId,
-                name: 'SessionEntity - Default',
-                component_name: 'SessionEntity',
-                entity_sha: 'sha-session-entity',
-                created_at: '2026-03-16 23:30:00',
-                updated_at: '2026-03-16 23:30:00',
+                name: 'Header - Default',
+                component_name: 'Header',
+                entity_sha: 'sha-header',
+                created_at: '2026-03-16 23:00:00',
             })
                 .execute();
-            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            // Entity WITHOUT analysis (CollectionPicker)
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-picker',
+                name: 'CollectionPicker',
+                entity_type: 'visual',
+                file_path: 'src/components/CollectionPicker.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-2',
+                project_id: projectId,
+                name: 'CollectionPicker - Default',
+                component_name: 'CollectionPicker',
+                entity_sha: 'sha-picker',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, null);
             expect(result).toEqual([
                 {
-                    entitySha: 'sha-session-entity',
-                    name: 'SessionEntity',
+                    entitySha: 'sha-picker',
+                    name: 'CollectionPicker',
                     scenarioCount: 1,
                     preExisting: false,
                 },
             ]);
         });
-    });
-    // ── identifyScenariosNeedingRecapture ──────────────────────────────
-    describe('identifyScenariosNeedingRecapture', () => {
-        // Reproduces the Margo bug: Feature 1 built app-level popup scenarios,
-        // Feature 2 edited LibraryView (used by App), but app-level scenarios
-        // were never flagged for recapture because the audit only checked
-        // component scenario existence — not whether app-level scenarios are stale.
-        //
-        // Each scenario's entityName is resolved by the caller via
-        // entity_sha → entities.name (the default export for app-level scenarios).
-        it('should flag app-level scenario when its entity is impacted by transitive dependency change', () => {
-            // LibraryView was edited → App is impacted (imports LibraryView)
-            // App-level scenario "Library - Rich Library" has entity_sha pointing to App
-            // It was NOT recaptured during Feature 2 → should be flagged
-            const entityChangeStatus = {
-                LibraryView: { status: 'edited' },
-                App: {
-                    status: 'impacted',
-                    impactedBy: [
-                        {
-                            name: 'LibraryView',
-                            filePath: 'src/components/LibraryView.tsx',
-                            changeType: 'edited',
-                        },
-                    ],
+        it('should return both pre-session and in-session entities with preExisting flags', async () => {
+            // Entity without analysis, scenario created BEFORE session
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-old',
+                name: 'OldComponent',
+                entity_type: 'visual',
+                file_path: 'src/OldComponent.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-old',
+                project_id: projectId,
+                name: 'OldComponent - Default',
+                component_name: 'OldComponent',
+                entity_sha: 'sha-old',
+                created_at: '2026-03-16 20:00:00',
+            })
+                .execute();
+            // Entity without analysis, scenario created DURING session
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-new',
+                name: 'NewComponent',
+                entity_type: 'visual',
+                file_path: 'src/NewComponent.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-new',
+                project_id: projectId,
+                name: 'NewComponent - Default',
+                component_name: 'NewComponent',
+                entity_sha: 'sha-new',
+                created_at: '2026-03-16 23:10:00',
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            // Both should be returned — OldComponent is preExisting, NewComponent is not
+            expect(result).toEqual(expect.arrayContaining([
+                {
+                    entitySha: 'sha-old',
+                    name: 'OldComponent',
+                    scenarioCount: 1,
+                    preExisting: true,
                 },
-            };
-            const result = identifyScenariosNeedingRecapture({
-                scenarios: [
-                    {
-                        name: 'Library - Rich Library',
-                        entityName: 'App', // resolved from entity_sha → entities.name
-                        updatedInSession: false,
-                    },
-                ],
-                entityChangeStatus,
-            });
-            expect(result).toHaveLength(1);
-            expect(result[0].scenarioName).toBe('Library - Rich Library');
-            expect(result[0].entityName).toBe('App');
-            expect(result[0].status.status).toBe('impacted');
-        });
-        it('should flag component scenario when its entity is directly edited and not recaptured', () => {
-            const entityChangeStatus = {
-                LibraryView: { status: 'edited' },
-            };
-            const result = identifyScenariosNeedingRecapture({
-                scenarios: [
-                    {
-                        name: 'LibraryView - Empty',
-                        entityName: 'LibraryView',
-                        updatedInSession: false,
-                    },
-                ],
-                entityChangeStatus,
-            });
-            expect(result).toHaveLength(1);
-            expect(result[0].scenarioName).toBe('LibraryView - Empty');
-            expect(result[0].entityName).toBe('LibraryView');
-            expect(result[0].status.status).toBe('edited');
+                {
+                    entitySha: 'sha-new',
+                    name: 'NewComponent',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]));
+            expect(result).toHaveLength(2);
         });
-        it('should NOT flag scenario that was already recaptured in the current session', () => {
-            const entityChangeStatus = {
-                App: {
-                    status: 'impacted',
-                    impactedBy: [
-                        {
-                            name: 'LibraryView',
-                            filePath: 'src/components/LibraryView.tsx',
-                            changeType: 'edited',
-                        },
-                    ],
+        it('should flag preExisting: false when scenario was updated in session even if created before', async () => {
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-updated',
+                name: 'UpdatedComponent',
+                entity_type: 'visual',
+                file_path: 'src/Updated.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-updated',
+                project_id: projectId,
+                name: 'UpdatedComponent - Default',
+                component_name: 'UpdatedComponent',
+                entity_sha: 'sha-updated',
+                created_at: '2026-03-16 20:00:00',
+                updated_at: '2026-03-16 23:20:00', // Updated in session
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            expect(result).toEqual([
+                {
+                    entitySha: 'sha-updated',
+                    name: 'UpdatedComponent',
+                    scenarioCount: 1,
+                    preExisting: false,
                 },
-            };
-            const result = identifyScenariosNeedingRecapture({
-                scenarios: [
-                    {
-                        name: 'App - Default',
-                        entityName: 'App',
-                        updatedInSession: true, // re-registered during Feature 2
-                    },
-                ],
-                entityChangeStatus,
-            });
-            expect(result).toHaveLength(0);
+            ]);
         });
-        it('should NOT flag scenario whose entity has no change status', () => {
-            const entityChangeStatus = {
-                LibraryView: { status: 'edited' },
+        it('should skip scenarios with null entity_sha', async () => {
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-null',
+                project_id: projectId,
+                name: 'Orphan Scenario',
+                component_name: 'Orphan',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should return empty when there are no scenarios', async () => {
+            const result = await queryIncompleteEntities(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should not flag entities when a sibling version (same name+filePath) has analyses', async () => {
+            // Old entity version WITH analysis
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-btn-v1',
+                name: 'OpenLibraryButton',
+                entity_type: 'visual',
+                file_path: 'src/components/OpenLibraryButton.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-btn-v1',
+                entity_sha: 'sha-btn-v1',
+                entity_name: 'OpenLibraryButton',
+                project_id: projectId,
+            })
+                .execute();
+            // New entity version WITHOUT analysis (created by file watcher)
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-btn-v2',
+                name: 'OpenLibraryButton',
+                entity_type: 'visual',
+                file_path: 'src/components/OpenLibraryButton.tsx',
+            })
+                .execute();
+            // Scenario points to the NEW version (backfilled after file watcher)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-btn',
+                project_id: projectId,
+                name: 'OpenLibraryButton - Default',
+                component_name: 'OpenLibraryButton',
+                entity_sha: 'sha-btn-v2',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            // Should NOT flag as incomplete — sibling version has analyses
+            const result = await queryIncompleteEntities(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+        it('should flag entity when sibling has analyses but different filePath (extracted component)', async () => {
+            // Old entity version WITH analysis at ORIGINAL file path
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-card-v1',
+                name: 'TaskCard',
+                entity_type: 'visual',
+                file_path: 'app/page.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('analyses')
+                .values({
+                id: 'a-card-v1',
+                entity_sha: 'sha-card-v1',
+                entity_name: 'TaskCard',
+                project_id: projectId,
+            })
+                .execute();
+            // New entity version WITHOUT analysis at EXTRACTED file path
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-card-v2',
+                name: 'TaskCard',
+                entity_type: 'visual',
+                file_path: 'app/components/TaskCard.tsx',
+            })
+                .execute();
+            // Scenario points to the new version (synced by syncScenarioEntityShas)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-card',
+                project_id: projectId,
+                name: 'TaskCard - Default',
+                component_name: 'TaskCard',
+                entity_sha: 'sha-card-v2',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            // SHOULD flag as incomplete — sibling has analyses but at a different filePath,
+            // so getAllEntities() won't inherit (it matches by name+filePath)
+            const result = await queryIncompleteEntities(db, projectId, null);
+            expect(result).toEqual([
+                {
+                    entitySha: 'sha-card-v2',
+                    name: 'TaskCard',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+        });
+        it('should still flag entities when no sibling version has analyses', async () => {
+            // Only one version, no analyses
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-icon',
+                name: 'ExternalLinkIcon',
+                entity_type: 'visual',
+                file_path: 'src/components/ExternalLinkIcon.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-icon',
+                project_id: projectId,
+                name: 'ExternalLinkIcon - Default',
+                component_name: 'ExternalLinkIcon',
+                entity_sha: 'sha-icon',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            // Should flag as incomplete — no version has analyses
+            const result = await queryIncompleteEntities(db, projectId, null);
+            expect(result).toEqual([
+                {
+                    entitySha: 'sha-icon',
+                    name: 'ExternalLinkIcon',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+        });
+        it('should skip phantom SHAs (entity_sha with no entity record)', async () => {
+            // Scenario has entity_sha but entity record doesn't exist.
+            // These are "phantom SHAs" created when scenarios were registered
+            // without component_path — they can never be fixed by analyze-imports
+            // and should not block audit progression.
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Ghost - Default',
+                component_name: 'GhostComponent',
+                entity_sha: 'sha-ghost',
+                created_at: '2026-03-16 23:00:00',
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, null);
+            // Phantom SHAs are excluded — not reportable as incomplete
+            expect(result).toEqual([]);
+        });
+        it('should detect incomplete entity whose scenario predates the session', async () => {
+            // Entity with no analyses, scenario created BEFORE session
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-preexisting',
+                name: 'PreExistingComponent',
+                entity_type: 'visual',
+                file_path: 'src/PreExistingComponent.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-preexisting',
+                project_id: projectId,
+                name: 'PreExistingComponent - Default',
+                component_name: 'PreExistingComponent',
+                entity_sha: 'sha-preexisting',
+                created_at: '2026-03-16 20:00:00',
+                updated_at: '2026-03-16 20:00:00',
+            })
+                .execute();
+            // Session started well after scenario was created/updated
+            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            // Should still be detected — the old time filter would have excluded it
+            expect(result).toEqual([
+                {
+                    entitySha: 'sha-preexisting',
+                    name: 'PreExistingComponent',
+                    scenarioCount: 1,
+                    preExisting: true,
+                },
+            ]);
+        });
+        it('should flag preExisting: true when all scenarios predate the session', async () => {
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-old-entity',
+                name: 'OldEntity',
+                entity_type: 'visual',
+                file_path: 'src/OldEntity.tsx',
+            })
+                .execute();
+            // Two scenarios, both before session
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-old-1',
+                project_id: projectId,
+                name: 'OldEntity - Default',
+                component_name: 'OldEntity',
+                entity_sha: 'sha-old-entity',
+                created_at: '2026-03-16 19:00:00',
+                updated_at: '2026-03-16 19:00:00',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-old-2',
+                project_id: projectId,
+                name: 'OldEntity - Hover',
+                component_name: 'OldEntity',
+                entity_sha: 'sha-old-entity',
+                created_at: '2026-03-16 19:30:00',
+                updated_at: '2026-03-16 19:30:00',
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            expect(result).toEqual([
+                {
+                    entitySha: 'sha-old-entity',
+                    name: 'OldEntity',
+                    scenarioCount: 2,
+                    preExisting: true,
+                },
+            ]);
+        });
+        it('should flag preExisting: false when scenario is from the current session', async () => {
+            await db
+                .insertInto('entities')
+                .values({
+                sha: 'sha-session-entity',
+                name: 'SessionEntity',
+                entity_type: 'visual',
+                file_path: 'src/SessionEntity.tsx',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-session',
+                project_id: projectId,
+                name: 'SessionEntity - Default',
+                component_name: 'SessionEntity',
+                entity_sha: 'sha-session-entity',
+                created_at: '2026-03-16 23:30:00',
+                updated_at: '2026-03-16 23:30:00',
+            })
+                .execute();
+            const result = await queryIncompleteEntities(db, projectId, '2026-03-16T23:07:12.698Z');
+            expect(result).toEqual([
+                {
+                    entitySha: 'sha-session-entity',
+                    name: 'SessionEntity',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+        });
+    });
+    // ── identifyScenariosNeedingRecapture ──────────────────────────────
+    describe('identifyScenariosNeedingRecapture', () => {
+        // Reproduces the Margo bug: Feature 1 built app-level popup scenarios,
+        // Feature 2 edited LibraryView (used by App), but app-level scenarios
+        // were never flagged for recapture because the audit only checked
+        // component scenario existence — not whether app-level scenarios are stale.
+        //
+        // Each scenario's entityName is resolved by the caller via
+        // entity_sha → entities.name (the default export for app-level scenarios).
+        it('should flag app-level scenario when its entity is impacted by transitive dependency change', () => {
+            // LibraryView was edited → App is impacted (imports LibraryView)
+            // App-level scenario "Library - Rich Library" has entity_sha pointing to App
+            // It was NOT recaptured during Feature 2 → should be flagged
+            const entityChangeStatus = {
+                LibraryView: { status: 'edited' },
+                App: {
+                    status: 'impacted',
+                    impactedBy: [
+                        {
+                            name: 'LibraryView',
+                            filePath: 'src/components/LibraryView.tsx',
+                            changeType: 'edited',
+                        },
+                    ],
+                },
+            };
+            const result = identifyScenariosNeedingRecapture({
+                scenarios: [
+                    {
+                        name: 'Library - Rich Library',
+                        entityName: 'App', // resolved from entity_sha → entities.name
+                        updatedInSession: false,
+                    },
+                ],
+                entityChangeStatus,
+            });
+            expect(result).toHaveLength(1);
+            expect(result[0].scenarioName).toBe('Library - Rich Library');
+            expect(result[0].entityName).toBe('App');
+            expect(result[0].status.status).toBe('impacted');
+        });
+        it('should flag component scenario when its entity is directly edited and not recaptured', () => {
+            const entityChangeStatus = {
+                LibraryView: { status: 'edited' },
+            };
+            const result = identifyScenariosNeedingRecapture({
+                scenarios: [
+                    {
+                        name: 'LibraryView - Empty',
+                        entityName: 'LibraryView',
+                        updatedInSession: false,
+                    },
+                ],
+                entityChangeStatus,
+            });
+            expect(result).toHaveLength(1);
+            expect(result[0].scenarioName).toBe('LibraryView - Empty');
+            expect(result[0].entityName).toBe('LibraryView');
+            expect(result[0].status.status).toBe('edited');
+        });
+        it('should NOT flag scenario that was already recaptured in the current session', () => {
+            const entityChangeStatus = {
+                App: {
+                    status: 'impacted',
+                    impactedBy: [
+                        {
+                            name: 'LibraryView',
+                            filePath: 'src/components/LibraryView.tsx',
+                            changeType: 'edited',
+                        },
+                    ],
+                },
+            };
+            const result = identifyScenariosNeedingRecapture({
+                scenarios: [
+                    {
+                        name: 'App - Default',
+                        entityName: 'App',
+                        updatedInSession: true, // re-registered during Feature 2
+                    },
+                ],
+                entityChangeStatus,
+            });
+            expect(result).toHaveLength(0);
+        });
+        it('should NOT flag scenario whose entity has no change status', () => {
+            const entityChangeStatus = {
+                LibraryView: { status: 'edited' },
             };
             const result = identifyScenariosNeedingRecapture({
                 scenarios: [
@@ -2508,6 +2943,25 @@ describe('editorAudit', () => {
             });
             expect(result).toHaveLength(0);
         });
+        it('should NOT flag scenarios for new entities (they need creation, not recapture)', () => {
+            // "new" entities are being seen for the first time. Their scenarios need
+            // initial creation, not recapture of old screenshots. Flagging them as
+            // "needs_recapture" sends the wrong remediation signal to Claude.
+            const entityChangeStatus = {
+                NewComponent: { status: 'new' },
+            };
+            const result = identifyScenariosNeedingRecapture({
+                scenarios: [
+                    {
+                        name: 'NewComponent - Default',
+                        entityName: 'NewComponent',
+                        updatedInSession: false,
+                    },
+                ],
+                entityChangeStatus,
+            });
+            expect(result).toHaveLength(0);
+        });
     });
     // ── detectDuplicateNames ──────────────────────────────────────────
     describe('detectDuplicateNames', () => {
@@ -2675,6 +3129,28 @@ describe('editorAudit', () => {
             expect(result.components[0].status).toBe('missing');
             expect(result.summary.componentsMissing).toBe(1);
         });
+        it('should not count needs_recapture components as componentsOk', () => {
+            // A needs_recapture component is not "ok" — it needs action. Counting it
+            // in componentsOk is misleading: if totalComponents=2, componentsOk=2,
+            // and componentsNeedingRecapture=1, the numbers don't add up (2+1 > 2).
+            const result = computeAudit({
+                components: [
+                    { name: 'Library', filePath: 'app/library/page.tsx' },
+                    { name: 'DrinkCard', filePath: 'app/components/DrinkCard.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: { DrinkCard: 2 },
+                testFileExistence: {},
+                totalScenarioCounts: { Library: 3 },
+                entityChangeStatus: { Library: { status: 'impacted' } },
+            });
+            expect(result.components[0].status).toBe('needs_recapture');
+            expect(result.components[1].status).toBe('ok');
+            // needs_recapture is not "ok" — should be counted separately
+            expect(result.summary.componentsOk).toBe(1);
+            expect(result.summary.componentsNeedingRecapture).toBe(1);
+            expect(result.summary.totalComponents).toBe(2);
+        });
     });
     // ── queryUnassociatedScenarios ──────────────────────────────────────
     describe('queryUnassociatedScenarios', () => {
@@ -2850,91 +3326,574 @@ describe('editorAudit', () => {
             const result = await queryUnassociatedScenarios(db, projectId, null);
             expect(result).toEqual([]);
         });
-        it('should scope to feature session when featureStartedAt is provided', async () => {
-            // Pre-existing unassociated scenario (before session)
-            await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-old',
-                project_id: projectId,
-                name: 'OldComponent - Default',
-                component_name: 'OldComponent',
-                component_path: 'src/components/OldComponent.tsx',
-                entity_sha: null,
-                created_at: '2026-03-19 10:00:00',
-                updated_at: '2026-03-19 10:00:00',
-            })
-                .execute();
-            // New unassociated scenario (during session)
-            await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-new',
-                project_id: projectId,
-                name: 'NewComponent - Default',
-                component_name: 'NewComponent',
-                component_path: 'src/components/NewComponent.tsx',
-                entity_sha: null,
-                created_at: '2026-03-20 18:45:00',
-                updated_at: '2026-03-20 18:45:00',
-            })
+        it('should scope to feature session when featureStartedAt is provided', async () => {
+            // Pre-existing unassociated scenario (before session)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-old',
+                project_id: projectId,
+                name: 'OldComponent - Default',
+                component_name: 'OldComponent',
+                component_path: 'src/components/OldComponent.tsx',
+                entity_sha: null,
+                created_at: '2026-03-19 10:00:00',
+                updated_at: '2026-03-19 10:00:00',
+            })
+                .execute();
+            // New unassociated scenario (during session)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-new',
+                project_id: projectId,
+                name: 'NewComponent - Default',
+                component_name: 'NewComponent',
+                component_path: 'src/components/NewComponent.tsx',
+                entity_sha: null,
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, '2026-03-20T18:00:00.000Z');
+            // Should only find the session-scoped one
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('NewComponent');
+        });
+        it('should include re-registered scenarios (updated_at in session) even if created before', async () => {
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'SearchBar - Default',
+                component_name: 'SearchBar',
+                component_path: 'src/components/SearchBar.tsx',
+                entity_sha: null,
+                created_at: '2026-03-19 10:00:00',
+                updated_at: '2026-03-20 18:45:00', // re-registered during session
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, '2026-03-20T18:00:00.000Z');
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('SearchBar');
+        });
+        it('should not include scenarios with entity_sha set (even if stale)', async () => {
+            // This scenario has an entity_sha — even if it's stale, that's a
+            // different problem (handled by queryIncompleteEntities)
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: 'sc-1',
+                project_id: projectId,
+                name: 'Header - Default',
+                component_name: 'Header',
+                component_path: 'src/components/Header.tsx',
+                entity_sha: 'sha-old-version',
+                created_at: '2026-03-20 18:45:00',
+                updated_at: '2026-03-20 18:45:00',
+            })
+                .execute();
+            const result = await queryUnassociatedScenarios(db, projectId, null);
+            expect(result).toEqual([]);
+        });
+    });
+    // ── isAutoRemediable with unassociatedScenarios ────────────────────
+    describe('isAutoRemediable always returns false (no inline full analysis)', () => {
+        // Full analyze-imports takes minutes on large projects. The audit should
+        // never trigger it — only the lightweight backfill path is acceptable.
+        it('should return false for unassociatedScenarios only', () => {
+            expect(isAutoRemediable({ unassociatedScenarios: 3 }, false)).toBe(false);
+        });
+        it('should return false for incompleteEntities + unassociatedScenarios', () => {
+            expect(isAutoRemediable({ incompleteEntities: 1, unassociatedScenarios: 2 }, false)).toBe(false);
+        });
+        it('should return false even with no other failures', () => {
+            expect(isAutoRemediable({ unassociatedScenarios: 2 }, false)).toBe(false);
+        });
+        it('should return false when already attempted', () => {
+            expect(isAutoRemediable({ unassociatedScenarios: 3 }, true)).toBe(false);
+        });
+    });
+    describe('suggestedTestFile for functions without testFile', () => {
+        it('should suggest conventional .test.ts path when testFile is undefined', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    { name: 'useLibraryShell', filePath: 'app/library/context.tsx' },
+                ],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.functions[0].suggestedTestFile).toBe('app/library/context.test.ts');
+            expect(result.functions[0].status).toBe('missing');
+        });
+        it('should suggest .test.ts for .ts files', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [{ name: 'calculatePrice', filePath: 'app/lib/pricing.ts' }],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.functions[0].suggestedTestFile).toBe('app/lib/pricing.test.ts');
+        });
+        it('should not set suggestedTestFile when testFile is already specified', () => {
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'calculatePrice',
+                        filePath: 'app/lib/pricing.ts',
+                        testFile: 'app/lib/pricing.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'app/lib/pricing.test.ts': true },
+            });
+            expect(result.functions[0].suggestedTestFile).toBeUndefined();
+        });
+    });
+    describe('hint for function audit entries', () => {
+        it('should include a hint for name_mismatch functions explaining the fix', () => {
+            // Claude sees "name mismatch" with no guidance on what it means or how
+            // to fix it. The hint should explain that a top-level describe block
+            // matching the function name is required for the CodeYam UI.
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'useDrinks',
+                        filePath: 'app/hooks/useDrinks.ts',
+                        testFile: 'app/hooks/useDrinks.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'app/hooks/useDrinks.test.ts': true },
+                testResults: {
+                    'app/hooks/useDrinks.test.ts': {
+                        passing: true,
+                        hasEntityNameDescribe: false,
+                    },
+                },
+            });
+            expect(result.functions[0].status).toBe('name_mismatch');
+            expect(result.functions[0].hint).toBeDefined();
+            expect(result.functions[0].hint).toContain('describe');
+            expect(result.functions[0].hint).toContain('useDrinks');
+        });
+        it('should include a hint for runner_error functions showing the error', () => {
+            // When the test runner crashes, Claude needs to see WHY it crashed
+            // to fix the underlying issue. Without this, Claude loops re-running audit.
+            const result = computeAudit({
+                components: [],
+                functions: [
+                    {
+                        name: 'getTimeAgo',
+                        filePath: 'src/lib/format.ts',
+                        testFile: 'src/lib/format.test.ts',
+                    },
+                ],
+                scenarioCounts: {},
+                testFileExistence: { 'src/lib/format.test.ts': true },
+                testResults: {
+                    'src/lib/format.test.ts': {
+                        passing: false,
+                        hasEntityNameDescribe: false,
+                        errorMessage: 'Cannot find module "@/lib/format"',
+                    },
+                },
+            });
+            expect(result.functions[0].status).toBe('runner_error');
+            expect(result.functions[0].hint).toBeDefined();
+            expect(result.functions[0].hint).toContain('Cannot find module');
+        });
+    });
+    describe('hint for missing components', () => {
+        it('should hint that layout files need app-level scenarios', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'LibraryLayout', filePath: 'app/library/layout.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toContain('layout');
+            expect(result.components[0].hint).toContain('pageFilePath');
+        });
+        it('should hint that page files need app-level scenarios', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'InboxPage', filePath: 'app/library/inbox/page.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toContain('page');
+            expect(result.components[0].hint).toContain('pageFilePath');
+        });
+        it('should hint that regular components need isolation routes', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'DrinkCard', filePath: 'app/components/DrinkCard.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toContain('isolated-components');
+        });
+        it('should not set hint when component has scenarios', () => {
+            const result = computeAudit({
+                components: [
+                    { name: 'DrinkCard', filePath: 'app/components/DrinkCard.tsx' },
+                ],
+                functions: [],
+                scenarioCounts: { DrinkCard: 2 },
+                testFileExistence: {},
+            });
+            expect(result.components[0].hint).toBeUndefined();
+        });
+        it('should provide a hint for needs_recapture components', () => {
+            // Components with needs_recapture status need guidance on what to do.
+            // Without a hint, Claude has no instructions for fixing the issue.
+            const result = computeAudit({
+                components: [{ name: 'Library', filePath: 'app/library/page.tsx' }],
+                functions: [],
+                scenarioCounts: {},
+                testFileExistence: {},
+                totalScenarioCounts: { Library: 3 },
+                entityChangeStatus: { Library: { status: 'impacted' } },
+            });
+            expect(result.components[0].status).toBe('needs_recapture');
+            expect(result.components[0].hint).toBeDefined();
+            expect(result.components[0].hint).toContain('recapture');
+        });
+    });
+    describe('formatIncompleteEntityGuidance', () => {
+        it('should include the entity name and scenario count', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: false,
+            });
+            expect(result).toContain('RuleBuilder');
+            expect(result).toContain('5');
+        });
+        it('should tell Claude the exact fix command', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: false,
+            });
+            expect(result).toContain('codeyam editor analyze-imports');
+        });
+        it('should flag pre-existing issues as non-blocking', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: true,
+            });
+            expect(result).toContain('pre-existing');
+        });
+        it('should explain what incomplete means', () => {
+            const { formatIncompleteEntityGuidance } = require('../editorAudit');
+            const result = formatIncompleteEntityGuidance({
+                entitySha: 'abc123',
+                name: 'RuleBuilder',
+                scenarioCount: 5,
+                preExisting: false,
+            });
+            // Should explain the root cause, not just the symptom
+            expect(result).toMatch(/scenario.*without.*import graph|import graph.*not.*built/i);
+        });
+    });
+    describe('formatManualAnalysisGuidance', () => {
+        it('should include entity name, scenario count, and error message', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 3,
+                error: 'TypeScript parsing error: unexpected token',
+            });
+            expect(result).toContain('Header');
+            expect(result).toContain('3 scenario(s)');
+            expect(result).toContain('TypeScript parsing error');
+        });
+        it('should include MANUAL ANALYSIS REQUIRED header', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('MANUAL ANALYSIS REQUIRED');
+        });
+        it('should tell Claude to read the source file', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('Read src/components/Header.tsx');
+        });
+        it('should include the manual-entity command', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('codeyam editor manual-entity');
+        });
+        it('should tell Claude to check glossary for imports', () => {
+            const { formatManualAnalysisGuidance } = require('../editorAudit');
+            const result = formatManualAnalysisGuidance({
+                name: 'Header',
+                filePath: 'src/components/Header.tsx',
+                scenarioCount: 2,
+                error: 'Parse error',
+            });
+            expect(result).toContain('glossary');
+        });
+    });
+    describe('getIncompleteEntityFilePaths', () => {
+        // The audit should auto-fix incomplete entities by running analysis on
+        // just their specific file paths, not all 117+ files. This function
+        // resolves entity SHAs to file paths for targeted analysis.
+        let db;
+        let rawDb;
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            await db.schema
+                .createTable('entities')
+                .addColumn('sha', 'varchar', (col) => col.primaryKey())
+                .addColumn('name', 'varchar')
+                .addColumn('file_path', 'varchar')
+                .addColumn('project_id', 'varchar')
+                .addColumn('entity_type', 'varchar')
                 .execute();
-            const result = await queryUnassociatedScenarios(db, projectId, '2026-03-20T18:00:00.000Z');
-            // Should only find the session-scoped one
-            expect(result).toHaveLength(1);
-            expect(result[0].name).toBe('NewComponent');
         });
-        it('should include re-registered scenarios (updated_at in session) even if created before', async () => {
+        afterEach(() => {
+            rawDb.close();
+        });
+        it('should resolve entity SHAs to file paths from the entities table', async () => {
+            const { getIncompleteEntityFilePaths } = require('../editorAudit');
             await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'SearchBar - Default',
-                component_name: 'SearchBar',
-                component_path: 'src/components/SearchBar.tsx',
-                entity_sha: null,
-                created_at: '2026-03-19 10:00:00',
-                updated_at: '2026-03-20 18:45:00', // re-registered during session
-            })
+                .insertInto('entities')
+                .values([
+                {
+                    sha: 'sha-rule',
+                    name: 'RuleBuilder',
+                    file_path: 'app/components/RuleBuilder.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+                {
+                    sha: 'sha-row',
+                    name: 'ArticleTableRow',
+                    file_path: 'app/components/ArticleTableRow.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+            ])
                 .execute();
-            const result = await queryUnassociatedScenarios(db, projectId, '2026-03-20T18:00:00.000Z');
-            expect(result).toHaveLength(1);
-            expect(result[0].name).toBe('SearchBar');
+            const result = await getIncompleteEntityFilePaths(db, [
+                {
+                    entitySha: 'sha-rule',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: false,
+                },
+                {
+                    entitySha: 'sha-row',
+                    name: 'ArticleTableRow',
+                    scenarioCount: 2,
+                    preExisting: false,
+                },
+            ]);
+            expect(result).toContain('app/components/RuleBuilder.tsx');
+            expect(result).toContain('app/components/ArticleTableRow.tsx');
+            expect(result).toHaveLength(2);
         });
-        it('should not include scenarios with entity_sha set (even if stale)', async () => {
-            // This scenario has an entity_sha — even if it's stale, that's a
-            // different problem (handled by queryIncompleteEntities)
+        it('should skip entities whose SHA is not in the entities table', async () => {
+            const { getIncompleteEntityFilePaths } = require('../editorAudit');
+            const result = await getIncompleteEntityFilePaths(db, [
+                {
+                    entitySha: 'nonexistent-sha',
+                    name: 'Ghost',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+            expect(result).toHaveLength(0);
+        });
+        it('should deduplicate file paths', async () => {
+            const { getIncompleteEntityFilePaths } = require('../editorAudit');
             await db
-                .insertInto('editor_scenarios')
-                .values({
-                id: 'sc-1',
-                project_id: projectId,
-                name: 'Header - Default',
-                component_name: 'Header',
-                component_path: 'src/components/Header.tsx',
-                entity_sha: 'sha-old-version',
-                created_at: '2026-03-20 18:45:00',
-                updated_at: '2026-03-20 18:45:00',
-            })
+                .insertInto('entities')
+                .values([
+                {
+                    sha: 'sha-v1',
+                    name: 'Foo',
+                    file_path: 'app/Foo.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+                {
+                    sha: 'sha-v2',
+                    name: 'Foo',
+                    file_path: 'app/Foo.tsx',
+                    project_id: 'p1',
+                    entity_type: 'component',
+                },
+            ])
                 .execute();
-            const result = await queryUnassociatedScenarios(db, projectId, null);
-            expect(result).toEqual([]);
+            const result = await getIncompleteEntityFilePaths(db, [
+                {
+                    entitySha: 'sha-v1',
+                    name: 'Foo',
+                    scenarioCount: 3,
+                    preExisting: false,
+                },
+                {
+                    entitySha: 'sha-v2',
+                    name: 'Foo',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ]);
+            expect(result).toEqual(['app/Foo.tsx']);
         });
     });
-    // ── isAutoRemediable with unassociatedScenarios ────────────────────
-    describe('isAutoRemediable with unassociatedScenarios', () => {
-        it('should return true when unassociatedScenarios is the only failure', () => {
-            expect(isAutoRemediable({ unassociatedScenarios: 3 }, false)).toBe(true);
+    describe('isAutoRemediable never triggers full analysis', () => {
+        // The audit must NEVER run handleAnalyzeImports inline — it takes minutes
+        // for large projects. Auto-remediation should only do the lightweight
+        // entity SHA backfill. isAutoRemediable is now always false; the callers
+        // use needsBackfillOnly for the fast path instead.
+        it('should always return false regardless of summary state', () => {
+            expect(isAutoRemediable({ incompleteEntities: 5 }, false)).toBe(false);
+            expect(isAutoRemediable({ unassociatedScenarios: 3 }, false)).toBe(false);
+            expect(isAutoRemediable({ incompleteEntities: 1, unassociatedScenarios: 2 }, false)).toBe(false);
+        });
+    });
+    // ── isOnlyPreExistingIncomplete ─────────────────────────────────────
+    describe('isOnlyPreExistingIncomplete', () => {
+        it('should return true when all incomplete entities are pre-existing and no other failures', () => {
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 2,
+                preExistingIncompleteEntities: 2,
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 0,
+                scenariosNeedingRecapture: 0,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: true,
+                },
+                {
+                    entitySha: 'b',
+                    name: 'ArticleTableRow',
+                    scenarioCount: 2,
+                    preExisting: true,
+                },
+            ])).toBe(true);
+        });
+        it('should return false when there are runner errors even if all incompletes are pre-existing', () => {
+            // Safety net: runner errors (crashed test runner) must NEVER bypass the gate.
+            // Without this test, a regression removing functionsRunnerError from
+            // isOnlyIncompleteEntities would silently let broken test infrastructure through.
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 1,
+                preExistingIncompleteEntities: 1,
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsRunnerError: 1,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'OldComponent',
+                    scenarioCount: 1,
+                    preExisting: true,
+                },
+            ])).toBe(false);
+        });
+        it('should return false when some incomplete entities are NOT pre-existing', () => {
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 2,
+                preExistingIncompleteEntities: 1,
+                componentsMissing: 0,
+                componentsWithErrors: 0,
+                functionsFailing: 0,
+                functionsNameMismatch: 0,
+                functionsMissing: 0,
+                missingFromGlossary: 0,
+                miscategorizedScenarios: 0,
+                scenariosNeedingRecapture: 0,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: true,
+                },
+                {
+                    entitySha: 'b',
+                    name: 'NewComponent',
+                    scenarioCount: 1,
+                    preExisting: false,
+                },
+            ])).toBe(false);
         });
-        it('should return true when both incompleteEntities and unassociatedScenarios are the only failures', () => {
-            expect(isAutoRemediable({ incompleteEntities: 1, unassociatedScenarios: 2 }, false)).toBe(true);
+        it('should return false when there are other failures besides incomplete entities', () => {
+            expect(isOnlyPreExistingIncomplete({
+                incompleteEntities: 2,
+                preExistingIncompleteEntities: 2,
+                componentsMissing: 1,
+            }, [
+                {
+                    entitySha: 'a',
+                    name: 'RuleBuilder',
+                    scenarioCount: 5,
+                    preExisting: true,
+                },
+                {
+                    entitySha: 'b',
+                    name: 'ArticleTableRow',
+                    scenarioCount: 2,
+                    preExisting: true,
+                },
+            ])).toBe(false);
         });
-        it('should return false when unassociatedScenarios exist alongside other failures', () => {
-            expect(isAutoRemediable({ unassociatedScenarios: 2, componentsMissing: 1 }, false)).toBe(false);
+        it('should return false when incomplete entities array is empty', () => {
+            expect(isOnlyPreExistingIncomplete({ incompleteEntities: 0 }, [])).toBe(false);
         });
-        it('should return false when already attempted', () => {
-            expect(isAutoRemediable({ unassociatedScenarios: 3 }, true)).toBe(false);
+        it('should return false when incomplete entities array is missing', () => {
+            expect(isOnlyPreExistingIncomplete({ incompleteEntities: 2, preExistingIncompleteEntities: 2 }, undefined)).toBe(false);
         });
     });
     describe('isOnlyIncompleteEntities with unassociatedScenarios', () => {
@@ -2948,5 +3907,254 @@ describe('editorAudit', () => {
             })).toBe(false);
         });
     });
+    // ── aggregateClientErrorsByComponent ─────────────────────────────────
+    describe('aggregateClientErrorsByComponent', () => {
+        it('should attribute errors to component using componentName from metadata', () => {
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'DrinkCard - Default',
+                    errors: ['TypeError: Cannot read property "price"'],
+                },
+            }, [
+                {
+                    name: 'DrinkCard - Default',
+                    componentName: 'DrinkCard',
+                },
+            ]);
+            expect(result['DrinkCard']).toEqual([
+                'TypeError: Cannot read property "price"',
+            ]);
+        });
+        it('should attribute app-level scenario errors using pageFilePath', () => {
+            // App-level scenarios have componentName=null. The old approach
+            // parsed the scenario name "Full Page with Library" and got
+            // "Full Page with Library" as the component — which matches nothing.
+            // With metadata, we derive the entity name from pageFilePath.
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'Full Page with Library',
+                    errors: ['TypeError: Cannot read property "title"'],
+                },
+            }, [
+                {
+                    name: 'Full Page with Library',
+                    componentName: null,
+                    pageFilePath: 'app/library/page.tsx',
+                },
+            ]);
+            // Should be keyed by the canonical entity name from scenarioEntityName()
+            expect(result['Library']).toEqual([
+                'TypeError: Cannot read property "title"',
+            ]);
+        });
+        it('should fall back to scenario name parsing when no metadata match exists', () => {
+            // If the scenario is not in the metadata list (e.g., metadata not yet loaded),
+            // fall back to the "ComponentName - Variant" convention
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'Header - Dark Mode',
+                    errors: ['ReferenceError: theme is not defined'],
+                },
+            }, []);
+            expect(result['Header']).toEqual([
+                'ReferenceError: theme is not defined',
+            ]);
+        });
+        it('should handle non-route file paths via scenarioEntityName', () => {
+            // Non-route files (src/...) are treated as app entry points by
+            // scenarioEntityName → buildRoutePattern returns '/' → 'Home'.
+            // When a url is available, it provides a better entity name.
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'LibraryApp - Rich',
+                    errors: ['Error: fetch failed'],
+                },
+            }, [
+                {
+                    name: 'LibraryApp - Rich',
+                    componentName: null,
+                    pageFilePath: 'src/library/LibraryApp.tsx',
+                    url: '/library',
+                },
+            ]);
+            // scenarioEntityName uses url fallback when pageFilePath is a non-route file
+            // pageFilePath 'src/...' → buildRoutePattern → '/' → routeDisplayName → 'Home'
+            // But componentName takes priority, and with url '/library' as final fallback
+            // scenarioEntityName({ pageFilePath: 'src/library/LibraryApp.tsx' }) → 'Home'
+            // because pageFilePath is checked before url
+            expect(result['Home']).toEqual(['Error: fetch failed']);
+        });
+        it('should skip scenarios with no errors', () => {
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'DrinkCard - Default',
+                    errors: [],
+                },
+            }, [
+                {
+                    name: 'DrinkCard - Default',
+                    componentName: 'DrinkCard',
+                },
+            ]);
+            expect(result).toEqual({});
+        });
+        it('should aggregate errors from multiple scenarios for same component', () => {
+            const result = aggregateClientErrorsByComponent({
+                'scenario-1': {
+                    scenarioName: 'DrinkCard - Default',
+                    errors: ['Error A'],
+                },
+                'scenario-2': {
+                    scenarioName: 'DrinkCard - Hover',
+                    errors: ['Error B', 'Error C'],
+                },
+            }, [
+                { name: 'DrinkCard - Default', componentName: 'DrinkCard' },
+                { name: 'DrinkCard - Hover', componentName: 'DrinkCard' },
+            ]);
+            expect(result['DrinkCard']).toEqual(['Error A', 'Error B', 'Error C']);
+        });
+        it('should use capitalized display name for page file paths, not lowercase directory', () => {
+            // aggregateClientErrorsByComponent must produce keys matching scenarioEntityName().
+            // scenarioEntityName({ pageFilePath: 'app/library/page.tsx' }) returns 'Library',
+            // so the key must be 'Library' — not 'library' (the raw directory name).
+            // computeAudit checks clientErrors[glossaryEntryName], so a lowercase key
+            // will never match, silently dropping all client errors for page-level scenarios.
+            const result = aggregateClientErrorsByComponent({
+                'sc-1': {
+                    scenarioName: 'Library - Default',
+                    errors: ['TypeError: fetch failed'],
+                },
+            }, [
+                {
+                    name: 'Library - Default',
+                    componentName: null,
+                    pageFilePath: 'app/library/page.tsx',
+                },
+            ]);
+            expect(result).toHaveProperty('Library');
+            expect(result['Library']).toEqual(['TypeError: fetch failed']);
+        });
+        it('should use "Home" for root page app/page.tsx, not "app"', () => {
+            // Root page: scenarioEntityName returns 'Home', not 'app'.
+            // Custom path parsing incorrectly pops the parent dir ('app').
+            const result = aggregateClientErrorsByComponent({
+                'sc-1': {
+                    scenarioName: 'Home - Default',
+                    errors: ['ReferenceError: window is not defined'],
+                },
+            }, [
+                {
+                    name: 'Home - Default',
+                    componentName: null,
+                    pageFilePath: 'app/page.tsx',
+                },
+            ]);
+            expect(result).toHaveProperty('Home');
+            expect(result['Home']).toEqual(['ReferenceError: window is not defined']);
+        });
+    });
+    // ── determineTargetedAnalysisPaths ──────────────────────────────────
+    describe('determineTargetedAnalysisPaths', () => {
+        it('should return unique file paths from unassociated scenarios', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [
+                    { filePath: 'app/components/CreateFromFiltersButton.tsx' },
+                    { filePath: 'app/components/StaleDismissedBanner.tsx' },
+                ],
+                incompleteEntities: [],
+            });
+            expect(result).toEqual([
+                'app/components/CreateFromFiltersButton.tsx',
+                'app/components/StaleDismissedBanner.tsx',
+            ]);
+        });
+        it('should include file paths from incomplete entities', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: 'app/components/TaskCard.tsx' }],
+                incompleteEntities: [{ filePath: 'app/components/Dashboard.tsx' }],
+            });
+            expect(result).toEqual([
+                'app/components/TaskCard.tsx',
+                'app/components/Dashboard.tsx',
+            ]);
+        });
+        it('should deduplicate file paths across both sources', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: 'app/components/TaskCard.tsx' }],
+                incompleteEntities: [{ filePath: 'app/components/TaskCard.tsx' }],
+            });
+            expect(result).toEqual(['app/components/TaskCard.tsx']);
+        });
+        it('should return empty array when no issues', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [],
+                incompleteEntities: [],
+            });
+            expect(result).toEqual([]);
+        });
+        it('should filter out entries with empty file paths', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: '' }],
+                incompleteEntities: [],
+            });
+            expect(result).toEqual([]);
+        });
+        it('should handle incomplete entities with undefined filePath', () => {
+            const result = determineTargetedAnalysisPaths({
+                unassociatedScenarios: [{ filePath: 'app/components/Good.tsx' }],
+                incompleteEntities: [
+                    {
+                    /* no filePath at all */
+                    },
+                    { filePath: undefined },
+                    { filePath: 'app/components/AlsoGood.tsx' },
+                ],
+            });
+            expect(result).toEqual([
+                'app/components/Good.tsx',
+                'app/components/AlsoGood.tsx',
+            ]);
+        });
+    });
+    // ── shouldAutoRecapture ─────────────────────────────────────────────
+    describe('shouldAutoRecapture', () => {
+        it('should return true when fix flag is set and stale scenarios exist', () => {
+            expect(shouldAutoRecapture({
+                fix: true,
+                scenariosNeedingRecapture: [
+                    {
+                        scenarioName: 'Default',
+                        entityName: 'TaskCard',
+                        status: { status: 'edited' },
+                    },
+                ],
+            })).toBe(true);
+        });
+        it('should return false when fix flag is not set', () => {
+            expect(shouldAutoRecapture({
+                fix: false,
+                scenariosNeedingRecapture: [
+                    {
+                        scenarioName: 'Default',
+                        entityName: 'TaskCard',
+                        status: { status: 'edited' },
+                    },
+                ],
+            })).toBe(false);
+        });
+        it('should return false when fix is set but no stale scenarios', () => {
+            expect(shouldAutoRecapture({
+                fix: true,
+                scenariosNeedingRecapture: [],
+            })).toBe(false);
+        });
+        it('should return false when both are falsy', () => {
+            expect(shouldAutoRecapture({
+                fix: false,
+                scenariosNeedingRecapture: [],
+            })).toBe(false);
+        });
+    });
 });
 //# sourceMappingURL=editorAudit.test.js.map