kushi-agents 3.4.2 → 3.13.0

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

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// pull-onenote/write-snapshot.mjs — kushi v3.11.5
+//
+// Translates runner.mjs JSON output into the canonical snapshot layout per
+// snapshot-vs-stream.instructions.md and pull-onenote/SKILL.md §"Snapshot file shape":
+//
+//   <engagement-root>/<project>/Evidence/<alias>/onenote/
+//      snapshot/pages/<safe-title>.md      — one file per page (HARD rule)
+//      refresh-reports/<YYYY-MM-DD>-<HHMM>-onenote.md
+//
+// Also upserts the per-page retry registry into m365-mutable.json#knownSections.<project>.one_pages[].
+//
+// Stream events (page-edit events) are NOT written here — those come from WorkIQ on the next
+// stream pass. This wrapper only handles snapshot + registry + run report.
+//
+// Usage (preferred — runs the runner internally, avoids shell pipe UTF-8 corruption):
+//   node plugin/skills/pull-onenote/write-snapshot.mjs \
+//     --section-url "<url>" \
+//     --project "<project>" \
+//     --engagement-root "<engagement-root>" \
+//     --alias "<alias>" \
+//     [--mutable <path>] [--timeout 120000]
+//
+// Usage (legacy — read pre-captured runner JSON):
+//   node plugin/skills/pull-onenote/write-snapshot.mjs \
+//     --json <path-to-runner-output.json> \
+//     --project "<project>" \
+//     --engagement-root "<engagement-root>" \
+//     --alias "<alias>" \
+//     [--mutable <path-to-m365-mutable.json>]
+//
+// Idempotency: snapshot/pages/*.md is replace-in-place (HARD per snapshot-vs-stream doctrine).
+// Registry merge: preserves prior attempts count, advances last_status if newer is captured.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_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 JSON_PATH = args.json;
+const SECTION_URL = args['section-url'];
+const TIMEOUT_MS = args.timeout || '120000';
+const PROJECT = args.project;
+const ROOT = args['engagement-root'];
+const ALIAS = args.alias || 'ushak';
+const MUTABLE_PATH = args.mutable || path.join(ROOT || '.', '.project-evidence', 'm365', 'm365-mutable.json');
+
+if ((!JSON_PATH && !SECTION_URL) || !PROJECT || !ROOT) {
+  console.error('Usage: (--json <runner-output> | --section-url <url>) --project <name> --engagement-root <root> [--alias ushak] [--mutable <path>] [--timeout 120000]');
+  process.exit(2);
+}
+
+// --- helpers ---
+function safeTitle(title) {
+  return title
+    .replace(/[\\/:*?"<>|]/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 120);
+}
+
+function nowUtc() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function isoWeekMonday(d = new Date()) {
+  const x = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  const day = x.getUTCDay() || 7;
+  x.setUTCDate(x.getUTCDate() - day + 1);
+  return x.toISOString().slice(0, 10);
+}
+
+function mkdirp(p) { fs.mkdirSync(p, { recursive: true }); }
+
+function readJson(p) {
+  const raw = fs.readFileSync(p, 'utf8');
+  // strip non-JSON header lines (e.g. "Docs: ...") emitted by some wrappers
+  const i = raw.indexOf('{');
+  return JSON.parse(raw.slice(i));
+}
+
+function writeJson(p, obj) {
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+}
+
+function renderPageMd(p, ctx) {
+  const fm = {
+    page_title: p.title,
+    section: ctx.sectionName,
+    notebook: ctx.notebookName,
+    section_id: ctx.sectionFileId,
+    wdpartid: p.wdpartid || null,
+    webPageId: p.webPageId || null,
+    last_modified: p.lastModified || null,
+    last_status: p.last_status,
+    captured_via: p.captured_via || 'browser',
+    attempts: p.attempts || 1,
+    last_attempt: p.capturedAt || nowUtc(),
+    captured_at: p.capturedAt || nowUtc()
+  };
+  const fmYaml = Object.entries(fm)
+    .map(([k, v]) => `${k.padEnd(13)}: ${v === null ? 'null' : JSON.stringify(v)}`)
+    .join('\n');
+
+  let body;
+  if (p.last_status === 'captured' || p.last_status === 'user-pasted') {
+    body = [
+      '## AI Narrative Summary',
+      '',
+      '_(Generated by build-state on next aggregation; verbatim body below is authoritative.)_',
+      '',
+      '## Body (verbatim)',
+      '',
+      '```',
+      p.body || '',
+      '```',
+      '',
+      `[source: ${PROJECT}/onenote/${ctx.sectionName}/${p.title} · ${(p.lastModified || p.capturedAt || '').slice(0, 10) || 'unknown'}]`
+    ].join('\n');
+  } else if (p.last_status === 'enumeration-only') {
+    body = `## ⏳ Enumeration-only\n\nPage discovered but body not yet captured. Will be attempted on next refresh.`;
+  } else {
+    body = [
+      `## ⛔ Unavailable — ${p.last_status}`,
+      '',
+      `Last attempt: ${p.capturedAt || nowUtc()}`,
+      '',
+      '### next_step',
+      '',
+      p.last_status === 'auth-required'
+        ? '1. Re-bootstrap the Playwright profile: `node plugin/skills/pull-onenote/runner.mjs --bootstrap`\n2. Re-run refresh.'
+        : p.last_status === 'notebook-unavailable'
+          ? '1. Open the notebook in OneNote desktop, force sync.\n2. Verify the section opens at onenote.cloud.microsoft.\n3. Re-run refresh.'
+          : '1. Re-run refresh on next cycle.'
+    ].join('\n');
+  }
+
+  return `---\n${fmYaml}\n---\n\n# ${p.title}\n\n${body}\n`;
+}
+
+// --- main ---
+let runOut;
+if (SECTION_URL) {
+  // Invoke runner.mjs directly via child_process to keep UTF-8 intact
+  // (PowerShell's Out-File default mangles non-ASCII chars like NBSP).
+  const runnerPath = path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\//, '')), 'runner.mjs');
+  const r = spawnSync(process.execPath, [
+    runnerPath,
+    '--project', PROJECT,
+    '--section-url', SECTION_URL,
+    '--skip-preflight',
+    '--headless',
+    '--timeout', String(TIMEOUT_MS)
+  ], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) {
+    console.error('[write-snapshot] runner failed:', r.stderr);
+    process.exit(r.status || 1);
+  }
+  const i = r.stdout.indexOf('{');
+  runOut = JSON.parse(r.stdout.slice(i));
+} else {
+  runOut = readJson(JSON_PATH);
+}
+const pages = runOut.pages || [];
+const sectionUrl = runOut.sectionUrl || SECTION_URL || '';
+
+// Resolve section/notebook context from m365-mutable.json#knownSections.<project>
+const mutable = fs.existsSync(MUTABLE_PATH) ? JSON.parse(fs.readFileSync(MUTABLE_PATH, 'utf8')) : { m365Mutable: { knownSections: {} } };
+const ks = mutable.m365Mutable?.knownSections?.[PROJECT] || {};
+const ctx = {
+  sectionName: ks.one_sectionName || 'unknown.one',
+  notebookName: ks.one_notebookName || 'unknown',
+  sectionFileId: ks.one_sectionFileId || null
+};
+
+// Paths
+const evDir = path.join(ROOT, PROJECT, 'Evidence', ALIAS, 'onenote');
+const pagesDir = path.join(evDir, 'snapshot', 'pages');
+const reportsDir = path.join(evDir, 'refresh-reports');
+mkdirp(pagesDir);
+mkdirp(reportsDir);
+
+// Write page snapshots
+const written = [];
+for (const p of pages) {
+  const fname = `${safeTitle(p.title)}.md`;
+  const fpath = path.join(pagesDir, fname);
+  const md = renderPageMd(p, ctx);
+  fs.writeFileSync(fpath, md, 'utf8');
+  written.push({ title: p.title, file: path.relative(ROOT, fpath), status: p.last_status, bytes: md.length });
+}
+
+// Upsert registry m365Mutable.knownSections.<project>.one_pages[]
+const priorPages = Array.isArray(ks.one_pages) ? ks.one_pages : [];
+const byKey = new Map(priorPages.map(x => [x.webPageId || x.wdpartid || x.title, x]));
+for (const p of pages) {
+  const key = p.webPageId || p.wdpartid || p.title;
+  const prior = byKey.get(key) || {};
+  byKey.set(key, {
+    title: p.title,
+    wdpartid: p.wdpartid || prior.wdpartid || null,
+    webPageId: p.webPageId || prior.webPageId || null,
+    lastModified: p.lastModified || prior.lastModified || null,
+    last_status: p.last_status,
+    captured_via: p.captured_via || 'browser',
+    attempts: (prior.attempts || 0) + 1,
+    last_attempt_at: p.capturedAt || nowUtc(),
+    snapshot_path: `${PROJECT}/Evidence/${ALIAS}/onenote/snapshot/pages/${safeTitle(p.title)}.md`,
+    captured_at: p.last_status === 'captured' ? (p.capturedAt || nowUtc()) : (prior.captured_at || null)
+  });
+}
+mutable.m365Mutable.knownSections[PROJECT] = {
+  ...ks,
+  one_pages: Array.from(byKey.values()),
+  one_lastPullAt: nowUtc(),
+  one_lastPullRunStatus: runOut.runStatus,
+  one_lastPullKushiVersion: '3.11.5'
+};
+writeJson(MUTABLE_PATH, mutable);
+
+// Run report
+const nowStamp = nowUtc().replace(/[-:]/g, '').replace('T', '-').slice(0, 13);
+const reportPath = path.join(reportsDir, `${nowStamp}-onenote.md`);
+const counts = pages.reduce((acc, p) => { acc[p.last_status] = (acc[p.last_status] || 0) + 1; return acc; }, {});
+const report = [
+  `# pull-onenote run report — ${PROJECT}`,
+  '',
+  `- **timestamp**: ${nowUtc()}`,
+  `- **alias**: ${ALIAS}`,
+  `- **section**: ${ctx.sectionName} (notebook: ${ctx.notebookName})`,
+  `- **section URL**: ${sectionUrl}`,
+  `- **runStatus**: ${runOut.runStatus}`,
+  `- **kushi runner**: v3.11.4+`,
+  '',
+  '## Per-status counts',
+  '',
+  ...Object.entries(counts).map(([s, n]) => `- ${s}: ${n}`),
+  '',
+  '## Pages written',
+  '',
+  ...written.map(w => `- \`${w.file}\` — ${w.status} (${w.bytes} bytes)`),
+  '',
+  '## Registry',
+  '',
+  `Upserted ${pages.length} entries in \`m365Mutable.knownSections."${PROJECT}".one_pages[]\`.`,
+  ''
+].join('\n');
+fs.writeFileSync(reportPath, report, 'utf8');
+
+console.log(JSON.stringify({
+  project: PROJECT,
+  alias: ALIAS,
+  pages_written: written.length,
+  pages_dir: path.relative(ROOT, pagesDir),
+  registry_path: MUTABLE_PATH,
+  registry_entries: pages.length,
+  report_path: path.relative(ROOT, reportPath),
+  counts
+}, null, 2));

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

@@ -1,17 +1,27 @@
 ---
 name: "pull-sharepoint"
-version: "2.0.0"
-description: "Pull SharePoint evidence (snapshot: folder tree + key file bodies; stream: file change events). WorkIQ-first; also walks local synced folder for metadata without auth."
+version: "2.2.1"
+description: "Pull SharePoint evidence (snapshot: folder tree + key file bodies; stream: file change events). Local synced folder walk for metadata (always allowed — no auth, no API). WorkIQ-ONLY for content/text extraction per workiq-only.instructions.md. `m365_search_files` / `m365_download_file` / Graph REST FORBIDDEN."
 ---
 
 # Skill: pull-sharepoint
 
+
+> **v3.7.6 + v3.11.0 contracts** — This skill operates under five HARD-rule doctrines:
+> - `verbatim-by-default.instructions.md` — full bodies/notetext/fields by default; no preview-grade pulls accepted.
+> - **`workiq-only.instructions.md` (v3.11.0)** — text-content extraction from SharePoint files goes through WorkIQ ONLY. `m365_search_files`, `m365_download_file`, `m365_list_files`, and Graph REST `https://graph.microsoft.com/v1.0/me/drive/*` are FORBIDDEN as content-extraction fallbacks. Local-synced folder walk for metadata (filename, mtime, size) is ALWAYS allowed because it's a filesystem read, not an M365 API call. The canonical WorkIQ prompt for SharePoint file content is codified in that instruction — do not re-discover.
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md` immediately.
+> - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale `no-match` / `not yet` notes referencing the prior unresolved state must be rewritten in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/YYYY-MM-DD-HHMM_refresh.md`.
+
+> **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`.
+
 Pulls **sharepoint** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
 - **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
 
-WorkIQ-first per `workiq-first.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`. 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 `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`.
 
 ## Inputs
 
@@ -27,9 +37,26 @@ WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thor
 - `sharePoint.siteUrl` — SP site URL
 - `sharePoint.driveId` — Graph drive ID for direct access
 
-## Snapshot pass
+## Boundaries (REQUIRED — see `scope-boundaries.instructions.md`)
+
+This skill REFUSES to query unless `<engagement-root>/<project>/integrations.yml#boundaries.sharepoint` is satisfied:
+
+- `boundaries.sharepoint.local_folders` — REQUIRED, non-empty (full local OneDrive-synced paths).
+- `boundaries.sharepoint.site_urls` — optional online-only scope.
+- `boundaries.sharepoint.drive_ids` — optional Graph-direct access.
+- `boundaries.date_window_days` — defaults to 30 if absent.
+
+The walk is **strictly inclusive** — only paths/sites/drives in the boundary are walked. There is no auto-discovery of additional folders. `path_includes`/`path_excludes` from `.settings.yml` further narrow inside the boundary; they cannot widen it.
 
-Write `snapshot/tree.md` (full folder hierarchy, no truncation) and `snapshot/files/<relative-path>.md` for each file selected for body extraction. The selected set is the **union** of:
+Refusal message when boundary is missing:
+
+```
+sharepoint-boundary-missing — add boundaries.sharepoint.local_folders to
+<engagement-root>/<project>/integrations.yml. See doctrine in
+plugin/instructions/scope-boundaries.instructions.md.
+```
+
+## Snapshot pass and `snapshot/files/<relative-path>.md` for each file selected for body extraction. The selected set is the **union** of:
 
 1. **Curated key files** — anything matching `architecture`, `decision`, `adr`, `deliverable`, `proposal`, `statement of work`, `sow`, `business case`, `roadmap`, `plan` in the filename or top-level folder name. These are always extracted.
 2. **Top-N most-recently-modified files** under the project's SharePoint folder, where N = `sharepoint.snapshot.recent_n` from the user's `.settings.yml` (default **25**, configurable to 0 to disable). This captures the live working tail without exploding on large team sites.
@@ -53,14 +80,15 @@ Use template: `templates/weekly/sharepoint-summary.template.md`
 
 If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
 
-## Tools (in order)
+## Tools (WorkIQ ONLY — per `workiq-only.instructions.md`)
+
+1. **WorkIQ (`workiq ask`)** — the ONLY allowed path for SharePoint file text/content extraction (snapshot bodies and stream change summaries). Use the canonical prompt codified in `plugin/instructions/workiq-only.instructions.md` (SharePoint file content section) — do NOT re-derive.
+2. **Local synced folder walk (filesystem only — ALWAYS allowed)** — for metadata only (filename, size, mtime, author from filesystem attributes, change-type via filesystem events). This is a `Get-ChildItem` against `boundaries.sharepoint.local_folders`; it is NOT an M365 API call and therefore not governed by workiq-only. Use it as the discovery layer; pipe interesting file paths into WorkIQ for content extraction.
+3. **Ask user (paste verbatim)** — first-class fallback when WorkIQ doubled-strict retry fails or returns insufficient content for a specific file (e.g. very large doc, encrypted PDF). NOT a degradation; coverage.md labels it `Source: User paste on <ISO>`.
 
-1. **WorkIQ** — ````$WorkIQQuery`````
-2. **Host fallback** — `m365_search_files` / `m365_list_files`; `helpers/sharepoint-pull.ps1` (uses `az account get-access-token --resource https://graph.microsoft.com`); also walk local synced folder under `sharePoint.localFolder` for metadata (no auth needed)
-3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
-4. **Ask user** — paste verbatim source content if all above fail.
+**FORBIDDEN** for this skill (per workiq-only.instructions.md): `m365_search_files`, `m365_list_files`, `m365_get_recent_files`, `m365_download_file` (for content extraction; downloading recording.mp4 in pull-meetings is a separate carve-out), Graph REST `https://graph.microsoft.com/v1.0/me/drive/*`, Graph REST `shares/{id}/driveItem`, SharePoint REST `_api/web/GetFileByServerRelativePath` (for content). These have a near-100% failure rate or produce metadata-only stubs. Calling them is a DEFECT; coverage.md must NOT show them in the attempt trail.
 
-Document which path succeeded under `## Source Basis` in each output file.
+Document the WorkIQ request-id + the exact prompt + which folder/site was queried under `## Source Basis` in each output file.
 
 ## Mutable hints to upsert (during the run, not at the end)
 
@@ -78,8 +106,12 @@ After successful pass:
 - `sources.sharepoint.item_count = <N>`
 - For each week touched, add to `weekly_files` index.
 
+## Depth bar (per `evidence-thoroughness.instructions.md`)
+
+Every snapshot file body starts with an **AI Narrative Summary (REQUIRED FIRST, 3+ paragraphs)** covering what the file is, what it argues / proposes / records, key positions, audience, why it matters — then the body summary at meeting-transcript depth (decisions, risks, actions, owners, dates, key context). Stream events also lead with a short AI Narrative Summary of the change.
+
 ## Stop conditions
 
 - 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 AND host fallback fails AND Graph fails → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.
+- 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.

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

@@ -1,17 +1,27 @@
 ---
 name: "pull-teams"
-version: "2.0.0"
-description: "Pull Teams chat + channel evidence (snapshot: chat roster; stream: messages with full message-by-message reproduction). WorkIQ-first."
+version: "2.2.1"
+description: "Pull Teams chat + channel evidence (snapshot: chat roster; stream: messages with full message-by-message reproduction). WorkIQ-ONLY for human-readable thread rendering per workiq-only.instructions.md. `m365_list_chat_messages` is the ONLY allowed host tool — used as parallel structured-data dump (chat-messages.json), NEVER a substitute for the WorkIQ human-readable pull. Graph REST / `m365_list_chats` / `m365_search_chats` FORBIDDEN."
 ---
 
 # Skill: pull-teams
 
+
+> **v3.7.6 + v3.11.0 contracts** — This skill operates under five HARD-rule doctrines:
+> - `verbatim-by-default.instructions.md` — full bodies/notetext/fields by default; no preview-grade pulls accepted.
+> - **`workiq-only.instructions.md` (v3.11.0)** — chat-thread human rendering goes through WorkIQ ONLY. Graph REST URLs (`/me/chats/*/messages`, etc.) are FORBIDDEN. `m365_list_chat_messages` is ALLOWED as a parallel structured-data dump (writes `chat-messages.json`) — it is NOT a fallback for the WorkIQ human-readable thread pull. The canonical WorkIQ prompt for chat threads is codified in that instruction — do not re-discover.
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md` immediately.
+> - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale `no-match` / `not yet` notes referencing the prior unresolved state must be rewritten in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/YYYY-MM-DD-HHMM_refresh.md`.
+
+> **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`.
+
 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
 
-WorkIQ-first per `workiq-first.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`. 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 `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`.
 
 ## Inputs
 
@@ -36,7 +46,7 @@ Use template: `templates/snapshot/teams-<kind>.template.md`
 
 ## Stream pass
 
-Per `evidence-thoroughness.instructions.md`: every thread touched in window gets full message-by-message reproduction. Group by thread, not by day. If a thread has 30 messages, reproduce all 30.
+Per `evidence-thoroughness.instructions.md`: every thread touched in window starts with an **AI Narrative Summary (REQUIRED FIRST, 3+ paragraphs)** covering what the thread is about, the conversation arc, positions taken, sentiment, what landed and what stayed open — then full message-by-message reproduction. Group by thread, not by day. If a thread has 30 messages, reproduce all 30.
 
 Write to: `<engagement-root>/<project>/Evidence/<alias>/teams/stream/<YYYY-MM-DD>_teams-stream.md` (date = Monday of the ISO week the events fall in).
 
@@ -44,14 +54,33 @@ Use template: `templates/weekly/teams-summary.template.md`
 
 If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
 
-## Tools (in order)
+## Boundaries (REQUIRED — see `scope-boundaries.instructions.md`)
+
+This skill REFUSES to query unless `<engagement-root>/<project>/integrations.yml#boundaries.teams` is satisfied:
+
+- `boundaries.teams.chat_ids` — REQUIRED, non-empty (pinned chat IDs; no fuzzy discovery beyond this list).
+- `boundaries.teams.channel_ids` — REQUIRED for any channel evidence (empty = no channel pulls).
+- `boundaries.date_window_days` — defaults to 30 if absent.
+
+There is **no fuzzy chat discovery** in v3.7.0+. The pre-existing `chatHints` / `participantHints` are now treated as **discovery aids during bootstrap only** — they help the user populate `boundaries.teams.chat_ids` once, and after that they are ignored at pull time.
+
+Refusal message when boundary is missing:
+
+```
+teams-boundary-missing — add boundaries.teams.chat_ids to
+<engagement-root>/<project>/integrations.yml. See doctrine in
+plugin/instructions/scope-boundaries.instructions.md.
+```
+
+## Tools (WorkIQ ONLY — per `workiq-only.instructions.md`)
+
+1. **WorkIQ (`workiq ask`)** — the ONLY allowed path for the human-readable thread reproduction (stream pass) and chat-roster enumeration (snapshot pass). Always cite the chat_ids in the prompt. Use the canonical prompts codified in `plugin/instructions/workiq-only.instructions.md` — do NOT re-derive them.
+2. **`m365_list_chat_messages` (PARALLEL structured-data dump ONLY — allowed exception)** — runs in parallel with the WorkIQ pull to write the raw JSON dump `chat-messages.json` for each chat-id in `boundaries.teams.chat_ids[]`. It is **NOT** a fallback for WorkIQ; the WorkIQ human-readable thread is still REQUIRED. If `m365_list_chat_messages` fails, the WorkIQ artifact still stands and the JSON dump is simply skipped (recorded in coverage.md).
+3. **Ask user (paste verbatim)** — first-class fallback when WorkIQ doubled-strict retry fails or returns insufficient content. NOT a degradation; coverage.md labels it `Source: User paste on <ISO>`.
 
-1. **WorkIQ** — ````$WorkIQQuery`````
-2. **Host fallback** — `m365_list_chats` + `m365_list_chat_messages` scoped by `chatIds` from mutable
-3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
-4. **Ask user** — paste verbatim source content if all above fail.
+**FORBIDDEN** for this skill (per workiq-only.instructions.md): `m365_list_chats` (chat-roster discovery — use WorkIQ), `m365_search_chats`, Graph REST `https://graph.microsoft.com/v1.0/me/chats*`, Graph REST `https://graph.microsoft.com/v1.0/teams/*/channels/*/messages`. These have a near-100% failure rate in this workspace. Calling them is a DEFECT; coverage.md must NOT show them in the attempt trail.
 
-Document which path succeeded under `## Source Basis` in each output file.
+Document the WorkIQ request-id + the exact prompt + which chat_ids were queried under `## Source Basis` in each output file (per workiq-only coverage.md requirements).
 
 ## Mutable hints to upsert (during the run, not at the end)
 
@@ -72,4 +101,4 @@ 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 AND host fallback fails AND Graph fails → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.
+- 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.

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

@@ -1,11 +1,23 @@
 ---
 name: "refresh-project"
-version: "2.1.0"
-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. Builds State/ only on `full` profile (skipped on `standard`). Defaults to since-watermark (fallback 7d if first refresh)."
+version: "2.3.1"
+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."
 ---
 
 # Skill: refresh-project
 
+> **Verbatim-by-default**: This orchestrator MUST dispatch every enabled `pull-<source>` skill whose boundary in `integrations.yml#boundaries.<source>` is satisfied. Skipping a source silently is a defect. See `verbatim-by-default.instructions.md`.
+>
+> **Discover once, consume deterministically**: Refresh MUST read canonical M365 IDs from `<engagement-root>/.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>` and pass them verbatim into each `pull-*`'s index-extractor query. **Refresh never re-discovers.** If the project entry is missing or a per-source key is empty, re-dispatch through `bootstrap-project` for that source's discovery only, then resume. See `m365-id-registry.instructions.md`.
+>
+> **Per-user refresh report REQUIRED**: At end of run, write `<project>/Evidence/<alias>/refresh-reports/<YYYY-MM-DD-HHmm>_refresh.md` per `run-reports.instructions.md`. Even on a no-op run. Cite the registry: `Resolved IDs sourced from m365-mutable.json#knownSections.<projectKey>`.
+>
+> **Cleanup on resolution**: When this run resolves a previously-unknown ID/folder/section, prune the stale `no-match` / probe-trail notes from integrations.yml, m365-mutable.json, run-log, and bootstrap-status.md per `cleanup-on-resolution.instructions.md`. UPSERT the newly-resolved ID into `m365-mutable.json#knownSections.<projectKey>` mid-run.
+>
+> **Capture learnings**: Any quirk / fix / workaround discovered mid-run is appended to `<KUSHI_ROOT>/plugin/learnings/<source>.md` in the same turn per `capture-learnings.instructions.md`.
+>
+> **Canonical evidence layout** (HARD, kushi v3.12.1+): every per-source artifact lands under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` and **nowhere else** under `<project>/`. Before per-source dispatch, refresh MUST scan `<project>/` for non-canonical source-output folders (e.g. `<project>/email-context/`, `<project>/notes/`, `<project>/_Weekly Summaries/`) and migrate each to `Evidence/<alias>/<source>/_legacy_<original-name>_pre-bootstrap/` (move verbatim; log under `## Layout migrations` in the refresh report; add `runs:` entry with `type: layout-migration`). Do NOT delete. See `evidence-layout-canonical.instructions.md`.
+
 Run this when the user says any of: "refresh `<X>`", "do it all for `<X>`" (when project already bootstrapped), "weekly extract for `<X>`", "update `<X>`", "pull `<X>` since `<date>`".
 
 ## Profile-aware behavior
@@ -42,12 +54,31 @@ Profile is read from `kushi-install.json#profile` next to the agent file. Defaul
 
 For each enabled source (or just the requested one), call its `pull-<source>` skill with the effective window.
 
+**OneNote pre-dispatch gate (kushi v3.10.0+, HARD):** Before invoking `pull-onenote`, run the browser-URL completeness check:
+```pwsh
+node plugin/skills/pull-onenote/scripts/recapture-section-url.mjs --project <name> --engagement-root <engagement-root> --check
+```
+If exit 1 (`incomplete`), dispatch the script interactively (no `--check`) so the user pastes the section URL once. Persist + proceed. This is a one-time self-heal of pre-doctrine registry entries — see `pull-onenote/SKILL.md` Pre-flight C and `m365-id-registry.instructions.md` § "Browser-fields self-heal exception". This is NOT re-discovery (which is forbidden); it is a backfill of fields that were never captured, cached forever after the first paste.
+
+Per-source pull skills (canonical order — refresh-project dispatches in this order, but each is independent):
+
+1. `pull-email`
+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)
+
 Each `pull-*` skill is responsible for:
 - Snapshot pass (always re-fetch known entities).
 - Stream pass (incremental from watermark, bucketed by ISO week, append-only merge).
 - Updating `sources.<src>.watermark`, `sources.<src>.last_pulled`, `sources.<src>.item_count` in run-log.
 - Updating `weekly_files` index in run-log.
 
+**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)
 
 If `Evidence/contributors.yml` lists more than one alias and any of them have new evidence in the window, dispatch `consolidate-evidence` for the same window.