feat(context): add warehouse verification tools (#46)

* feat(context): add warehouse dialect dispatch * feat(context): read warehouse scan catalog * feat(context): add entity details verification tool * feat(context): add ingest SQL verification tool * feat(context): add raw warehouse discovery tool * feat(context): expose warehouse verification tools to ingest * docs(context): add ingest identifier verification protocol * test(context): guard ingest identifier verification prompts * chore(context): verify warehouse verification tools * docs: add warehouse verification tools plan and spec * fix(context): expose target warehouses to Notion ingest * fix(context): update ingest prompts for warehouse verification tools * fix(context): scope raw schema discovery to allowed connections * fix(context): verify warehouse column display targets * docs: add notion warehouse verification gap closure plan * fix(context): include raw discovery connection names * fix(context): expose warehouse targets for LookML and MetricFlow * fix(context): pass connection config to ingest query executors * fix(cli): enable read-only SQL probes for local ingest * docs: add warehouse verification final v1 closure plan * fix(context): align warehouse sql probe prompt shape * docs: add warehouse verification prompt shape closure plan * test(context): catch connectionless sql execution prompt examples * fix(context): include connection name in sl capture sql example * docs: add warehouse verification sql example closure plan * fix(context): report structured entity detail misses * docs: add warehouse verification structured target miss closure plan * fix: report untracked squash merge conflicts * feat: require ingest verification ledger * fix: stabilize ingest wiki references
2026-06-19 08:28:06 +02:00 · 2026-05-13 13:43:23 +02:00 · 2026-05-13 13:43:23 +02:00 · c22248dabf
commit c22248dabf
parent bcb0d2f8f7
89 changed files with 7818 additions and 191 deletions
--- a/docs/superpowers/plans/2026-05-12-notion-warehouse-verification-gap-closure.md
+++ b/docs/superpowers/plans/2026-05-12-notion-warehouse-verification-gap-closure.md
@ -0,0 +1,785 @@
+# Notion Warehouse Verification Gap Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the remaining v1 gaps that prevent ingest agents, especially
+Notion WorkUnits, from reliably verifying warehouse table and column
+identifiers before writing wiki or semantic-layer output.
+
+**Architecture:** Keep the existing warehouse verification tool module and
+runner wiring. Add Notion target-warehouse scoping through the local adapter
+factory, make the active WorkUnit prompt name the shipped tools, enforce
+`allowedConnectionNames` in `discover_data`, and teach `entity_details` to
+resolve and reject column-level display targets.
+
+**Tech Stack:** TypeScript, Node 22, Vitest, AI SDK v6 tools, Zod, KTX local
+ingest adapters, KTX file store.
+
+---
+
+## Audit summary
+
+The previous implementation plan landed the main tool module and prompt
+protocol, but four v1-blocking gaps remain:
+
+- Notion ingest sessions still allow only the Notion connection unless a
+  specific adapter supplies target IDs. `NotionSourceAdapter` does not supply
+  target warehouse IDs, so the original Notion hallucination case cannot use
+  `entity_details` or raw-schema `discover_data` for the warehouse connection.
+- The active WorkUnit framing prompt still tells agents to call
+  `wiki_sl_search` and `sl_describe_table`, which are not shipped KTX tools.
+- `discover_data` accepts an explicit out-of-scope `connectionName` and still
+  searches raw schema for that connection.
+- `entity_details({ targets: [{ display: "schema.table.column" }] })` does not
+  resolve column display strings and does not fail explicit missing-column
+  targets.
+
+Non-blocking gaps remain out of scope for this plan:
+
+- Full DDL-style `entity_details` formatting with FK and profile summaries.
+- AST-backed SQL read-only validation for data-modifying CTEs.
+- Search over `enrichment/descriptions.json` for generated descriptions.
+- Lexicographic latest-sync edge cases for non-timestamp sync IDs.
+- Hard write-time validation in `wiki_write` and `emit_unmapped_fallback`.
+
+## File structure
+
+Modify these files:
+
+- `packages/context/src/ingest/adapters/notion/notion.adapter.ts`: add
+  configured target warehouse IDs and implement `listTargetConnectionIds()`.
+- `packages/context/src/ingest/adapters/notion/notion.adapter.test.ts`: cover
+  Notion target connection ID fan-out.
+- `packages/context/src/ingest/local-adapters.ts`: pass primary warehouse IDs
+  into `NotionSourceAdapter`.
+- `packages/context/src/ingest/local-adapters.test.ts`: cover local Notion
+  adapter target IDs.
+- `packages/context/src/ingest/adapters/notion/chunk.ts`: update Notion
+  WorkUnit notes to prefer the warehouse verification tools.
+- `packages/context/src/ingest/adapters/notion/notion.adapter.test.ts`: update
+  Notion note expectations.
+- `packages/context/prompts/memory_agent_bundle_ingest_work_unit.md`: replace
+  stale tool names in the active WorkUnit prompt.
+- `packages/context/src/ingest/ingest-prompts.test.ts`: guard the WorkUnit
+  prompt against stale tool names.
+- `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts`:
+  refuse explicit out-of-scope connection names.
+- `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts`:
+  cover `discover_data` scoping.
+- `packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts`:
+  add column-aware display-target resolution.
+- `packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts`:
+  cover column display resolution.
+- `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts`:
+  use column-aware resolution and report missing columns.
+- `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts`:
+  cover column display and missing-column behavior.
+
+### Task 1: Give Notion ingest access to target warehouses
+
+**Files:**
+- Modify: `packages/context/src/ingest/adapters/notion/notion.adapter.ts`
+- Modify: `packages/context/src/ingest/adapters/notion/notion.adapter.test.ts`
+- Modify: `packages/context/src/ingest/local-adapters.ts`
+- Modify: `packages/context/src/ingest/local-adapters.test.ts`
+
+- [ ] **Step 1: Write the failing Notion adapter test**
+
+Add this test inside `describe('NotionSourceAdapter', ...)` in
+`packages/context/src/ingest/adapters/notion/notion.adapter.test.ts`:
+
+```ts
+it('returns configured target warehouse connection ids', async () => {
+  const adapter = new NotionSourceAdapter({
+    targetConnectionIds: ['warehouse', 'warehouse', 'analytics'],
+  });
+
+  await expect(adapter.listTargetConnectionIds?.(stagedDir)).resolves.toEqual([
+    'analytics',
+    'warehouse',
+  ]);
+});
+```
+
+- [ ] **Step 2: Run the failing Notion adapter test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/adapters/notion/notion.adapter.test.ts -t "target warehouse connection ids"
+```
+
+Expected: FAIL because `NotionSourceAdapterDeps` has no
+`targetConnectionIds` option and `NotionSourceAdapter` does not implement
+`listTargetConnectionIds()`.
+
+- [ ] **Step 3: Implement Notion target connection IDs**
+
+Modify `packages/context/src/ingest/adapters/notion/notion.adapter.ts`:
+
+```ts
+export interface NotionSourceAdapterDeps {
+  onPullSucceeded?: (ctx: NotionPullSucceededContext) => Promise<void>;
+  logger?: NotionFetchLogger;
+  targetConnectionIds?: string[];
+}
+
+function uniqueSorted(values: readonly string[] | undefined): string[] {
+  return [...new Set(values ?? [])].sort((left, right) =>
+    left.localeCompare(right),
+  );
+}
+```
+
+Add this method to `NotionSourceAdapter`:
+
+```ts
+  async listTargetConnectionIds(_stagedDir: string): Promise<string[]> {
+    return uniqueSorted(this.deps.targetConnectionIds);
+  }
+```
+
+- [ ] **Step 4: Pass primary warehouses into the local Notion adapter**
+
+Modify the Notion adapter construction in
+`packages/context/src/ingest/local-adapters.ts`:
+
+```ts
+    new NotionSourceAdapter({
+      targetConnectionIds: primaryWarehouseConnectionIds(project),
+      ...(options.logger ? { logger: options.logger } : {}),
+    }),
+```
+
+- [ ] **Step 5: Write the local adapter fan-out test**
+
+Add this test to `packages/context/src/ingest/local-adapters.test.ts`:
+
+```ts
+it('passes primary warehouse connection ids to the local Notion adapter', async () => {
+  const adapters = createDefaultLocalIngestAdapters(
+    projectWithConnections({
+      notion: {
+        driver: 'notion',
+        auth_token: 'secret',
+        crawl_mode: 'selected_roots',
+        root_page_ids: ['page-1'],
+      },
+      warehouse: {
+        driver: 'postgres',
+        url: 'postgresql://readonly@db.example.test/analytics',
+      },
+      docs: {
+        driver: 'dbt',
+        source_dir: './dbt',
+      },
+    } as never),
+  );
+
+  const notion = adapters.find((adapter) => adapter.source === 'notion');
+
+  await expect(notion?.listTargetConnectionIds?.('/tmp/staged-notion')).resolves.toEqual([
+    'warehouse',
+  ]);
+});
+```
+
+- [ ] **Step 6: Run the Notion target tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/adapters/notion/notion.adapter.test.ts -t "target warehouse connection ids" \
+  src/ingest/local-adapters.test.ts -t "local Notion adapter"
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/adapters/notion/notion.adapter.ts \
+  packages/context/src/ingest/adapters/notion/notion.adapter.test.ts \
+  packages/context/src/ingest/local-adapters.ts \
+  packages/context/src/ingest/local-adapters.test.ts
+git commit -m "fix(context): expose target warehouses to Notion ingest"
+```
+
+### Task 2: Remove stale tool names from active ingest prompts
+
+**Files:**
+- Modify: `packages/context/prompts/memory_agent_bundle_ingest_work_unit.md`
+- Modify: `packages/context/src/ingest/ingest-prompts.test.ts`
+- Modify: `packages/context/src/ingest/adapters/notion/chunk.ts`
+- Modify: `packages/context/src/ingest/adapters/notion/notion.adapter.test.ts`
+
+- [ ] **Step 1: Add failing prompt guards**
+
+Add this test to `packages/context/src/ingest/ingest-prompts.test.ts`:
+
+```ts
+it('uses shipped warehouse verification tools in the WorkUnit prompt', async () => {
+  const prompt = await readFile(
+    new URL('../../prompts/memory_agent_bundle_ingest_work_unit.md', import.meta.url),
+    'utf-8',
+  );
+
+  expect(prompt).toContain('discover_data');
+  expect(prompt).toContain('entity_details');
+  expect(prompt).not.toContain('wiki_sl_search');
+  expect(prompt).not.toContain('sl_describe_table');
+});
+```
+
+- [ ] **Step 2: Run the failing prompt guard**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/ingest-prompts.test.ts -t "warehouse verification tools"
+```
+
+Expected: FAIL because the WorkUnit prompt still contains `wiki_sl_search` and
+`sl_describe_table`.
+
+- [ ] **Step 3: Update the WorkUnit framing prompt**
+
+In `packages/context/prompts/memory_agent_bundle_ingest_work_unit.md`, replace
+the first `<role>` paragraph with:
+
+```md
+You are processing ONE WorkUnit of a multi-file ingest bundle. The WorkUnit gives you a slice of raw source files (LookML views, dbt/MetricFlow YAMLs, Metabase card JSONs, Notion pages, or similar) and you must translate that slice into KTX semantic-layer sources and/or knowledge wiki pages, in one pass. Prior WorkUnits in this same job may have already written SL sources and wiki pages; their writes are visible on the working branch and discoverable with `discover_data`.
+```
+
+In workflow step 2, replace the final sentence with:
+
+```md
+The triage skill tells you how to react when `discover_data` reveals that a prior WU already wrote something overlapping.
+```
+
+In workflow step 4, replace the sentence that starts
+`For each raw file:` with:
+
+```md
+4. For each raw file: call `read_raw_file` (or `read_raw_span` for slicing large files) to load content. Before writing a new SL source or wiki page, call `discover_data` for each candidate source, table, metric, or topic name to find prior-WU writes, existing wiki pages, SL sources, and raw warehouse matches; apply `ingest_triage` when you hit one, and apply any matching canonical pin before deciding whether to edit, rename, or skip.
+```
+
+In the `<do_not>` block, replace the physical-column rule with:
+
+```md
+- Do not invent physical column names or grain keys. For table-backed SL sources, every `columns:`, `grain:`, `joins:`, `segments:`, and `measures[].expr` column must come from raw-file column declarations or warehouse-backed discovery (`discover_data`, `sl_discover`, `entity_details`). If column names are not confirmed, capture the business context in wiki instead of writing a full SL source.
+```
+
+- [ ] **Step 4: Update Notion WorkUnit notes**
+
+In `packages/context/src/ingest/adapters/notion/chunk.ts`, replace
+`NOTION_SL_WRITE_GUIDANCE` with:
+
+```ts
+const NOTION_SL_WRITE_GUIDANCE =
+  'Write wiki entries with wiki_write. Wiki keys must be flat slugs like orbit-company-overview, not orbit/company-overview. Search existing wiki pages, SL sources, and raw warehouse schema for the same tables or sl_refs with discover_data before creating a new page. Only write or edit SL sources after discover_data plus sl_discover/sl_read_source or entity_details confirms a mapped non-Notion target source; if no mapped target exists, emit_unmapped_fallback and keep the fact wiki-only. Notion dataSourceCount counts Notion databases/data sources only, not warehouse/dbt mappings. If a warehouse/dbt connection exists but the named table or source is absent, use reason no_physical_table rather than no_connection_mapping. Do not create SL sources under the Notion connection just because a page mentions a warehouse table.';
+```
+
+In the `reconcileNotes` array in the same file, replace:
+
+```ts
+      'Notion dataSourceCount is Notion-only; use sl_discover for warehouse/dbt mapping decisions.',
+```
+
+with:
+
+```ts
+      'Notion dataSourceCount is Notion-only; use discover_data/entity_details for warehouse/dbt mapping decisions.',
+```
+
+- [ ] **Step 5: Update Notion note expectations**
+
+In `packages/context/src/ingest/adapters/notion/notion.adapter.test.ts`,
+update the note expectations in `it('chunks changed Notion pages...')`:
+
+```ts
+expect(result.workUnits[0].notes).toContain('discover_data');
+expect(result.workUnits[0].notes).toContain('entity_details');
+```
+
+Update the exact `reconcileNotes` expectation to:
+
+```ts
+expect(result.reconcileNotes).toEqual([
+  'Notion maxKnowledgeCreatesPerRun=25',
+  'Notion maxKnowledgeUpdatesPerRun=20',
+  'Notion dataSourceCount is Notion-only; use discover_data/entity_details for warehouse/dbt mapping decisions.',
+  'Reconcile Notion wiki pages sharing tables/sl_refs before creating distinct artifacts.',
+]);
+```
+
+- [ ] **Step 6: Run prompt and Notion note tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/ingest-prompts.test.ts \
+  src/ingest/adapters/notion/notion.adapter.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/prompts/memory_agent_bundle_ingest_work_unit.md \
+  packages/context/src/ingest/ingest-prompts.test.ts \
+  packages/context/src/ingest/adapters/notion/chunk.ts \
+  packages/context/src/ingest/adapters/notion/notion.adapter.test.ts
+git commit -m "fix(context): update ingest prompts for warehouse verification tools"
+```
+
+### Task 3: Enforce allowed connection scope in discover_data
+
+**Files:**
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts`
+
+- [ ] **Step 1: Write the failing scoping test**
+
+Add this test to
+`packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts`:
+
+```ts
+it('refuses explicit out-of-scope connection names', async () => {
+  const result = await tool.call({ query: 'orders', connectionName: 'billing' }, context);
+
+  expect(result.markdown).toContain('Connection "billing" is not available to this ingest stage.');
+  expect(result.structured).toEqual({ wiki: null, sl: null, raw: null });
+  expect(wikiSearchTool.call).not.toHaveBeenCalled();
+  expect(slDiscoverTool.call).not.toHaveBeenCalled();
+  expect(catalog.searchByName).not.toHaveBeenCalled();
+});
+```
+
+- [ ] **Step 2: Run the failing scoping test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/discover-data.tool.test.ts -t "out-of-scope"
+```
+
+Expected: FAIL because `discover_data` currently searches raw schema for an
+explicit `connectionName` even when it is not in `allowedConnectionNames`.
+
+- [ ] **Step 3: Add the scope guard**
+
+In
+`packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts`,
+add this helper near `totalSources()`:
+
+```ts
+function allowedConnectionNames(context: ToolContext): ReadonlySet<string> | null {
+  return context.session?.allowedConnectionNames ?? null;
+}
+```
+
+At the top of `DiscoverDataTool.call()`, before the `sourceName` branch and
+before calling any child tool, add:
+
+```ts
+    const allowed = allowedConnectionNames(context);
+    if (input.connectionName && allowed && !allowed.has(input.connectionName)) {
+      return {
+        markdown: `Connection "${input.connectionName}" is not available to this ingest stage.`,
+        structured: { wiki: null, sl: null, raw: null },
+      };
+    }
+```
+
+Then replace the raw connection-list construction with:
+
+```ts
+    const connections = input.connectionName ? [input.connectionName] : [...(allowed ?? [])].sort();
+```
+
+- [ ] **Step 4: Run discover_data tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/discover-data.tool.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts
+git commit -m "fix(context): scope raw schema discovery to allowed connections"
+```
+
+### Task 4: Fix column-level entity_details verification
+
+**Files:**
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts`
+
+- [ ] **Step 1: Write failing catalog column-target tests**
+
+First update `seedLiveDatabaseScan()` in that test file so BigQuery tables have
+a project/catalog. Replace the repeated inline table refs with:
+
+```ts
+const tableRef = {
+  catalog: driver === 'bigquery' ? 'analytics' : null,
+  db: driver === 'sqlite' ? null : 'public',
+  name: 'orders',
+};
+```
+
+Use `tableRef.catalog`, `tableRef.db`, and `tableRef.name` for the seeded
+table and profile table references.
+
+Then add these tests to
+`packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts`:
+
+```ts
+it('resolves postgres column display strings without treating the column as a table', async () => {
+  await seedLiveDatabaseScan();
+  const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
+
+  await expect(catalog.resolveDisplayTarget('warehouse', 'public.orders.status')).resolves.toMatchObject({
+    resolved: { catalog: null, db: 'public', name: 'orders', column: 'status' },
+    candidates: [],
+    dialect: 'postgres',
+  });
+});
+
+it('resolves BigQuery column display strings with four parts', async () => {
+  await seedLiveDatabaseScan('warehouse', 'sync-bigquery', 'bigquery');
+  const catalog = new WarehouseCatalogService({ fileStore: project.fileStore });
+
+  await expect(catalog.resolveDisplayTarget('warehouse', 'analytics.public.orders.status')).resolves.toMatchObject({
+    resolved: { catalog: 'analytics', db: 'public', name: 'orders', column: 'status' },
+    candidates: [],
+    dialect: 'bigquery',
+  });
+});
+```
+
+- [ ] **Step 2: Run the failing catalog tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts -t "column display"
+```
+
+Expected: FAIL because `resolveDisplayTarget()` does not exist.
+
+- [ ] **Step 3: Implement column-aware display resolution**
+
+In
+`packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts`,
+add this exported interface near `RawSchemaHit`:
+
+```ts
+export interface DisplayTargetResolution {
+  resolved: (KtxTableRef & { column?: string }) | null;
+  candidates: KtxTableRef[];
+  dialect: string;
+}
+```
+
+Add these helpers near `parseDisplay()`:
+
+```ts
+function expectedDisplayPartCount(driver: CatalogDriver): number {
+  if (driver === 'sqlite' || driver === 'sqlite3') {
+    return 1;
+  }
+  if (driver === 'bigquery' || driver === 'snowflake' || driver === 'sqlserver') {
+    return 3;
+  }
+  return 2;
+}
+
+function parseColumnDisplay(driver: CatalogDriver, display: string): (KtxTableRef & { column: string }) | null {
+  const parts = splitDisplay(display);
+  const tablePartCount = expectedDisplayPartCount(driver);
+  if (parts.length !== tablePartCount + 1) {
+    return null;
+  }
+  const column = parts.at(-1);
+  if (!column) {
+    return null;
+  }
+  const table = parseDisplay(driver, parts.slice(0, -1).join('.'));
+  return table ? { ...table, column } : null;
+}
+```
+
+Add this method to `WarehouseCatalogService` after `resolveDisplay()`:
+
+```ts
+  async resolveDisplayTarget(connectionName: string, display: string): Promise<DisplayTargetResolution> {
+    const catalog = await this.loadCatalog(connectionName);
+    if (!catalog) {
+      return { resolved: null, candidates: [], dialect: 'unknown' };
+    }
+
+    const dialect = getDialectForDriver(catalog.driver).type;
+    const tableResolution = await this.resolveDisplay(connectionName, display);
+    if (tableResolution.resolved) {
+      return tableResolution;
+    }
+
+    const parsedColumn = parseColumnDisplay(catalog.driver, display);
+    if (!parsedColumn) {
+      return { resolved: null, candidates: bestCandidates(catalog.tables, display), dialect };
+    }
+
+    const table = catalog.tables.find((candidate) => refsEqual(candidate, parsedColumn));
+    if (!table) {
+      return { resolved: null, candidates: bestCandidates(catalog.tables, display), dialect };
+    }
+
+    return {
+      resolved: {
+        catalog: table.catalog,
+        db: table.db,
+        name: table.name,
+        column: parsedColumn.column,
+      },
+      candidates: [],
+      dialect,
+    };
+  }
+```
+
+- [ ] **Step 4: Write failing entity_details column tests**
+
+Add these tests to
+`packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts`:
+
+```ts
+it('resolves display targets that include a column name', async () => {
+  const result = await tool.call(
+    { connectionName: 'warehouse', targets: [{ display: 'public.orders.status' }] },
+    context,
+  );
+
+  expect(result.markdown).toContain('### public.orders');
+  expect(result.markdown).toContain('- status (text, nullable=false)');
+  expect(result.markdown).not.toContain('- id (integer');
+  expect(result.structured.resolved).toHaveLength(1);
+  expect(result.structured.resolved[0]?.columns.map((column) => column.name)).toEqual(['status']);
+});
+
+it('reports missing explicit columns instead of returning an empty column list', async () => {
+  const result = await tool.call(
+    { connectionName: 'warehouse', targets: [{ display: 'public.orders.plan_tier' }] },
+    context,
+  );
+
+  expect(result.markdown).toContain('Column not found in scan: public.orders.plan_tier');
+  expect(result.markdown).toContain('Available columns: id, status');
+  expect(result.structured.resolved).toHaveLength(0);
+  expect(result.structured.missing).toHaveLength(1);
+});
+```
+
+- [ ] **Step 5: Run the failing entity_details tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/entity-details.tool.test.ts -t "column"
+```
+
+Expected: FAIL because display column targets are treated as table names and
+missing columns are not reported.
+
+- [ ] **Step 6: Use column-aware resolution in entity_details**
+
+In
+`packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts`,
+add this helper near `appendTableMarkdown()`:
+
+```ts
+function findColumn(detail: TableDetail, columnName: string): TableDetail['columns'][number] | null {
+  const normalized = columnName.toLowerCase();
+  return detail.columns.find((column) => column.name.toLowerCase() === normalized) ?? null;
+}
+```
+
+Replace the display resolution block inside the `for (const target of
+input.targets)` loop with:
+
+```ts
+      const resolution =
+        'display' in target
+          ? await catalog.resolveDisplayTarget(input.connectionName, target.display)
+          : {
+              resolved: { catalog: target.catalog, db: target.db, name: target.name, column: target.column },
+              candidates: [],
+              dialect: '',
+            };
+```
+
+After `const detail = await catalog.getTable(...)`, replace the existing
+`resolved.push(detail); appendTableMarkdown(...)` lines with:
+
+```ts
+      const requestedColumn = resolution.resolved.column;
+      if (requestedColumn) {
+        const column = findColumn(detail, requestedColumn);
+        if (!column) {
+          missing.push({
+            target,
+            candidates: [{ catalog: detail.catalog, db: detail.db, name: detail.name }],
+          });
+          parts.push(`Column not found in scan: ${detail.display}.${requestedColumn}`);
+          parts.push(`Available columns: ${detail.columns.map((candidate) => candidate.name).join(', ')}`);
+          continue;
+        }
+        const scopedDetail = { ...detail, columns: [column] };
+        resolved.push(scopedDetail);
+        appendTableMarkdown(parts, scopedDetail, column.name);
+        continue;
+      }
+
+      resolved.push(detail);
+      appendTableMarkdown(parts, detail);
+```
+
+- [ ] **Step 7: Run warehouse verification tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts \
+  src/ingest/tools/warehouse-verification/entity-details.tool.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts \
+  packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts \
+  packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts
+git commit -m "fix(context): verify warehouse column display targets"
+```
+
+### Task 5: Verify the v1 gap closure
+
+**Files:**
+- Verify all files changed by Tasks 1-4.
+
+- [ ] **Step 1: Run focused tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/adapters/notion/notion.adapter.test.ts \
+  src/ingest/local-adapters.test.ts \
+  src/ingest/ingest-prompts.test.ts \
+  src/ingest/tools/warehouse-verification/discover-data.tool.test.ts \
+  src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts \
+  src/ingest/tools/warehouse-verification/entity-details.tool.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run package type-check**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context run type-check
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Run package tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context run test
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Run pre-commit on changed files when configured**
+
+Run:
+
+```bash
+uv run pre-commit run --files \
+  packages/context/src/ingest/adapters/notion/notion.adapter.ts \
+  packages/context/src/ingest/adapters/notion/notion.adapter.test.ts \
+  packages/context/src/ingest/local-adapters.ts \
+  packages/context/src/ingest/local-adapters.test.ts \
+  packages/context/src/ingest/adapters/notion/chunk.ts \
+  packages/context/prompts/memory_agent_bundle_ingest_work_unit.md \
+  packages/context/src/ingest/ingest-prompts.test.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts \
+  packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts \
+  packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts \
+  packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts
+```
+
+Expected: PASS. If the repo has no pre-commit config or the local `uv` version
+cannot satisfy the project pin, record the exact error and rely on focused
+tests plus type-check.
+
+- [ ] **Step 5: Inspect final git status**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected: only intentional files are modified. Commit any formatter-driven
+changes with:
+
+```bash
+git add packages/context
+git commit -m "chore(context): verify warehouse verification v1 gaps"
+```
+
+## Self-review checklist
+
+- Spec coverage: this plan closes the remaining v1 paths for Notion warehouse
+  verification, active WorkUnit prompt correctness, raw discovery scoping, and
+  column-level identifier verification.
+- Placeholder scan: no task relies on future-work markers, unnamed edge-case
+  handling, or cross-task shorthand.
+- Type consistency: `discover_data` continues to use `connectionName`,
+  `sl_discover` still receives `connectionId` internally, and
+  `resolveDisplayTarget()` returns the same table identity plus optional
+  `column`.
--- a/docs/superpowers/plans/2026-05-12-warehouse-verification-final-v1-closure.md
+++ b/docs/superpowers/plans/2026-05-12-warehouse-verification-final-v1-closure.md
@ -0,0 +1,957 @@
+# Warehouse Verification Final V1 Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the remaining v1 gaps that still prevent ingest agents from
+reliably following warehouse verification results through to `entity_details`
+and `sql_execution`.
+
+**Architecture:** Keep the existing warehouse verification module and runner
+session scoping. Add connection names to raw discovery hits, expose primary
+warehouse targets from the remaining source adapters, and make local ingest
+SQL probes use the same scan connector read-only execution path as schema scan.
+
+**Tech Stack:** TypeScript, Node 22, Vitest, AI SDK v6 tools, Zod, KTX local
+ingest runtime, KTX scan connectors.
+
+---
+
+## Audit summary
+
+The first two implementation plans landed the warehouse verification tools,
+prompt protocol, Notion warehouse scoping, and stale prompt-name cleanup. The
+focused audit on May 12, 2026, found three remaining v1-blocking gaps:
+
+- `discover_data` searches multiple allowed raw warehouse scans, but raw hits do
+  not carry or render `connectionName`. The tool tells the agent to call
+  `entity_details({connectionName, targets: [...]})`, then omits the required
+  `connectionName` from the follow-up evidence.
+- Local LookML and MetricFlow adapters do not expose primary warehouse target
+  IDs. The runner only adds adapter-provided targets to `allowedConnectionNames`,
+  so those WorkUnits cannot use raw warehouse verification unless their source
+  connection is itself the warehouse.
+- `sql_execution` calls the local ingest connection catalog, but the catalog
+  either has no query executor in normal CLI ingest or calls an injected
+  executor without `projectDir` and connection config. The default local query
+  executor cannot dispatch without that config.
+
+Non-blocking gaps remain out of scope for this v1 plan:
+
+- Full DDL-style `entity_details` formatting with FK profile summaries.
+- AST-backed SQL read-only validation for data-modifying CTE bodies.
+- Search over generated `enrichment/descriptions.json`.
+- Lexicographic latest-sync edge cases for non-timestamp sync IDs.
+- Hard write-time validation in `wiki_write` and `emit_unmapped_fallback`.
+
+## File structure
+
+Modify these files:
+
+- `packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts`:
+  add `connectionName` to raw schema hit records.
+- `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts`:
+  render raw hit connection names and preserve them in structured output.
+- `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts`:
+  cover multi-connection raw discovery follow-up data.
+- `packages/context/src/ingest/adapters/lookml/lookml.adapter.ts`:
+  accept and return configured target warehouse connection IDs.
+- `packages/context/src/ingest/adapters/lookml/lookml.adapter.test.ts`:
+  cover LookML target warehouse IDs.
+- `packages/context/src/ingest/adapters/metricflow/metricflow.adapter.ts`:
+  accept and return configured target warehouse connection IDs.
+- `packages/context/src/ingest/adapters/metricflow/metricflow.adapter.test.ts`:
+  cover MetricFlow target warehouse IDs.
+- `packages/context/src/ingest/local-adapters.ts`:
+  pass primary warehouse IDs into LookML and MetricFlow adapters.
+- `packages/context/src/ingest/local-adapters.test.ts`:
+  cover local adapter warehouse target fan-out.
+- `packages/context/src/ingest/local-bundle-runtime.ts`:
+  pass full project connection config to local ingest query executors.
+- `packages/context/src/ingest/local-bundle-runtime.test.ts`:
+  cover the local ingest query executor call shape.
+- `packages/context/src/ingest/local-ingest.ts`:
+  use the shared query executor port type.
+- `packages/context/src/mcp/local-project-ports.ts`:
+  no behavior change expected, but type-checks against the updated local ingest
+  query executor type.
+- `packages/cli/src/ingest.ts`:
+  provide a read-only scan-connector-backed query executor for normal local
+  ingest runs.
+
+Create these files:
+
+- `packages/cli/src/ingest-query-executor.ts`: CLI query executor that adapts
+  scan connectors' `executeReadOnly()` method to `KtxSqlQueryExecutorPort`.
+- `packages/cli/src/ingest-query-executor.test.ts`: unit coverage for the CLI
+  ingest query executor.
+
+### Task 1: Preserve raw discovery connection names
+
+**Files:**
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts`
+
+- [ ] **Step 1: Write the failing multi-connection discovery test**
+
+Add this test to
+`packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts`:
+
+```ts
+  it('includes connectionName on raw schema hits so entity_details can follow up', async () => {
+    const multiConnectionContext: ToolContext = {
+      ...context,
+      session: { allowedConnectionNames: new Set(['warehouse', 'analytics']) } as any,
+    };
+    catalog.searchByName.mockImplementation(async (connectionName: string, query: string) => [
+      {
+        kind: 'table',
+        connectionName,
+        ref: { catalog: null, db: 'public', name: `${connectionName}_${query}` },
+        display: `public.${connectionName}_${query}`,
+        matchedOn: 'name',
+      },
+    ]);
+
+    const result = await tool.call({ query: 'orders', limit: 10 }, multiConnectionContext);
+
+    expect(catalog.searchByName).toHaveBeenCalledWith('analytics', 'orders', 10);
+    expect(catalog.searchByName).toHaveBeenCalledWith('warehouse', 'orders', 10);
+    expect(result.markdown).toContain('connectionName=analytics');
+    expect(result.markdown).toContain('connectionName=warehouse');
+    expect(result.markdown).toContain(
+      'entity_details({connectionName: "analytics", targets: [{display: "public.analytics_orders"}]})',
+    );
+    expect(result.structured.raw?.hits.map((hit) => hit.connectionName)).toEqual([
+      'analytics',
+      'warehouse',
+    ]);
+  });
+```
+
+- [ ] **Step 2: Run the failing discovery test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/discover-data.tool.test.ts -t "connectionName on raw schema hits"
+```
+
+Expected: FAIL because `RawSchemaHit` has no `connectionName` property and the
+markdown only renders the display string.
+
+- [ ] **Step 3: Add `connectionName` to raw schema hits**
+
+Modify the raw hit type and hit construction in
+`packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts`:
+
+```ts
+export type RawSchemaHit =
+  | {
+      kind: 'table';
+      connectionName: string;
+      ref: KtxTableRef;
+      display: string;
+      matchedOn: 'name' | 'db' | 'comment' | 'description';
+    }
+  | {
+      kind: 'column';
+      connectionName: string;
+      ref: KtxTableRef & { column: string };
+      display: string;
+      matchedOn: 'name' | 'comment' | 'description';
+    };
+```
+
+In the table hit block, add `connectionName`:
+
+```ts
+        hits.push({
+          kind: 'table',
+          connectionName,
+          ref: { catalog: table.catalog, db: table.db, name: table.name },
+          display: formatDisplay(catalog.driver, table),
+          matchedOn: tableMatch,
+        });
+```
+
+In the column hit block, add `connectionName`:
+
+```ts
+        hits.push({
+          kind: 'column',
+          connectionName,
+          ref: { catalog: table.catalog, db: table.db, name: table.name, column: column.name },
+          display: `${formatDisplay(catalog.driver, table)}.${column.name}`,
+          matchedOn: columnMatch,
+        });
+```
+
+- [ ] **Step 4: Render follow-up-ready raw hits**
+
+Modify the raw schema markdown in
+`packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts`:
+
+```ts
+      parts.push('## Raw Warehouse Schema', '> use `entity_details({connectionName, targets: [{display}]})` for full DDL + sample values');
+      parts.push(
+        rawHits
+          .slice(0, limit)
+          .map(
+            (hit) =>
+              `- ${hit.kind}: ${hit.display} [connectionName=${hit.connectionName}] (matched on ${hit.matchedOn}) — ` +
+              `follow up with \`entity_details({connectionName: "${hit.connectionName}", targets: [{display: "${hit.display}"}]})\``,
+          )
+          .join('\n'),
+      );
+```
+
+- [ ] **Step 5: Run the discovery test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/discover-data.tool.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts
+git commit -m "fix(context): include raw discovery connection names"
+```
+
+### Task 2: Expose LookML and MetricFlow warehouse targets
+
+**Files:**
+- Modify: `packages/context/src/ingest/adapters/lookml/lookml.adapter.ts`
+- Modify: `packages/context/src/ingest/adapters/lookml/lookml.adapter.test.ts`
+- Modify: `packages/context/src/ingest/adapters/metricflow/metricflow.adapter.ts`
+- Modify: `packages/context/src/ingest/adapters/metricflow/metricflow.adapter.test.ts`
+- Modify: `packages/context/src/ingest/local-adapters.ts`
+- Modify: `packages/context/src/ingest/local-adapters.test.ts`
+
+- [ ] **Step 1: Write failing adapter target tests**
+
+Add this test to
+`packages/context/src/ingest/adapters/lookml/lookml.adapter.test.ts`:
+
+```ts
+  it('returns configured target warehouse connection ids', async () => {
+    const adapter = new LookmlSourceAdapter({
+      homeDir: join(tmpRoot, 'home'),
+      targetConnectionIds: ['warehouse', 'analytics', 'warehouse'],
+    });
+
+    await expect(adapter.listTargetConnectionIds?.(join(tmpRoot, 'staged'))).resolves.toEqual([
+      'analytics',
+      'warehouse',
+    ]);
+  });
+```
+
+Add this test to
+`packages/context/src/ingest/adapters/metricflow/metricflow.adapter.test.ts`:
+
+```ts
+  it('returns configured target warehouse connection ids', async () => {
+    const metricflow = new MetricflowSourceAdapter({
+      homeDir: join(tmpRoot, 'cache-home'),
+      targetConnectionIds: ['warehouse', 'analytics', 'warehouse'],
+    });
+
+    await expect(metricflow.listTargetConnectionIds?.(stagedDir)).resolves.toEqual([
+      'analytics',
+      'warehouse',
+    ]);
+  });
+```
+
+- [ ] **Step 2: Run the failing adapter tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/adapters/lookml/lookml.adapter.test.ts -t "target warehouse connection ids" \
+  src/ingest/adapters/metricflow/metricflow.adapter.test.ts -t "target warehouse connection ids"
+```
+
+Expected: FAIL because neither adapter accepts `targetConnectionIds` or
+implements `listTargetConnectionIds()`.
+
+- [ ] **Step 3: Implement target ID support in LookML**
+
+Modify `packages/context/src/ingest/adapters/lookml/lookml.adapter.ts`:
+
+```ts
+export interface LookmlSourceAdapterDeps {
+  homeDir: string;
+  targetConnectionIds?: string[];
+}
+
+function uniqueSorted(values: readonly string[] | undefined): string[] {
+  return [...new Set(values ?? [])].sort((left, right) => left.localeCompare(right));
+}
+```
+
+Add this method to `LookmlSourceAdapter`:
+
+```ts
+  async listTargetConnectionIds(_stagedDir: string): Promise<string[]> {
+    return uniqueSorted(this.deps.targetConnectionIds);
+  }
+```
+
+- [ ] **Step 4: Implement target ID support in MetricFlow**
+
+Modify `packages/context/src/ingest/adapters/metricflow/metricflow.adapter.ts`:
+
+```ts
+export interface MetricflowSourceAdapterDeps {
+  homeDir: string;
+  targetConnectionIds?: string[];
+}
+
+function uniqueSorted(values: readonly string[] | undefined): string[] {
+  return [...new Set(values ?? [])].sort((left, right) => left.localeCompare(right));
+}
+```
+
+Add this method to `MetricflowSourceAdapter`:
+
+```ts
+  async listTargetConnectionIds(_stagedDir: string): Promise<string[]> {
+    return uniqueSorted(this.deps.targetConnectionIds);
+  }
+```
+
+- [ ] **Step 5: Pass primary warehouses from the local adapter factory**
+
+Modify the LookML and MetricFlow adapter construction in
+`packages/context/src/ingest/local-adapters.ts`:
+
+```ts
+    new LookmlSourceAdapter({
+      homeDir: join(project.projectDir, '.ktx/cache'),
+      targetConnectionIds: primaryWarehouseConnectionIds(project),
+    }),
+```
+
+```ts
+    new MetricflowSourceAdapter({
+      homeDir: join(project.projectDir, '.ktx/cache'),
+      targetConnectionIds: primaryWarehouseConnectionIds(project),
+    }),
+```
+
+- [ ] **Step 6: Write the local adapter fan-out test**
+
+Add this test to `packages/context/src/ingest/local-adapters.test.ts`:
+
+```ts
+  it('passes primary warehouse connection ids to local LookML and MetricFlow adapters', async () => {
+    const adapters = createDefaultLocalIngestAdapters(
+      projectWithConnections({
+        warehouse: {
+          driver: 'postgres',
+          url: 'postgresql://readonly@db.example.test/analytics',
+        },
+        lookml_docs: {
+          driver: 'lookml',
+          lookml: {
+            repoUrl: 'https://github.com/acme/lookml.git',
+          },
+        },
+        metrics_repo: {
+          driver: 'metricflow',
+          metricflow: {
+            repoUrl: 'https://github.com/acme/metrics.git',
+          },
+        },
+      } as never),
+    );
+
+    const lookml = adapters.find((adapter) => adapter.source === 'lookml');
+    const metricflow = adapters.find((adapter) => adapter.source === 'metricflow');
+
+    await expect(lookml?.listTargetConnectionIds?.('/tmp/staged-lookml')).resolves.toEqual([
+      'warehouse',
+    ]);
+    await expect(metricflow?.listTargetConnectionIds?.('/tmp/staged-metricflow')).resolves.toEqual([
+      'warehouse',
+    ]);
+  });
+```
+
+- [ ] **Step 7: Run the target fan-out tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/adapters/lookml/lookml.adapter.test.ts \
+  src/ingest/adapters/metricflow/metricflow.adapter.test.ts \
+  src/ingest/local-adapters.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/adapters/lookml/lookml.adapter.ts \
+  packages/context/src/ingest/adapters/lookml/lookml.adapter.test.ts \
+  packages/context/src/ingest/adapters/metricflow/metricflow.adapter.ts \
+  packages/context/src/ingest/adapters/metricflow/metricflow.adapter.test.ts \
+  packages/context/src/ingest/local-adapters.ts \
+  packages/context/src/ingest/local-adapters.test.ts
+git commit -m "fix(context): expose warehouse targets for LookML and MetricFlow"
+```
+
+### Task 3: Pass full connection config to local ingest SQL execution
+
+**Files:**
+- Modify: `packages/context/src/ingest/local-bundle-runtime.ts`
+- Modify: `packages/context/src/ingest/local-bundle-runtime.test.ts`
+- Modify: `packages/context/src/ingest/local-ingest.ts`
+
+- [ ] **Step 1: Write the failing local connection catalog test**
+
+In `packages/context/src/ingest/local-bundle-runtime.test.ts`, change the
+Vitest import to include `vi`:
+
+```ts
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+```
+
+Extend `RuntimeWithConnectionDeps`:
+
+```ts
+type RuntimeWithConnectionDeps = {
+  deps: {
+    connections: {
+      listEnabledConnections(ids: string[]): Promise<Array<{ id: string; name: string; connectionType: string }>>;
+      getConnectionById(connectionId: string): Promise<{ id: string; name: string; connectionType: string } | null>;
+      executeQuery(connectionId: string, sql: string): Promise<unknown>;
+    };
+  };
+};
+```
+
+Add this test:
+
+```ts
+  it('passes project connection config to local ingest query executors', async () => {
+    const agentRunner = new AgentRunnerService({ llmProvider: { getModel: () => ({}) as never } as any });
+    const queryExecutor = {
+      execute: vi.fn(async () => ({
+        headers: ['answer'],
+        rows: [[1]],
+        totalRows: 1,
+        command: 'SELECT',
+        rowCount: 1,
+      })),
+    };
+
+    const runtime = createLocalBundleIngestRuntime({
+      project,
+      adapters: [new FakeSourceAdapter()],
+      agentRunner,
+      queryExecutor,
+    });
+    const connections = (runtime.runner as unknown as RuntimeWithConnectionDeps).deps.connections;
+
+    await expect(connections.executeQuery('warehouse', 'select 1')).resolves.toMatchObject({
+      headers: ['answer'],
+    });
+    expect(queryExecutor.execute).toHaveBeenCalledWith({
+      connectionId: 'warehouse',
+      projectDir: project.projectDir,
+      connection: project.config.connections.warehouse,
+      sql: 'select 1',
+    });
+  });
+```
+
+- [ ] **Step 2: Run the failing local runtime test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/local-bundle-runtime.test.ts -t "project connection config"
+```
+
+Expected: FAIL because `LocalConnectionCatalog.executeQuery()` only passes
+`connectionId` and `sql`.
+
+- [ ] **Step 3: Update local ingest query executor types**
+
+In `packages/context/src/ingest/local-bundle-runtime.ts`, import the shared
+query executor type:
+
+```ts
+import { localConnectionInfoFromConfig, type KtxSqlQueryExecutorPort } from '../connections/index.js';
+```
+
+Change `CreateLocalBundleIngestRuntimeOptions.queryExecutor` to:
+
+```ts
+  queryExecutor?: KtxSqlQueryExecutorPort;
+```
+
+Change `LocalConnectionCatalog` to store that type:
+
+```ts
+class LocalConnectionCatalog implements SlConnectionCatalogPort {
+  constructor(
+    private readonly project: KtxLocalProject,
+    private readonly queryExecutor?: KtxSqlQueryExecutorPort,
+  ) {}
+```
+
+Change `executeQuery()`:
+
+```ts
+  async executeQuery(connectionId: string, sql: string): Promise<KtxQueryResult> {
+    if (!this.queryExecutor) {
+      throw new Error('Local ingest has no query executor configured');
+    }
+    return this.queryExecutor.execute({
+      connectionId,
+      projectDir: this.project.projectDir,
+      connection: this.project.config.connections[connectionId],
+      sql,
+    });
+  }
+```
+
+In `packages/context/src/ingest/local-ingest.ts`, replace the local query
+executor object type with the shared port:
+
+```ts
+import type { KtxSqlQueryExecutorPort } from '../connections/index.js';
+```
+
+```ts
+  queryExecutor?: KtxSqlQueryExecutorPort;
+```
+
+- [ ] **Step 4: Run the local runtime test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/local-bundle-runtime.test.ts -t "project connection config"
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/local-bundle-runtime.ts \
+  packages/context/src/ingest/local-bundle-runtime.test.ts \
+  packages/context/src/ingest/local-ingest.ts
+git commit -m "fix(context): pass connection config to ingest query executors"
+```
+
+### Task 4: Supply a scan-connector query executor to CLI ingest
+
+**Files:**
+- Create: `packages/cli/src/ingest-query-executor.ts`
+- Create: `packages/cli/src/ingest-query-executor.test.ts`
+- Modify: `packages/cli/src/ingest.ts`
+
+- [ ] **Step 1: Write the CLI query executor tests**
+
+Create `packages/cli/src/ingest-query-executor.test.ts`:
+
+```ts
+import type { KtxLocalProject } from '@ktx/context/project';
+import { createKtxConnectorCapabilities, type KtxScanConnector } from '@ktx/context/scan';
+import { describe, expect, it, vi } from 'vitest';
+import { createKtxCliIngestQueryExecutor } from './ingest-query-executor.js';
+
+function project(): KtxLocalProject {
+  return {
+    projectDir: '/tmp/ktx-query-project',
+    config: {
+      project: 'warehouse',
+      connections: {
+        warehouse: { driver: 'postgres', url: 'postgresql://readonly@example.test/db' },
+      },
+    },
+  } as unknown as KtxLocalProject;
+}
+
+function connector(overrides: Partial<KtxScanConnector> = {}): KtxScanConnector {
+  return {
+    id: 'warehouse',
+    driver: 'postgres',
+    capabilities: createKtxConnectorCapabilities({ readOnlySql: true }),
+    async introspect() {
+      throw new Error('introspect is not used by this test');
+    },
+    executeReadOnly: vi.fn(async () => ({
+      headers: ['answer'],
+      rows: [[1]],
+      totalRows: 1,
+      rowCount: 1,
+    })),
+    cleanup: vi.fn(async () => {}),
+    ...overrides,
+  };
+}
+
+describe('createKtxCliIngestQueryExecutor', () => {
+  it('executes read-only SQL through the scan connector and cleans it up', async () => {
+    const scanConnector = connector();
+    const createConnector = vi.fn(async () => scanConnector);
+    const executor = createKtxCliIngestQueryExecutor(project(), { createConnector });
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        connection: { driver: 'postgres', url: 'postgresql://readonly@example.test/db' },
+        projectDir: '/tmp/ktx-query-project',
+        sql: 'select 1',
+        maxRows: 5,
+      }),
+    ).resolves.toMatchObject({
+      headers: ['answer'],
+      rows: [[1]],
+      totalRows: 1,
+      command: 'SELECT',
+      rowCount: 1,
+    });
+
+    expect(createConnector).toHaveBeenCalledWith(project(), 'warehouse');
+    expect(scanConnector.executeReadOnly).toHaveBeenCalledWith(
+      { connectionId: 'warehouse', sql: 'select 1', maxRows: 5 },
+      { runId: 'ingest-sql-execution' },
+    );
+    expect(scanConnector.cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects connectors without read-only SQL support', async () => {
+    const scanConnector = connector({
+      capabilities: createKtxConnectorCapabilities({ readOnlySql: false }),
+      executeReadOnly: undefined,
+    });
+    const executor = createKtxCliIngestQueryExecutor(project(), {
+      createConnector: vi.fn(async () => scanConnector),
+    });
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        connection: { driver: 'postgres' },
+        projectDir: '/tmp/ktx-query-project',
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('Connection "warehouse" driver "postgres" does not support read-only SQL execution.');
+    expect(scanConnector.cleanup).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+- [ ] **Step 2: Run the failing CLI query executor test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/cli exec vitest run src/ingest-query-executor.test.ts
+```
+
+Expected: FAIL because `ingest-query-executor.ts` does not exist.
+
+- [ ] **Step 3: Add the scan-connector-backed query executor**
+
+Create `packages/cli/src/ingest-query-executor.ts`:
+
+```ts
+import type { KtxSqlQueryExecutionInput, KtxSqlQueryExecutorPort } from '@ktx/context/connections';
+import type { KtxLocalProject } from '@ktx/context/project';
+import type { KtxScanConnector, KtxScanContext } from '@ktx/context/scan';
+import { createKtxCliScanConnector } from './local-scan-connectors.js';
+
+type CreateConnector = typeof createKtxCliScanConnector;
+
+export interface KtxCliIngestQueryExecutorDeps {
+  createConnector?: CreateConnector;
+}
+
+async function cleanupConnector(connector: KtxScanConnector | null): Promise<void> {
+  await connector?.cleanup?.();
+}
+
+export function createKtxCliIngestQueryExecutor(
+  project: KtxLocalProject,
+  deps: KtxCliIngestQueryExecutorDeps = {},
+): KtxSqlQueryExecutorPort {
+  const createConnector = deps.createConnector ?? createKtxCliScanConnector;
+  return {
+    async execute(input: KtxSqlQueryExecutionInput) {
+      let connector: KtxScanConnector | null = null;
+      try {
+        connector = await createConnector(project, input.connectionId);
+        if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
+          throw new Error(
+            `Connection "${input.connectionId}" driver "${connector.driver}" does not support read-only SQL execution.`,
+          );
+        }
+
+        const ctx: KtxScanContext = { runId: 'ingest-sql-execution' };
+        const result = await connector.executeReadOnly(
+          { connectionId: input.connectionId, sql: input.sql, maxRows: input.maxRows },
+          ctx,
+        );
+        return {
+          headers: result.headers,
+          rows: result.rows,
+          totalRows: result.totalRows,
+          command: 'SELECT',
+          rowCount: result.rowCount,
+        };
+      } finally {
+        await cleanupConnector(connector);
+      }
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Wire the CLI executor into local ingest runs**
+
+In `packages/cli/src/ingest.ts`, import the executor and type:
+
+```ts
+import type { KtxSqlQueryExecutorPort } from '@ktx/context/connections';
+import type { KtxLocalProject } from '@ktx/context/project';
+import { createKtxCliIngestQueryExecutor } from './ingest-query-executor.js';
+```
+
+Extend `KtxIngestDeps`:
+
+```ts
+  createQueryExecutor?: (project: KtxLocalProject) => KtxSqlQueryExecutorPort;
+```
+
+Inside the `args.command === 'run'` branch, after `localIngestOptions` is
+defined, add:
+
+```ts
+      const queryExecutor =
+        localIngestOptions.queryExecutor ??
+        (deps.createQueryExecutor ?? createKtxCliIngestQueryExecutor)(project);
+```
+
+Pass `queryExecutor` to both local ingest execution paths. In the Metabase
+fan-out call:
+
+```ts
+          ...localIngestOptions,
+          queryExecutor,
+          trigger: 'manual_resync',
+```
+
+In the normal local ingest call:
+
+```ts
+          ...localIngestOptions,
+          queryExecutor,
+          pullConfigOptions: adapterOptions,
+```
+
+- [ ] **Step 5: Add CLI wiring coverage**
+
+Add this test to `packages/cli/src/ingest.test.ts`:
+
+```ts
+  it('supplies a scan-connector query executor to local ingest runs', async () => {
+    const io = makeIo();
+    const projectDir = join(tempDir, 'query-executor-project');
+    await writeWarehouseConfig(projectDir);
+    const queryExecutor = {
+      execute: vi.fn(async () => ({
+        headers: [],
+        rows: [],
+        totalRows: 0,
+        command: 'SELECT',
+        rowCount: 0,
+      })),
+    };
+    const runLocalIngest = vi.fn(async (input: RunLocalIngestOptions): Promise<LocalIngestResult> =>
+      completedLocalBundleRun(input, 'query-executor-run'),
+    );
+
+    await expect(
+      runKtxIngest(
+        {
+          command: 'run',
+          projectDir,
+          connectionId: 'warehouse',
+          adapter: 'fake',
+          outputMode: 'json',
+        },
+        io.io,
+        {
+          runLocalIngest,
+          createAdapters: () => [],
+          createQueryExecutor: () => queryExecutor,
+        },
+      ),
+    ).resolves.toBe(0);
+
+    expect(runLocalIngest).toHaveBeenCalledWith(expect.objectContaining({ queryExecutor }));
+  });
+```
+
+- [ ] **Step 6: Run CLI query executor tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/cli exec vitest run src/ingest-query-executor.test.ts src/ingest.test.ts -t "query executor"
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/cli/src/ingest-query-executor.ts \
+  packages/cli/src/ingest-query-executor.test.ts \
+  packages/cli/src/ingest.ts \
+  packages/cli/src/ingest.test.ts
+git commit -m "fix(cli): enable read-only SQL probes for local ingest"
+```
+
+### Task 5: Final verification
+
+**Files:**
+- Verify: all files changed by Tasks 1-4.
+
+- [ ] **Step 1: Run focused context tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run \
+  src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts \
+  src/ingest/tools/warehouse-verification/entity-details.tool.test.ts \
+  src/ingest/tools/warehouse-verification/discover-data.tool.test.ts \
+  src/ingest/tools/warehouse-verification/sql-execution.tool.test.ts \
+  src/ingest/local-bundle-runtime.test.ts \
+  src/ingest/local-adapters.test.ts \
+  src/ingest/adapters/lookml/lookml.adapter.test.ts \
+  src/ingest/adapters/metricflow/metricflow.adapter.test.ts \
+  src/ingest/ingest-bundle.runner.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run focused CLI tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/cli exec vitest run src/ingest-query-executor.test.ts src/ingest.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Run type checks**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context run type-check
+pnpm --filter @ktx/cli run type-check
+```
+
+Expected: both commands pass.
+
+- [ ] **Step 4: Run pre-commit on changed files if configured**
+
+Run:
+
+```bash
+uv run pre-commit run --files \
+  packages/context/src/ingest/tools/warehouse-verification/warehouse-catalog.service.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/discover-data.tool.test.ts \
+  packages/context/src/ingest/adapters/lookml/lookml.adapter.ts \
+  packages/context/src/ingest/adapters/lookml/lookml.adapter.test.ts \
+  packages/context/src/ingest/adapters/metricflow/metricflow.adapter.ts \
+  packages/context/src/ingest/adapters/metricflow/metricflow.adapter.test.ts \
+  packages/context/src/ingest/local-adapters.ts \
+  packages/context/src/ingest/local-adapters.test.ts \
+  packages/context/src/ingest/local-bundle-runtime.ts \
+  packages/context/src/ingest/local-bundle-runtime.test.ts \
+  packages/context/src/ingest/local-ingest.ts \
+  packages/cli/src/ingest-query-executor.ts \
+  packages/cli/src/ingest-query-executor.test.ts \
+  packages/cli/src/ingest.ts \
+  packages/cli/src/ingest.test.ts \
+  docs/superpowers/plans/2026-05-12-warehouse-verification-final-v1-closure.md
+```
+
+Expected: PASS. If the repository has no pre-commit config or the local `uv`
+version cannot satisfy the configured toolchain, record the exact error and use
+the focused test and type-check results as the closest verification.
+
+- [ ] **Step 5: Commit final verification fixes if any were needed**
+
+If verification required edits, run:
+
+```bash
+git add <changed-files>
+git commit -m "test: cover warehouse verification v1 closure"
+```
+
+If verification required no edits, do not create an empty commit.
+
+## Self-review
+
+Spec coverage:
+
+- Raw warehouse discovery still covers wiki, semantic-layer, and raw schema
+  results, and now raw hits include the connection name needed by the required
+  `entity_details` follow-up.
+- Every local synthesis adapter with an external source connection now has a
+  path to target warehouse IDs: dbt and Notion already had it, Looker resolves
+  staged mappings, Metabase fan-out runs under target warehouse IDs, and this
+  plan adds LookML and MetricFlow.
+- `sql_execution` remains scoped by `allowedConnectionNames`, retains the
+  read-only SQL wrapper, and gains a normal local ingest execution backend.
+
+Placeholder scan:
+
+- This plan contains no deferred implementation placeholders.
+- Every code-changing step includes the exact test or implementation snippet to
+  add.
+
+Type consistency:
+
+- `connectionName` is added to `RawSchemaHit` and used by `DiscoverDataTool`.
+- `targetConnectionIds` and `listTargetConnectionIds()` match the existing dbt
+  and Notion adapter pattern.
+- Local ingest uses `KtxSqlQueryExecutorPort` consistently from CLI to context.
--- a/docs/superpowers/plans/2026-05-12-warehouse-verification-tools.md
+++ b/docs/superpowers/plans/2026-05-12-warehouse-verification-tools.md
--- a/docs/superpowers/plans/2026-05-13-warehouse-verification-prompt-shape-closure.md
+++ b/docs/superpowers/plans/2026-05-13-warehouse-verification-prompt-shape-closure.md
@ -0,0 +1,345 @@
+# Warehouse Verification Prompt Shape Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make every warehouse-verification prompt use KTX's shipped
+`sql_execution` input shape so ingest agents include `connectionName` when they
+probe warehouse identifiers.
+
+**Architecture:** Keep the warehouse verification tool code unchanged. Add
+prompt-asset tests that reject Kaelio's old session-only SQL examples, then
+update the shared identifier protocol and the three remaining per-skill SQL
+probe examples that still show the legacy shape.
+
+**Tech Stack:** Markdown skill prompts, TypeScript, Vitest, pnpm workspace
+commands.
+
+---
+
+## Audit Summary
+
+The warehouse verification tools, runner wiring, adapter target fan-out, and
+focused tests are present. Focused verification passed:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/connections/dialects.test.ts src/connections/read-only-sql.test.ts src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts src/ingest/tools/warehouse-verification/entity-details.tool.test.ts src/ingest/tools/warehouse-verification/sql-execution.tool.test.ts src/ingest/tools/warehouse-verification/discover-data.tool.test.ts src/ingest/ingest-prompts.test.ts src/ingest/ingest-runtime-assets.test.ts src/memory/memory-runtime-assets.test.ts src/ingest/local-adapters.test.ts src/ingest/adapters/notion/notion.adapter.test.ts src/ingest/adapters/lookml/lookml.adapter.test.ts src/ingest/adapters/metricflow/metricflow.adapter.test.ts
+pnpm --filter @ktx/cli exec vitest run src/ingest-query-executor.test.ts src/ingest.test.ts -t "supplies a scan-connector query executor"
+```
+
+Remaining v1-blocking gap:
+
+- `packages/context/skills/lookml_ingest/SKILL.md`,
+  `packages/context/skills/metricflow_ingest/SKILL.md`, and
+  `packages/context/skills/sl_capture/SKILL.md` still contain
+  `sql_execution({ sql ... })` / "session shape" guidance inherited from
+  Kaelio. KTX's tool contract is
+  `sql_execution({connectionName, sql, rowLimit?})`, so these examples can make
+  agents call the shipped tool with invalid input.
+
+Non-blocking gaps remain out of scope for this v1 plan:
+
+- Full DDL-style `entity_details` formatting with FK profile summaries.
+- AST-backed SQL validation for data-modifying CTE bodies.
+- Search over generated `enrichment/descriptions.json`.
+- Per-WorkUnit reuse of a single `WarehouseCatalogService` instance for cache
+  hits across separate tool calls.
+- A deterministic fake-LLM end-to-end Notion hallucination regression. Prompt
+  guards and tool contract tests cover the v1 contract; a broader behavior
+  regression can land as follow-up.
+
+## File Structure
+
+Modify these files:
+
+- `packages/context/src/memory/memory-runtime-assets.test.ts`: add a prompt
+  guard that rejects the legacy session-only `sql_execution` shape.
+- `packages/context/src/ingest/ingest-runtime-assets.test.ts`: strengthen the
+  shared prompt asset assertion for the KTX `connectionName` SQL shape.
+- `packages/context/skills/_shared/identifier-verification.md`: make both SQL
+  probe instructions show the KTX `connectionName` argument.
+- `packages/context/skills/notion_synthesize/SKILL.md`: inline the updated
+  protocol block.
+- `packages/context/skills/dbt_ingest/SKILL.md`: inline the updated protocol
+  block.
+- `packages/context/skills/lookml_ingest/SKILL.md`: inline the updated protocol
+  block and fix the legacy SQL fallback example.
+- `packages/context/skills/looker_ingest/SKILL.md`: inline the updated
+  protocol block.
+- `packages/context/skills/metabase_ingest/SKILL.md`: inline the updated
+  protocol block.
+- `packages/context/skills/metricflow_ingest/SKILL.md`: inline the updated
+  protocol block and fix the legacy SQL fallback example.
+- `packages/context/skills/live_database_ingest/SKILL.md`: inline the updated
+  protocol block.
+- `packages/context/skills/historic_sql_table_digest/SKILL.md`: inline the
+  updated protocol block.
+- `packages/context/skills/historic_sql_patterns/SKILL.md`: inline the updated
+  protocol block.
+- `packages/context/skills/knowledge_capture/SKILL.md`: inline the updated
+  protocol block.
+- `packages/context/skills/sl_capture/SKILL.md`: inline the updated protocol
+  block and fix the join-discovery SQL example.
+
+### Task 1: Add Prompt Guards For The KTX SQL Tool Shape
+
+**Files:**
+- Modify: `packages/context/src/memory/memory-runtime-assets.test.ts`
+- Modify: `packages/context/src/ingest/ingest-runtime-assets.test.ts`
+
+- [ ] **Step 1: Add the failing memory asset guard**
+
+In `packages/context/src/memory/memory-runtime-assets.test.ts`, add this test
+after `does not ship stale warehouse verification tool names or fictional
+identifiers`:
+
+```ts
+  it('ships only the KTX connectionName sql_execution call shape in writer guidance', async () => {
+    const shared = await readFile(join(skillsDir, '_shared', 'identifier-verification.md'), 'utf-8');
+
+    expect(shared).toContain('sql_execution({connectionName, sql: "SELECT DISTINCT');
+    expect(shared).toContain('sql_execution({connectionName, sql: "SELECT 1 FROM');
+
+    for (const skillName of verificationWriterSkills) {
+      const body = await readFile(join(skillsDir, skillName, 'SKILL.md'), 'utf-8');
+      expect(body).toContain('sql_execution({connectionName');
+      expect(body).not.toContain('sql_execution({ sql');
+      expect(body).not.toContain('session shape');
+      expect(body).not.toContain('connection is already pinned by the ingest session');
+    }
+  });
+```
+
+- [ ] **Step 2: Strengthen the shared ingest asset guard**
+
+In `packages/context/src/ingest/ingest-runtime-assets.test.ts`, update
+`packages identifier verification prompt assets` so the final assertions are:
+
+```ts
+    expect(shared).toContain('discover_data');
+    expect(shared).toContain('entity_details');
+    expect(shared).toContain('sql_execution');
+    expect(shared).toContain('sql_execution({connectionName, sql: "SELECT DISTINCT');
+    expect(shared).toContain('sql_execution({connectionName, sql: "SELECT 1 FROM');
+```
+
+- [ ] **Step 3: Run the failing prompt guards**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/memory/memory-runtime-assets.test.ts src/ingest/ingest-runtime-assets.test.ts
+```
+
+Expected: FAIL. The failure must mention at least one current legacy string:
+`sql_execution({ sql`, `session shape`, or missing
+`sql_execution({connectionName`.
+
+### Task 2: Update The Shared Identifier Verification Protocol
+
+**Files:**
+- Modify: `packages/context/skills/_shared/identifier-verification.md`
+- Modify: `packages/context/skills/notion_synthesize/SKILL.md`
+- Modify: `packages/context/skills/dbt_ingest/SKILL.md`
+- Modify: `packages/context/skills/lookml_ingest/SKILL.md`
+- Modify: `packages/context/skills/looker_ingest/SKILL.md`
+- Modify: `packages/context/skills/metabase_ingest/SKILL.md`
+- Modify: `packages/context/skills/metricflow_ingest/SKILL.md`
+- Modify: `packages/context/skills/live_database_ingest/SKILL.md`
+- Modify: `packages/context/skills/historic_sql_table_digest/SKILL.md`
+- Modify: `packages/context/skills/historic_sql_patterns/SKILL.md`
+- Modify: `packages/context/skills/knowledge_capture/SKILL.md`
+- Modify: `packages/context/skills/sl_capture/SKILL.md`
+
+- [ ] **Step 1: Replace the shared protocol text**
+
+Replace the full `## Identifier Verification Protocol` block in
+`packages/context/skills/_shared/identifier-verification.md` with:
+
+```md
+## Identifier Verification Protocol
+
+Before writing a wiki page or SL source on any topic:
+
+1. `discover_data({query: "<topic>"})` - see what wikis, SL sources, and raw
+   tables already exist. Prefer updating existing pages over creating new ones.
+
+Before emitting any `schema.table` or `schema.table.column` into a wiki body,
+SL source, `tables:` frontmatter, `sl_refs`, or `emit_unmapped_fallback`:
+
+2. `entity_details({connectionName, targets: [{display: "<identifier>"}]})` -
+   confirm the identifier resolves; inspect native types, FK/PK, and
+   sampleValues.
+3. For literal values from the source, such as status codes or plan tiers,
+   check whether they appear in `entity_details` sampleValues for the relevant
+   column. If sampleValues is short or the sample may have missed real values,
+   run a `sql_execution` probe with the same warehouse connection name:
+   `sql_execution({connectionName, sql: "SELECT DISTINCT <col> FROM <ref> LIMIT 50"})`.
+4. If the candidate identifier still does not resolve, do one of:
+   - Use `sql_execution({connectionName, sql: "SELECT 1 FROM <ref> LIMIT 0"})`.
+     If it errors, the identifier is fictional.
+   - Wrap the identifier in `[unverified - from <rawPath>]` in the wiki body,
+     citing the exact raw path that mentioned it.
+   - When recording `emit_unmapped_fallback` with `no_physical_table`, include
+     the failing probe error in `clarification`.
+5. Never copy `<schema>.<table>` placeholder strings from these instructions
+   into output.
+```
+
+- [ ] **Step 2: Inline the same protocol in every writer skill**
+
+Replace the existing `## Identifier Verification Protocol` block in each writer
+skill with the exact block from Step 1:
+
+```bash
+packages/context/skills/notion_synthesize/SKILL.md
+packages/context/skills/dbt_ingest/SKILL.md
+packages/context/skills/lookml_ingest/SKILL.md
+packages/context/skills/looker_ingest/SKILL.md
+packages/context/skills/metabase_ingest/SKILL.md
+packages/context/skills/metricflow_ingest/SKILL.md
+packages/context/skills/live_database_ingest/SKILL.md
+packages/context/skills/historic_sql_table_digest/SKILL.md
+packages/context/skills/historic_sql_patterns/SKILL.md
+packages/context/skills/knowledge_capture/SKILL.md
+packages/context/skills/sl_capture/SKILL.md
+```
+
+- [ ] **Step 3: Run the shared prompt asset tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/memory/memory-runtime-assets.test.ts src/ingest/ingest-runtime-assets.test.ts
+```
+
+Expected: still FAIL because the per-skill legacy SQL examples in LookML,
+MetricFlow, and `sl_capture` have not been fixed yet.
+
+### Task 3: Fix Legacy Per-Skill SQL Examples
+
+**Files:**
+- Modify: `packages/context/skills/lookml_ingest/SKILL.md`
+- Modify: `packages/context/skills/metricflow_ingest/SKILL.md`
+- Modify: `packages/context/skills/sl_capture/SKILL.md`
+
+- [ ] **Step 1: Fix the LookML fallback probe example**
+
+In `packages/context/skills/lookml_ingest/SKILL.md`, replace the current
+Required flow item 2 with:
+
+```md
+2. If the table isn't in the manifest, use the warehouse `connectionName`
+   returned by `discover_data` or the target connection chosen from
+   `sl_discover`, then call a dialect-appropriate SQL probe with that
+   connection name, for example:
+   `sql_execution({connectionName: "warehouse", sql: "SELECT 1 FROM analytics.orders LIMIT 0"})`.
+   Replace `warehouse`, `analytics`, and `orders` with the verified connection,
+   schema or dataset, and table from the WorkUnit evidence.
+```
+
+- [ ] **Step 2: Fix the MetricFlow fallback probe example**
+
+In `packages/context/skills/metricflow_ingest/SKILL.md`, replace the paragraph
+that begins `If \`sl_discover\` errors` with:
+
+```md
+If `sl_discover` errors because no such table exists, use `discover_data` and
+`entity_details` to find the warehouse target. If a SQL probe is still needed,
+call `sql_execution` with the same warehouse connection name, for example:
+`sql_execution({connectionName: "warehouse", sql: "SELECT 1 FROM analytics.orders LIMIT 0"})`.
+**Never invent column names** - every column in `columns:`, `grain:`, and
+`sql:` must be sourced from raw files, `entity_details`, or a successful SQL
+probe.
+```
+
+- [ ] **Step 3: Fix the `sl_capture` join probe example**
+
+In `packages/context/skills/sl_capture/SKILL.md`, replace Tool sequence item 6
+with:
+
+```md
+6. For join discovery: use `sql_execution({connectionName: "warehouse", sql: "SELECT count(*) FROM public.orders o JOIN public.customers c ON c.id = o.customer_id LIMIT 20"})` with the target warehouse connection name and dialect-correct table names to verify the join key exists in both tables and assess cardinality before declaring the join.
+```
+
+- [ ] **Step 4: Run the prompt asset tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/memory/memory-runtime-assets.test.ts src/ingest/ingest-runtime-assets.test.ts
+```
+
+Expected: PASS. The tests must report 2 files passed.
+
+### Task 4: Final Verification
+
+**Files:**
+- No new files.
+
+- [ ] **Step 1: Run focused warehouse prompt and tool tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/connections/dialects.test.ts src/connections/read-only-sql.test.ts src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts src/ingest/tools/warehouse-verification/entity-details.tool.test.ts src/ingest/tools/warehouse-verification/sql-execution.tool.test.ts src/ingest/tools/warehouse-verification/discover-data.tool.test.ts src/ingest/ingest-prompts.test.ts src/ingest/ingest-runtime-assets.test.ts src/memory/memory-runtime-assets.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run package type-check**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context run type-check
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Inspect final diff**
+
+Run:
+
+```bash
+git diff -- packages/context/src/memory/memory-runtime-assets.test.ts packages/context/src/ingest/ingest-runtime-assets.test.ts packages/context/skills/_shared/identifier-verification.md packages/context/skills/notion_synthesize/SKILL.md packages/context/skills/dbt_ingest/SKILL.md packages/context/skills/lookml_ingest/SKILL.md packages/context/skills/looker_ingest/SKILL.md packages/context/skills/metabase_ingest/SKILL.md packages/context/skills/metricflow_ingest/SKILL.md packages/context/skills/live_database_ingest/SKILL.md packages/context/skills/historic_sql_table_digest/SKILL.md packages/context/skills/historic_sql_patterns/SKILL.md packages/context/skills/knowledge_capture/SKILL.md packages/context/skills/sl_capture/SKILL.md
+```
+
+Expected: only prompt wording and prompt-asset guards changed. No tool
+implementation files changed.
+
+- [ ] **Step 4: Commit**
+
+Run:
+
+```bash
+git add packages/context/src/memory/memory-runtime-assets.test.ts packages/context/src/ingest/ingest-runtime-assets.test.ts packages/context/skills/_shared/identifier-verification.md packages/context/skills/notion_synthesize/SKILL.md packages/context/skills/dbt_ingest/SKILL.md packages/context/skills/lookml_ingest/SKILL.md packages/context/skills/looker_ingest/SKILL.md packages/context/skills/metabase_ingest/SKILL.md packages/context/skills/metricflow_ingest/SKILL.md packages/context/skills/live_database_ingest/SKILL.md packages/context/skills/historic_sql_table_digest/SKILL.md packages/context/skills/historic_sql_patterns/SKILL.md packages/context/skills/knowledge_capture/SKILL.md packages/context/skills/sl_capture/SKILL.md
+git commit -m "fix(context): align warehouse sql probe prompt shape"
+```
+
+Expected: one focused commit.
+
+## Self-Review
+
+Spec coverage:
+
+- The original spec requires `sql_execution` inputs to include
+  `connectionName`; this plan removes contradictory session-only examples from
+  all active writer guidance.
+- The shared protocol remains in `_shared` and inlined in every synthesis
+  writer skill named by the original spec.
+- The tool implementation remains unchanged because the shipped schema already
+  enforces the v1 contract.
+
+Placeholder scan:
+
+- The plan has no deferred implementation markers.
+- Prompt examples use concrete `warehouse`, `analytics`, and `orders` example
+  names only to demonstrate JSON shape, and each example tells the worker to
+  replace them with discovered evidence.
+
+Type consistency:
+
+- Tests assert the exact KTX tool call shape:
+  `sql_execution({connectionName, sql: ...})`.
+- Prompt wording consistently uses `connectionName`, matching
+  `packages/context/src/ingest/tools/warehouse-verification/sql-execution.tool.ts`.
--- a/docs/superpowers/plans/2026-05-13-warehouse-verification-sql-example-closure.md
+++ b/docs/superpowers/plans/2026-05-13-warehouse-verification-sql-example-closure.md
@ -0,0 +1,215 @@
+# Warehouse Verification SQL Example Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Remove the last connectionless `sql_execution` prompt example so
+warehouse-verification writer guidance always matches KTX's shipped tool
+contract.
+
+**Architecture:** Keep the warehouse verification tool code unchanged. Tighten
+the prompt asset guard so multiline `sql_execution({ sql: ... })` examples
+fail tests, then update the stale `sl_capture` worked example to pass
+`connectionName` explicitly.
+
+**Tech Stack:** Markdown skill prompts, TypeScript, Vitest, pnpm workspace
+commands.
+
+---
+
+## Audit summary
+
+The warehouse verification tools, runner wiring, source-adapter target fan-out,
+CLI query executor, and focused tests are present. Focused verification passed:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/connections/dialects.test.ts src/connections/read-only-sql.test.ts src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts src/ingest/tools/warehouse-verification/entity-details.tool.test.ts src/ingest/tools/warehouse-verification/sql-execution.tool.test.ts src/ingest/tools/warehouse-verification/discover-data.tool.test.ts src/ingest/ingest-prompts.test.ts src/ingest/ingest-runtime-assets.test.ts src/memory/memory-runtime-assets.test.ts src/ingest/local-adapters.test.ts src/ingest/adapters/notion/notion.adapter.test.ts src/ingest/adapters/lookml/lookml.adapter.test.ts src/ingest/adapters/metricflow/metricflow.adapter.test.ts
+pnpm --filter @ktx/cli exec vitest run src/ingest-query-executor.test.ts src/ingest.test.ts -t "supplies a scan-connector query executor"
+```
+
+Remaining v1-blocking gap:
+
+- `packages/context/skills/sl_capture/SKILL.md` still contains a worked example
+  with a multiline `sql_execution({ sql: ... })` call. KTX's tool contract is
+  `sql_execution({connectionName, sql, rowLimit?})`, so this example can teach
+  agents to call the shipped tool with invalid input.
+
+Non-blocking gaps remain out of scope for this v1 plan:
+
+- Full DDL-style `entity_details` formatting with FK profile summaries.
+- AST-backed SQL validation for data-modifying CTE bodies.
+- Search over generated `enrichment/descriptions.json`.
+- Per-WorkUnit reuse of a single `WarehouseCatalogService` instance for cache
+  hits across separate tool calls.
+- A deterministic fake-LLM end-to-end Notion hallucination regression.
+- Tokenized or embedding-backed raw schema search ranking in `discover_data`.
+
+## File structure
+
+Modify these files:
+
+- `packages/context/src/memory/memory-runtime-assets.test.ts`: add a prompt
+  guard that catches multiline `sql_execution` calls without `connectionName`.
+- `packages/context/skills/sl_capture/SKILL.md`: update the stale worked
+  example to include the target warehouse `connectionName`.
+
+### Task 1: Add a multiline SQL prompt guard
+
+**Files:**
+- Modify: `packages/context/src/memory/memory-runtime-assets.test.ts`
+
+- [ ] **Step 1: Add a helper that extracts `sql_execution` call examples**
+
+In `packages/context/src/memory/memory-runtime-assets.test.ts`, add this helper
+after `forbiddenProductPattern()`:
+
+```ts
+function sqlExecutionCallBlocks(body: string): string[] {
+  const blocks: string[] = [];
+  const marker = 'sql_execution({';
+  let offset = 0;
+
+  while (offset < body.length) {
+    const start = body.indexOf(marker, offset);
+    if (start === -1) {
+      break;
+    }
+    const end = body.indexOf('})', start + marker.length);
+    blocks.push(body.slice(start, end === -1 ? start + marker.length : end + 2));
+    offset = start + marker.length;
+  }
+
+  return blocks;
+}
+```
+
+- [ ] **Step 2: Strengthen the existing SQL-shape test**
+
+Replace the body of
+`ships only the KTX connectionName sql_execution call shape in writer guidance`
+with:
+
+```ts
+    const shared = await readFile(join(skillsDir, '_shared', 'identifier-verification.md'), 'utf-8');
+    const bodies = [{ name: '_shared/identifier-verification.md', body: shared }];
+
+    expect(shared).toContain('sql_execution({connectionName, sql: "SELECT DISTINCT');
+    expect(shared).toContain('sql_execution({connectionName, sql: "SELECT 1 FROM');
+
+    for (const skillName of verificationWriterSkills) {
+      const body = await readFile(join(skillsDir, skillName, 'SKILL.md'), 'utf-8');
+      bodies.push({ name: `${skillName}/SKILL.md`, body });
+      expect(body).toContain('sql_execution({connectionName');
+      expect(body).not.toContain('sql_execution({ sql');
+      expect(body).not.toContain('session shape');
+      expect(body).not.toContain('connection is already pinned by the ingest session');
+    }
+
+    for (const { name, body } of bodies) {
+      const calls = sqlExecutionCallBlocks(body);
+      expect(calls.length, `${name} should contain sql_execution guidance`).toBeGreaterThan(0);
+      expect(
+        calls.filter((call) => !call.includes('connectionName')),
+        `${name} has sql_execution calls without connectionName`,
+      ).toEqual([]);
+      expect(body, `${name} has a connectionless multiline sql_execution call`).not.toMatch(
+        /sql_execution\(\{\s*sql\s*:/,
+      );
+    }
+```
+
+- [ ] **Step 3: Run the failing prompt guard**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/memory/memory-runtime-assets.test.ts -t "connectionName sql_execution"
+```
+
+Expected: FAIL. The failure must identify
+`sl_capture/SKILL.md` as having a `sql_execution` call without
+`connectionName` or a connectionless multiline `sql_execution` call.
+
+- [ ] **Step 4: Commit the failing guard**
+
+Run:
+
+```bash
+git add packages/context/src/memory/memory-runtime-assets.test.ts
+git commit -m "test(context): catch connectionless sql execution prompt examples"
+```
+
+### Task 2: Fix the stale `sl_capture` SQL example
+
+**Files:**
+- Modify: `packages/context/skills/sl_capture/SKILL.md`
+- Test: `packages/context/src/memory/memory-runtime-assets.test.ts`
+- Test: `packages/context/src/ingest/ingest-runtime-assets.test.ts`
+
+- [ ] **Step 1: Update the worked example**
+
+In `packages/context/skills/sl_capture/SKILL.md`, replace the `sql_execution`
+block in "Worked example - new join" with:
+
+```md
+sql_execution({
+  connectionName: "warehouse",
+  sql: "SELECT COUNT(*), COUNT(DISTINCT a.admin_user_id) FROM public.fct_orders a JOIN public.fct_mau_multiprotocol b ON a.admin_user_id = b.admin_user_id LIMIT 1"
+})
+```
+
+- [ ] **Step 2: Run the prompt guards**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/memory/memory-runtime-assets.test.ts src/ingest/ingest-runtime-assets.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Run a direct stale-shape scan**
+
+Run:
+
+```bash
+rg -n -U "sql_execution\\(\\{\\s*\\n\\s*sql:" packages/context/skills packages/context/prompts
+```
+
+Expected: no matches and exit code 1.
+
+- [ ] **Step 4: Run the context type-check**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context run type-check
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit the prompt fix**
+
+Run:
+
+```bash
+git add packages/context/skills/sl_capture/SKILL.md
+git commit -m "fix(context): include connection name in sl capture sql example"
+```
+
+## Self-review
+
+Spec coverage:
+
+- The only remaining v1-blocking prompt-shape gap has a failing test and a
+  direct prompt edit.
+- Tool implementation, runner wiring, adapter scoping, and CLI execution
+  remain covered by the focused suites listed in the audit summary.
+
+Placeholder scan:
+
+- This plan contains no deferred implementation placeholders.
+
+Type consistency:
+
+- The plan uses the shipped KTX tool shape:
+  `sql_execution({connectionName, sql, rowLimit?})`.
--- a/docs/superpowers/plans/2026-05-13-warehouse-verification-structured-target-miss-closure.md
+++ b/docs/superpowers/plans/2026-05-13-warehouse-verification-structured-target-miss-closure.md
@ -0,0 +1,236 @@
+# Warehouse Verification Structured Target Miss Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `entity_details` return model-visible not-found evidence for every documented target shape, including structured `{catalog, db, name, column?}` targets.
+
+**Architecture:** Keep the existing warehouse verification module. Add focused tests for missing structured table and column targets, then route structured target labels through the same candidate lookup used by display targets while preserving exact structured resolution.
+
+**Tech Stack:** TypeScript, Node 22, Vitest, AI SDK v6 tools, Zod, KTX ingest tools.
+
+---
+
+## Audit Summary
+
+The implemented plans have landed the warehouse verification tools, ingest
+runner wiring, adapter warehouse target fan-out, CLI read-only query executor,
+and prompt-shape closures. Focused verification passed on May 13, 2026:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/connections/dialects.test.ts src/connections/read-only-sql.test.ts src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts src/ingest/tools/warehouse-verification/entity-details.tool.test.ts src/ingest/tools/warehouse-verification/sql-execution.tool.test.ts src/ingest/tools/warehouse-verification/discover-data.tool.test.ts src/ingest/ingest-prompts.test.ts src/ingest/ingest-runtime-assets.test.ts src/memory/memory-runtime-assets.test.ts src/ingest/local-adapters.test.ts src/ingest/adapters/notion/notion.adapter.test.ts src/ingest/adapters/lookml/lookml.adapter.test.ts src/ingest/adapters/metricflow/metricflow.adapter.test.ts
+pnpm --filter @ktx/cli exec vitest run src/ingest-query-executor.test.ts src/ingest.test.ts -t "supplies a scan-connector query executor"
+rg -n -U "sql_execution\\(\\{\\s*\\n\\s*sql:" packages/context/skills packages/context/prompts
+rg -n "wiki_sl_search|sl_describe_table|orbit_analytics\\.customer" packages/context/skills packages/context/prompts packages/context/src/ingest/tools/emit-unmapped-fallback.tool.ts packages/context/src/sl/tools/sl-warehouse-validation.ts
+```
+
+Remaining v1-blocking gap:
+
+- `entity_details` accepts structured targets, but if a structured table target
+  does not exist, it records `structured.missing` and emits no markdown. Tool
+  outputs are sent to the model as markdown only, so the synthesis agent gets
+  an empty response instead of the required "Not found in scan" verification
+  signal.
+
+Non-blocking gaps remain out of scope for this v1 plan:
+
+- Full DDL-style `entity_details` formatting with FK and profile summaries.
+- AST-backed SQL validation for data-modifying CTE bodies.
+- Dialect-specific row-limit wrapping for SQL Server probes.
+- Search over generated `enrichment/descriptions.json`.
+- Per-WorkUnit reuse of a single `WarehouseCatalogService` instance for cache
+  hits across separate tool calls.
+- A deterministic fake-LLM end-to-end Notion hallucination regression.
+- Cleanup of legacy demo Orbit wiki fixtures that still mention
+  `orbit_analytics.customer`.
+
+## File Structure
+
+Modify these files:
+
+- `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts`: add failing coverage for missing structured targets.
+- `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts`: render missing structured targets into markdown and reuse candidate lookup.
+
+### Task 1: Report Structured Target Misses In `entity_details`
+
+**Files:**
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts`
+- Modify: `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts`
+
+- [ ] **Step 1: Add failing structured miss tests**
+
+In `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts`, add these tests after `reports missing explicit columns instead of returning an empty column list`:
+
+```ts
+  it('reports missing structured table targets in model-visible markdown', async () => {
+    const result = await tool.call(
+      {
+        connectionName: 'warehouse',
+        targets: [{ catalog: null, db: 'public', name: 'orderz' }],
+      },
+      context,
+    );
+
+    expect(result.markdown).toContain('Not found in scan: public.orderz');
+    expect(result.markdown).toContain('Closest matches: orders');
+    expect(result.structured.resolved).toHaveLength(0);
+    expect(result.structured.missing).toHaveLength(1);
+  });
+
+  it('reports missing structured column targets in model-visible markdown', async () => {
+    const result = await tool.call(
+      {
+        connectionName: 'warehouse',
+        targets: [{ catalog: null, db: 'public', name: 'orders', column: 'plan_tier' }],
+      },
+      context,
+    );
+
+    expect(result.markdown).toContain('Column not found in scan: public.orders.plan_tier');
+    expect(result.markdown).toContain('Available columns: id, status');
+    expect(result.structured.resolved).toHaveLength(0);
+    expect(result.structured.missing).toHaveLength(1);
+  });
+```
+
+- [ ] **Step 2: Run the failing focused test**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/entity-details.tool.test.ts -t "structured"
+```
+
+Expected: FAIL. The first new test must fail because `result.markdown` does not contain `Not found in scan: public.orderz`.
+
+- [ ] **Step 3: Add structured target labels and candidate lookup**
+
+In `packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts`, add this type alias after `type EntityDetailsInput = z.infer<typeof entityDetailsInputSchema>;`:
+
+```ts
+type EntityDetailsTarget = EntityDetailsInput['targets'][number];
+```
+
+Add these helpers after `function allowedConnectionNames(context: ToolContext): ReadonlySet<string> | null { ... }`:
+
+```ts
+function targetLabel(target: EntityDetailsTarget): string {
+  if ('display' in target) {
+    return target.display;
+  }
+  return [target.catalog, target.db, target.name, target.column].filter((part): part is string => !!part).join('.');
+}
+
+function appendMissingTargetMarkdown(parts: string[], target: EntityDetailsTarget, candidates: KtxTableRef[]): void {
+  parts.push(`Not found in scan: ${targetLabel(target)}`);
+  if (candidates.length > 0) {
+    parts.push(`Closest matches: ${candidates.map((candidate) => candidate.name).join(', ')}`);
+  }
+}
+
+async function resolveTarget(
+  catalog: WarehouseCatalogService,
+  connectionName: string,
+  target: EntityDetailsTarget,
+): Promise<{ resolved: (KtxTableRef & { column?: string }) | null; candidates: KtxTableRef[] }> {
+  if ('display' in target) {
+    return catalog.resolveDisplayTarget(connectionName, target.display);
+  }
+
+  const candidateResolution = await catalog.resolveDisplayTarget(connectionName, targetLabel(target));
+  return {
+    resolved: {
+      catalog: target.catalog,
+      db: target.db,
+      name: target.name,
+      column: target.column,
+    },
+    candidates: candidateResolution.candidates,
+  };
+}
+```
+
+Then replace the `const resolution = ...` block inside the `for (const target of input.targets)` loop with:
+
+```ts
+      const resolution = await resolveTarget(catalog, input.connectionName, target);
+```
+
+Replace the missing-resolution block with:
+
+```ts
+      if (!resolution.resolved) {
+        missing.push({ target, candidates: resolution.candidates });
+        appendMissingTargetMarkdown(parts, target, resolution.candidates);
+        continue;
+      }
+```
+
+Replace the missing-detail block with:
+
+```ts
+      if (!detail) {
+        missing.push({ target, candidates: resolution.candidates });
+        appendMissingTargetMarkdown(parts, target, resolution.candidates);
+        continue;
+      }
+```
+
+- [ ] **Step 4: Run the focused entity-details tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/entity-details.tool.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Run warehouse verification regression tests**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context exec vitest run src/ingest/tools/warehouse-verification/warehouse-catalog.service.test.ts src/ingest/tools/warehouse-verification/entity-details.tool.test.ts src/ingest/tools/warehouse-verification/discover-data.tool.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Run context type-check**
+
+Run:
+
+```bash
+pnpm --filter @ktx/context run type-check
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+Run:
+
+```bash
+git add \
+  packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.ts \
+  packages/context/src/ingest/tools/warehouse-verification/entity-details.tool.test.ts
+git commit -m "fix(context): report structured entity detail misses"
+```
+
+## Self-review
+
+Spec coverage:
+
+- The original `entity_details` contract says structured and display targets
+  are mixed shapes and unresolved targets must produce `Not found in scan` with
+  candidates. This plan adds that model-visible behavior for structured table
+  misses and preserves the existing column-miss behavior.
+
+Placeholder scan:
+
+- This plan contains no deferred implementation placeholders.
+
+Type consistency:
+
+- The plan uses the existing `WarehouseCatalogService`, `KtxTableRef`,
+  `EntityDetailsStructured`, and `ToolOutput` types without adding public API
+  compatibility wrappers.