kushi-agents 3.4.2 → 3.13.0

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/

package/plugin/instructions/update-ledger.instructions.md

@@ -0,0 +1,132 @@
+---
+applyTo: "**"
+description: "Write-path doctrine for Kushi. Any skill that writes outside the engagement folder (currently: ADO Initiative field + Discussion comment) MUST flow through propose → review/approve → apply → append-to-ledger, with citation, confidence, fingerprint, and a reverse op recorded for every applied item. Read-only refresh and aggregation are NOT subject to this gate."
+---
+
+# Update Ledger — Write-Path Doctrine
+
+Kushi is read-first. Aggregation, refresh, ask, and report skills produce no external side effects — they only write inside the engagement folder under `Evidence/`, `State/`, `Reports/`, etc.
+
+The **write path** — currently `apply-ado-update`, future possibly CRM / OneNote / SharePoint — is governed by this file. Any new write skill must follow these rules and pass self-check rule **C13** (write-path safety).
+
+## The 4 stages, every time
+
+```
+propose  →  review (or auto-allowlist)  →  apply  →  append to ledger
+```
+
+No write skill skips a stage. No write skill writes without a corresponding ledger entry in the same operation.
+
+## Where the ledger lives
+
+```
+<engagement-root>/<project>/ado-updates/<YYYY-MM-DD>/
+  proposed.md         ← from propose-ado-update (Markdown, human-reviewable)
+  ledger.jsonl        ← from apply-ado-update (one line per applied write)
+  planned.jsonl       ← preview-stub only: writes that would have happened
+  attachments/        ← optional: payloads sent to ADO (raw HTML for comments)
+```
+
+One subfolder per run date, **inside the project folder** (sibling to `Evidence/`, `State/`, `Reports/`). Files are append-only — never edit a past ledger entry. Mistakes are corrected by appending a `revert` entry (see "Reversal").
+
+## Ledger entry schema
+
+One JSON object per line (JSONL), one entry per applied write. Required fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `timestamp` | ISO-8601 UTC | When the write was sent. |
+| `initiativeId` | int | ADO work item ID written to. (Same value as `integrations.yml ado.engagement_id`.) |
+| `org`, `project` | string | ADO org + project (so a ledger entry is unambiguous standalone). |
+| `kind` | `"field"` \| `"comment"` | What was written. |
+| `fieldRefName` | string \| null | For `kind: "field"` — the ADO reference name. Null for `comment`. |
+| `currentValue` | string | Value just before the write (from the optimistic-lock pre-fetch). |
+| `proposedValue` | string | Value sent in the write. |
+| `appliedValue` | string | Value confirmed in the write response. May differ from proposed if ADO normalized it. |
+| `revBefore`, `revAfter` | int | ADO `/rev` values before/after — together with `currentValue` they form the reversal anchor. |
+| `approver` | string | `<alias>` for human, `auto:<rule-name>` for allowlisted auto-apply, never empty. |
+| `confidence` | `"high" \| "medium" \| "low"` | Carried forward from `proposed.md`. |
+| `evidenceCitations` | string[] | Each entry is `<source-path> · <YYYY-MM-DD>`. Min 1; entries with 0 citations MUST NOT be approved. |
+| `fingerprint` | string | Deterministic, derived from project + week + initiativeId + kind. Used by duplicate detection on the next run. Format: `kushi-weekly-<YYYY-WW>-<initiativeId>-<kind>`. |
+| `reverseOp` | object | What to do to undo this write. See "Reversal". |
+| `result` | `"ok" \| "rev-mismatch" \| "duplicate-skipped" \| "error"` | Final disposition. |
+| `errorMessage` | string \| null | Populated only when `result: "error"`. |
+| `kushiVersion` | semver | The version of `kushi-agents` that wrote this entry. |
+
+Anything else (correlation IDs, request payload hashes) is allowed but optional.
+
+## Reversal
+
+Every ledger entry includes a `reverseOp` that, applied alone, restores the prior state:
+
+```json
+"reverseOp": {
+  "kind": "field",
+  "fieldRefName": "Custom.FDEStatusSummary",
+  "patch": [
+    { "op": "test", "path": "/rev", "value": <revAfter> },
+    { "op": "add", "path": "/fields/Custom.FDEStatusSummary", "value": "<currentValue>" }
+  ]
+}
+```
+
+For comments, the reverse op is a `DELETE` of the comment ID returned by the POST:
+
+```json
+"reverseOp": {
+  "kind": "comment",
+  "commentId": 9871,
+  "method": "DELETE",
+  "url": "https://dev.azure.com/{org}/{project}/_apis/wit/workItems/{id}/comments/9871?api-version=7.1-preview.4"
+}
+```
+
+A future `revert-ado-update` skill (not in v0.1.0-preview) will read the latest ledger and apply reverse ops in reverse chronological order, again gated by user approval.
+
+## Approval rules (HARD)
+
+1. **No write without an entry in `proposed.md`.** Apply skills MUST refuse to write items that aren't in the proposal, even if asked.
+2. **No write without ≥ 1 citation.** Items with empty `evidenceCitations` are rejected at the gate.
+3. **No silent overwrite of drift.** If the live ADO value differs from the `currentValue` recorded in `proposed.md`, the apply step MUST stop and require explicit re-approval (showing both values).
+4. **Auto-apply is opt-in, narrow, and per-field.** Allowed only when:
+   - `writes.<kind>.autoApply: true` in `<engagement-root>/.kushi/ado-update.yml`, AND
+   - `confidence == "high"`, AND
+   - The proposed value matches a configured pattern (e.g., `<MMM YYYY>: <text>` for `statusSummary` with `strategy: append-month`).
+   Items failing any of these auto-apply criteria fall back to interactive approval.
+5. **No bulk apply across projects.** One project per invocation. (Iterating projects is the orchestrator's job; the apply skill itself is single-project.)
+6. **No write outside the allowlist.** The apply skill must reject any field reference name or work-item ID not declared in the project's `integrations.yml ado.writes.allowlist.fields` (and the work-item ID must equal `ado.engagement_id`).
+
+## Duplicate detection
+
+Before writing a comment, fetch the latest N comments on the work item and look for the Kushi fingerprint line:
+
+```
+— Generated by Kushi v<version> · proposed <YYYY-MM-DD> · ledger:ado-updates/<YYYY-MM-DD>/ledger.jsonl
+```
+
+If a comment with the same `kushi-weekly-<YYYY-WW>-<initiativeId>-comment` fingerprint exists for the current ISO week → record `result: "duplicate-skipped"` in the ledger and do NOT write again. Field updates use idempotency on the value itself (same `<MMM YYYY>: ...` line not duplicated).
+
+## What is NOT subject to this doctrine
+
+- `aggregate`, `bootstrap`, `refresh`, `consolidate`, `pull-*` — pure reads from M365 + CRM + ADO. They write to the engagement folder only.
+- `ask`, `fde-*`, `state`, `project-status` — pure local file operations.
+- `self-check`, `intro` — never write outside the kushi install.
+
+The gate exists because **writing into someone else's system of record demands an audit trail and a path back**. Reads inside the engagement folder do not.
+
+## Self-check coverage
+
+A future self-check rule **C13: write-path safety** will verify:
+
+- Every skill folder whose `SKILL.md` contains the word `PATCH` or `POST` (HTTP write verbs) outside a fenced quote → must reference this instruction file in its `## References` section.
+- Every such skill must declare its allowlist source (config file path) explicitly in the SKILL.md.
+- The repo MUST NOT contain a skill that issues an ADO write call without a corresponding `ledger.jsonl` append in the same code path.
+
+C13 is not yet implemented in `self-check/run.ps1` — added when `apply-ado-update` graduates from preview-stub to write-enabled.
+
+## References
+
+- `propose-ado-update` SKILL.md — produces the `proposed.md` this doctrine governs.
+- `apply-ado-update` SKILL.md — the only code path authorized to write to ADO; consumes `proposed.md`, appends to `ledger.jsonl`.
+- `azure-auth-patterns.instructions.md` — pre-flight + token + tenant guards that protect every write.
+- `side-by-side-config.instructions.md` — `integrations.yml ado.writes:` follows the same template-vs-live pattern.

package/plugin/instructions/verbatim-by-default.instructions.md

@@ -0,0 +1,73 @@
+---
+applyTo: "**"
+description: "Verbatim-by-default rule — every pull-* skill captures full bodies and full content as the default mode. Headlines / one-line summaries / 'preview only' are defects. The user does NOT have to ask for detail; detail is the contract."
+---
+
+# Verbatim-by-default (HARD RULE)
+
+Every `pull-<source>` skill captures **full content verbatim** as its default mode. The user does NOT have to say "more detail" or "give me the full body" — that's the contract, every time.
+
+This restates and hardens the existing thoroughness contract in `evidence-thoroughness.instructions.md` with one additional rule: **the user asking for detail is a defect signal, not a feature request**.
+
+## What "verbatim" means per source
+
+| Source | Default capture |
+|---|---|
+| Email | Full body of every message in scope, every header, every attachment metadata. NOT just subject + sender + 200-char preview. |
+| Teams chats | Every message in every in-scope thread, full text, sender, timestamp, reactions, attachments, replies. NOT just an outcome line. |
+| Meetings | Full transcript walk-through with verbatim quotes + timestamps, every attendee, every artifact link. NOT a 3-bullet "what happened". |
+| OneNote | Full page bodies, every page in scope, last-modified + author. NOT page titles only. |
+| SharePoint | Full extracted body of every key file + every recently-modified file (top-N) + every user-pinned file. NOT a folder tree alone. |
+| CRM | Every field the API returns, all long-text fields verbatim, every annotation/note verbatim, every related activity. NOT a 5-field summary. |
+| ADO | Engagement + every child WI; per-item all fields verbatim, every comment verbatim, every revision verbatim. NOT parent-only. |
+
+## Anti-patterns (defects to refuse, not negotiate)
+
+The following are defects in any `pull-*` output. If the runtime detects one, it MUST auto-retry with stricter prompting per `thoroughness-detector.instructions.md` rather than ship the thin output.
+
+1. **Email preview-only** — capturing only `bodyPreview` (200 chars) instead of `body`. Defect.
+2. **"And N more"** — any phrase like "...and 12 more emails", "10 of 47 shown", "see source for rest". Defect.
+3. **Single-message-per-thread** — collapsing a 30-message thread into one "summary" line. Defect.
+4. **Speaker-name only transcripts** — listing meeting attendees and decisions without the chronological verbatim quotes. Defect.
+5. **Folder tree without bodies** — SharePoint snapshot that lists files but extracts no key-file bodies. Defect.
+6. **CRM "key fields"-only** — pulling only title + status + customer instead of every populated field + all long-text + all annotations. Defect.
+7. **ADO parent-only** — pulling the engagement WI without expanding the tree to every child + per-item comments + per-item revisions. Defect.
+8. **Inferred narrative as substitute for body** (NEW v3.7.6.1) — when a source returns no body / `page-body-unavailable` / `body-not-extractable`, writing an "AI Narrative Summary" that infers what the artifact "likely contains" from adjacent evidence (other emails, chat traffic, page titles, file names). This is fabrication, not capture, and it pollutes the citation chain. The correct behavior is to write the header + the unavailable marker + a `next_step` asking the user to paste — and STOP. Empty is the correct state until the body is actually retrieved.
+9. **Meeting summary without sibling verbatim/ folder** (NEW v3.10.0) — meetings are the one EXPIRING evidence class. A per-meeting curated block in `Evidence/<alias>/meetings/stream/*.md` without a matching `Evidence/<alias>/meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` directory is a defect even if the curated block is rich. See `meetings-verbatim-required.instructions.md` for the full contract and self-check rule D13. Rationale: Teams recordings and VTT transcripts are purged by tenant retention (often within 60 days). If the only artifact captured is the curated summary, the underlying evidence is unrecoverable once the source expires.
+
+## The "you should do better" defect
+
+When a user reads evidence and says any of:
+
+- "you should do better and get details better"
+- "this is too light"
+- "where's the detail from `<source>`?"
+- "i want detail by default"
+- "why is nothing captured?"
+
+— that is the **highest-severity** thoroughness defect. Treat it as a hard rule violation, not a preference. Specifically:
+
+1. The skill that produced the thin output is at fault. Identify which `pull-*` skill underdelivered.
+2. Re-pull from source at full depth in the same turn (no asking for confirmation).
+3. Append a `learnings/<source>.md` entry per `capture-learnings.instructions.md` describing the miss + the fix.
+4. If the miss was a doctrinal gap (skill spec didn't require the thing), update the SKILL.md or this instruction in the same commit.
+
+## Orchestrator contract
+
+`bootstrap-project` and `refresh-project` MUST dispatch every enabled `pull-<source>` skill that has its boundary satisfied. **Skipping a source silently is a defect** — if a source is not pulled, the orchestrator must:
+
+1. Log the skip with reason (`boundary-missing`, `auth-blocked`, `user-disabled`) in the per-user refresh report (per `run-reports.instructions.md`).
+2. Mark the source `not-pulled-this-run` in `bootstrap-status.md`'s Context Artifact Status table.
+3. Suggest the fix in the report's "Skips & gaps" section.
+
+A run that pulled CRM + ADO but silently omitted email is a defect of the orchestrator, even if every individual `pull-*` it did invoke was perfect.
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` deep-mode rule **D11** (added v3.7.6):
+- For each per-user refresh report, warn if any source listed in `<project>/integrations.yml#boundaries.<source>` (with non-empty boundary) is absent from the report's "What was done" table.
+- Warn on per-source evidence files smaller than the per-source minimum byte threshold (defaults: email-stream 5KB / week, teams-stream 5KB / week, meetings-stream 8KB / week, onenote-snapshot 3KB / page, sharepoint key file 2KB / file, crm-snapshot 4KB / record, ado-snapshot 3KB / WI). Below threshold suggests headlines-only.
+
+## Apply
+
+Every `pull-*` SKILL.md MUST reference this instruction file in its frontmatter or first paragraph alongside `evidence-thoroughness.instructions.md`. The two are co-equal.

package/plugin/instructions/workiq-first.instructions.md

@@ -1,47 +1,31 @@
 ---
 applyTo: "**"
-description: "WorkIQ is the required path for all M365 + CRM + ADO source pulls. Graph REST is NOT a routine fallback; ask the user to paste when WorkIQ can't answer."
+description: "DEPRECATED as of kushi v3.11.0. The canonical M365 doctrine is workiq-only.instructions.md. This file is preserved as a stub redirect — do NOT use any of the old Graph-REST-fallback language; it is OVERRIDDEN by workiq-only."
 ---
 
-# WorkIQ-required rule (HARD RULE)
+# DEPRECATED — see `workiq-only.instructions.md`
 
-WorkIQ is the **required** path for every source pull. Graph REST has known issues in this workspace (token rejection, OneNote 40001, Dataverse 501/415, SharePoint 403, mailbox throttling) and **MUST NOT** be used as a routine fallback — doing so produces thin metadata-only evidence that violates `evidence-thoroughness.instructions.md`. WorkIQ gives richer extraction (full page bodies, full transcript text, message-by-message thread reproduction).
+This file is a **deprecation stub** as of kushi **v3.11.0** (formalised in **v3.12.0**).
 
-## Resolution order (per source)
+The previous "WorkIQ-first, Graph REST as last-resort fallback" cascade is **REMOVED**. It produced thin metadata-only evidence, silent fall-throughs, and a defect-looking trail in coverage.md because the Graph / `m365_*` host tools fail nearly every call in this workspace.
 
-For every source, try in order:
+## The new canonical rule
 
-1. **WorkIQ** — `<workiq.cli_path> ask -q "<question>"` (path resolved from `<USER_HOME>/.copilot/project-evidence.yml workiq.cli_path`, otherwise from PATH).
-2. **Ask user to paste** — if WorkIQ is missing, unauthenticated, or returns insufficient content, ask the user to paste the data **verbatim** (NOT summarized). This is a first-class path, not an error.
-3. **Graph REST / `m365_*` host tools** — **last resort only**, used non-blocking with an explicit `➖ partial via Graph REST` marker in the evidence file. Skills MUST NOT silently fall through to Graph when WorkIQ fails; the user must be informed and given a chance to paste.
+All M365 evidence retrieval (Email, Teams, OneNote, SharePoint, Meetings, Calendar discovery) is governed by:
 
-**Always document which path succeeded** in the evidence file under `## Source Basis`.
+**`plugin/instructions/workiq-only.instructions.md`** — WorkIQ is the ONLY path. Graph REST and `m365_*` host tools are **FORBIDDEN** as fallbacks for in-scope M365 sources. The single allowed exception is `m365_list_chat_messages` as a parallel structured-data dump (`chat-messages.json`) alongside the WorkIQ pull — NEVER as a substitute.
 
-If WorkIQ is not installed or not on PATH, the skill MUST surface this immediately with a link to `docs/getting-started/install-workiq.md` rather than degrading to thin Graph-only evidence.
+When WorkIQ fails after a doubled-strict retry → ask the user to paste verbatim. User-paste is a **first-class evidence path**, not a degradation.
 
-## Per-source preferred WorkIQ queries
+## Out of WorkIQ scope (unchanged)
 
-| Source | WorkIQ query template |
-|---|---|
-| Email | `Find emails about <project> in folder <folder> between <start> and <end>, give me sender, recipients, full body, and reply chain` |
-| Teams Chats | `Show full message-by-message reproduction of <project> Teams threads between <start> and <end>` |
-| OneNote | `Get full page bodies from OneNote section <section> notebook <notebook> modified between <start> and <end>` |
-| SharePoint | `List SharePoint files for <project> modified between <start> and <end> with author and brief content summary` |
-| Meetings | `Get full transcript and Copilot recap for meeting <subject> on <date>` |
-| CRM | `Get CRM engagement record FE-<id> with all field values, comments, and audit history` |
-| ADO | `Get ADO work items for <project> updated between <start> and <end> with full discussion thread` |
+These remain on their direct paths and are NOT governed by `workiq-only`:
 
-## Pre-flight (every pull-* skill)
+- **CRM (Dataverse)** — REST via `az account get-access-token --resource https://<env>.crm.dynamics.com` per `crm-bootstrap-discovery.instructions.md` + `pull-crm/SKILL.md`.
+- **ADO** — REST via `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798` per `ado-bootstrap-discovery.instructions.md` + `pull-ado/SKILL.md`.
 
-Before issuing the first WorkIQ query in a run:
+## Migration
 
-1. `Get-Command workiq` (or the configured `cli_path`). If missing → log `workiq-not-on-path` in `run-log.yml`, write a one-line evidence file pointing at `docs/getting-started/install-workiq.md`, and STOP this source.
-2. Probe `workiq ask -q "ping"`. If EULA prompt → run `workiq accept-eula` once, retry. If auth-failed → log `workiq-auth-failed` and ask user to re-authenticate.
-3. Only after a successful probe, proceed to per-source queries.
+Every reference to `workiq-first.instructions.md` in skills / agents / docs should be updated to `workiq-only.instructions.md`. References to the old "Graph REST as last-resort" paragraph are invalid and MUST be removed.
 
-## Graph REST — when explicitly allowed
-
-Graph is allowed only as a non-blocking last resort, and only with:
-- An explicit `➖ partial via Graph REST` marker in the evidence file.
-- A `next_step` line telling the user to install/repair WorkIQ for full-fidelity capture next run.
-- Never as a silent default.
+See `workiq-only.instructions.md` for: the canonical per-source WorkIQ prompts, the doubled-strict retry pattern, the user-paste fallback, the forbidden-paths list, and the coverage.md requirements.