kushi-agents 3.4.2 → 3.12.1

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.

package/plugin/instructions/scope-boundaries.instructions.md

@@ -0,0 +1,218 @@
+---
+applyTo: "**"
+description: "Scope & Boundaries — every WorkIQ ask MUST cite a configured boundary; CRM/ADO require config.yml. Discovery is bounded, not free-form. No improvisation, no figure-it-out."
+---
+
+# Scope & Boundaries (HARD RULE — partial-determinism contract)
+
+Kushi's credibility depends on **knowing where it is allowed to look** and refusing
+to improvise outside that perimeter. WorkIQ is powerful but fuzzy; Microsoft Graph
+is broad and easy to mis-scope; CRM and ADO are tenant-specific. Without explicit
+boundaries, the same question can return different evidence on different runs — and
+every cited assertion becomes "trust me, I asked WorkIQ".
+
+This file defines the contract that every `pull-*` skill, every WorkIQ ask, every
+host-fallback Graph call, and every CRM/ADO probe MUST honor.
+
+## The contract — three rules, no exceptions
+
+### Rule 1 — Every ask cites a configured boundary
+
+Before issuing **any** WorkIQ query, `m365_*` host call, Graph REST call, or CRM/ADO
+REST call, the skill MUST resolve the boundary it is operating inside from
+`<engagement-root>/<project>/integrations.yml boundaries:` (per-source) or the
+global `<engagement-root>/.project-evidence/{crm,ado}/config.yml` (auth +
+tenant + org). The resolved boundary MUST be recorded in the evidence file's
+`## Source Basis` block, e.g.:
+
+```
+## Source Basis
+- path: workiq
+- boundary: integrations.yml#boundaries.email.mailboxes=["Inbox","FDE-Intake"]
+- boundary: integrations.yml#boundaries.email.sender_domains=["microsoft.com","hcahealthcare.com"]
+- boundary: integrations.yml#boundaries.date_window_days=30
+```
+
+A query issued without a citable boundary is a **defect** — the skill must refuse
+and ask the user to update `integrations.yml boundaries:` (or the relevant
+config.yml) instead of guessing.
+
+### Rule 2 — No source is queried outside its boundary
+
+A boundary is **inclusive only**: only sources / mailboxes / channels / sections /
+folders / domains explicitly listed are queried. There is no "and also widen if I
+don't find enough" fallback. If the boundary is too narrow and a refresh comes
+back light, the skill writes a Coverage Notes entry pointing at the boundary that
+limited the scope and asks the user to widen it next run — it does NOT widen on
+its own.
+
+This is the partial-determinism contract: **the user controls scope; Kushi controls
+depth.** Once the user has set the boundary, every refresh under that boundary
+returns evidence over the same surface — no run-to-run drift.
+
+### Rule 3 — CRM & ADO require explicit config.yml; no inference, no narration-from-email
+
+`pull-crm` and `pull-ado` (and the downstream `propose-ado-update` /
+`apply-ado-update`) are **HARD-fail** without their global config.yml:
+
+| Skill | Hard prerequisite | Failure message (verbatim) |
+|---|---|---|
+| `pull-crm` | `<engagement-root>/.project-evidence/crm/config.yml` exists with non-placeholder `environmentUrl` | `crm-config-missing — drop a filled config.yml at <engagement-root>/.project-evidence/crm/config.yml. See plugin/templates/init/crm-config.template.yml.` |
+| `pull-ado` | `<engagement-root>/.project-evidence/ado/config.yml` exists with non-placeholder `organization` AND `defaultProject` | `ado-config-missing — drop a filled config.yml at <engagement-root>/.project-evidence/ado/config.yml. See plugin/templates/init/ado-config.template.yml.` |
+| `propose-ado-update` | both above + `integrations.yml ado.engagement_id > 0` | per `propose-ado-update/SKILL.md` Prerequisites table |
+
+Pre-v3.7.0 behavior allowed `pull-crm` to "narrate from email" when the live
+config was missing — that is **explicitly forbidden as of v3.7.0**. CRM evidence
+must come from CRM. Email evidence stays in the email source. Cross-source
+synthesis happens at the consolidation step, not at the pull step.
+
+## The boundaries schema
+
+Lives in `<engagement-root>/<project>/integrations.yml` under a top-level
+`boundaries:` key. Every per-source key is **optional** — but if a source's
+boundary is omitted, that source is **disabled** for the project (not silently
+queried with defaults).
+
+```yaml
+boundaries:
+  date_window_days: 30                          # default lookback window for streams (snapshot ignores)
+
+  email:
+    mailboxes:                                  # required if email enabled
+      - "Inbox"
+      - "Inbox/FDE Intake"                      # well-known names OR folder IDs
+    sender_domains:                             # optional — narrows by sender
+      - "microsoft.com"
+      - "hcahealthcare.com"
+    subject_keywords:                           # optional — additional narrowing
+      - "HCA"
+      - "FE-2026-001458"
+
+  teams:
+    chat_ids:                                   # required if teams enabled — pinned, not fuzzy-discovered
+      - "19:meeting_…@thread.v2"
+    channel_ids: []                             # required for channel evidence (empty = no channels)
+
+  meetings:
+    series_join_urls:                           # required if meetings enabled — pinned, not subject-keyword-fuzzy
+      - "https://teams.microsoft.com/l/meetup-join/…"
+    organizer_emails: []                        # optional — additional filter
+
+  onenote:
+    section_file_ids:                           # required if onenote enabled — drive-item IDs (narrowest)
+      - "3d0ad388-fd6b-45a8-8619-60dd709b7ade"
+    notebooks: []                               # optional — broaden if needed; section_file_ids preferred
+
+  sharepoint:
+    local_folders:                              # required if sharepoint enabled
+      - "C:\\…\\HCA"
+    site_urls: []                               # optional — for online-only docs
+    drive_ids: []                               # optional — Graph-direct access
+
+  crm:
+    entity_sets:                                # optional — overrides global defaultEntitySet
+      - "msdyn_engagements"
+    record_ids:                                 # required if crm enabled — pinned record GUIDs
+      - "<guid>"
+    request_ids:                                # OR pinned FE-XXXXX IDs
+      - "FE-2026-001458"
+
+  ado:
+    area_paths:                                 # required if ado enabled
+      - "ISE-Engagements\\HCA"
+    iteration_paths: []                         # optional — for sprint-scoped queries
+    initiative_query: ""                        # optional — saved WIQL query ID
+    work_item_ids: []                           # optional — pin specific work items
+```
+
+### Why this shape
+
+- **Per-source, not per-skill** — one place to read; every `pull-*` consumes from
+  `boundaries.<source>`.
+- **IDs preferred over names** — `chat_ids` over `chat_topics`, `section_file_ids`
+  over `section_names`, `record_ids` over `title_contains`. IDs survive renames;
+  names drift.
+- **Required vs optional is explicit** — the schema doc above marks each.
+  Bootstrap scaffolds the required keys; missing required keys = source disabled.
+- **No global default boundaries** — each project declares its own; the only
+  cross-project default is `date_window_days`. Engagements differ; boundaries
+  must too.
+
+## How `pull-*` skills MUST consume the boundary
+
+Each per-source skill follows this template (already enforced in v3.7.0 SKILL.md
+rewrites):
+
+```
+1. Resolve boundary:
+   - read integrations.yml#boundaries.<source>
+   - if missing or empty for a required key → REFUSE with explicit message:
+     "<source>-boundary-missing — add boundaries.<source>.<key> to
+     <engagement-root>/<project>/integrations.yml. See doctrine in
+     plugin/instructions/scope-boundaries.instructions.md."
+2. Issue every query scoped to the resolved boundary:
+   - WorkIQ ask: include boundary keys in the prompt
+     ("…in mailbox 'Inbox/FDE Intake' from senders @microsoft.com,@hcahealthcare.com…")
+   - m365_* host call: pass folder/chat/section/site IDs as filter args
+   - Graph REST: use exact resource paths, not /search?
+3. Record the boundary in `## Source Basis` of every evidence file written.
+4. If the boundary is too narrow (zero hits): write a Coverage Notes entry
+   citing the limiting boundary key. Do NOT widen the query.
+```
+
+## Bootstrap behavior (per `bootstrap-project/SKILL.md`)
+
+On first run for a new project, bootstrap MUST:
+
+1. Create `<engagement-root>/<project>/integrations.yml` with the `boundaries:`
+   block scaffolded (every source as `_required: true` with empty value list).
+2. Detect which sources have enough hints in `m365-mutable.json` to auto-populate
+   the boundary (e.g. a previously discovered `section_file_id` populates
+   `boundaries.onenote.section_file_ids` automatically).
+3. For sources where bootstrap cannot auto-populate, write the source as
+   **disabled** (`enabled: false`) with a one-liner in `OPEN-QUESTIONS-DRAFT.md`
+   asking the user to fill the boundary and re-enable.
+4. For CRM and ADO, ALSO check that the global `<engagement-root>/.project-evidence/{crm,ado}/config.yml`
+   exists and has non-placeholder values; if not, scaffold from
+   `plugin/templates/init/{crm,ado}-config.template.yml` and park in
+   `OPEN-QUESTIONS-DRAFT.md` with the path the user needs to fill.
+
+Bootstrap **never silently widens** an empty boundary by inferring from the rest
+of the corpus. Empty boundary = source disabled = explicit user action required.
+
+## Coverage Notes — boundary-aware
+
+Every per-entity Coverage Notes block (per `evidence-thoroughness.instructions.md`)
+MUST now also enumerate which boundaries were hit and which were exhausted /
+empty. Example:
+
+```
+## Coverage Notes
+- Boundary: integrations.yml#boundaries.email.mailboxes=["Inbox","Inbox/FDE Intake"] — HIT (12 threads)
+- Boundary: integrations.yml#boundaries.email.sender_domains=["microsoft.com","hcahealthcare.com"] — HIT (all 12 in-scope)
+- Boundary: integrations.yml#boundaries.date_window_days=30 — HIT (full window)
+- Source not queried: any mailbox outside boundary (by design — see scope-boundaries.instructions.md)
+```
+
+## What this rule replaces
+
+- The pre-v3.7.0 "WorkIQ-first, fall back to Graph, then ask user" cascade is
+  REPLACED by "WorkIQ-only within boundary, ask user when WorkIQ fails after
+  doubled-strict retry." Per `workiq-only.instructions.md` (v3.11.0+), Graph /
+  `m365_*` are FORBIDDEN as fallbacks for in-scope M365 sources. There is no
+  scope expansion at any tier.
+- The pre-v3.7.0 `pull-crm` "narrate from email" fallback is REMOVED. CRM
+  evidence requires CRM source.
+- The pre-v3.7.0 fuzzy-discovery loops in `pull-ado` (title_contains, tags_contains)
+  are PRESERVED but only run inside `boundaries.ado.area_paths`.
+
+## Cross-references
+
+- `evidence-thoroughness.instructions.md` — depth bar (orthogonal: depth applies
+  inside the boundary; this rule defines the boundary).
+- `workiq-only.instructions.md` — query strategy (now scoped per Rule 1; Graph /
+  `m365_*` fallbacks FORBIDDEN for in-scope M365 sources).
+- `bootstrap-project/SKILL.md` — scaffolding the boundaries block.
+- `pull-*/SKILL.md` (all 7) — Boundaries (REQUIRED) sub-section enforces Rule 1+2.
+- `pull-crm/SKILL.md` + `pull-ado/SKILL.md` — Hard prerequisites enforce Rule 3.
+- `propose-ado-update/SKILL.md` — Prerequisites table (already enforces ADO config + engagement_id).

package/plugin/instructions/snapshot-vs-stream.instructions.md

@@ -29,6 +29,8 @@ Every source produces evidence in TWO distinct shapes. Mixing them is a defect.
 
 ## Storage layout
 
+> **Path is canonical** — every per-source artifact lives under `Evidence/<alias>/<source>/` and **nowhere else** under `<project>/`. Sibling folders like `<project>/email-context/`, `<project>/notes/`, `<project>/_Weekly Summaries/` are FORBIDDEN per `evidence-layout-canonical.instructions.md`. Bootstrap and refresh auto-migrate any legacy folders into `Evidence/<alias>/<source>/_legacy_*_pre-bootstrap/`.
+
 ```
 <engagement-root>/<project>/Evidence/<alias>/
    email/