kushi-agents 4.4.4 → 4.7.4

package/plugin/skills/pull-loop/write-snapshot.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// pull-loop write-snapshot wrapper. Drives runner.mjs, writes canonical layout, upserts
+// m365-mutable.json#knownSections.<project>.loop.workspaces[].loop_pages[], emits run report.
+// Per pull-loop SKILL.md v1.0.0.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const args = Object.fromEntries(
+  process.argv.slice(2).reduce((acc, cur, idx, arr) => {
+    if (cur.startsWith('--')) {
+      const key = cur.replace(/^--/, '');
+      const next = arr[idx + 1];
+      acc.push([key, next && !next.startsWith('--') ? next : true]);
+    }
+    return acc;
+  }, [])
+);
+
+const PROJECT = args.project;
+const WORKSPACE_URL = args['workspace-url'];
+const ENG_ROOT = args['engagement-root'];
+const ALIAS = args.alias;
+const HEADLESS = !!args.headless;
+const TITLES = args.titles || null;
+
+if (!PROJECT || !WORKSPACE_URL || !ENG_ROOT || !ALIAS) {
+  console.error('Usage: --project <name> --workspace-url <url> --engagement-root <path> --alias <alias> [--headless] [--titles "a,b"]');
+  process.exit(2);
+}
+
+const slugify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80) || 'untitled';
+const isoStamp = () => new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+
+const runnerArgs = ['plugin/skills/pull-loop/runner.mjs', '--project', PROJECT, '--workspace-url', WORKSPACE_URL];
+if (HEADLESS) runnerArgs.push('--headless');
+if (TITLES) runnerArgs.push('--titles', TITLES);
+
+const result = spawnSync(process.execPath, runnerArgs, { encoding: 'utf8' });
+let payload;
+try {
+  payload = JSON.parse(result.stdout || '{}');
+} catch {
+  console.error('Runner did not return JSON. stderr:\n' + result.stderr);
+  process.exit(5);
+}
+
+const { pages = [], runStatus = 'workspace-unavailable', authRequiredCount = 0, preflight } = payload;
+
+function workspaceSlugFromUrl(url) {
+  try {
+    const m = String(url).match(/\/loop\/p\/([^/]+)/i);
+    return slugify((m && m[1]) || 'workspace');
+  } catch { return 'workspace'; }
+}
+const wsSlug = workspaceSlugFromUrl(WORKSPACE_URL);
+
+const snapDir = path.join(ENG_ROOT, PROJECT, 'Evidence', ALIAS, 'loop', 'snapshot', wsSlug);
+fs.mkdirSync(snapDir, { recursive: true });
+
+const workspaceMd = [
+  '---',
+  `source: loop`,
+  `project: ${PROJECT}`,
+  `workspace_url: ${WORKSPACE_URL}`,
+  `captured_at: ${new Date().toISOString()}`,
+  `evidence_source_kind: tree-only`,
+  '---',
+  '',
+  `# Loop workspace — ${wsSlug}`,
+  '',
+  `Source URL: ${WORKSPACE_URL}`,
+  `Captured: ${new Date().toISOString()}`,
+  `Pages enumerated: ${pages.length}`,
+  '',
+  '## Pages',
+  '',
+  ...pages.map(p => `- [${p.pageTitle || '(untitled)'}](${p.pageUrl}) — last_status: \`${p.last_status}\``),
+  ''
+].join('\n');
+fs.writeFileSync(path.join(snapDir, '_workspace.md'), workspaceMd, 'utf8');
+
+for (const p of pages) {
+  const pSlug = slugify(p.pageTitle || p.pageUrl);
+  const md = [
+    '---',
+    `source: loop`,
+    `project: ${PROJECT}`,
+    `workspace_url: ${WORKSPACE_URL}`,
+    `page_url: ${p.pageUrl}`,
+    `page_title: ${JSON.stringify(p.pageTitle || '')}`,
+    `captured_at: ${p.capturedAt || new Date().toISOString()}`,
+    `captured_via: ${p.captured_via || 'playwright'}`,
+    `last_status: ${p.last_status}`,
+    `evidence_source_kind: ${p.evidence_source_kind || (p.bodyLen > 0 ? 'page-body' : 'page-body-unavailable')}`,
+    '---',
+    '',
+    `# ${p.pageTitle || '(untitled)'}`,
+    '',
+    `Source: ${p.pageUrl}`,
+    '',
+    p.body || '_(body unavailable — see coverage notes)_',
+    ''
+  ].join('\n');
+  fs.writeFileSync(path.join(snapDir, `${pSlug}.md`), md, 'utf8');
+}
+
+function findMutableJson() {
+  const candidates = [
+    path.resolve('.kushi', 'config', 'user', 'm365-mutable.json'),
+    path.join(process.env.USERPROFILE || process.env.HOME || '', '.copilot', 'm-skills', 'kushi', 'config', 'user', 'm365-mutable.json')
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+const mutPath = findMutableJson();
+if (mutPath) {
+  try {
+    const mut = JSON.parse(fs.readFileSync(mutPath, 'utf8'));
+    mut.knownSections = mut.knownSections || {};
+    mut.knownSections[PROJECT] = mut.knownSections[PROJECT] || {};
+    mut.knownSections[PROJECT].loop = mut.knownSections[PROJECT].loop || { workspaces: [] };
+    let ws = mut.knownSections[PROJECT].loop.workspaces.find(w => w.workspaceUrl === WORKSPACE_URL);
+    if (!ws) {
+      ws = { workspaceUrl: WORKSPACE_URL, loop_pages: [] };
+      mut.knownSections[PROJECT].loop.workspaces.push(ws);
+    }
+    ws.loop_pages = ws.loop_pages || [];
+    for (const p of pages) {
+      let existing = ws.loop_pages.find(x => x.pageUrl === p.pageUrl);
+      if (!existing) {
+        existing = { pageUrl: p.pageUrl };
+        ws.loop_pages.push(existing);
+      }
+      existing.pageTitle = p.pageTitle || existing.pageTitle;
+      existing.last_status = p.last_status;
+      existing.last_captured_at = p.capturedAt;
+      existing.captured_via = p.captured_via;
+    }
+    fs.writeFileSync(mutPath, JSON.stringify(mut, null, 2), 'utf8');
+  } catch (e) {
+    console.error('Upsert m365-mutable.json failed:', e?.message || e);
+  }
+}
+
+const reportDir = path.join(ENG_ROOT, PROJECT, 'Evidence', ALIAS, 'refresh-reports');
+fs.mkdirSync(reportDir, { recursive: true });
+const reportPath = path.join(reportDir, `${isoStamp()}_loop.md`);
+const okCount = pages.filter(p => p.last_status === 'ok').length;
+const report = [
+  `# pull-loop run — ${PROJECT} — ${new Date().toISOString()}`,
+  '',
+  `Workspace: ${WORKSPACE_URL}`,
+  `Run status: \`${runStatus}\``,
+  `Pages: ${pages.length} (ok: ${okCount}; auth-required: ${authRequiredCount})`,
+  preflight ? `Preflight: ${JSON.stringify(preflight)}` : '',
+  '',
+  '## Per-page outcomes',
+  '',
+  '| Title | Status | Source-kind | Bytes |',
+  '|---|---|---|---:|',
+  ...pages.map(p => `| ${(p.pageTitle || '(untitled)').replace(/\|/g, '\\|')} | ${p.last_status} | ${p.evidence_source_kind} | ${p.bodyLen || 0} |`),
+  ''
+].filter(Boolean).join('\n');
+fs.writeFileSync(reportPath, report, 'utf8');
+
+console.log(JSON.stringify({
+  project: PROJECT,
+  workspaceUrl: WORKSPACE_URL,
+  snapshotDir: snapDir,
+  reportPath,
+  runStatus,
+  pagesWritten: pages.length,
+  okCount,
+  authRequiredCount
+}, null, 2));

package/plugin/skills/pull-meetings/SKILL.md

@@ -23,7 +23,7 @@ Pulls **meetings** evidence in three shapes per `snapshot-vs-stream.instructions
 - **stream/** — per-meeting curated blocks: attendees (req/opt/actual), agenda, **chronological transcript walk-through with verbatim quotes + timestamps**, decisions, actions, open questions, artifact links. Each block MUST cite the matching verbatim/ folder.
 - **verbatim/** (REQUIRED, NEW v2.2.0) — per-meeting subfolder `verbatim/<YYYY-MM-DD-HHMM>_<slug>/` containing the raw immutable capture: `captured-at.txt`, `chat-messages.json`, `chat-messages.md`, `transcript.vtt` or `transcript-source.md`, `recording-url.txt`, `recap-card.md`, `attachments/`, `coverage.md`. See `templates/snapshot/meeting-verbatim.template.md` for the contract.
 
-Auth + retry + error logging per `auth-and-retry.instructions.md`. WorkIQ-only per `workiq-only.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`.
+Auth + retry + error logging per `auth-and-retry.instructions.md`. WorkIQ-only per `workiq-only.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `evidence-thoroughness.instructions.md`. Citations per `citation-ledger.instructions.md`.
 
 ## Inputs
 
@@ -159,3 +159,13 @@ After the pass:
 - A meeting has neither transcript NOR chat messages → write `verbatim/<dir>/coverage.md` documenting every failed path + write `❌ source-expired-or-unrecoverable` block in stream/, log error, continue.
 - All paths failed for ALL meetings in the window → mark source `failed`, write a single `❌ all paths failed` evidence file with actionable next step. Verbatim/ folders for each meeting still get created with captured-at.txt + coverage.md (the empty-folder audit trail is itself evidence).
 - A per-meeting block lacks a sibling `verbatim/<YYYY-MM-DD-HHMM>_<slug>/` directory → **defect** per `meetings-verbatim-required.instructions.md`. Re-run Half A immediately; do NOT ship the curated block alone.
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/pull-misc/README.md

@@ -8,7 +8,7 @@ See `SKILL.md` for the full doctrine.
 
 ```pwsh
 # Install deps in the kushi repo
-cd C:\Usha\ISERepos\kushi
+cd <kushi-repo-root>
 npm install playwright jsdom @mozilla/readability
 npx playwright install chromium
 
@@ -21,9 +21,9 @@ node plugin/skills/pull-onenote/runner.mjs --bootstrap
 
 ```pwsh
 node plugin/skills/pull-misc/runner.mjs `
-  --project "ABN AMRO" `
-  --links-file "C:\Users\ushak\OneDrive - Microsoft\ISE\Engagement Assets\ABN AMRO\external-links.txt" `
-  --engagement-root "C:\Users\ushak\OneDrive - Microsoft\ISE\Engagement Assets" `
+  --project "<project>" `
+  --links-file "<engagement-root>/<project>/external-links.txt" `
+  --engagement-root "<engagement-root>" `
   --headless
 ```
 

package/plugin/skills/pull-misc/SKILL.md

@@ -12,7 +12,7 @@ description: "Pull miscellaneous evidence from a user-curated link list (<projec
 > - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/misc.md`.
 > - `cleanup-on-resolution.instructions.md` — when a placeholder URL resolves, all stale unavailable-markers are upgraded in the same turn.
 > - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/`.
-> - `thoroughness-detector.instructions.md` — the per-link retry registry IS this skill's thoroughness contract.
+> - `evidence-thoroughness.instructions.md` — the per-link retry registry IS this skill's thoroughness contract.
 
 > **Canonical evidence layout** (HARD, kushi v3.12.1+): all artifacts produced by this skill MUST be written under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` — sibling folders under `<project>/` (e.g. `<project>/<source>-context/`, `<project>/<source>/`, `<project>/_Weekly Summaries/`) are FORBIDDEN. See `evidence-layout-canonical.instructions.md`.
 
@@ -48,7 +48,7 @@ Format:
 | `onenote` | pull-onenote | delegated |
 | `sharepoint` | pull-sharepoint | delegated |
 | `ado` | pull-ado | delegated |
-| `loop` **(new)** | pull-misc | browser (Playwright, OneNote profile) |
+| `loop` | pull-loop | delegated (v4.6.0+ — was inline-browser in v3.9.0–v4.5.x) |
 | `web` | pull-misc | http (fetch + readability) |
 | `confluence` | pull-misc | http (anonymous) — auth'd Confluence not yet supported |
 | `learn` | pull-misc | http |
@@ -105,15 +105,11 @@ For each project, the bootstrap step:
 
 The runner branches per `type`:
 
-### B.1 `loop` — browser
+### B.1 `loop` — delegate (v4.6.0+)
 
-```js
-// pages.goto(loopUrl); detect login redirect → auth-required.
-// Wait for primary canvas selector; for Loop, that's the Fluid container.
-// Read text via document.body.innerText after settle.
-```
+Skip fetch. Write registry entry with `captured_via: delegated`, `delegated_to: pull-loop`. The actual workspace/page capture happens in `pull-loop` (see `plugin/skills/pull-loop/SKILL.md`), which uses the canonical Loop boundary in `<project>/integrations.yml#boundaries.loop.workspace_ids[]` rather than free-text `external-links.txt` URLs.
 
-If login redirect detected: `last_status: auth-required`, `captured_via: browser`, exit early for this link.
+If the Loop URL pasted into `external-links.txt` references a workspace NOT registered in `boundaries.loop.workspace_ids[]`, `pull-misc` records `last_status: unregistered-loop-workspace` and notes the URL in `<project>/OPEN-QUESTIONS-DRAFT.md` so the user can decide whether to register it via `@Kushi setup --reconfigure`.
 
 ### B.2 `web` / `confluence` / `learn` / `docs` / `github` / unknown — HTTP
 
@@ -134,9 +130,9 @@ If login redirect detected: `last_status: auth-required`, `captured_via: browser
 // Read text; if binary, mark last_status: skipped-binary (use a different pipeline if needed).
 ```
 
-### B.4 `onenote` / `sharepoint` / `ado` — delegate
+### B.4 `onenote` / `sharepoint` / `ado` / `loop` — delegate
 
-Skip fetch. Write registry entry with `captured_via: delegated`, `delegated_to: pull-onenote|pull-sharepoint|pull-ado`. Per-skill captures already happen in their own pipelines.
+Skip fetch. Write registry entry with `captured_via: delegated`, `delegated_to: pull-onenote|pull-sharepoint|pull-ado|pull-loop`. Per-skill captures already happen in their own pipelines.
 
 ## Per-link retry registry
 
@@ -151,7 +147,7 @@ Stored at `m365-mutable.json#knownSections.<projectKey>.misc_links[]`. Schema:
   "notes":            "<as in external-links.txt>",
   "last_status":      "captured | placeholder | auth-required | fetch-failed | skipped-binary | removed | not-yet-attempted | delegated",
   "captured_via":     "browser | http | file | delegated",
-  "delegated_to":     "pull-onenote | pull-sharepoint | pull-ado",   // only when captured_via=delegated
+  "delegated_to":     "pull-onenote | pull-sharepoint | pull-ado | pull-loop",   // only when captured_via=delegated
   "http_status":      200,                                            // only for HTTP
   "content_type":     "text/html",                                    // only for HTTP
   "char_count":       12345,
@@ -255,3 +251,13 @@ Citations from misc evidence MUST follow:
 ```
 
 Example: `[source: misc/loop/ABN-Core-Team-Sync-2026-03-27 · 2026-05-14]`
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/pull-onenote/SKILL.md

@@ -1,18 +1,21 @@
 ---
 name: "pull-onenote"
-version: "2.5.1"
-description: "Pull OneNote evidence (snapshot: full page bodies; stream: page-edit events). Browser-scrape (OneNote-for-Web via Playwright with persisted profile) is the PRIMARY capture path because it is the only mechanism that returns reliable, complete, verbatim page bodies in this tenant. WorkIQ remains the fallback when the browser auth profile expires (Conditional Access / MFA). Per-page retry registry persists both ID forms (browser webPageId + WorkIQ wdpartid) and tracks last_status across runs."
+version: "2.7.0"
+description: "Pull OneNote evidence (snapshot: full page bodies; stream: page-edit events). WorkIQ natural-language queries by display name are the PRIMARY capture path (per workiq-onenote-query-shape.instructions.md). Playwright browser-scrape is OPT-IN, RECOVERY-ONLY fallback — never invoked unless the user has set m365Auth.oneNote.playwrightFallback: true AND the per-page retry registry shows persistent BODY-NOT-EXPOSED across multiple refreshes. Per-page retry registry persists both ID forms (browser webPageId + WorkIQ wdpartid) when both are observed; wdpartid alone is sufficient for WorkIQ-only operation."
 ---
 
 # Skill: pull-onenote
 
-> **v3.8.0 contracts** — This skill operates under six HARD-rule doctrines:
+> **v2.7.0 contract change (kushi v4.7.3, 2026-05-26):** Playwright is **demoted from PRIMARY to opt-in recovery-only fallback**. WorkIQ natural-language queries by display name are now the primary path. See `..\..\instructions\workiq-onenote-query-shape.instructions.md` for the working query shapes and the empirical record. The v3.8.0 pivot to Playwright-primary was driven by HCA body-retrieval rate (1/18 on 2026-05-14) — but per-page retry registries + multi-refresh accumulation close that gap without forcing every contributor onto Edge + Conditional Access + bootstrap-profile complexity.
+
+> **v2.7.0 contracts** — This skill operates under seven HARD-rule doctrines:
+> - `workiq-onenote-query-shape.instructions.md` — **PRIMARY**. The only working WorkIQ phrasings for OneNote.
 > - `verbatim-by-default.instructions.md` — full bodies by default; no preview-grade pulls accepted.
-> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (section IDs, dual page-id schema).
+> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (section IDs, dual page-id schema when both observed).
 > - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md`.
 > - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale unavailable-markers are upgraded in the same turn.
 > - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/`.
-> - `thoroughness-detector.instructions.md` — runtime detector + auto-retry + paste-prompt for any page where the primary path returns nothing or partial. The per-page retry registry IS this skill's thoroughness contract.
+> - `evidence-thoroughness.instructions.md` — runtime detector + auto-retry + paste-prompt for any page where the primary path returns nothing or partial. The per-page retry registry IS this skill's thoroughness contract.
 
 > **Canonical evidence layout** (HARD, kushi v3.12.1+): all artifacts produced by this skill MUST be written under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` — sibling folders under `<project>/` (e.g. `<project>/<source>-context/`, `<project>/<source>/`, `<project>/_Weekly Summaries/`) are FORBIDDEN. See `evidence-layout-canonical.instructions.md`.
 
@@ -23,18 +26,56 @@ Pulls **onenote** evidence in two shapes per `snapshot-vs-stream.instructions.md
 
 ## Tools (in order)
 
-1. **Playwright (browser-scrape, persisted profile)** — PRIMARY. Drives OneNote-for-Web to enumerate pages and read verbatim bodies via `#PageContentWrapper`. Profile lives at `~/.kushi/playwright-profile/onenote/` and is reused across runs. Implementation: `plugin/skills/pull-onenote/runner.mjs`.
-2. **WorkIQ** — FALLBACK only. Used when the Playwright profile is auth-expired (`auth-required`) and for the stream/edit-event source. Always cite `m365-id-registry` doctrine when invoking; never use as primary for body retrieval (proven non-deterministic).
-3. **Host (m365_*)** — not used (Graph `Notes.Read.All` denied admin consent in this tenant).
+1. **WorkIQ (natural-language by display name)** — **PRIMARY**. Use the approved query shapes from `workiq-onenote-query-shape.instructions.md`: one section per query, display names only, no enumeration verbs, no filter-syntax, no ID-lookup questions. Drives both section/page discovery and body retrieval. Pages that return `BODY-NOT-EXPOSED` are logged into `one_pages[].last_status` for retry on the next refresh — this multi-refresh accumulation is the thoroughness mechanism.
+2. **Playwright (browser-scrape, persisted profile)** — **OPT-IN RECOVERY-ONLY FALLBACK**. Only invoked when ALL of: (a) `m365Auth.oneNote.playwrightFallback: true`, (b) `one_pages[]` shows ≥ N pages with `last_status: BODY-NOT-EXPOSED` for ≥ 2 consecutive refreshes (N default 5, configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`), (c) WorkIQ has been attempted in the current run. Profile lives at `~/.kushi/playwright-profile/onenote/`. Implementation: `plugin/skills/pull-onenote/runner.mjs`. See "Playwright fallback (optional)" section below.
+3. **Host (m365_*)** — not used (Graph `Notes.Read.All` denied admin consent in this tenant; also forbidden by kushi's WorkIQ-first doctrine).
 
-## Canonical CLI invocations (do NOT re-derive — copy these exactly)
+## Canonical CLI invocations
 
-These are the empirically validated invocations as of kushi v3.11.3. The runner has surprising defaults (visible browser by default, 60s timeout, preflight required) that can derail a run. Use these recipes; do not improvise flags.
+### Primary path: WorkIQ natural-language (kushi v4.7.3+, default for all installs)
 
-### Bootstrap (one-time per machine; ~3-5 days between runs as cookies expire)
+Per `..\..\instructions\workiq-onenote-query-shape.instructions.md`. Resolves section IDs and pulls page bodies via display-name queries:
 
 ```pwsh
-cd C:\Usha\ISERepos\kushi
+# Per-section discovery + page enumeration (also extracts wdpartid + wdsectionfileid from URL fragments):
+workiq ask -q "In the OneNote notebook '<NOTEBOOK DISPLAY NAME>', show me the pages in the section named '<SECTION DISPLAY NAME>'. Return a flat table with: page title, last modified, web URL. No commentary. Do not truncate."
+
+# Per-page body pull (one page at a time — narrow scope is mandatory):
+workiq ask -q "Open the OneNote page titled '<PAGE TITLE>' in section '<SECTION>' of notebook '<NOTEBOOK>'. Return the verbatim page body, no summary, no truncation."
+
+# Edit-event stream:
+workiq ask -q "Show me OneNote page edits in section '<SECTION>' of notebook '<NOTEBOOK>' since <ISO-DATE>. For each edit: page title, edited by, edited at, brief change summary."
+```
+
+Driver behavior:
+1. Run discovery query → parse `wdsectionfileid`, `wdpartid`, `sourcedoc` GUIDs out of the URL fragments in the response.
+2. Persist into `m365-mutable.json#knownSections.<projectKey>` per `m365-id-registry.instructions.md`. `webPageId` is left empty — it is only populated if/when Playwright fallback runs.
+3. For each enumerated page, run the body-pull query. Write snapshot files to the canonical layout. Populate `one_pages[].last_status`: `captured` on verbatim body return, `BODY-NOT-EXPOSED` on empty/partial, `workiq-degraded` on classified WorkIQ failure (per `fallback-status-reporting.instructions.md`).
+4. Pages with `BODY-NOT-EXPOSED` are surfaced in the run report and queued for retry on the next refresh. The per-page retry registry is the thoroughness mechanism — over multiple refreshes, transient non-determinism is absorbed.
+
+### Playwright fallback (OPT-IN, RECOVERY-ONLY — kushi v4.7.3+)
+
+**Do NOT bootstrap a Playwright profile on a fresh install.** This path exists only as a recovery valve for contributors whose WorkIQ body-retrieval rate stays poor across multiple refreshes. Enable explicitly:
+
+```jsonc
+// In <kushi-config-root>/user/m365-auth.json:
+"oneNote": {
+  "enabled": true,
+  "defaultNotebookName": "...",
+  "playwrightFallback": true            // OPT-IN — default false
+}
+```
+
+Once opted in, the driver auto-escalates to Playwright when `one_pages[]` shows ≥ N pages with `last_status: BODY-NOT-EXPOSED` for ≥ 2 consecutive refreshes (N default 5; configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`). Until both thresholds are met, the driver MUST continue using WorkIQ. Never auto-bootstrap a profile — that is always a user-initiated action.
+
+The Playwright invocations below remain valid (cookie surfaces, channel requirements, preflight three-way classification are all empirically unchanged) — they are simply the **fallback** path now, not the default.
+
+These are the empirically validated invocations as of kushi v3.11.3 (still in force for the fallback path). The runner has surprising defaults (visible browser by default, 60s timeout, preflight required) that can derail a run. Use these recipes; do not improvise flags.
+
+### Bootstrap the Playwright profile (FALLBACK PATH ONLY — opt-in required)
+
+```pwsh
+cd <kushi-repo-root>
 node plugin/skills/pull-onenote/runner.mjs --bootstrap
 ```
 
@@ -60,13 +101,13 @@ The bare `runner.mjs` emits JSON to stdout only. The driver (PowerShell or agent
 **HARD rule (kushi v3.11.5+):** drivers MUST call `write-snapshot.mjs`, which invokes the runner internally (child_process, no shell pipe), writes the snapshot in the canonical layout, upserts `m365Mutable.knownSections.<project>.one_pages[]`, and emits a run report. Never hand-write snapshot files from runner JSON.
 
 ```pwsh
-cd C:\Usha\ISERepos\kushi
+cd <kushi-repo-root>
 $url = '<exact-section-url-from-m365-mutable.json#one_sectionWebUrl>'
 node plugin/skills/pull-onenote/write-snapshot.mjs `
   --section-url $url `
   --project "<project>" `
   --engagement-root "<engagement-root>" `
-  --alias ushak
+  --alias <your-alias>
 ```
 
 Output structure (per `snapshot-vs-stream.instructions.md`):
@@ -130,13 +171,14 @@ await ctx.close();
 
 Run: `node plugin/skills/pull-onenote/diag.mjs "<section-url>"`. If you see `, Page. Selected.` but not `, page N of M, Page.` → single-page section, runner must be v3.11.3+.
 
-## Empirical contract (what is true, validated 2026-05-13/14)
+## Empirical contract (what is true, validated 2026-05-13/14 + reframed 2026-05-26)
 
-These three facts are HARD-rule and supersede any earlier doctrine in this skill or in older learnings:
+These facts are HARD-rule and supersede any earlier doctrine in this skill or in older learnings:
 
-1. **Browser-scrape via OneNote-for-Web is the only reliable verbatim-body path.** Tested against HCA on 2026-05-14: 16 of 16 pages captured (~120KB), vs WorkIQ's 1 of 18 (~7KB) on the same section minutes earlier. Browser-scrape uses the same SharePoint-resident OneNote canvas the user sees, so what it returns IS the page.
-2. **WorkIQ is non-deterministic for OneNote bodies and shall not be the primary path.** Same page returned a verbatim body and `BODY-NOT-EXPOSED` 6 minutes apart with no edits. WorkIQ is retained ONLY as the auth-degraded fallback (when the browser profile cannot complete sign-in) and as the source of stream/edit-event data.
-3. **The OneNote-for-Web `pageid` and the WorkIQ `wdpartid` are different identifiers.** Both must be persisted per page (`webPageId` for browser navigation; `wdpartid` for WorkIQ correlation and stream events). Neither alone is sufficient.
+1. **WorkIQ natural-language by display name IS the primary, working path for OneNote.** Reframed v4.7.3 (2026-05-26) — see `..\..\instructions\workiq-onenote-query-shape.instructions.md`. The only WorkIQ phrasings that work are: (a) narrow, single-section-by-display-name discovery queries; (b) single-page-by-title body pulls; (c) section-scoped edit-event stream queries. Forbidden: enumeration verbs, structured-field filter syntax, ID-lookup questions, broad "list my notebooks" probes. Those all empirically fail (WorkIQ punts to Graph Explorer or routes to summary mode).
+2. **WorkIQ body retrieval is non-deterministic, BUT per-page retry registries close the gap over multiple refreshes.** The v3.8.0 pivot to Playwright was driven by HCA's 1-of-18 body-retrieval rate on 2026-05-14. That rate is the snapshot of one refresh — the retry registry (`one_pages[].last_status`) is the durable mechanism that accumulates captures across refreshes. A page that returns `BODY-NOT-EXPOSED` today is retried tomorrow; over 3-5 refreshes the cumulative capture rate converges. This is acceptable for engagement evidence (which is time-windowed, not real-time). Playwright remains as the opt-in recovery valve for contributors who need faster convergence and have accepted the Edge + Conditional Access + bootstrap complexity.
+3. **The OneNote-for-Web `pageid` and the WorkIQ `wdpartid` are different identifiers.** Both should be persisted per page when both are observed (`webPageId` for browser navigation; `wdpartid` for WorkIQ correlation and stream events). For WorkIQ-only operation, `wdpartid` alone is sufficient — `webPageId` is only populated if/when Playwright fallback runs.
+4. **Browser-scrape via OneNote-for-Web returns higher-fidelity verbatim bodies when it works** — tested against HCA on 2026-05-14: 16 of 16 pages captured (~120KB) in one run. This is why Playwright remains as the opt-in fallback. It is NOT the default because: (a) it requires Edge + Conditional Access compliance — not all contributors have that; (b) it requires a per-machine bootstrap that expires every 3-5 days; (c) most engagements do not need real-time full-fidelity capture — multi-refresh WorkIQ converges adequately.
 
 ## Pre-flight
 
@@ -429,3 +471,13 @@ Every refresh writes `Evidence/<alias>/refresh-reports/<YYYY-MM-DD>-<HHMM>-oneno
 - Any short-suspect entries needing user verification
 
 
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/pull-sharepoint/SKILL.md

@@ -21,7 +21,7 @@ Pulls **sharepoint** evidence in two shapes per `snapshot-vs-stream.instructions
 - **snapshot/** — tree.md (full folder tree) + files/<path>.md (key files with full extracted content)
 - **stream/** — file change events (created/modified/renamed/deleted) with author + size + brief content summary
 
-Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
+Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `evidence-thoroughness.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
 
 ## Inputs
 
@@ -114,4 +114,13 @@ Every snapshot file body starts with an **AI Narrative Summary (REQUIRED FIRST,
 
 - Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
 - Multiple plausible candidates → ask user to pick, persist answer.
-- WorkIQ fails (after doubled-strict retry) AND user declines to paste → write evidence file with `❌ workiq-empty-after-retry` marker, log to run-log errors with `next_step: re-run after WorkIQ recovery or paste verbatim`, continue with rest of run. Do NOT fall through to Graph / `m365_*` — FORBIDDEN per workiq-only.
+- WorkIQ fails (after doubled-strict retry) AND user declines to paste → write evidence file with `❌ workiq-empty-after-retry` marker, log to run-log errors with `next_step: re-run after WorkIQ recovery or paste verbatim`, continue with rest of run. Do NOT fall through to Graph / `m365_*` — FORBIDDEN per workiq-only.
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/pull-teams/SKILL.md

@@ -21,7 +21,7 @@ Pulls **teams** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 - **snapshot/** — chat roster + member list per chat the user is part of for this project
 - **stream/** — messages with full message-by-message reproduction — sender, timestamp, verbatim text, reactions, attachments, replies — grouped by thread
 
-Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
+Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `evidence-thoroughness.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
 
 ## Inputs
 
@@ -101,4 +101,13 @@ After successful pass:
 
 - Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
 - Multiple plausible candidates → ask user to pick, persist answer.
-- WorkIQ fails (after doubled-strict retry) AND user declines to paste → write evidence file with `❌ workiq-empty-after-retry` marker, log to run-log errors with `next_step: re-run after WorkIQ recovery or paste verbatim`, continue with rest of run. Do NOT fall through to Graph / `m365_*` — FORBIDDEN per workiq-only.
+- WorkIQ fails (after doubled-strict retry) AND user declines to paste → write evidence file with `❌ workiq-empty-after-retry` marker, log to run-log errors with `next_step: re-run after WorkIQ recovery or paste verbatim`, continue with rest of run. Do NOT fall through to Graph / `m365_*` — FORBIDDEN per workiq-only.
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/refresh-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "refresh-project"
-version: "2.3.1"
+version: "2.3.2"
 description: "Incremental refresh for an already-bootstrapped project. Reads run-log watermarks, pulls only what is new since last run per source, splits stream output by ISO week, replaces snapshots in place. Verbatim-by-default per `verbatim-by-default.instructions.md` — every enabled source MUST be dispatched, no silent skips. Writes per-user refresh report per `run-reports.instructions.md`. Cleans stale no-match notes on resolution per `cleanup-on-resolution.instructions.md`. Builds State/ only on `full` profile."
 ---
 
@@ -43,6 +43,7 @@ Profile is read from `kushi-install.json#profile` next to the agent file. Defaul
 
 ### Step 1 — Resolve project + read run-log
 
+- **Sync-pending gate (v4.5.0):** before resolving, check `<workspace>/.kushi/config/user/project-evidence.yml#projects_root_status`. If `syncing` or `manual-sync-pending`, refuse: *"Engagement root sync still pending. Run `@Kushi setup --resume-sync` once OneDrive finishes."* Exit cleanly.
 - Fuzzy-match `<project>` per `engagement-root-resolution.instructions.md`.
 - Read `<engagement-root>/<project>/Evidence/run-log.yml`.
 - For each source, compute effective window:
@@ -86,10 +87,11 @@ Per-source pull skills (canonical order — refresh-project dispatches in this o
 2. `pull-teams`
 3. `pull-meetings`
 4. `pull-onenote`
-5. `pull-sharepoint`
-6. `pull-crm` (if enabled)
-7. `pull-ado` (if enabled)
-8. `pull-misc` (if `<project>/external-links.txt` exists)
+5. `pull-loop` (if enabled — boundary `boundaries.loop.workspace_ids[]` populated)
+6. `pull-sharepoint`
+7. `pull-crm` (if enabled)
+8. `pull-ado` (if enabled)
+9. `pull-misc` (if `<project>/external-links.txt` exists)
 
 Each `pull-*` skill is responsible for:
 - Snapshot pass (always re-fetch known entities).
@@ -97,6 +99,25 @@ Each `pull-*` skill is responsible for:
 - Updating `sources.<src>.watermark`, `sources.<src>.last_pulled`, `sources.<src>.item_count` in run-log.
 - Updating `weekly_files` index in run-log.
 
+**Verification gate after each per-source dispatch (v4.4.8+, HARD):** Per `..\..\instructions\per-source-verification-gate.instructions.md`, immediately after each `pull-*` returns:
+
+```
+gate = run_verification_gate(source, result)
+if gate.status == "fail":
+    retry = dispatch(source, --window <same>, --retry)
+    gate2 = run_verification_gate(source, retry)
+    if gate2.status == "fail":
+        append_to_followups(<project>/FOLLOW-UPS.md, gate2)   # 5-field shape (D19)
+        append_to_runlog(<project>/Evidence/run-log.yml,
+                         source, status: "failed-gate",
+                         gate_failures: gate2.failures,
+                         process_audit: gate2.process_audit_failures)
+        append_to_tracking(gate2.process_audit_failures)
+        # do NOT abort the whole refresh — continue to next source
+```
+
+Refresh is **never** aborted by a single source's gate failure. The gate's job is to surface — not to block.
+
 **pull-misc dispatch:** invoke as `node plugin/skills/pull-misc/runner.mjs --project <name> --links-file <engagement-root>/<project>/external-links.txt --engagement-root <engagement-root> --headless`. Parse the JSON output, write per-link snapshot files to `Evidence/<alias>/misc/snapshot/<safe-type>__<safe-title>.md`, and merge the `links[]` records into `m365-mutable.json#knownSections.<projectKey>.misc_links[]` (preserving prior `attempts`, bumping `last_attempt_at`).
 
 ### Step 3 — Consolidate (if multi-user)
@@ -112,9 +133,10 @@ If `standard` (or `core`) → **skip this step**. Note in the run summary: *"Sta
 ### Step 5 — Run summary
 
 Display:
-- Per-source table: items pulled, weeks affected, errors.
+- Per-source table: items pulled, weeks affected, errors, **gate status** (pass / retried-pass / failed-followups-written).
 - Side-by-side mutable hints written this run (per `side-by-side-config.instructions.md`).
 - New Open Questions opened/resolved/staled.
+- **Open follow-ups delta** — count of entries newly written to `<project>/FOLLOW-UPS.md` this run + count of entries auto-moved from Open → Resolved by `cleanup-on-resolution.instructions.md`.
 
 ## Watermark semantics
 
@@ -137,4 +159,13 @@ Re-running refresh with the same window is safe:
 - "update `<X>`"
 - "pull `<X>` since `<date>`"
 - "refresh `<X>` last `<N>` days"
-- "backfill `<X>` from `<from>` to `<to>`"
+- "backfill `<X>` from `<from>` to `<to>`"
+## References (v4.4.7)
+
+- Name → ID resolution (any source) follows `..\..\instructions\fuzzy-disambiguation.instructions.md`.
+- After each per-source pull, run the gate per `..\..\instructions\per-source-verification-gate.instructions.md` (retry once → FOLLOW-UPS.md on failure).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/self-check/SKILL.md

@@ -46,7 +46,20 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D4 | Live install sync | if `~/.copilot/m-skills/kushi/` exists, its `SKILL.md` is byte-identical to `plugin/agents/kushi.agent.md` |
 | D5 | skills-metadata.json sync | if `~/.copilot/m-skills/skills-metadata.json` lists `kushi`, its description matches the live `SKILL.md` frontmatter |
 | D6 | Side-by-side rule cited | every SKILL.md that touches user config references `side-by-side-config.instructions.md` |
-| D7 | Live install manifest | if `~/.copilot/m-skills/kushi/kushi-install.json` exists, its skill list matches the resolved profile chain from `plugin.json` (no missing, no extras) |
+| D15 | Legacy path regression | no `.project-evidence/{m365,crm,ado}` references outside CHANGELOG / learnings (v4.4.0+ moved per-user config to `<workspace>/.kushi/config/{user,shared}/`) |
+| D16 | Cross-platform parity | every contributor-facing install/setup surface (setup/SKILL.md, install-workiq.md, check-workiq.mjs) addresses BOTH Windows (`winget` + `win32` branch) and macOS (`brew` + `darwin` branch). Also: self-check ships both `run.ps1` and `run.sh`. |
+| D17 | Fuzzy disambiguation cited | every name→ID resolver (pull-onenote / pull-sharepoint / pull-teams / pull-crm / pull-ado / pull-email / ask-project / engagement-root-resolution) cites `fuzzy-disambiguation.instructions.md`. |
+| D18 | Verification gate cited | every pull-* skill + bootstrap-project + refresh-project + aggregate-project cites `per-source-verification-gate.instructions.md`. |
+| D19 | FOLLOW-UPS format | when `<project>/FOLLOW-UPS.md` exists, every `## Open follow-ups` entry has the 5 required fields (Gate failures / Next-time-do / Tracking / Run-log entry / Status). |
+| D20 | README verbs coverage | every `plugin/prompts/<verb>.prompt.md` has a row in README's `## Verbs` table, and every row maps to a real prompt (or known alias). |
+| D21 | Cross-platform .ps1 scripts | every `.ps1` in the repo runs on pwsh 7 cross-platform — Windows-only APIs (`Get-WmiObject`, `Win32_*`, COM, `HKLM:`) are gated with `if ($IsWindows)`. |
+| D22 | Duplicate / overlap detection | flag pairs of `plugin/instructions/*.instructions.md` whose `description:` frontmatter has ≥ 60% word overlap — these are candidates for merge or scope-clarification. |
+| D23 | Instructions map parity | every `plugin/instructions/*.instructions.md` is listed in `docs/reference/instructions-map.md`; every row in the map maps to a real file. |
+| D24 | OneDrive pin policy applicable | when `projects_root` is INSIDE a OneDrive-managed path AND OneDrive is running, warn if own-alias `Evidence/<my-alias>/` exists but appears cloud-only (Windows: `attrib` shows `+U`; macOS: `xattr` lacks `com.microsoft.OneDrive.PinnedToDevice`). Surface as "may slow writes; re-run @Kushi setup --reconfigure to re-pin". Cited from `onedrive-pin-policy.instructions.md`. |
+| D25 | Documentation coverage | every `plugin/instructions/*.instructions.md` is mentioned in EITHER `docs/reference/instructions-map.md` (mandatory via D23) AND at least one of: `CHANGELOG.md`, a `docs/concepts/*.md` doc, a `docs/reference/*.md` doc, or a `docs/how-to/*.md` doc. Catches new doctrines that landed without any user-facing prose. |
+| D26 | Issue Recovery cite | every skill in the recovery-required set (`pull-*`, `aggregate-project`, `consolidate-evidence`, `bootstrap-project`, `refresh-project`, `apply-ado-update`, `propose-ado-update`) cites `issue-recovery.instructions.md` in its References section. Ensures the Issue Recovery Rule applies whenever an external service exposes a doctrine gap. |
+| D27 | Personal-path leakage | no contributor-specific path / email / repo-local-path patterns (`OneDrive - Microsoft\ISE\Engagement Assets`, `C:\Users\<contributor>`, `<contributor>@microsoft.com`, etc.) appear in `plugin/`, `docs/getting-started/`, or `README.md`. Examples must use placeholders. Exemptions: `CHANGELOG.md`, `plugin/learnings/`, `plugin/reference-packs/`. |
+| D28 | Predecessor-agent leakage | no current-doc file in `plugin/` or `docs/` references the historical predecessor agent by name. Use neutral language ('predecessor agent' / 'another internal agent'). Exemptions: `CHANGELOG.md` (historical commit notes), `plugin/learnings/`, `plugin/reference-packs/`, `docs/reference/instructions-map.md`. |
 
 ## Execution flow (agent path)