kushi-agents 5.0.0 → 5.0.2

package/plugin/skills/pull-onenote/references/playwright-fallback.md

@@ -0,0 +1,111 @@
+# references/playwright-fallback.md (pull-onenote)
+
+> **Load this file when `m365Auth.oneNote.playwrightFallback: true` AND `_index/entities.yml` shows ≥ N pages with `status: body-not-exposed` for ≥ 2 consecutive refreshes** (N default 5; configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`).
+>
+> Otherwise: WorkIQ is the primary path. Do NOT bootstrap a Playwright profile on a fresh install.
+
+## When to enable
+
+```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 the threshold is met. Until then the driver MUST continue using WorkIQ. Never auto-bootstrap a profile — that is always a user-initiated action.
+
+## Bootstrap the Playwright profile
+
+```pwsh
+cd <kushi-repo-root>
+node plugin/skills/pull-onenote/runner.mjs --bootstrap
+```
+
+Expected console flow (any deviation = defect):
+
+```
+[bootstrap] Step 1/2: Sign in to OneNote-for-Web. ...
+[bootstrap] Sign-in detected (OneNote chrome rendered).   ← MUST appear before Step 2/2
+[bootstrap] Step 2/2: Seeding SharePoint cookies at https://microsoft-my.sharepoint.com/
+[bootstrap] Step 2/2: Seeding SharePoint cookies at https://microsoft-my.sharepoint-df.com/
+[bootstrap] Both surfaces visited. Close the browser window when ready.
+[bootstrap] Profile saved at: ...
+```
+
+If `Sign-in detected` is missing → the v3.11.1-or-earlier `waitForURL` bug is back; bootstrap is invalid; cookies are not minted; every subsequent scrape will return `auth-required`. Re-bootstrap with v3.11.2+.
+
+The visible Edge window stays open until you close it. Sign in fully, wait for OneNote to render, then close.
+
+## Scrape a section — use the wrapper, not the bare runner
+
+The bare `runner.mjs` emits JSON to stdout only. Hand-wiring snapshot writes from runner JSON is brittle (PowerShell's default `Out-File` mangles UTF-8 — NBSP becomes `┬á`) and almost always violates the canonical layout.
+
+**HARD rule (kushi v3.11.5+):** drivers MUST call `write-snapshot.mjs`. Never hand-write snapshot files from runner JSON.
+
+```pwsh
+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 <your-alias>
+```
+
+The wrapper writes back to `m365-mutable.json`:
+
+- `one_pages[]` — per-page retry registry (title, wdpartid, webPageId, lastModified, last_status, attempts, snapshot_path, captured_at)
+- `one_lastPullAt`, `one_lastPullRunStatus`, `one_lastPullKushiVersion`
+
+Wrapper-set flags (all load-bearing):
+
+| Flag | Why required |
+|---|---|
+| `--skip-preflight` | Standalone preflight at `https://onenote.cloud.microsoft/` is unreliable post-bootstrap (OneNote SPA forces `prompt=select_account` even when SPO cookies are valid). The Doc.aspx URL uses different cookies and works fine. |
+| `--headless` | Without it, a visible browser opens — if the user accidentally closes it during scrape, run fails with `Target page, context or browser has been closed`. |
+| `--timeout 120000` | Default 60s is too short under tenant load. 120s is the empirical safety margin for sections up to ~25 pages. |
+
+## Diagnostics (when scrape produces `pages: []`)
+
+If the scrape returns `pages: []` with `runStatus: "partial"` and `error: "frame.waitForFunction: Timeout"`, the cause is almost always one of:
+
+1. **Single-page section regex mismatch** — fixed in v3.11.3. Verify runner is v3.11.3+.
+2. **Page-rail genuinely slow to render** — bump `--timeout` to 180000 and retry once.
+3. **Section URL stale** — re-run `scripts/recapture-section-url.mjs`.
+
+Quick aria-label diagnostic (drop into `plugin/skills/pull-onenote/diag.mjs`):
+
+```js
+import { chromium } from 'playwright';
+import os from 'os';
+import path from 'path';
+const ctx = await chromium.launchPersistentContext(
+  path.join(os.homedir(), '.copilot', 'playwright-profile', 'onenote'),
+  { headless: true, channel: 'msedge', viewport: { width: 1400, height: 900 } }
+);
+const page = ctx.pages()[0] || await ctx.newPage();
+await page.goto(process.argv[2], { timeout: 60000 });
+await page.waitForTimeout(60000);
+for (const f of page.frames()) {
+  try {
+    const labels = await f.evaluate(() =>
+      Array.from(document.querySelectorAll('[aria-label]'))
+        .map(n => n.getAttribute('aria-label'))
+        .filter(x => x && (x.includes('page') || x.includes('Page')))
+    );
+    if (labels.length) console.log(f.url().slice(0, 80), labels.slice(0, 40));
+  } catch (e) {}
+}
+await ctx.close();
+```
+
+If you see `, Page. Selected.` but not `, page N of M, Page.` → single-page section, runner must be v3.11.3+.
+
+## Browser-channel and two-surface bootstrap (HARD rules)
+
+- **Channel:** `channel: 'msedge'` only. Vanilla Chromium is denied by Conditional Access with "You can't get there from here". If the user has no Edge installed, fail fast — do NOT fall back to Chromium.
+- **Two-surface seed:** bootstrap MUST visit `https://onenote.cloud.microsoft/` AND BOTH `https://microsoft-my.sharepoint.com/` AND `https://microsoft-my.sharepoint-df.com/`. Cookie domains don't transfer between `*.cloud.microsoft` and `*.sharepoint(-df).com`. Profile reset required when switching channels.
+- **Post-auth signal:** bootstrap MUST wait for one of `[aria-label*="Account manager" i]`, `[data-automationid="NotebookList"]`, `button[aria-label*="notebook" i]`, `iframe[src*="onenoteframe.aspx"]` — NOT for a URL match (no-op because we just navigated there).

package/plugin/skills/pull-onenote/references/preflight.md

@@ -0,0 +1,85 @@
+# references/preflight.md (pull-onenote)
+
+> **Load this file when constructing or debugging the OneNote pre-flight gate** (browser-URL completeness, OneNote-for-Web reachability, three-way runStatus classification).
+
+## A. Playwright profile (only if fallback opted in)
+
+```pwsh
+$prof = "$env:USERPROFILE\.kushi\playwright-profile\onenote"
+if (-not (Test-Path $prof)) {
+  Write-Host "[pull-onenote] Playwright profile not yet seeded."
+  Write-Host "[pull-onenote] Run plugin/skills/pull-onenote/runner.mjs --bootstrap once interactively to sign in."
+  # Skill MUST NOT fall through silently. Surface as run-report 'auth-required' on every pending page.
+}
+```
+
+See `playwright-fallback.md` for the bootstrap procedure, channel/cookie rules, and recovery patterns.
+
+## B. WorkIQ EULA (PRIMARY path needs this once per machine)
+
+```pwsh
+workiq accept-eula  # idempotent
+```
+
+## C. OneNote-for-Web reachability — three-way classification (HARD, v3.11.0+)
+
+Before navigating to any section URL the runner MUST probe `https://onenote.cloud.microsoft/` and classify the end-state:
+
+| End-state | Detection | runStatus | Driver action |
+|---|---|---|---|
+| `ok` | Account chrome / notebook list / `onenoteframe.aspx` iframe rendered within `--preflight-timeout` (default 25s) | n/a (proceed) | Navigate to section URL as normal. |
+| `auth-required` | URL bounced to `login.microsoftonline.com` or `login.live.com` | `auth-required` | Surface in run report; next refresh re-attempts. |
+| `onenote-web-unavailable` | "Sorry, we ran into a problem" / "Something went wrong" / "We couldn't open" / "This notebook can't be opened" / "There was a problem" detected in any frame's body text, OR pre-flight timeout with no chrome | `notebook-unavailable` | **Do NOT retry blindly.** Surface recovery checklist (below). Mark pages `status: notebook-unavailable`. |
+
+The same three-way classification ALSO applies after navigating to the section URL. The two failure modes are distinct; conflating them sends the user down the wrong recovery path.
+
+Standalone pre-flight CLI:
+
+```pwsh
+node plugin/skills/pull-onenote/runner.mjs --preflight
+# Exit 0 = ok, 4 = auth-required, 3 = onenote-web-unavailable, 1 = unexpected
+# stdout: { "preflight": { "ok": bool, "reason"?, "detail"? } }
+```
+
+### Recovery checklist for `notebook-unavailable` (surface verbatim)
+
+1. Hard-refresh `https://onenote.cloud.microsoft/` — if the root page shows the same error, the issue is service- or notebook-side.
+2. Open the notebook in **OneNote desktop** and let it fully sync.
+3. If the notebook opens in desktop but not web, wait 10–15 minutes (web index lag) and retry.
+4. If the section specifically fails (root loads, section errors), re-capture `one_sectionWebUrl` from the address bar via `scripts/recapture-section-url.mjs` — the persisted URL may be stale or for a moved section.
+5. Only after the user can manually open the notebook in OneNote-for-Web, re-run the kushi pull.
+
+## D. Browser-URL completeness gate (HARD, v3.10.0+)
+
+The Playwright runner navigates to `one_sectionWebUrl`. That URL is composed from FIVE registry fields, and ALL must be present and accurate:
+
+| Key | Source | Notes |
+|---|---|---|
+| `one_sectionName` | OneNote section file name | e.g. `AGCO.one` |
+| `one_sectionFileId` | `wd=target(<name>\|<GUID>/)` fragment | Same GUID as WorkIQ's wd-section-file id |
+| `one_notebookSourceDoc` | `sourcedoc={<GUID>}` query param | Identifies the parent notebook |
+| `one_notebookSpoBaseUrl` | `<scheme>://<host>/personal/<upn>` segment | Tenant-specific |
+| `one_sectionWebUrl` | the canonical Doc.aspx URL | **MUST be user-pasted from address bar** |
+
+**No-synthesis rule (HARD, v3.10.2+):** `one_sectionWebUrl` MUST be the URL the user actually copied. Two formulas were tried and BOTH failed in production:
+
+- `wd=target(<name>|<fileId>/)` → silent "Sorry, we ran into a problem".
+- `wd=target(/<name>/)` → silent "Sorry, we ran into a problem".
+
+OneNote's routing depends on internal session/tenant tokens we cannot reverse-engineer. Any template-synthesized URL is invalid.
+
+**Gate before dispatching the runner:**
+
+```pwsh
+node plugin/skills/pull-onenote/scripts/recapture-section-url.mjs `
+  --project <name> `
+  --engagement-root <engagement-root> `
+  --check
+```
+
+- Exit 0 + `{"status":"ok"}` → proceed.
+- Exit 1 + `{"status":"incomplete","missing":[...]}` → invoke recapture (interactive paste prompt) without `--check`.
+
+This gate runs in BOTH bootstrap and refresh — if a refresh discovers the gate is open, it MUST self-heal via the script before invoking the runner. This is a one-time backfill of pre-doctrine or stale registry fields, NOT re-discovery.
+
+If the user declines to paste a URL, mark the OneNote source as `disabled: true, reason: section-url-not-captured` in `<project>/integrations.yml#boundaries.onenote`, log a refresh-report entry, and skip the runner. Do NOT fall back to WorkIQ-only — WorkIQ returns `body-not-exposed` for most pages without browser-URL grounding.

package/plugin/skills/pull-onenote/references/runtime-contract.md

@@ -0,0 +1,118 @@
+# references/runtime-contract.md (pull-onenote)
+
+> **Load this file when implementing the runner / wrapper / per-page retry logic, or when debugging snapshot/+stream/ legacy artifacts.** Reading-only consumers (build-state, ask-project, link-entities) should not need this file — the canonical contract for them is the v4.9.0 weekly CSC + `_index/entities.yml` layout described in the main SKILL.md.
+
+## Empirical contract (HARD-rule, supersedes earlier doctrine)
+
+1. **WorkIQ natural-language by display name IS the primary, working path for OneNote.** Reframed v4.7.3 (2026-05-26) — see `workiq-onenote-query-shape.instructions.md`. The only working WorkIQ phrasings: (a) narrow, single-section-by-display-name discovery; (b) single-page-by-title body pulls; (c) section-scoped edit-event stream. Forbidden: enumeration verbs, structured-field filter syntax, ID-lookup questions, broad notebook-enumeration probes — all empirically fail.
+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 a single refresh. The `_index/entities.yml#status` field accumulates captures across refreshes; over 3–5 refreshes the cumulative rate converges. Playwright remains as the opt-in recovery valve for contributors who need faster convergence.
+3. **The OneNote-for-Web `pageid` and the WorkIQ wd-part id are different identifiers.** Persist both per page when both are observed (`webPageId` for browser navigation; `wdpartid` for WorkIQ correlation). WorkIQ-only operation needs `wdpartid` alone.
+4. **Browser-scrape via OneNote-for-Web returns higher-fidelity verbatim bodies when it works** — HCA on 2026-05-14: 16/16 pages captured (~120KB) in one run. NOT the default because: (a) Edge + Conditional Access compliance required; (b) per-machine bootstrap expires every 3–5 days; (c) multi-refresh WorkIQ converges adequately for time-windowed engagement evidence.
+
+## Bootstrap discovery (one-time per project)
+
+For a project we have not pulled OneNote for before, capture into `m365-mutable.json#knownSections.<projectKey>`:
+
+| Key | Source | Example (HCA) |
+|---|---|---|
+| `one_sectionName` | OneNote section file name | `HCA.one` |
+| `one_sectionFileId` | OneNote-for-Web wd= URL fragment AND WorkIQ wd-section-file id (they match) | `3d0ad388-fd6b-45a8-8619-60dd709b7ade` |
+| `one_notebookSourceDoc` | SharePoint sourcedoc GUID for the parent notebook | `2036c7b1-db1b-47fd-a14f-d8ee94ddd9bc` |
+| `one_notebookName` | OneNote notebook display name | `ISE Work` |
+| `one_notebookSpoBaseUrl` | host segment before `/_layouts/15/Doc.aspx` | `https://microsoft-my.sharepoint-df.com/personal/<upn>` |
+
+Discover by:
+
+1. Open OneNote-for-Web at `https://onenote.cloud.microsoft/`. Sign in.
+2. Open notebook → click section.
+3. Read URL — contains `sourcedoc={<notebookSourceDoc>}` and `wd=target(<sectionName>|<sectionFileId>/...)`.
+4. Persist all five values per `m365-id-registry.instructions.md`.
+
+If the section already exists in `knownSections.<projectKey>` from a prior WorkIQ run, only the browser-specific fields need to be added.
+
+## Step A — enumerate pages (browser fallback only)
+
+The runner navigates to the section's deep-link URL and waits for the OneNote canvas inside the nested `ffc-onenote.officeapps.live.com/onenoteframe.aspx` frame. Page enumeration uses the accessibility tree and MUST handle BOTH aria-label formats (kushi v3.11.3+):
+
+| Section state | aria-label format | Parsed as |
+|---|---|---|
+| Multi-page | `<title>, page N of M, Page.` | `{ title, pos: N, total: M }` |
+| Single-page | `<title>, Page. Selected.` | `{ title, pos: 1, total: 1 }` |
+
+**HARD rule (v3.11.3+):** any aria-label-driven enumerator MUST handle the N=1 special-case format. Single-page sections do NOT render the multi-page format; assuming they do is the defect signature `frame.waitForFunction: Timeout` with `pages: []`.
+
+After clicking each page, capture `webPageId` from the `wd=target(...|<title>|<webPageId>/)` segment.
+
+## Step B — fetch verbatim body (browser fallback only)
+
+For each page, click the rail entry, wait 2.5s, then:
+
+```js
+const body = await wac.evaluate(() => {
+  const node = document.querySelector('#PageContentWrapper')
+            || document.querySelector('.Page')
+            || document.querySelector('[role="main"]');
+  return node ? node.innerText : '';
+});
+```
+
+Acceptance check (HARD):
+
+- Captured body must contain title line + ≥ 1 non-toolbar paragraph.
+- Body < 50 chars: mark `status: short-suspect` and retry unless verified sparse in OneNote desktop.
+- Redirect to `login.microsoftonline.com`: mark `status: auth-required` and EXIT the run loop early.
+
+## Step B' — fallback: WorkIQ verbatim probe
+
+Used ONLY when (a) Playwright profile absent, (b) previous run hit auth-required and retry-cooldown not elapsed (24h), or (c) user requests WorkIQ-only diagnostic.
+
+The canonical WorkIQ Step B verbatim prompt lives in `workiq-only.instructions.md` § OneNote verbatim. Acceptance: real body OR explicit unavailable marker. Anything else → `status: workiq-degraded`.
+
+## Per-page retry registry (legacy m365-mutable schema)
+
+> v4.9.0 moves the per-page retry registry into `_index/entities.yml#status` and `low_signal`. The legacy `m365-mutable.json#knownSections.<projectKey>.one_pages[]` shape is retained for back-compat reads. New writes go to `_index/entities.yml`.
+
+Status values (canonical across both old and new schemas):
+
+| Status | Meaning | Next-run action |
+|---|---|---|
+| `captured` | Browser scrape returned full body | None unless `lastModified` advanced |
+| `user-pasted` | Human pasted body | Treat as captured; do not overwrite |
+| `auth-required` | Browser hit MFA / sign-in page | Retry browser; surface in run report |
+| `notebook-unavailable` | OneNote-for-Web error dialog (service- or notebook-side) | Do NOT auto-retry. Surface recovery checklist (preflight.md §C). |
+| `workiq-degraded` | Browser unavailable AND WorkIQ returned unavailable marker | Retry browser when profile valid again |
+| `body-not-exposed` | WorkIQ-fallback explicitly returned the literal marker | Retry browser next run |
+| `short-suspect` | Body < 50 chars, may not be genuinely sparse | Verify in OneNote desktop, then retry |
+| `enumeration-only` | Page enumerated but Step B not yet attempted | Attempt Step B on next run |
+
+Retry doctrine: every refresh re-runs Step A and re-runs Step B for any page where status NOT IN (`captured`, `user-pasted`). Pages with `captured` are re-fetched only if `lastModified` differs.
+
+## Legacy snapshot file shape (pre-v4.9.0, reader fallback only)
+
+Front-matter (yaml) at top of every legacy `snapshot/pages/<safe-title>.md`:
+
+```yaml
+---
+page_title:    "4/3 - HCA with Jay and Martin"
+section:       "HCA.one"
+notebook:      "ISE Work"
+section_id:    "3d0ad388-fd6b-45a8-8619-60dd709b7ade"
+wdpartid:      "2233ac5a-007a-4b70-9d93-d6113f318ba3"
+webPageId:     "78aac9b5-0629-4daa-ada3-f2436cb2381c"
+last_modified: "April 3rd"
+last_status:   "captured"
+captured_via:  "browser"
+attempts:      2
+last_attempt:  "2026-05-14T03:55:00Z"
+captured_at:   "2026-05-14T03:55:00Z"
+---
+```
+
+Body shape:
+
+- `captured` / `user-pasted`: `## AI Narrative Summary` (3+ paragraphs) + `## Body (verbatim)` with exact extracted text. NEVER paraphrase a captured body.
+- `auth-required` / `workiq-degraded` / `body-not-exposed`: unavailable-marker block + `### next_step` block + metadata table. Do NOT fabricate body content from emails or chats.
+- `enumeration-only`: transient marker only.
+- `short-suspect`: captured text + `### unconfirmed` note.
+
+This file is NOT written by v4.9.0+ runs; it is read by build-state's legacy fallback chain.

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

@@ -1,7 +1,7 @@
 ---
 name: "pull-sharepoint"
 version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull SharePoint evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_sharepoint-csc.md. One block per file touched that week, upserted in _index/entities.yml. Local synced-folder walk for metadata still allowed (filesystem only). WorkIQ-ONLY for content via CSC canonical prompts. No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
+description: "USE WHEN refresh-project / bootstrap-project dispatches SharePoint source OR the user says \"pull SharePoint for <X>\" AND project boundaries.sharepoint.site_url is set. DO NOT USE for tenant-wide site discovery. Capability: pulls SharePoint evidence (document library activity, page edits, list items) as CSC blocks written to weekly/YYYY-MM-DD_sharepoint-csc.md, upserted in _index/entities.yml. WorkIQ-only."
 ---
 
 # Skill: pull-sharepoint
@@ -21,6 +21,14 @@ description: "v3.0.0 (kushi v4.9.0): Pull SharePoint evidence as Comprehensive S
 > - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
 > - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
 
+## Gotchas
+
+- **Forbidden tenant-wide phrasings** — tenant-wide "list … sites" enumerate, site-ID lookups, and structured-field site searches all punt to Graph admin endpoints. Use display-name content queries per `sharepoint-bootstrap-discovery.instructions.md` (which holds the canonical forbidden list).
+- **`sharepoint://siteurl=...` is the canonical id, not `siteId`** — site GUIDs change when a site is renamed; the URL is stable. Always cite by URL.
+- **Drive item activity needs `Sites.Read.All` AND `Files.Read.All`** — when WorkIQ returns "no activity" for a site that clearly has activity, the consent scope is the culprit. Surface as `degraded-list-only` in `_index/entities.yml#status`.
+- **List items vs library files vs pages all live under one site** — the CSC writer separates them under different anchors (`{#list-<name>}`, `{#file-<safe-title>}`, `{#page-<safe-title>}`). Do NOT collapse into one block.
+- **SharePoint syncing to OneDrive is on a separate pin policy** — see `sharepoint-to-onedrive-sync.instructions.md`. Pulled content is read FROM SharePoint, not from the local OneDrive mirror.
+
 ## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
 
 Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
@@ -61,8 +69,8 @@ Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructi
 
 - Local synced folder walk stays (filesystem metadata enumeration is always allowed; not an M365 API call).
 - WorkIQ CSC prompt per selected file.
-- Drop `snapshot/tree.md` + `snapshot/files/<path>.md`. Tree information becomes the `Artifacts/Links` section of CSC blocks (each block lists the file's path + parent folder + any sibling files cited in its content).
-
+- Drop `snapshot/tree.md` + `snapshot/files/<path>.md`. Tree information becomes the `Artifacts/Links` section of CSC blocks (each block lists the file's path + parent folder + any sibling files cited in its content).
+
 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)
@@ -171,11 +179,11 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
 
 - 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.
-## 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).
+- 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
@@ -190,4 +198,13 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
   info now lands in CSC `Artifacts/Links`). WorkIQ prompts switched to CSC canonical prompts. AI
   Narrative Summary requirement removed (CSC bulleted sections carry the load). Local synced-folder
   walk unchanged. Legacy snapshot/+stream/ folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-sharepoint`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

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

@@ -1,7 +1,7 @@
 ---
 name: "pull-teams"
 version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull Teams chat + channel evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_teams-csc.md. One block per chat/channel thread touched that week, upserted in _index/entities.yml. WorkIQ-ONLY via CSC canonical prompts; `m365_list_chat_messages` allowed as parallel structured-data dump to `_index/chat-messages_<chatId>.json`. No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
+description: "USE WHEN refresh-project / bootstrap-project dispatches Teams source OR the user says \"pull Teams for <X>\" AND project boundaries.teams (chats/channels) list is non-empty. DO NOT USE for general Teams search. Capability: pulls Teams chat + channel evidence as CSC blocks written to weekly/YYYY-MM-DD_teams-csc.md, one block per thread touched, upserted in _index/entities.yml. WorkIQ-only."
 ---
 
 # Skill: pull-teams
@@ -21,6 +21,14 @@ description: "v3.0.0 (kushi v4.9.0): Pull Teams chat + channel evidence as Compr
 > - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
 > - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
 
+## Gotchas
+
+- **Chat ID and channel ID are different namespaces** — `teams://chat_id=<id>` (1:1 / group chats) and `teams://channel=<teamId>/<channelId>` (team channels) must NOT be merged in `_index/entities.yml`. Different `id:` prefixes are intentional.
+- **Forbidden bulk-enumerate phrasings** — bulk "list … chats", chat-ID lookups, and structured-field chat searches all punt to Graph. Use display-name content queries per `teams-bootstrap-discovery.instructions.md` (which holds the canonical forbidden list).
+- **Edited messages do NOT change `createdDateTime`** — incrementality keyed on `createdDateTime` misses edits. Use `lastModifiedDateTime` for the watermark; CSC bullets cite the edit time.
+- **Channel threads include the root + replies as one entity** — `_index/entities.yml` rolls the whole thread under one anchor. Reply-only weeks still touch the thread''s `last_touched`.
+- **Bots and webhook posts have synthetic `from.user` blocks** — when `from.user.userIdentityType == "applicationInstance"`, render as `[bot] <displayName>` in CSC participants; never resolve as a person.
+
 ## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
 
 Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
@@ -63,8 +71,8 @@ Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructi
 
 - Run `m365_list_chat_messages(chatId)` in **PARALLEL** with WorkIQ CSC pull (allowed structured-data dump exception). Save raw JSON to `_index/chat-messages_<chatId>.json` (no longer the legacy `snapshot/`).
 - WorkIQ CSC prompts per chat/channel — one CSC block per thread.
-- For channels, the root post defines the thread; the entity anchor is the rootMessageId.
-
+- For channels, the root post defines the thread; the entity anchor is the rootMessageId.
+
 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
@@ -158,11 +166,11 @@ 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.
-## 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).
+- 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
@@ -183,4 +191,13 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
   removed (CSC bulleted sections carry the load). Per-message verbatim reproduction removed.
   `m365_list_chat_messages` parallel dump now lands in `_index/chat-messages_<chatId>.json`.
   Legacy snapshot/+stream/ folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-teams`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

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

@@ -1,7 +1,7 @@
 ---
 name: "refresh-project"
 version: "4.0.0"
-description: "Incremental refresh for an already-bootstrapped project (kushi v4.9.0+). Uses _index/entities.yml for incrementality; writes to the current ISO week's weekly/<YYYY-MM-DD>_<source>-csc.md; intra-week reruns merge by entity-anchor per weekly-csc.instructions.md. Verbatim-by-default — 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."
+description: "USE WHEN the user says \"refresh <X>\", \"weekly extract for <X>\", \"update <X>\", \"pull <X> since <date>\", or \"do it all for <X>\" AND the project is ALREADY bootstrapped (Evidence/ exists). DO NOT USE for first-time setup (use bootstrap-project). Capability: incremental refresh — uses _index/entities.yml for incrementality, writes to current ISO week's weekly/<YYYY-MM-DD>_<source>-csc.md, intra-week reruns merge by entity-anchor. Verbatim-by-default. Builds State/ only on full profile."
 ---
 
 # Skill: refresh-project
@@ -46,6 +46,19 @@ Profile is read from `kushi-install.json#profile` next to the agent file. Defaul
 
 ## Steps
 
+
+## Step checklist
+
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+
+- [ ] Step 1 — Resolve project + read run-log
+- [ ] Step 2a — Drain deferred-retry queue (REQUIRED, kushi v4.4.1+, per `deferred-retry-on-workiq-fail.instructions.md`)
+- [ ] Step 2 — Per-source dispatch
+- [ ] Step 3 — Consolidate (if multi-user)
+- [ ] Step 4 — Build state (FULL PROFILE ONLY)
+- [ ] Step 4b — Cross-source graph + dashboard + tour (kushi v5.0.0)
+- [ ] Step 5 — Run summary
+
 ### 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.
@@ -200,4 +213,13 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
 ## Changelog
 
 - **v4.0.0 (kushi v5.0.0, 2026-05-26)**: After build-state, dispatch the v5 enrichment chain — `link-entities` → `dashboard` → `tour`. Each step's success/failure is recorded in the run summary; a failure of one step does not block the next.
-- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: Incremental refresh now driven by `_index/entities.yml` (last_touched comparison). Output goes to current week's `weekly/<YYYY-MM-DD>_<source>-csc.md`; intra-week reruns merge by entity-anchor. Deferred-retry drain targets weekly/ output. No new writes to snapshot/ or stream/.
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: Incremental refresh now driven by `_index/entities.yml` (last_touched comparison). Output goes to current week's `weekly/<YYYY-MM-DD>_<source>-csc.md`; intra-week reruns merge by entity-anchor. Deferred-retry drain targets weekly/ output. No new writes to snapshot/ or stream/.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted refresh`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

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

@@ -1,7 +1,7 @@
 ---
 name: "self-check"
 version: "2.0.0"
-description: "Pre-commit / pre-push validator. Checks that Kushi's skills, instructions, prompts, agent definition, templates, and key docs are all internally consistent. Source of truth is the file system. Findings are warnings with concrete fixes — never blocking."
+description: "USE WHEN the user says \"self-check\", \"validate kushi\", \"pre-commit check\", \"are all skills documented?\", or before committing/pushing changes to the kushi repo. DO NOT USE for evidence-validation of a specific project (use ask-project / project-status). Capability: validates kushi's skills, instructions, prompts, agent definition, templates, and key docs are internally consistent against the file system. Findings are warnings with concrete fixes — never blocking."
 ---
 
 # Skill: self-check
@@ -61,6 +61,14 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | 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`. |
 | D29 | Vertex integration integrity | validates `plugin/config/studios.json` + schema, parses `detect-vertex-repo.mjs` / `vertex-validate.mjs`, asserts no vendored `templates/vertex-schemas/`, and confirms `emit-vertex` + `vertex-link` skills ship. |
+| D30.skill-size | agentskills.io size cap | every `plugin/skills/<name>/SKILL.md` ≤ 500 lines AND ≤ 5000 tokens (chars/4). See `agentskills-compliance.instructions.md`. |
+| D30.references-layout | Load-on-trigger pointers | any skill with a sibling `references/` folder must cite at least one `references/<file>.md` from SKILL.md (the load-on-trigger pattern). |
+| D30.gotchas-section | Top-5 gotchas surfaced | every `pull-*` SKILL has a `## Gotchas` section near the top. |
+| D30.checklist-orchestrators | Orchestrator checklists | `bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour` use `- [ ]` syntax for their step lists. |
+| D30.validation-loop | Writer validation loop | every writer skill (writes to `Evidence/`, `State/`, `_graph/`, `dashboards/`, `tours/`) ends with a `## Validation loop` section. |
+| D30.description-optimized | Trigger-based description | every SKILL.md `description:` front-matter leads with `USE WHEN` or `WHEN ` per <https://agentskills.io/skill-creation/optimizing-descriptions>. |
+| D31.genealogy | Release genealogy entry exists | every `git tag` matching `v<x.y.z>` MUST appear in `docs/genealogy.md` as a `## v<x.y.z>` heading or be named under a parent's "Patch lineage" line. See `release-genealogy.instructions.md`. |
+| D32.multi-host | Multi-host install integrity | validates `src/multi-host.mjs` exports + `bin/cli.mjs` flag handling, then performs a temp-dir dry-run install for BOTH supported hosts (Clawpilot + VS Code Chat) under a fake `$HOME` in `$env:TEMP`. Asserts SKILL.md + agent file + skills/ + prompts/ + skills-metadata.json with a kushi entry are present, then asserts a clean uninstall. NEVER touches the real `~/.copilot/` or `~/.vscode/`. See `multi-host-install.instructions.md`. |
 | **CSC weekly-layout checks (kushi v4.9.0)** | | gated on `Resolve-EngagementRoots` — no-ops on the kushi repo itself. |
 | D11.csc | CSC entity coverage + depth | every `Evidence/<alias>/<source>/weekly/*-csc.md` has ≥ 1 entity heading; per-source minimum bullet count + populated-section count (meetings 25/6, email 8/4, teams 6/3, onenote 10/4, sharepoint 8/3, crm 12/5, ado 8/4). Coverage-Notes-only blocks (low-signal escape) are exempt. |
 | D12.csc | CSC section order | every entity block's `###` section headings appear in the canonical order: Participants → Topics → Q&A → Who Said What → Decisions → Dates & Numbers → Action Items → Next Steps → Open Questions → Risks → Customer Asks → Artifacts → Coverage Notes. |