kushi-agents 3.4.2 → 3.13.0

package/plugin/instructions/m365-id-registry.instructions.md

@@ -0,0 +1,134 @@
+---
+applyTo:
+  - "plugin/skills/bootstrap-project/**"
+  - "plugin/skills/refresh-project/**"
+  - "plugin/skills/pull-*/**"
+priority: HARD
+---
+
+# M365 ID Registry — discover once, consume deterministically
+
+**Doctrine:** Bootstrap discovers; refresh consumes. Refresh runs MUST NOT re-discover canonical M365 identifiers — that is the source of "it worked the first time but not the second" non-determinism.
+
+## The registry
+
+`<engagement-root>/.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>` is the **single source of truth** for canonical M365 identifiers per project.
+
+Schema (populate every key the source supports):
+
+```jsonc
+"<projectKey>": {
+  // OneNote
+  "one_sectionName":         "<displayName>.one",
+  "one_sectionFileId":       "<wdsectionfileid GUID>",       // primary, extracted from Doc.aspx URL fragment
+  "one_sectionGroupId":      "<wdsectiongroupid GUID>",      // when boundary is a section group
+  "one_sectionOneNoteGuid":  "<wdsectiononenoteguid GUID>",  // alternate
+  "one_sectionPath":         "/<group>/<section>.one",
+  "one_sectionWebUrl":       "<full Doc.aspx URL>",
+  "one_notebookSourceDoc":   "<notebook sourceDoc GUID>",
+  "one_notebookName":        "<notebook display name>",        // browser path needs display name
+  "one_notebookSpoBaseUrl":  "https://<tenant>.sharepoint(-df)?.com/personal/<upn>",  // browser path
+  "one_pages": [                                              // per-page retry registry (dual-ID schema, pull-onenote v2.6.0)
+    {
+      "title":           "<page title>",
+      "wdpartid":        "<SharePoint search-index page GUID — used by WorkIQ>",
+      "webPageId":       "<OneNote-for-Web page GUID — used by browser scrape>",
+      "lastModified":    "<as reported by source>",
+      "last_status":     "captured | user-pasted | auth-required | workiq-degraded | BODY-NOT-EXPOSED | short-suspect | enumeration-only",
+      "captured_via":    "browser | workiq | user-paste",
+      "attempts":        0,
+      "last_attempt_at": "<ISO-8601>",
+      "snapshot_path":   "Evidence/<alias>/onenote/snapshot/pages/<safe-title>.md",
+      "captured_at":     "<ISO-8601, only when last_status ∈ {captured, user-pasted}>"
+    }
+  ],
+  // Email
+  "emailContext":            "Inbox/<folder-path>",
+  // Teams
+  "teamsChatContext": {
+    "chatHints":         ["..."],
+    "channelHints":      ["..."],
+    "participantHints":  ["..."]
+  },
+  // SharePoint
+  "sp_siteId":   "<siteId>",
+  "sp_webId":    "<webId>",
+  "sp_listId":   "<listId>",
+  "sp_path":     "/<site>/<library>/<folder>",
+  // CRM
+  "crm_envUrl":     "<env>.crm.dynamics.com",
+  "crm_entitySet":  "<entityset>",
+  "crm_recordId":   "<guid>",
+  "crm_requestId":  "<FE-YYYY-NNNNNN>",
+  // ADO
+  "ado_org":           "<orgName>",
+  "ado_project":       "<projectName>",
+  "ado_engagementId":  "<int>",
+  "ado_workItemIds":   [<int>, ...],
+  // Misc — user-curated link list (pull-misc v0.1.0+)
+  "misc_links": [                                              // per-link retry registry
+    {
+      "type":             "loop | web | learn | pdf | github | file | onenote | sharepoint | ado",
+      "owner":            "<as in external-links.txt>",
+      "title":            "<as in external-links.txt>",
+      "url":              "<as in external-links.txt>",
+      "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",
+      "http_status":      200,
+      "content_type":     "text/html",
+      "char_count":       12345,
+      "etag":             "<HTTP ETag>",
+      "last_modified_http":"<HTTP Last-Modified>",
+      "attempts":         0,
+      "last_attempt_at":  "<ISO-8601>",
+      "captured_at":      "<ISO-8601, only when last_status=captured>",
+      "snapshot_path":    "Evidence/<alias>/misc/snapshot/<safe-type>__<safe-title>.md"
+    }
+  ]
+}
+```
+
+## Bootstrap contract (HARD)
+
+For every enabled source, bootstrap MUST:
+
+1. **Probe** WorkIQ / source-native API with the user-supplied seed (folder name, channel name, request id, work item id) using the per-source discovery procedure in `pull-<source>/SKILL.md` § "Bootstrap discovery".
+2. **Validate** by re-issuing the source's Step A enumerate query against the resolved ID. The resolved ID is accepted ONLY if the validate query returns ≥ 1 row.
+3. **Persist** the resolved IDs to `m365-mutable.json#knownSections.<projectKey>` AND mirror them into the corresponding `boundaries.<source>.*` keys in `<project>/integrations.yml`.
+4. **Record** one line per source in `bootstrap-status.md`: `<source>: resolved <key>=<value> via seed "<seed>" (<count> items enumerated)`.
+5. If discovery fails after trying all alternate identifiers documented in the per-source SKILL, write the source as `disabled` in `integrations.yml`, park the question in `OPEN-QUESTIONS-DRAFT.md` (or `State/09_open-questions.md`), and continue. Never write speculative or partial IDs.
+
+## Refresh contract (HARD)
+
+Every refresh MUST:
+
+1. **Read** `m365-mutable.json#knownSections.<projectKey>` first. If the entry is missing or the per-source key is empty → DO NOT probe. Re-dispatch through `bootstrap-project` for that source's discovery only, then resume.
+2. **Pass the canonical IDs to each pull-* skill in the form that skill's WorkIQ queries actually use.** Different sources need different forms:
+   - **OneNote (corrected v3.8.0):** PRIMARY path is browser-scrape via Playwright with persisted profile (returns reliable verbatim bodies — 16/16 captured for HCA on 2026-05-14 vs WorkIQ's 1/18). FALLBACK path is WorkIQ natural-language by display name (used only when Playwright profile is auth-expired). Per-page identifiers are stored in BOTH forms: `webPageId` (used by browser-scrape navigation) AND `wdpartid` (used by WorkIQ correlation and stream events). See `pull-onenote/SKILL.md` v2.6.0 § "Empirical contract" and `learnings/onenote.md` 2026-05-14 for proof. The v3.7.8 wdsectionfileid-filter doctrine and the v3.7.9 WorkIQ-primary doctrine are both retracted.
+   - **Email / Teams / SharePoint / CRM / ADO:** the registry IDs are passed as documented in each pull-* skill — typically as Graph IDs in API calls, not WorkIQ prose.
+   - **Misc (pull-misc v0.1.0+):** the link list is the user-curated `<project>/external-links.txt` file. Refresh re-parses the file every run, matches existing `misc_links[]` entries by `(type, url)` tuple, marks deleted entries as `removed` (preserves snapshot), creates new entries as `not-yet-attempted`, and routes per-type to runner branches (browser for loop, http for web/learn/docs/pdf/github, file for local, delegated for onenote/sharepoint/ado). See `pull-misc/SKILL.md` § "Step A — enumerate".
+3. **Never re-discover.** A refresh that probes WorkIQ with seeds (folder name, channel name) instead of canonical IDs is a defect. The only exception is the cleanup-on-resolution path documented in `cleanup-on-resolution.instructions.md`, which UPSERTS newly-resolved IDs into the registry mid-run.
+
+### Browser-fields self-heal exception (kushi v3.10.0+, OneNote-only)
+
+OneNote requires FIVE registry fields to drive the Playwright runner — not just the WorkIQ `wdsectionfileid`. Pre-doctrine registry entries (bootstrapped before kushi v3.10.0) and entries written from synthesized URL templates are missing or wrong on `one_notebookSourceDoc`, `one_notebookSpoBaseUrl`, and `one_sectionWebUrl`. Refresh MAY (and MUST) dispatch `plugin/skills/pull-onenote/scripts/recapture-section-url.mjs` mid-run when these fields are absent. This is **not** re-discovery — `wdsectionfileid` is preserved if already present. It is a one-time backfill via user URL paste, cached forever after.
+
+The script's `--check` mode is the gate; the interactive mode is the heal. See `pull-onenote/SKILL.md` Pre-flight C for the contract.
+
+4. **Cite** the registry path in the per-user refresh report: `Resolved IDs sourced from m365-mutable.json#knownSections.<projectKey> (last_updated: <ts>)`.
+
+## Anti-patterns (HARD-rule violations)
+
+1. ❌ Refresh probes WorkIQ for `"List sections in OneNote notebook"` instead of reading `one_sectionFileId` from the registry.
+2. ❌ Bootstrap persists an ID without validating it via the source's Step A enumerate query.
+3. ❌ Pull-* skill uses the wrong WorkIQ phrasing for the source. For OneNote specifically: using `wdsectionfileid = <id>` as filter syntax routes WorkIQ to summary mode — the working WorkIQ pattern is natural-language naming `one_sectionName` and notebook display name. But per `pull-onenote/SKILL.md` v2.6.0, browser-scrape is the PRIMARY path; WorkIQ is fallback only.
+6. ❌ A pull-* skill silently drops pages/items that returned BODY-NOT-EXPOSED, auth-required, or workiq-degraded instead of registering them for retry. Per-page retry registries (e.g. `one_pages[]` for OneNote) are the durable state that survives across refreshes — without them, refresh runs cannot tell pending-retry from never-attempted.
+7. ❌ A pull-* skill stores only ONE form of an identifier when the registry doctrine requires multiple forms. For OneNote specifically: `one_pages[]` entries MUST persist BOTH `webPageId` (browser navigation) AND `wdpartid` (WorkIQ correlation) when both are observed. Storing only one creates a single-path lock-in that the empirical record (browser-vs-WorkIQ retrieval gap) explicitly forbids.
+4. ❌ Bootstrap writes a partial / speculative ID with a `_note` field instead of marking the source disabled.
+5. ❌ Refresh "rediscovers" because it didn't find the project key — must re-dispatch through bootstrap, not improvise.
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` D12 (v3.7.8 / retuned v3.7.9 / extended v3.8.0) verifies that each `pull-*/SKILL.md` cites `m365-id-registry.instructions.md` at least once and contains source-specific contract tokens. For `pull-onenote` v2.6.0 the required tokens are: `m365-id-registry`, `one_pages`, `webPageId`, `auth-required`, `playwright-profile` — these prove the skill carries the dual-ID retry registry + browser-primary contract.

package/plugin/instructions/meetings-verbatim-required.instructions.md

@@ -0,0 +1,176 @@
+---
+applyTo: "**"
+description: "HARD rule — meetings are an EXPIRING evidence class. Every meeting MUST have a sibling verbatim/ folder containing the raw chat thread + transcript text + recording URL. Curated 7-section snapshot is NOT a substitute; it cannot be rebuilt once the recording/transcript is purged by tenant retention."
+---
+
+# Meetings verbatim is REQUIRED (HARD RULE, v3.10.0)
+
+Meetings differ from every other evidence class in one critical way: **the source expires.**
+
+- Teams recordings are deleted by tenant retention (default 60 days for many tenants; sometimes shorter).
+- VTT transcripts are tied to the recording and disappear with it.
+- Copilot recap cards persist only as long as the meeting object does.
+- Attendee memory degrades to zero within weeks.
+
+Email bodies, OneNote pages, SharePoint files, CRM records, and ADO work items all persist in their source systems indefinitely (or for years). Meetings do not. If the curated 7-section meeting summary is the only artifact kushi captures, and the recording later expires, **the evidence is unrecoverable**. This has happened in production (see `learnings/meetings.md` — FDE Intake John Deere, 2026-05-18).
+
+## The rule
+
+For every meeting captured by `pull-meetings`, the skill MUST produce **two** outputs, not one:
+
+1. **Curated snapshot** — `Evidence/<alias>/Meetings/snapshot/<slug>.md` (existing) or `Evidence/<alias>/Meetings/stream/<week>_meetings-stream.md` per-meeting block (existing). 7-section doctrine summary. Human-readable.
+2. **Verbatim folder** — `Evidence/<alias>/Meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` (NEW, REQUIRED). Raw immutable artifacts that survive source expiry.
+
+A per-meeting block in `stream/` that has NO sibling `verbatim/<...>/` folder is a **defect**, even if the curated block is rich and well-cited. Self-check rule **D13** enforces this in deep mode.
+
+## "Verbatim" means the FULL TRANSCRIPT TEXT — not just chat (HARD RULE)
+
+The defining artifact of a meeting verbatim folder is **the full speaker-by-speaker transcript text of what was said in the meeting**. Chat messages are SUPPORTING evidence; they are **NOT** a substitute for the transcript.
+
+Order of preference for the transcript artifact (highest fidelity first):
+
+1. **Raw VTT** (`transcript.vtt`) — verbatim, timestamped, per-speaker turns. Captured via `m365_get_transcript(joinUrl)` or the Graph `/me/onlineMeetings/{id}/transcripts/{tid}/content` endpoint with `Accept: text/vtt`. **Required first attempt.**
+2. **Plain-text transcript** (`transcript.txt`) — full speaker-by-speaker text without VTT formatting. Allowed only when raw VTT cannot be retrieved but a plain text dump is available (e.g. WorkIQ returns the full text but not the VTT bytes). Must include speaker names + at least timestamp markers.
+3. **Copilot recap summary** (`transcript-source.md`) — Copilot-generated SUMMARY returned by WorkIQ when both VTT and plain transcript are unavailable. Must carry the `WARNING: NOT a verbatim transcript` header. This is the LOWEST acceptable transcript-class artifact and only counts when nothing higher exists.
+4. **Chat reconstruction** (`chat-messages.json` + `chat-messages.md`) — the chat thread alone. **This is NOT a transcript.** A verbatim folder whose only "transcript" is chat reconstruction is marked `transcript-missing` in `coverage.md` and the meeting block in `stream/` carries `Source basis: ❌ no-transcript-recovered-chat-only`.
+
+A verbatim folder is **transcript-complete** only when one of files 1, 2, or 3 exists with non-empty content. A folder with only chat is `transcript-missing` — a degraded state, not the goal. Self-check D13 distinguishes these two outcomes.
+
+## Transcript capture cascade — WorkIQ-only (HARD RULE, v3.11.0+)
+
+Per `workiq-only.instructions.md`: kushi does NOT use `m365_get_transcript`, `m365_get_facilitator_notes`, `m365_list_meetings`, `m365_list_events`, or Graph REST for transcripts. They fail almost every call in this workspace. The capture cascade is short and codified:
+
+1. **WorkIQ — full transcript pull (REQUIRED first attempt)**:
+   ```
+   workiq ask -q "Find the Teams meeting titled \"<subject>\" that occurred on <YYYY-MM-DD>. Return the full transcript verbatim with speaker labels and timestamps. Do not summarize."
+   ```
+   - If output contains speaker turns (≥ ~10 distinct `Name:` lines) → strip the `request-id:` prefix lines, save body as `transcript.txt` with the standard header (source, query, request-id, fidelity).
+   - If output is a summary (paragraphs only, no speaker turns) → run the **doubled-strict retry** from `workiq-only.instructions.md`. If still summary-only, save as `transcript-source.md` with the `WARNING: NOT a verbatim transcript` header.
+
+2. **WorkIQ — Copilot recap (SUPPLEMENTARY, always attempt)**:
+   ```
+   workiq ask -q "Get the Copilot meeting recap (decisions, action items, key points) for the Teams meeting \"<subject>\" on <YYYY-MM-DD>. Return the FULL recap card verbatim. Do not summarize."
+   ```
+   - Save as `facilitator-notes.md`. This is supplementary; does NOT replace the transcript.
+
+3. **Chat structured dump (ALWAYS in parallel, allowed)**:
+   - `m365_list_chat_messages(chatId)` → `chat-messages.json` raw + `chat-messages.md` rendered.
+   - Chat-id is sourced from `boundaries.teams.chat_ids[]` in integrations.yml, OR from the WorkIQ meeting-discovery query if not pre-known:
+     ```
+     workiq ask -q "List my Teams meetings between <start> and <end> where the subject contains \"<token>\". Return subject, date, organizer, joinUrl, and Teams chat id."
+     ```
+   - **Allowed exception to workiq-only**: `m365_list_chat_messages` is a structured-data dump for the chat-id'd thread. It is NOT a transcript and NOT a fallback for one. It runs in parallel.
+
+4. **Recording URL discovery (WorkIQ)**:
+   ```
+   workiq ask -q "For the meeting \"<subject>\" on <YYYY-MM-DD>, return the SharePoint Stream recording URL if it exists, and the calendar event body."
+   ```
+   - Save URL(s) to `recording-url.txt`. If a `.mp4` URL is present and `m365_download_file` against the SharePoint item succeeds (size < 200MB), download to `recording.mp4` so a future transcription pass remains possible after the cloud copy expires.
+
+5. **Ask user to paste** (when 1 returns empty AND 2 returns empty):
+   - Prompt user to paste the transcript. Save to `transcript.txt` with header `User-pasted; WorkIQ returned no transcript on <ISO timestamp>`. This is a first-class evidence path, not a degradation.
+
+**Forbidden paths** (do NOT attempt; do NOT log as cascade steps in coverage.md):
+- `m365_get_transcript(joinUrl)` — FORBIDDEN. Use WorkIQ step 1.
+- `m365_get_facilitator_notes(joinUrl)` — FORBIDDEN. Use WorkIQ step 2.
+- `m365_list_meetings`, `m365_list_events` — FORBIDDEN for discovery. Use WorkIQ chat-id discovery in step 3.
+- Graph REST `/me/onlineMeetings/.../transcripts/.../content` — FORBIDDEN. Use WorkIQ step 1.
+
+If steps 1–2 both return empty AND user-paste in step 5 is declined: the meeting is **`transcript-unrecoverable`**. The verbatim folder still exists with chat (if any) + `coverage.md` documenting every WorkIQ attempt with request-ids. The stream/ block carries `Source basis: ❌ no-transcript-recovered-chat-only` and the run-log records `transcript-unrecoverable` as the source-level error signature.
+
+## Required contents of `verbatim/<YYYY-MM-DD-HHMM>_<slug>/`
+
+Slug = lowercase ASCII, spaces→hyphens, max 60 chars, derived from meeting subject. Time = local 24h.
+
+| File | When required | Source |
+|---|---|---|
+| `captured-at.txt` | Always | ISO timestamps + every path attempted (success + failures) + kushi version + REST endpoints used |
+| `coverage.md` | Always | What was captured, what was attempted, what failed, source-basis classification |
+| `transcript.vtt` | When `m365_get_transcript` or Graph REST returned VTT bytes | Raw VTT — highest fidelity; required first attempt |
+| `transcript.txt` | When VTT unavailable but plain text retrieved (WorkIQ full-text or user paste) | Speaker-by-speaker plain text; second preference |
+| `transcript-source.md` | When only a Copilot summary is available | WorkIQ markdown verbatim with `WARNING: NOT a verbatim transcript` header; lowest acceptable transcript-class artifact |
+| `facilitator-notes.md` | When `m365_get_facilitator_notes` returned content | Copilot AI decisions + action items; supplementary, NOT a transcript |
+| `chat-messages.json` | Always when meeting has a chat thread | Full `m365_list_chat_messages` raw API dump |
+| `chat-messages.md` | Always when chat-messages.json exists | Human-readable rendering: sender + ISO timestamp + full body per message |
+| `recording-url.txt` | When any recording URL is found in chat or event body | One URL per line; SharePoint/Stream URLs |
+| `recording.mp4` | When `recording-url.txt` resolves and size < 200MB | `m365_download_file` of the recording binary; last-chance source for re-transcription after cloud expiry |
+| `recap-card.md` | When a Copilot recap card was posted to chat | Verbatim card body |
+| `attachments/` | When chat included shared files | `m365_download_file` of every attachment referenced by chat messages |
+
+**Transcript-class file required.** A verbatim folder MUST contain at least ONE of `transcript.vtt` / `transcript.txt` / `transcript-source.md` to be classified `transcript-complete`. A folder with only `chat-messages.*` (no transcript-class file) is `transcript-missing` — the meeting is flagged in coverage.md and run-log as `transcript-unrecoverable` and the corresponding stream/ block carries `Source basis: ❌ no-transcript-recovered-chat-only`. Self-check D13 enforces both presence and classification.
+
+## Capture-on-pull execution order
+
+Every step writes to `verbatim/` BEFORE producing the curated snapshot. The order is locked and is now WorkIQ-only for transcript capture (no `m365_get_transcript`, no Graph REST):
+
+1. Create `verbatim/<YYYY-MM-DD-HHMM>_<slug>/` and write `captured-at.txt` (started).
+2. **Transcript cascade — WorkIQ-only** (steps 1–5 of the cascade in "Transcript capture cascade — WorkIQ-only" above, in order — do not stop early):
+   - a. WorkIQ full-transcript pull → `transcript.txt` if speaker-turns returned, else `transcript-source.md` (with `WARNING: NOT a verbatim transcript` header) after the doubled-strict retry.
+   - b. WorkIQ Copilot recap → `facilitator-notes.md` (supplementary; not a transcript).
+   - c. WorkIQ recording-URL discovery → `recording-url.txt`; if `.mp4` URL present and size < 200MB, `m365_download_file` against the SharePoint item id → `recording.mp4` (binary download carve-out — WorkIQ does not return binaries).
+   - d. User-paste fallback (first-class) when (a) returns empty after doubled-strict retry → `transcript.txt` with `User-pasted; WorkIQ returned no transcript on <ISO>` header.
+3. **Chat capture (always, in parallel with step 2 — allowed structured-data dump)**: `m365_list_chat_messages(chatId)` → `chat-messages.json` + `chat-messages.md`. If it fails, run the WorkIQ Teams chat-thread prompt as fallback.
+4. Walk chat for attachments → `m365_download_file` each → `attachments/<original-name>` (binary download carve-out).
+5. Walk chat for Copilot recap card → `recap-card.md`.
+6. Classify the verbatim folder per "transcript-class file required" rule above:
+   - `transcript-complete` if any of transcript.vtt / transcript.txt / transcript-source.md is non-empty.
+   - `transcript-missing` otherwise.
+7. Write `coverage.md` with classification + per-path WorkIQ attempt log (every WorkIQ path attempted, with request-id).
+8. Update `captured-at.txt` with `completed_at` + `final_status`.
+9. **Only now** produce the curated snapshot/stream block, citing verbatim files relatively: `[source: Evidence/<alias>/meetings/verbatim/<dir>/transcript.txt · <date>]` (preferred) or `transcript-source.md` (with warning) or `chat-messages.md` if transcript-missing.
+
+If steps 2(a-d) all return empty AND chat in step 3 is also empty: meeting is `unrecoverable`. Mark the per-meeting block `❌ source-expired-or-unrecoverable`, write `coverage.md` listing every WorkIQ attempt with request-ids, and ask the user to paste from memory/notes (paste lands in `transcript.txt` with the user-paste header).
+
+**Note**: `transcript.vtt` is no longer produced because the only paths that yielded raw VTT (`m365_get_transcript` and Graph REST `/transcripts/.../content`) are FORBIDDEN per `workiq-only.instructions.md`. Existing pre-v3.12.0 `transcript.vtt` files in verbatim/ folders remain valid evidence and continue to satisfy the transcript-complete classification — they just won't be created by new runs.
+
+## Why a folder per meeting (not a flat file)
+
+- Multiple artifact kinds per meeting (chat + transcript + recap + attachments) — a folder is the natural shape.
+- Attachments are binary; they don't belong inline in a markdown file.
+- Future capture additions (e.g. screen-share thumbnails, whiteboard exports) shouldn't break the layout.
+- Easy to dedupe by directory existence on subsequent runs.
+
+## Naming
+
+- Folder: `<YYYY-MM-DD>-<HHMM>_<slug>` — e.g. `2026-05-13-1530_fde-intake-john-deere`
+- Slug rules: lowercase, ASCII, spaces and punctuation → single hyphen, collapse repeats, trim trailing hyphens, max 60 chars.
+- Time: meeting start time in the user's local timezone (per `m365_get_mailbox_settings`), 24h, no separator.
+- If two meetings share start time + slug: append `-2`, `-3`, etc.
+
+## Citation convention
+
+Inside the curated snapshot/stream files, cite verbatim files with the kushi standard format:
+
+```
+[source: Evidence/<alias>/meetings/verbatim/2026-05-13-1530_fde-intake-john-deere/chat-messages.md · 2026-05-13]
+```
+
+The curated snapshot is the assertion; the verbatim file is the evidence. The two must always travel together.
+
+## What this is NOT
+
+- This is NOT a backup of OneNote, email, or SharePoint. Those sources persist; we cite them in place.
+- This is NOT a place for AI-generated summaries. `transcript-source.md` from WorkIQ is allowed because WorkIQ returns it as the only available form of the transcript; everything in verbatim/ must be source-derived, not Kushi-derived.
+- This is NOT optional based on meeting size. A 5-minute side meeting with 3 chat messages still gets a verbatim folder.
+
+## Self-check enforcement (D13)
+
+`plugin/skills/self-check/run.ps1` deep-mode rule D13 walks every per-meeting block in `Evidence/*/meetings/stream/*.md` and emits:
+
+- **D13.a** — verbatim/<dir> missing entirely for a referenced meeting (HARD defect).
+- **D13.b** — verbatim/<dir> exists but contains only `captured-at.txt` / `coverage.md` (cascade failed silently; HARD defect).
+- **D13.c** — verbatim/<dir> contains chat-messages.* but no transcript-class file (`transcript.vtt`, `transcript.txt`, or `transcript-source.md`). Surfaces as `transcript-missing` warning. Not a hard defect if `coverage.md` documents the exhaustive cascade was attempted; IS a hard defect if any transcript path was skipped.
+
+## Anti-patterns (defects)
+
+1. **Verbatim folder absent** — per-meeting block in stream/ with no sibling verbatim/<...>/ dir. Hard defect.
+2. **Verbatim folder empty / captured-at-only** — capture cascade failed silently. Hard defect; surface in coverage.md and run-log.
+3. **Chat-only treated as transcript** — verbatim/ contains only chat-messages.* but coverage.md claims `transcript-complete`. Hard defect (misclassification of source basis).
+4. **Transcript cascade stopped early** — first path (m365_get_transcript) failed and skill jumped straight to chat without trying Graph REST fallback + WorkIQ strict pull + recording URL discovery. Hard defect — the cascade is exhaustive, not first-success.
+5. **Inline transcript in stream/** — pasting raw VTT into the stream file instead of writing to verbatim/transcript.vtt. Defect; bloats the curated file and obscures the audit trail.
+6. **Curated-only refresh** — refresh-project re-runs pull-meetings without re-checking that the verbatim folder is still intact (in case of accidental cleanup). The orchestrator should warn if verbatim/ for an existing meeting disappeared between runs.
+7. **AI-narrative substitution** — when no transcript and no chat exist, writing an inferred narrative as `transcript-source.md`. Forbidden; per `verbatim-by-default.instructions.md` anti-pattern #8.
+
+## Apply
+
+`pull-meetings/SKILL.md` v2.2.0+ MUST cite this instruction in its front contracts blockquote. Templates `meetings-stream.template.md` and `meetings-series-index.template.md` MUST reference the verbatim/ folder location. Template `meeting-verbatim.template.md` defines the standard contents of a verbatim folder.

package/plugin/instructions/run-reports.instructions.md

@@ -0,0 +1,129 @@
+---
+applyTo: "**"
+description: "Run-reports rule — every bootstrap and refresh MUST write a per-user, per-run report under <project>/Evidence/<alias>/refresh-reports/ so each contributor can see what was done when, what worked, what didn't, and what changed."
+---
+
+# Run-reports (HARD RULE)
+
+Every `bootstrap-project` and `refresh-project` invocation MUST produce a per-user, per-run report file in addition to updating `<project>/bootstrap-status.md` and `Evidence/run-log.yml`.
+
+## Why
+
+`bootstrap-status.md` is the **current durable state** (per bootstrap-status-format.instructions.md — short, scannable, no run narrative).
+
+`run-log.yml` is **structured history** (machine-readable, watermarks + per-source status).
+
+Neither tells a user "what just happened in my last run" in narrative form. The per-user run report fills that gap. It's the contributor's audit trail of **what the agent did on their behalf** — what was pulled, what worked, what was skipped, what gaps remain, and what to do next.
+
+Critical for multi-user projects: each contributor's runs are independent, and each user needs to see their own report without scrolling through everyone else's history.
+
+## Where it lives
+
+```
+<engagement-root>/<project>/Evidence/<alias>/refresh-reports/
+  YYYY-MM-DD-HHmm_<mode>.md
+```
+
+- `<alias>` — the contributor running the skill (from `~/.copilot/project-evidence.yml#alias`).
+- `<mode>` — one of `bootstrap`, `refresh`, `force-refresh`, `consolidate`.
+- Timestamp uses the **start time** of the run, in local time, format `YYYY-MM-DD-HHmm` (no seconds, no timezone — local-time prefix is enough for chronological sort).
+
+Newest at the bottom of `Get-ChildItem` listings (sortable by name = sortable by time).
+
+## Required structure
+
+```markdown
+# Refresh Report — <project> — <YYYY-MM-DD HH:mm local>
+
+- **Mode**: bootstrap | refresh | force-refresh | consolidate
+- **Contributor**: <alias>
+- **Window**: <effective window per source>
+- **Profile**: standard | full | core
+- **Started**: <ISO timestamp>
+- **Ended**: <ISO timestamp>
+- **Duration**: <Hh Mm Ss>
+
+## What was done
+
+| Source | Action | Items pulled | Outcome | Notes |
+|---|---|---|---|---|
+| ado | snapshot+stream | 2 WIs / 6 comments / 24 revisions | resolved | ... |
+| crm | snapshot | 1 record / 24 annotations | resolved | ... |
+| email | stream | 47 messages / 12 threads | populated | ... |
+| teams | stream | ... | ... | ... |
+| meetings | snapshot+stream | ... | ... | ... |
+| onenote | snapshot | ... | ... | ... |
+| sharepoint | snapshot+stream | ... | ... | ... |
+
+## Resolutions this run
+
+For each ID/folder/section newly resolved during this run, one bullet:
+- `ado.engagement_id` resolved to `96944` (HCA - Engagement) — pinned to integrations.yml + m365-mutable.json.
+- `crm.record_id` resolved to `e561b31e-...` — pinned + env override applied (iscrm.crm.dynamics.com).
+
+## Cleanups this run
+
+Per `cleanup-on-resolution.instructions.md`. List entries pruned when a resolution succeeded:
+- Removed stale `ado.last_discovery_result: 'no-match'` from integrations.yml (resolved this run).
+- Removed `## Current Bootstrap Outcome` note `ADO context sync pending` from bootstrap-status.md.
+
+## Learnings appended
+
+Per `capture-learnings.instructions.md`. List new entries written to `<KUSHI_ROOT>/plugin/learnings/<file>.md`:
+- `learnings/crm.md` — "Custom entities don't expose Annotations as a navigation property" (HCA / pull-crm).
+- `learnings/ado.md` — "$top=500 exceeds permissible range on workItems updates endpoint" (HCA / pull-ado).
+
+## Skips & gaps
+
+What was deliberately skipped or couldn't be retrieved, with reason:
+- `sharepoint` — no folder pinned in `integrations.yml#boundaries.sharepoint.folder_paths`; root-fallback would be too noisy. ACTION: ask user to pin folder, or accept root-scope on next run.
+- `meetings` transcripts — 2 of 5 meetings had no transcript; chat-reconstruction used.
+
+## Files written
+
+| Path | Bytes | Type |
+|---|---|---|
+| `Evidence/<alias>/ado/snapshot/engagement-96944.md` | 18,420 | snapshot |
+| `Evidence/<alias>/ado/snapshot/items/96571.md` | 4,210 | snapshot |
+| `Evidence/<alias>/crm/snapshot/.../e561b31e-...md` | 24,180 | snapshot |
+| `Evidence/<alias>/email/stream/2026-05-04_email-stream.md` | 38,910 | stream |
+| ... | | |
+
+## Next steps for this contributor
+
+Plain-language list. What the contributor should do next, e.g.:
+- Review `Evidence/<alias>/email/stream/2026-05-04_email-stream.md` — 3 emails from James Gibbings have substantive customer needs that should land in `State/00_overview.md`.
+- Pin a SharePoint folder for HCA in `integrations.yml#boundaries.sharepoint.folder_paths` so next refresh covers it.
+- Re-run with `force-refresh HCA` if today's run looks partial.
+
+---
+
+_Generated by kushi <version>. See `<KUSHI_ROOT>/plugin/instructions/run-reports.instructions.md` for the format spec._
+```
+
+## When sections are empty
+
+Same rule as evidence-thoroughness: write `_None this run._` rather than omit a section. Empty section signals "checked, none" vs missing section signals "skipped".
+
+## Relationship to other artifacts
+
+| Artifact | What it captures | Lifecycle |
+|---|---|---|
+| `<project>/bootstrap-status.md` | Current durable project state | Overwritten each bootstrap/refresh; short |
+| `<project>/Evidence/run-log.yml` | Structured per-source history (watermarks, item counts, runs[]) | Append-only history block + replaceable per-source summary |
+| `<project>/Evidence/<alias>/refresh-reports/<ts>_<mode>.md` | Narrative per-user per-run report | Append-only (one new file per run); never overwritten |
+| `<KUSHI_ROOT>/plugin/learnings/<source>.md` | Cross-project doctrine (API quirks, fixes) | Append-only, kushi-repo-wide |
+
+The four are complementary; do not collapse them.
+
+## When the report is generated
+
+- `bootstrap-project` — at the END of the run, after all per-source pulls have completed (success or with coverage gaps). Write the file before announcing "bootstrap complete" to the user.
+- `refresh-project` — same, at the END. Even if no source had new data ("no new evidence — state unchanged"), write a 1-section report saying so. The user needs to see the run happened.
+- `force-refresh` (per `force-refresh.md` how-to) — same, with `Mode: force-refresh` so the report distinguishes deliberate re-pulls from incremental refreshes.
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` deep-mode rule **D10** (added v3.7.6):
+- Warns if `<project>/Evidence/<alias>/` exists but `refresh-reports/` is missing or empty after a run.
+- Warns if `run-log.yml` shows a `runs[]` entry from today but no matching `refresh-reports/<today's-prefix>_*.md` exists.