kushi-agents 4.8.0 → 4.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -42,6 +42,7 @@
   "license": "MIT",
   "scripts": {
     "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs",
+    "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm test && npm run smoke"
   },

package/plugin/instructions/customer-hint-discovery.instructions.md

@@ -87,6 +87,7 @@ For each source whose sweep runs:
 | 0 candidates | no | `unresolved` (annotated `discovery-empty`) | `user-action` | yes — "Discovery sweep for `<source>` returned 0 hits for `<hint>`; widen hint or seed `boundaries.<source>.<key>` manually" |
 | 1–10 candidates | yes (all) | `completed-with-coverage-gaps` (because rows are `needs_review`) | `watch` | only if any row low-confidence |
 | > 10 candidates | yes (top 10 by recency) | `completed-with-coverage-gaps` | `watch` | yes — "Discovery sweep returned >10 candidates; review the deferred list" |
+| **WorkIQ punted — no surface for this source** (sharepoint sites, teams channels — v4.8.1 empirical) | no | `unresolved` (annotated `discovery-empty-no-workiq-surface`) | `user-action` | yes — cite that this source has no known WorkIQ discovery surface and direct the user to manual configuration (the per-source doctrine has the exact wording) |
 | Sweep query failed (WorkIQ error / classified per `fallback-status-reporting.instructions.md`) | no | `deferred` (write marker per `deferred-retry-on-workiq-fail.instructions.md`) | `retry` | no — next refresh will drain |
 | Prerequisite genuinely missing (e.g. CRM shared config empty) | no | `blocked-config` | `user-action` | yes — cite specific missing field |
 

package/plugin/instructions/meetings-bootstrap-discovery.instructions.md

@@ -11,7 +11,7 @@ Governed by `customer-hint-discovery.instructions.md` — read that file first f
 
 | Boundary key | Element shape | Example |
 |---|---|---|
-| `boundaries.meetings.series_join_urls[]` | string — Teams meeting join URL | `"https://teams.microsoft.com/l/meetup-join/19%3a..."` |
+| `boundaries.meetings.series_join_urls[]` | string — Teams meeting URL. Two accepted shapes (v4.8.1+): (1) `meetup-join` URL `https://teams.microsoft.com/l/meetup-join/...` if returned, (2) `meeting/details?eventId=` URL `https://teams.microsoft.com/l/meeting/details?eventId=...` — empirically the form WorkIQ returns. Pull-meetings accepts both via the eventId resolver. | `"https://teams.microsoft.com/l/meeting/details?eventId=AAMkAD..."` |
 
 Optional `organizer_emails[]` is NOT populated by the sweep (user narrowing only).
 
@@ -20,9 +20,11 @@ Optional `organizer_emails[]` is NOT populated by the sweep (user narrowing only
 Issued ONCE per bootstrap, per project:
 
 ```
-workiq ask -q "In my Outlook calendar, find the recurring meeting series and one-off meetings whose subject mentions '<HINT>' and that have at least one occurrence in the last <N> days OR the next 30 days. Return a flat table with: subject, organizer name, organizer email, recurrence pattern (single | daily | weekly | other), Teams meeting join URL, most recent occurrence date. Do not summarize. Do not truncate. Flat table only."
+workiq ask -q "In my Outlook calendar, find the recurring meeting series and one-off meetings whose subject mentions '<HINT>' and that have at least one occurrence in the last <N> days OR the next 30 days. Return a flat table with: subject, organizer name, organizer email, recurrence pattern (single | daily | weekly | other), Teams meeting join URL or meeting details URL, most recent occurrence date. Do not summarize. Do not truncate. Flat table only."
 ```
 
+**v4.8.1 empirical finding:** WorkIQ rarely returns the `meetup-join` URL form — it returns `meeting/details?eventId=...` URLs instead (the calendar-event-ID-anchored details URL). Both forms uniquely identify the meeting/series; pull-meetings v2.x+ accepts either and resolves the join URL on demand.
+
 Substitution rules:
 
 - `<HINT>` = verbatim customer hint.
@@ -44,8 +46,11 @@ This phrasing — **natural-language by subject + organizer + join URL request**
 
 ## Parsing the response
 
-1. Extract `Teams meeting join URL` column — keep only rows whose URL matches `^https?://teams\.microsoft\.com/l/meetup-join/`.
-2. **Collapse recurring series:** for rows with `recurrence pattern != single`, the join URL of any occurrence is the canonical series URL (Outlook reuses one URL per series). Deduplicate by URL.
+1. Extract any URL column. Accept rows whose URL matches EITHER pattern (v4.8.1):
+   - `^https?://teams\.microsoft\.com/l/meetup-join/` — preferred form.
+   - `^https?://teams\.microsoft\.com/l/meeting/details\?eventId=` — empirical form WorkIQ returns. Persist as-is; pull-meetings resolves the join URL via eventId lookup.
+   If the row says `"Not available in source"` or similar AND no URL is present in any other cell of the row, log the row to OPEN-QUESTIONS-DRAFT.md under `## Meetings discovered without join URLs` (subject + organizer + recurrence) so the user can supply the URL manually. Do NOT persist a placeholder.
+2. **Collapse recurring series:** for rows with `recurrence pattern != single`, the URL of any occurrence is the canonical series URL (Outlook reuses one URL per series). Deduplicate by URL.
 3. Deduplicate against existing `boundaries.meetings.series_join_urls[]`.
 4. Cap at top 10 by `most recent occurrence date` (descending).
 5. Confidence ranking:

package/plugin/instructions/sharepoint-bootstrap-discovery.instructions.md

@@ -7,6 +7,16 @@ description: "SharePoint site URL resolution — title/URL-substring WorkIQ phra
 
 Governed by `customer-hint-discovery.instructions.md` — read that file first for the orchestration contract.
 
+## Empirical finding (kushi v4.8.1) — WorkIQ has no SharePoint site-inventory surface
+
+Validated against the live WorkIQ surface on 2026-05-26 with hint `HCA`: WorkIQ returns a hard punt — *"the sources do not contain site inventory or SharePoint site properties; I cannot construct the requested table without fabricating data (which I will not do per policy)."* This is consistent — tenant-wide SharePoint site enumeration requires Graph admin endpoints that WorkIQ does not expose.
+
+**Therefore:**
+
+- The sweep below is retained as a **best-effort** opt-in. It MUST be attempted (so the doctrine self-validates if WorkIQ ever gains a site-inventory surface) but bootstrap MUST NOT block on it and MUST NOT write `last_status: blocked-config` when it returns 0 or a punt response.
+- **The reliable path is `local_folders[]` — user-supplied OneDrive sync paths.** The companion Open Question (below) is the PRIMARY UX for SharePoint bootstrap.
+- When the sweep returns a punt response (recognizable by classifier-keywords `cannot construct`, `fabricating data`, `no site inventory`, `routing to Graph`), classify as `discovery-empty-no-workiq-surface` (NOT `blocked-config`).
+
 ## What this sweep populates — and what it does NOT
 
 | Boundary key | Populated by sweep? | Why |
@@ -43,11 +53,14 @@ This phrasing — **natural-language by site title/URL** — is empirically the
 
 ## Parsing the response
 
-1. Extract `full site URL` column — keep rows whose URL matches `^https?://[^/]+\.sharepoint\.com/sites/`.
-2. Normalize: strip query strings and trailing slashes.
-3. Deduplicate against existing `boundaries.sharepoint.site_urls[]`.
-4. Cap at top 10 by `most recent activity date` (descending). If activity date is missing, fall back to alphabetical site title.
-5. Confidence ranking:
+WorkIQ commonly punts on this query (see Empirical finding above). Apply this classifier BEFORE attempting to parse a table:
+
+1. **Punt detection** — if the response body contains any of: `cannot construct`, `fabricating data`, `no site inventory`, `routing to Graph`, `Graph admin endpoint`, `SharePoint Admin`, OR the body has no markdown table at all → classify as `discovery-empty-no-workiq-surface`, write `last_status: unresolved` (NOT `blocked-config`), proceed to the companion Open Question. Do NOT attempt further parsing.
+2. If a table IS present, extract `full site URL` column — keep rows whose URL matches `^https?://[^/]+\.sharepoint\.com/sites/`.
+3. Normalize: strip query strings and trailing slashes.
+4. Deduplicate against existing `boundaries.sharepoint.site_urls[]`.
+5. Cap at top 10 by `most recent activity date` (descending). If activity date is missing, fall back to alphabetical site title.
+6. Confidence ranking:
    - `high` — site title contains the hint (case-insensitive substring).
    - `medium` — site URL slug contains the hint (e.g. `/sites/HCA-Engagement` for hint `HCA`).
    - `low` — match was on site description only.

package/plugin/instructions/teams-bootstrap-discovery.instructions.md

@@ -14,17 +14,24 @@ Governed by `customer-hint-discovery.instructions.md` — read that file first f
 | `boundaries.teams.chat_ids[]` | string — Teams chat ID (Graph thread-id format) | `"19:abc...@thread.v2"` |
 | `boundaries.teams.channel_ids[]` | string — `<teamId>:<channelId>` composite | `"abc-team-guid:19:def@thread.tacv2"` |
 
-## Approved WorkIQ queries (the ONLY shapes that return this data)
+## Empirical findings (kushi v4.8.1 — what WorkIQ actually returns)
+
+Validated against the live WorkIQ surface on 2026-05-26 with hint `HCA`:
+
+- **Query 1 (chats) — works**, but WorkIQ returns `chat ID = N/A` (the column is present but empty). The chat ID MUST be extracted from the per-row message permalink URL — see "Parsing the response" below.
+- **Query 2 (channels) — DOES NOT WORK.** WorkIQ has no Teams channel-enumeration surface. Every empirical attempt either returned empty or reclassified channel hits as chats with `N/A` IDs. The query is retained below as a `best-effort` opt-in only — bootstrap MUST NOT block on it and MUST NOT write `last_status: blocked-config` when it returns 0. Manual user-supplied `channel_ids[]` is the only reliable path.
+
+## Approved WorkIQ queries (the ONLY shapes that may return this data)
 
 Two narrow queries — issued in sequence (chats first, then channels). Each issued ONCE per bootstrap, per project.
 
-### Query 1 — Chats
+### Query 1 — Chats (REQUIRED, primary path)
 
 ```
 workiq ask -q "In my Microsoft Teams 1:1 and group chats, find chats where the topic or any member's name or email mentions '<HINT>' and that had at least one message in the last <N> days. Return a flat table with: chat topic, chat ID, all member display names, all member emails, most recent message date. Do not summarize. Do not truncate. Flat table only."
 ```
 
-### Query 2 — Channels
+### Query 2 — Channels (BEST-EFFORT only; v4.8.1 empirical: returns nothing usable)
 
 ```
 workiq ask -q "In the Microsoft Teams I have joined, find channels whose channel display name or parent team display name mentions '<HINT>'. Return a flat table with: team name, team ID, channel name, channel ID, channel type. Do not summarize. Do not truncate. Flat table only."
@@ -54,23 +61,29 @@ For each query, WorkIQ returns a markdown table.
 
 ### Chat parsing (Query 1)
 
-1. Extract `chat ID` column — keep only rows with non-empty IDs matching the `^19:.+@thread\.(v2|skype|tacv2)$` pattern.
-2. Deduplicate against existing `boundaries.teams.chat_ids[]`.
-3. Cap at top 10 by `most recent message date` (descending).
-4. Confidence ranking:
+WorkIQ returns the `chat ID` column populated as `N/A` (empirical, v4.8.1). The canonical chat ID lives in the per-row message permalink URL. Extract it as follows:
+
+1. For each row, scan all hyperlink URLs in the `Most Recent Message Date` (and any other) cell. The shape is:
+   `https://teams.microsoft.com/l/message/<chatId>/<messageId>?context=...`
+   where `<chatId>` matches `^19:[^/]+@thread\.(v2|skype|tacv2|spaces)$`.
+2. Extract the first matching `<chatId>`. URL-decode any `%3a` → `:` and `%40` → `@`.
+3. If the URL form is `19:48ed1b82-...-..._...@unq.gbl.spaces/...` (1:1 chat), that IS the chat id — keep as-is.
+4. Deduplicate against existing `boundaries.teams.chat_ids[]`.
+5. Cap at top 10 by `most recent message date` (descending).
+6. Confidence ranking:
    - `high` — `chat topic` explicitly contains the hint (case-insensitive substring).
    - `medium` — any member's email domain matches a known customer domain (heuristic: hint appears as substring in domain), e.g. hint `HCA` + member `@hcahealthcare.com`.
    - `low` — match was on a member's display name only.
 
+**If no message permalink URL is found in a row**, that row CANNOT be persisted to `boundaries.teams.chat_ids[]` — log it to OPEN-QUESTIONS-DRAFT.md under `## Teams chats discovered without IDs` with the topic + members so the user can supply the chat id manually.
+
 ### Channel parsing (Query 2)
 
-1. Build composite `<teamId>:<channelId>` for each row.
-2. Deduplicate against existing `boundaries.teams.channel_ids[]`.
-3. Cap at top 10 by — channels rarely exceed 10; if they do, prefer channels whose `team name` contains the hint over channels whose `channel name` contains the hint.
-4. Confidence ranking:
-   - `high` — team name contains the hint.
-   - `medium` — channel name contains the hint (e.g. `General` channel inside a hint-matched team).
-   - `low` — neither, but inference was made via member list (rare).
+**v4.8.1 empirical finding:** WorkIQ does not surface true Teams channel data. Every attempted query either returned empty or reclassified channel hits as 1:1/group chats with `N/A` IDs. Treat any output from Query 2 as informational:
+
+1. If the response is empty or every row has `team ID = N/A` AND `channel ID = N/A`: write `last_status: unresolved` with annotation `discovery-empty-no-workiq-surface` (NOT `blocked-config`). Open Question: *"Teams channel-id discovery has no working WorkIQ surface as of kushi v4.8.1. If this engagement uses Teams channels (not chats), populate `boundaries.teams.channel_ids[]` manually with the `<teamId>:<channelId>` composite — found in the channel URL under Teams ⟶ ⋯ ⟶ Get link to channel."*
+2. If a row HAS both `team ID` and `channel ID` populated (rare — happens only when WorkIQ has cached channel metadata from a recent direct probe): build composite `<teamId>:<channelId>`, dedupe, cap at 10.
+3. The cross-reference with Query 1 chats is informational only — do NOT auto-convert a chat-id into a channel-id.
 
 ## Sidecar file shape
 

package/src/bootstrap-dryrun.integration.test.mjs

@@ -0,0 +1,235 @@
+// Integration test: validate that each per-source discovery doctrine's approved WorkIQ query
+// actually returns usable data against the live WorkIQ surface. OPT-IN — not run by `npm test`.
+//
+// Run with: KUSHI_DRYRUN_HINT=HCA node src/bootstrap-dryrun.integration.test.mjs
+//   or:     npm run test:integration:bootstrap
+//
+// This is the gate that would have caught the v4.8.0 shipping defects (teams-channels punt,
+// sharepoint sites punt, meetings join URL not surfaced, teams chat IDs returned as N/A).
+
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '..');
+const HINT = process.env.KUSHI_DRYRUN_HINT || 'HCA';
+const WORKIQ = process.env.KUSHI_WORKIQ_BIN || 'C:\\Users\\ushak\\.copilot\\bin\\workiq.cmd';
+const LOOKBACK = Number(process.env.KUSHI_DRYRUN_LOOKBACK || 90);
+
+// Source -> { doctrine file, approved-query extraction rule, classifier }
+const SOURCES = [
+  {
+    id: 'email',
+    doctrine: 'email-bootstrap-discovery.instructions.md',
+    // Doctrine has ONE ```\nworkiq ask -q "..."\n``` block — the approved query.
+    expects: 'table with folder path column populated',
+    classify(stdout) {
+      if (/cannot construct|fabricating data|no .* inventory|routing to Graph/i.test(stdout)) return 'punt';
+      const lines = stdout.split(/\r?\n/).filter(l => /^\|/.test(l));
+      if (lines.length < 3) return 'empty';
+      // Header + separator + ≥1 data row. Look for folder path column (non-empty).
+      const dataRows = lines.slice(2);
+      const folderRows = dataRows.filter(l => {
+        const cols = l.split('|').map(c => c.trim()).filter(c => c.length > 0);
+        return cols[0] && cols[0] !== 'N/A' && !/^-+$/.test(cols[0]);
+      });
+      return folderRows.length > 0 ? `ok (${folderRows.length} folders)` : 'empty';
+    },
+  },
+  {
+    id: 'teams-chats',
+    doctrine: 'teams-bootstrap-discovery.instructions.md',
+    queryIndex: 0, // first ```workiq ask block
+    expects: 'table with chat topic + extractable chat ID from message URL',
+    classify(stdout) {
+      if (/cannot construct|fabricating data|no .* inventory/i.test(stdout)) return 'punt';
+      const lines = stdout.split(/\r?\n/).filter(l => /^\|/.test(l));
+      if (lines.length < 3) return 'empty';
+      // Need chat topic non-empty AND at least one row with extractable chat ID from a URL
+      const dataRows = lines.slice(2);
+      const withTopic = dataRows.filter(l => {
+        const cols = l.split('|').map(c => c.trim());
+        return cols[1] && cols[1] !== 'N/A';
+      });
+      const extractableIds = stdout.match(/19:[^/)\s"']+@thread\.(v2|skype|tacv2|spaces)/g) || [];
+      if (withTopic.length === 0) return 'empty';
+      return `ok (${withTopic.length} chats, ${extractableIds.length} extractable thread IDs in response)`;
+    },
+  },
+  {
+    id: 'teams-channels',
+    doctrine: 'teams-bootstrap-discovery.instructions.md',
+    queryIndex: 1, // second ```workiq ask block
+    expects: 'KNOWN-EMPTY (v4.8.1 empirical: WorkIQ has no Teams channel-enumeration surface)',
+    classify(stdout) {
+      if (/cannot construct|fabricating data|no .* inventory|Graph-backed|not a channel/i.test(stdout)) return 'punt (as expected — no WorkIQ surface)';
+      const lines = stdout.split(/\r?\n/).filter(l => /^\|/.test(l));
+      if (lines.length < 3) return 'empty (as expected)';
+      const dataRows = lines.slice(2);
+      const withChannelId = dataRows.filter(l => {
+        const cols = l.split('|').map(c => c.trim());
+        // team ID col index 2, channel ID col index 4 in the doctrine table
+        return cols[2] && cols[2] !== 'N/A' && cols[4] && cols[4] !== 'N/A';
+      });
+      return withChannelId.length > 0
+        ? `unexpected-ok (${withChannelId.length} channels with IDs — UPDATE doctrine!)`
+        : 'punt (as expected — no WorkIQ surface)';
+    },
+    expectedClassification: /^punt|^empty/,
+  },
+  {
+    id: 'meetings',
+    doctrine: 'meetings-bootstrap-discovery.instructions.md',
+    expects: 'table with subject + meeting URL (meetup-join OR meeting/details?eventId)',
+    classify(stdout) {
+      if (/cannot construct|fabricating data|no .* inventory/i.test(stdout)) return 'punt';
+      const lines = stdout.split(/\r?\n/).filter(l => /^\|/.test(l));
+      if (lines.length < 3) return 'empty';
+      const dataRows = lines.slice(2);
+      const withSubject = dataRows.filter(l => {
+        const cols = l.split('|').map(c => c.trim());
+        return cols[1] && cols[1] !== 'N/A';
+      });
+      const withJoinUrl = dataRows.filter(l => /teams\.microsoft\.com\/l\/(meetup-join|meeting\/details)/i.test(l));
+      if (withSubject.length === 0) return 'empty';
+      return `ok (${withSubject.length} meetings, ${withJoinUrl.length} with extractable URLs)`;
+    },
+  },
+  {
+    id: 'sharepoint',
+    doctrine: 'sharepoint-bootstrap-discovery.instructions.md',
+    expects: 'KNOWN-EMPTY (v4.8.1 empirical: WorkIQ has no SharePoint site-inventory surface)',
+    classify(stdout) {
+      if (/cannot construct|fabricating data|no .* inventory|routing to Graph|SharePoint Admin/i.test(stdout)) return 'punt (as expected — no WorkIQ surface)';
+      const lines = stdout.split(/\r?\n/).filter(l => /^\|/.test(l));
+      if (lines.length < 3) return 'empty (as expected)';
+      const dataRows = lines.slice(2);
+      const withUrl = dataRows.filter(l => {
+        const cols = l.split('|').map(c => c.trim());
+        // cols[2] is Full Site URL column. Must be a real /sites/ or /teams/ collection URL,
+        // not a personal mysite (-my.sharepoint.com) or a citation in another column.
+        const url = cols[2] || '';
+        return /^https:\/\/[^/]*sharepoint\.com\/(sites|teams)\//i.test(url);
+      });
+      return withUrl.length > 0
+        ? `unexpected-ok (${withUrl.length} sites — UPDATE doctrine!)`
+        : 'punt (as expected — no usable WorkIQ surface)';
+    },
+    expectedClassification: /^punt|^empty/,
+  },
+];
+
+function extractApprovedQuery(doctrineFile, queryIndex = 0) {
+  const text = readFileSync(join(repoRoot, 'plugin', 'instructions', doctrineFile), 'utf8');
+  // Find every ``` fenced block containing `workiq ask -q "..."`. Capture the quoted query.
+  const re = /```[^\n]*\n([\s\S]*?)\n```/g;
+  const queries = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const block = m[1];
+    const qMatch = block.match(/workiq\s+ask\s+-q\s+"([\s\S]+?)"/);
+    if (qMatch) queries.push(qMatch[1]);
+  }
+  if (queries.length <= queryIndex) {
+    throw new Error(`Doctrine ${doctrineFile} does not contain query #${queryIndex} (found ${queries.length})`);
+  }
+  return queries[queryIndex];
+}
+
+function substituteHint(query, hint, lookback) {
+  return query
+    .replace(/'<HINT>'/g, `'${hint}'`)
+    .replace(/<HINT>/g, hint)
+    .replace(/<N>/g, String(lookback));
+}
+
+function runWorkIQ(query) {
+  const t0 = Date.now();
+  // cmd.exe quote-handling: spawn without shell, use .cmd directly via shell escape, OR
+  // pass the full command as a single argv[0] with shell:true. Easier: spawn workiq directly
+  // (cmd shim works with shell:false on Windows when the path ends in .cmd via the runtime).
+  // We pre-escape the query to survive cmd's parser: wrap in "...", escape internal " as "".
+  const escaped = `"${query.replace(/"/g, '""')}"`;
+  const res = spawnSync(WORKIQ, ['ask', '-q', escaped], {
+    encoding: 'utf8',
+    maxBuffer: 50 * 1024 * 1024,
+    shell: true,
+    timeout: 240_000,
+    windowsVerbatimArguments: true,
+  });
+  // Strip ANSI color codes — WorkIQ emits them and they break ^| line classifiers.
+  const ansi = /\x1b\[[0-9;]*m/g;
+  const raw = (res.stdout || '') + (res.stderr || '');
+  return {
+    stdout: raw.replace(ansi, ''),
+    exitCode: res.status,
+    elapsedMs: Date.now() - t0,
+  };
+}
+
+function main() {
+  if (!existsSync(WORKIQ)) {
+    console.error(`✗ workiq binary not found at ${WORKIQ}. Set KUSHI_WORKIQ_BIN or install workiq.`);
+    process.exit(2);
+  }
+
+  console.log(`# kushi bootstrap-dryrun integration test`);
+  console.log(`hint=${HINT}  lookback=${LOOKBACK}d  workiq=${WORKIQ}`);
+  console.log(``);
+
+  const outDir = join(repoRoot, '.dryrun-output');
+  mkdirSync(outDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+
+  const results = [];
+  let failures = 0;
+
+  for (const src of SOURCES) {
+    process.stdout.write(`▶ ${src.id.padEnd(16)} `);
+    let query;
+    try {
+      query = substituteHint(extractApprovedQuery(src.doctrine, src.queryIndex || 0), HINT, LOOKBACK);
+    } catch (e) {
+      console.log(`extract-failed: ${e.message}`);
+      failures++;
+      results.push({ source: src.id, status: `extract-failed: ${e.message}`, elapsedMs: 0 });
+      continue;
+    }
+    let { stdout, exitCode, elapsedMs } = runWorkIQ(query);
+    // Retry once on transient WorkIQ HTTP/2 / protocol / 5xx errors.
+    const transient = /HttpProtocolError|HTTP\/2 server reset|INTERNAL_ERROR|503|502|504|ECONNRESET|ETIMEDOUT/i;
+    if (transient.test(stdout)) {
+      process.stdout.write('(transient, retry) ');
+      const retry = runWorkIQ(query);
+      stdout = retry.stdout;
+      exitCode = retry.exitCode;
+      elapsedMs += retry.elapsedMs;
+    }
+    const classification = src.classify(stdout);
+    const expectedRe = src.expectedClassification || /^ok/;
+    const pass = expectedRe.test(classification);
+    console.log(`${pass ? '✓' : '✗'} ${classification}  (${elapsedMs}ms, exit=${exitCode})`);
+    if (!pass) {
+      failures++;
+      console.log(`     expects: ${src.expects}`);
+      console.log(`     query  : ${query.slice(0, 120)}...`);
+    }
+    results.push({ source: src.id, classification, expects: src.expects, pass, elapsedMs, exitCode });
+    // Save raw response for debugging
+    writeFileSync(join(outDir, `${ts}_${src.id}.txt`), `# query\n${query}\n\n# response\n${stdout}\n`, 'utf8');
+  }
+
+  console.log('');
+  console.log(`Outputs saved to: ${outDir}`);
+  console.log(`Result: ${results.length - failures}/${results.length} passed.`);
+
+  if (failures > 0) {
+    console.log('');
+    console.log('FAILED — review .dryrun-output/ files. If WorkIQ surface changed, update the doctrine and re-run.');
+    process.exit(1);
+  }
+}
+
+main();