kushi-agents 3.4.2 → 3.12.1

package/plugin/instructions/answer-from-evidence.instructions.md

@@ -67,7 +67,7 @@ Inventing, smoothing-over, or guessing is forbidden.
 ## Interplay with other doctrine
 
 - **`citation-ledger.instructions.md`** — citation format authority. This doctrine adds the "per-assertion" rule.
-- **`workiq-first.instructions.md`** — does NOT apply at answer time (read-only).
+- **`workiq-only.instructions.md`** — does NOT apply at answer time (read-only; the producer skills already enforced it during the pull).
 - **`evidence-thoroughness.instructions.md`** — applies to producer skills only; `ask-project` consumes whatever depth the producers wrote.
 - **`snapshot-vs-stream.instructions.md`** — `ask-project` reads both shapes; the load order above respects the snapshot/stream split.
 - **`engagement-root-resolution.instructions.md`** — used by Step 1 (project resolution).

package/plugin/instructions/auth-and-retry.instructions.md

@@ -17,11 +17,11 @@ Before the first call to a given service in a run, run the matching pre-flight.
 
 | Service | Pre-flight |
 |---|---|
-| WorkIQ | `Get-Command workiq -ErrorAction SilentlyContinue`. If missing → record `workiq-not-on-path`, fall back to host tools. Then probe with a trivial `workiq ask -q "ping"`; if output contains `accept the End User License Agreement` → run `workiq accept-eula` once and continue. |
-| Graph / `m365_*` | Call `m_m365_status`. If `signedIn != true` → record `m365-not-signed-in`, suggest `m_m365_sign_in` to user, skip Graph for this source, continue with WorkIQ + host fallbacks. |
+| WorkIQ | `Get-Command workiq -ErrorAction SilentlyContinue`. If missing → record `workiq-not-on-path`, write evidence file pointing at `docs/getting-started/install-workiq.md`, STOP this source (do NOT fall back to Graph; in-scope M365 sources are WorkIQ-only per `workiq-only.instructions.md`). Then probe with a trivial `workiq ask -q "ping"`; if output contains `accept the End User License Agreement` → run `workiq accept-eula` once and continue. |
+| Graph / `m365_*` | Used ONLY for: (a) CRM/ADO direct REST (out of WorkIQ scope), (b) the `m365_list_chat_messages` parallel structured-data dump in `pull-teams` / `pull-meetings`, and (c) the `m365_download_file` binary carve-out for `recording.mp4` and chat attachments in `pull-meetings`. For these cases only: call `m_m365_status`; if `signedIn != true` → record `m365-not-signed-in`, suggest `m_m365_sign_in` to user, skip the parallel dump (the WorkIQ artifact still stands). |
 | CRM / Dataverse | `az account show`. If non-zero → suggest `az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47`, skip CRM (per `az-auth-conditional`). |
 | ADO | `az account show` AND tenant must be in allowed list (`72f988bf-86f1-41af-91ab-2d7cd011db47`). If wrong tenant → suggest re-login, skip ADO. |
-| SharePoint (host-specific) | Acquire token for the **exact URL origin** (`$($uri.Scheme)://$($uri.Host)`), NOT the configured default host. Personal sites use `<tenant>-my.sharepoint.com`. |
+| SharePoint (host-specific, CRM/ADO-adjacent only) | Used only when CRM/ADO REST needs to read a SharePoint-hosted attachment. For pull-sharepoint content extraction, this entire row is FORBIDDEN — use WorkIQ. |
 
 ---
 
@@ -83,25 +83,60 @@ The skill MUST set `last_status` based on errors:
 
 ## 5. Path-cascade contract (per source)
 
-Each `pull-<source>` skill tries paths in order. On each failure, append `errors[]` entry, then try next path. If all paths fail, write evidence file with `❌ all paths failed` marker and the actionable next step.
+Each `pull-<source>` skill tries paths in order. On each failure, append `errors[]` entry, then try the next path. If all paths fail, write evidence file with `❌ all paths failed` marker and the actionable next step.
 
-| Source | Path 1 | Path 2 | Path 3 | Path 4 |
-|---|---|---|---|---|
-| email | WorkIQ | `m365_search_emails` / `m365_list_emails` | Graph REST | ask user |
-| teams | WorkIQ | `m365_list_chat_messages` (per chat ID) | Graph REST | ask user |
-| onenote | **WorkIQ-only per workspace policy** (see `workiq-first.instructions.md`) | n/a — Graph for OneNote is unreliable; do not attempt | n/a | ask user to paste page text |
-| sharepoint | WorkIQ | `m365_list_files` / `m365_search_files` | Graph `shares/{id}/driveItem` (for share links) or SharePoint REST `_api/web/GetFileByServerRelativePath` (for direct paths) | ask user |
-| meetings | WorkIQ (transcript) | `m365_get_transcript` | reconstruct from meeting chat (`m365_list_chat_messages`) + Copilot recap message | ask user |
-| crm | WorkIQ | Dataverse REST | n/a | ask user |
-| ado | WorkIQ | ADO REST WIQL | n/a | ask user |
+**M365 sources are WorkIQ-only** per `workiq-only.instructions.md` (v3.11.0+). 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`) — NEVER a substitute for the WorkIQ pull.
 
-For meetings specifically: **transcripts may legitimately not exist** (transcription was off). If WorkIQ + `m365_get_transcript` both return "not found" / "tool error" → **immediately reconstruct from the meeting chat** (`m365_list_chat_messages` for the meeting's chat ID — already captured during teams pull). This is "evidence reconstructed from chat" not "no evidence". Record `transcripts-not-generated` in errors with `action_taken: reconstructed-from-chat`.
+| Source | Path 1 | Path 2 | Path 3 |
+|---|---|---|---|
+| email | WorkIQ (enumerate + per-message body) | doubled-strict WorkIQ retry | ask user to paste |
+| teams | WorkIQ (thread reproduction) + `m365_list_chat_messages` in parallel (structured-data dump only) | doubled-strict WorkIQ retry | ask user to paste |
+| onenote | Playwright browser-scrape (PRIMARY, see `pull-onenote/SKILL.md`) | WorkIQ tier-C per-page | ask user to paste |
+| sharepoint | WorkIQ (content extraction) + local synced folder walk in parallel (metadata; filesystem, not API) | doubled-strict WorkIQ retry | ask user to paste |
+| meetings | WorkIQ transcript pull + `m365_list_chat_messages` in parallel + WorkIQ recap + WorkIQ recording-URL discovery | doubled-strict WorkIQ retry | ask user to paste |
+| calendar discovery | WorkIQ meeting-discovery prompt | doubled-strict WorkIQ retry | ask user to paste joinUrl |
+| crm (NOT in workiq scope) | Dataverse REST per `pull-crm/SKILL.md` | WorkIQ supplementary | ask user |
+| ado (NOT in workiq scope) | ADO REST WIQL per `pull-ado/SKILL.md` | WorkIQ supplementary | ask user |
+
+**Forbidden** as cascade steps for M365 sources (in-scope): `m365_get_email`, `m365_search_emails`, `m365_list_emails`, `m365_list_mail_folders`, `m365_list_chats`, `m365_search_chats`, `m365_get_transcript`, `m365_get_facilitator_notes`, `m365_list_meetings`, `m365_list_events`, `m365_search_files`, `m365_list_files`, `m365_get_recent_files`, `m365_download_file` (for content; binary downloads in pull-meetings for `recording.mp4`/attachments are a separate carve-out), and any Graph REST URL for those resources. Calling them is a defect; coverage.md must NOT show them in the attempt trail.
+
+For meetings specifically: **transcripts may legitimately not exist** (transcription was off). If WorkIQ returns "not found" / empty after the doubled-strict retry → reconstruct from the meeting chat (`m365_list_chat_messages` for the meeting's chat ID — already captured during teams pull, allowed as structured-data dump). This is "evidence reconstructed from chat" not "no evidence". Record `transcripts-not-generated` in errors with `action_taken: reconstructed-from-chat`.
 
 ---
 
-## 6. Try-again UX
+## 6. Try-again UX + auto-retry from run-log (HARD RULE v3.12.0+)
+
+**Failure surface is part of the run summary, every time.** Every orchestrator verb (`bootstrap`, `refresh`, `aggregate`) MUST:
+
+1. **At the end of the run**, read `Evidence/run-log.yml` and compute a per-source summary table including `last_status`, `signature`, `items_pulled`, and `next_step`.
+2. **If ANY source has `last_status` in {`failed`, `partial`, `skipped-auth`} with a retryable `signature`**, auto-surface a retry prompt to the user with two options:
+   - **Retry now (failed sources only)** — re-invokes only the per-source pull-* skills whose run-log entries are retryable, scoped to the same boundary and window as the original run.
+   - **Skip retry (continue)** — leaves the failure markers in place. Run-log keeps the error for next-run pickup.
+
+   The prompt MUST display the per-source signatures so the user can decide. Example:
+   ```
+   ⚠️ 2 sources failed last run:
+     - email      partial       signature: workiq-empty-after-retry        items: 0
+     - meetings   failed        signature: transient-server-error          items: 0
+   Retry these now? [Y/n]
+   ```
+
+3. **Retryable signatures** (auto-prompt to retry):
+   - `tool-error`, `transient-server-error`, `workiq-empty-after-retry` (first-time only), `workiq-eula-required` (after `workiq accept-eula`), `token-401-after-reacquire` (after re-auth), `auth-required` (OneNote, after re-bootstrap), `notebook-unavailable` (OneNote, after user re-syncs).
+
+4. **Non-retryable signatures** (do NOT auto-retry — surface guidance only):
+   - `transcripts-not-generated` (recording was off; need user action to re-record),
+   - `no-match` (boundary too narrow; need user to widen `integrations.yml boundaries:`),
+   - `accessDenied` / `403` (need permission grant from owner),
+   - `Sorry, I can't` (copyright/blocked content),
+   - `workiq-not-on-path` (need install/repair WorkIQ),
+   - `<source>-boundary-missing` (need user to populate integrations.yml).
+
+5. **"try again" / "refresh failed" / "retry errors" user message** → read `Evidence/run-log.yml errors[]`, retry only the entries where `signature` is in the retryable set. Surface a one-line skip notice per non-retryable entry with the actionable next step. Do NOT silently skip — the user must see what was skipped and why.
+
+6. **Auto-retry budget**: a single source can be auto-retried at most **once per orchestrator run**. If the retried call fails again with a retryable signature, the orchestrator MUST stop retrying that source for the run and surface the failure for user follow-up (do not loop).
 
-When the user says "try again" / "refresh" / "fix the errors" — read `Evidence/run-log.yml errors[]`, retry only the entries where `signature` is in the retryable set (`tool-error`, `transient-server-error`, `graph-401-*` after re-auth). Skip entries where `signature` is in `transcripts-not-generated`, `no-match`, `accessDenied`, `Sorry, I can't` — those need user action (re-record meeting, wait for ADO WI, file access request).
+This codifies the user-asked feature: "is there a way to check the failure report and redo if failed automatically or at least ask about what failed and redo?" — yes, every run ends with the retry prompt; non-retryable failures surface actionable guidance instead.
 
 ---
 

package/plugin/instructions/azure-auth-patterns.instructions.md

@@ -9,7 +9,7 @@ This file is the **concrete** companion to:
 
 - `auth-and-retry.instructions.md` — pre-flight, token reuse, retry, error-log schema, path cascade.
 - `az-auth-conditional.instructions.md` — when to require `az login` (only if CRM/ADO are configured).
-- `workiq-first.instructions.md` — WorkIQ is the required path for M365 sources.
+- `workiq-only.instructions.md` — WorkIQ is the ONLY path for in-scope M365 sources (supersedes the deprecated `workiq-first.instructions.md`).
 
 Where those files describe **what** to do, this one shows **how** in PowerShell. Skill authors implementing `pull-crm`, `pull-ado`, `pull-sharepoint`, and any other external-service caller MUST follow the patterns here. Silent 401 loops and "no evidence found" misreports almost always come from skipping one of these.
 
@@ -99,18 +99,25 @@ A raw browser-facing SharePoint URL is often the **wrong endpoint** for bearer-t
 - **For direct file paths** under `/personal/.../Documents/...` → prefer SharePoint REST `_api/web/GetFileByServerRelativePath(...)` on the exact host.
 - If the canonical API then returns `403 accessDenied` or SharePoint `UnauthorizedAccessException`, treat it as a **real permission / sharing problem** — do not chase it as a token-host mismatch. Record `errors[]` with `signature: blocked-host-or-permissions-401` per `auth-and-retry.instructions.md §4`.
 
-### 2.4 Microsoft Graph / OneNote
+### 2.4 Microsoft Graph / `m365_*` proxies — narrow carve-outs ONLY
 
-**Do not use Microsoft Graph for OneNote in this workspace.** Per `workiq-first.instructions.md`, OneNote is **WorkIQ-only**. Graph's OneNote endpoint repeatedly fails with 401/consent issues that don't represent real permission problems.
+**Do not use Microsoft Graph or `m365_*` host tools for in-scope M365 sources** (Email / Teams human-readable threads / OneNote bodies / SharePoint content / meeting transcripts / calendar discovery). Per `workiq-only.instructions.md` (v3.11.0+), these are WorkIQ-only. Graph / `m365_*` have a near-100% failure rate in this workspace and pollute the coverage trail.
+
+The ONLY allowed Graph / `m365_*` calls inside kushi pull-* skills are:
+
+1. **`m365_list_chat_messages(chatId)`** — parallel structured-data dump in `pull-teams` and `pull-meetings`. Writes `chat-messages.json`. Runs in parallel with the WorkIQ human-readable thread pull; NEVER a substitute. If it fails, the WorkIQ artifact still stands and the JSON dump is skipped.
+2. **`m365_download_file(itemId)`** for **binary media only** in `pull-meetings`: `recording.mp4` (when a SharePoint Stream URL is found and size < 200MB) and chat `attachments/<original-name>`. WorkIQ does not return binaries, so this carve-out is required for media survival.
+3. **CRM / ADO** — direct REST via Azure CLI tokens (sections 2.1 and 2.2 of this file). Out of WorkIQ scope.
 
 ```powershell
 if (-not (Get-Command workiq -ErrorAction SilentlyContinue)) {
-    throw "workiq CLI not found on PATH. OneNote queries cannot proceed. See: https://gim-home.github.io/kushi/getting-started/install-workiq/"
+    throw "workiq CLI not found on PATH. M365 source queries cannot proceed. See: https://gim-home.github.io/kushi/getting-started/install-workiq/"
 }
-# Prefer narrowest WorkIQ query: one_sectionFileId > one_sectionName > project-alias keyword search.
+# Prefer the canonical WorkIQ prompts codified in workiq-only.instructions.md.
+# Do NOT improvise. Do NOT fall back to m365_* for in-scope sources.
 ```
 
-For other Graph endpoints (Mail, Teams, Calendar) Kushi defers to the host's `m365_*` proxies; see `auth-and-retry.instructions.md §5` for the path cascade.
+For the allowed carve-outs (`m365_list_chat_messages`, `m365_download_file` for binaries): no `az` token is needed — these go through the Clawpilot M365 proxy authenticated via `m_m365_status` / `m_m365_sign_in`.
 
 ---
 

package/plugin/instructions/bootstrap-status-format.instructions.md

@@ -0,0 +1,113 @@
+---
+applyTo: "**"
+excludeAgent: "code-review"
+---
+
+# Bootstrap Status Artifact — Format Contract
+
+When `bootstrap-project` (or any full refresh / retry workflow) finishes a project run, it MUST write `<project>/bootstrap-status.md` using the format below. This file is the **fast orientation artifact** for the project — what was bootstrapped, what durable context now exists, what stage the engagement is in, what gaps remain. It is NOT a transcript of the run.
+
+## Required section order
+
+```
+# Bootstrap Status
+
+- Bootstrap Date: YYYY-MM-DD HH:MM TZ
+- Project: <name>
+- Customer Hint: <token used to resolve>
+- Mode: bootstrap | refresh | retry | force
+- Lookback Window: <days>
+
+## Preflight Checks
+
+| Check | Status | Notes |
+|---|---|---|
+| `.project-evidence/ado/config.yml` filled | resolved \| blocked-auth \| missing | ... |
+| `.project-evidence/crm/config.yml` filled | ... | ... |
+| `<project>/integrations.yml` boundaries present | ... | ... |
+| `az` CLI tenant matches | cli-available \| blocked-auth | ... |
+
+## Context Artifact Status
+
+| Artifact | Status | Notes |
+|---|---|---|
+| `crm/snapshot/<entity>/<id>.md` | populated \| unsynced \| degraded \| partial-template | <annotation count> |
+| `ado/snapshot/engagement-<id>.md` | populated \| ado-not-complete | <tree size> |
+| `ado/snapshot/items/*.md` | populated \| skipped \| ado-not-complete | <N items> |
+| `onenote/snapshot/<section>/*.md` | populated \| degraded | <pages enumerated/failed> |
+| `email/_index/<week>_message-index.md` | populated \| degraded-list-only \| throttled-tooManyRequests | <N enumerated> |
+| `email/stream/<week>_email-stream.md` | populated \| degraded-list-only | <N threads> |
+| `teams/...` | ... | ... |
+
+## Current Bootstrap Outcome
+
+- One-line current state per source.
+- CRM stage: <plain-language interpretation of statuscode> (`internal-only` per `evidence-confidence-ladder`).
+- ADO linkage: pinned engagement <id> | pending pick from N candidates | `ado-not-complete`.
+- Notable gaps: ...
+
+## Access Limitations
+
+| System | Status | Reason | Workaround |
+|---|---|---|---|
+| ADO | resolved | — | — |
+| CRM | blocked-auth | tenant mismatch | `az login --tenant <id>` |
+| Email | throttled-tooManyRequests | WorkIQ rate-limited | retry next refresh |
+
+## Bootstrap Status
+
+ONE final line, normalized:
+- `bootstrap-complete`
+- `bootstrap-complete-with-coverage-gaps`
+- `bootstrap-blocked — <primary reason>`
+- `refresh-complete`
+- `refresh-complete-with-coverage-gaps`
+```
+
+## Normalized status vocabulary
+
+Use these exact strings everywhere (table cells, run-log, narrative):
+
+- `resolved` — check passed
+- `cli-available` — required CLI is installed and authenticated
+- `blocked-auth` — auth missing/failed
+- `partial-template` — file exists but only template scaffolding written
+- `unsynced` — file does not contain real data yet
+- `populated` — file contains real fetched data
+- `degraded` / `degraded-list-only` — partial fetch (e.g. email body-unavailable for some messages)
+- `throttled-tooManyRequests` — source rate-limited
+- `ado-not-complete` — engagement record not found yet OR ADO linkage missing
+- `completed-with-coverage-gaps` — final outcome with explicit gaps recorded
+
+## Sections to AVOID in bootstrap-status
+
+Do NOT keep these in `bootstrap-status.md` (they belong elsewhere or become stale):
+
+- `Fallback Inputs Used` → run-log only
+- `Evidence & Current Context` → State files
+- `FDE Fitness Assessment` → State/00_overview.md
+- `Source Coverage` → already covered by Access Limitations
+- `Recommended Actions` → State/05_action-items.md or Open Questions/
+- long historical retry logs → run-log only
+
+## Stable-summary test
+
+When deciding whether a detail belongs in `bootstrap-status.md`, ask: **"Does this help a future reader understand the current durable project state?"** If it's mainly describing how this one run unfolded, push it to `update-status.md` (per-run history) or the run-log instead.
+
+## ADO-not-complete note
+
+When a bootstrap cannot resolve the ADO Engagement WI, include in `## Current Bootstrap Outcome`:
+
+> ADO context sync pending: engagement record not found yet; bootstrap is usable with CRM/transcript context and should be revisited after ADO engagement creation or when the candidate WI is pinned to `integrations.yml#ado.engagement_id`.
+
+And reflect `ado-not-complete` in the relevant Context Artifact Status rows.
+
+## Relationship to other artifacts
+
+- Detailed CRM content → `crm-context/record-profile.md` + `crm/snapshot/`
+- Detailed ADO tree → `ado/snapshot/tree.md` + per-item files
+- Detailed transcripts → `meeting-transcripts/index.md`
+- Per-run history → `update-status.md` (project-local)
+- Cross-source synthesis → `State/`
+
+`bootstrap-status.md` summarizes; it never duplicates these artifacts.

package/plugin/instructions/capture-learnings.instructions.md

@@ -0,0 +1,95 @@
+---
+applyTo: "**"
+description: "Capture-learnings loop — every fix, quirk, or workaround discovered mid-run must be written back into doctrine in the same turn it is learned."
+---
+
+# Capture-learnings loop (HARD RULE)
+
+Every kushi skill is a learning agent. When the agent discovers a new fact, fixes a bug, hits an API quirk, or finds a workaround — that lesson MUST be persisted back to doctrine **in the same run, before the skill exits**. Otherwise the next run repeats the same mistake.
+
+This is the difference between a skilled engineer (writes the runbook entry as soon as they finish the fix) and an amateur (fixes it in their head and forgets next month).
+
+## What counts as a "learning"
+
+Capture all of these:
+
+- **API quirks** — undocumented limits (`$top` max, mandatory headers, navigation properties that don't exist on custom entities), required preview API versions, encoding gotchas.
+- **Auth fixes** — tenant IDs, audience strings, env overrides per project.
+- **Schema surprises** — fields that don't exist where you'd expect, entity-set name plurals, custom-field naming conventions.
+- **Resolution misses** — "the title-substring probe missed this project because…", "the default folder fast-path didn't apply here because…".
+- **Workarounds** — pagination switch from one endpoint to another, separate filtered query instead of `$expand`, fallback ordering changes.
+- **User pushback** — any time the user corrects scope, identity, or interpretation, that correction is doctrine.
+
+Don't capture: one-off transient errors (network blip, expired token), or things already in the doctrine you just didn't read.
+
+## Where learnings live
+
+| File | Purpose |
+|---|---|
+| `<KUSHI_ROOT>/plugin/learnings/<source>.md` | Per-source register: `ado.md`, `crm.md`, `email.md`, `teams.md`, `onenote.md`, `sharepoint.md`, `meetings.md`. Owned by the matching `pull-<source>` skill. |
+| `<KUSHI_ROOT>/plugin/learnings/cross-cutting.md` | Lessons that span multiple sources (auth, encoding, host-tool quirks). |
+| `<KUSHI_ROOT>/plugin/learnings/README.md` | Index + how-to-add-an-entry. |
+
+## Entry format (one per learning)
+
+```markdown
+### YYYY-MM-DD — short title
+
+**Symptom**: what broke or what was confusing (one sentence, verbatim error if applicable).
+
+**Root cause**: why it happened.
+
+**Fix / workaround**: the exact thing that worked (code snippet or 1–2 sentences).
+
+**Doctrine impact**: which SKILL.md, instructions file, or template was updated in the same commit. Link by relative path. If "none yet — register only", say so explicitly and open a TODO.
+
+**Discovered during**: project name + skill that hit it (e.g. `HCA / pull-crm`).
+```
+
+Newest entry on top. Never delete — only mark superseded with a one-liner.
+
+## When the loop runs (every skill, every time)
+
+### Preflight (start of run)
+1. Read `plugin/learnings/<source>.md` for the skill being run.
+2. Apply known workarounds without re-discovering them. If a learning says "use `$top=200` not `$top=500`", use it.
+
+### Mid-run (the moment a fix lands)
+1. Stop. Don't move on yet.
+2. Append a new entry to the appropriate `learnings/<source>.md` (or `cross-cutting.md`).
+3. If the fix changes how the skill should always behave, also edit the relevant SKILL.md or instructions file in the same edit batch.
+4. Then resume.
+
+### Postflight (end of run)
+1. If any learnings were appended, the run summary MUST list them with file path + entry title.
+2. If a doctrine file was updated, the run summary MUST mention the version bump or commit pending.
+
+## Doctrine vs register: when to upgrade
+
+A `learnings/<source>.md` entry is **the proven workaround**. If the same learning hits twice (same project re-run, or a different project), promote it from register to first-class doctrine:
+
+- Move the rule into the matching SKILL.md or a focused `*.instructions.md`.
+- Leave a one-liner in the register: `→ promoted to plugin/instructions/<file>.md on YYYY-MM-DD`.
+
+Don't pre-promote — wait for the second sighting. Otherwise the SKILL.md balloons with one-off fixes.
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` deep-mode rule **D7** verifies:
+- `plugin/learnings/` exists with `README.md` + at least the per-source files for `pull-*` skills.
+- Each `pull-*` SKILL.md references this instruction file (`capture-learnings.instructions.md`) by relative path in its frontmatter or body.
+- Each `learnings/<source>.md` has the standard entry format header.
+
+A missing register file or unreferenced skill is a hard fail.
+
+## Why this matters
+
+Without this loop:
+- Same Dataverse `$expand=Annotations` 500 hits us every quarter.
+- Same `$top=500` ADO updates 400-error gets re-discovered every refresh.
+- Same per-project env override (iscrm vs microsoftit) gets re-debugged from scratch.
+
+With it:
+- The agent gets smarter every run.
+- The next contributor reads `learnings/crm.md` once and skips a half-day of debugging.
+- Doctrine stays small (only proven, recurring rules) and the register catches everything else.

package/plugin/instructions/cleanup-on-resolution.instructions.md

@@ -0,0 +1,69 @@
+---
+applyTo: "**"
+description: "Cleanup-on-resolution rule — when a probe resolves a real ID/match, prune the stale 'no-match' / 'probe-trail' notes left by previous failed attempts. Don't accumulate audit cruft next to a resolved fact."
+---
+
+# Cleanup-on-resolution (HARD RULE)
+
+When a `pull-*` or `bootstrap-project` skill resolves a previously-unknown ID, folder, section, or record (e.g. ADO engagement WI, CRM record, OneNote section, email folder, Teams chat) — the skill MUST prune the stale "didn't find it" notes left by earlier failed attempts in the **same turn** the success lands.
+
+## Why
+
+Without cleanup, every project's `integrations.yml`, `m365-mutable.json`, run-log, and `bootstrap-status.md` slowly accumulate:
+
+- `last_discovery_result: 'no-match'` next to a now-resolved ID
+- A list of probe attempts ("tried query X — 0 hits", "tried query Y — TF51005") next to the proven-correct query
+- "❌ ado-not-complete" status notes next to a now-resolved engagement WI
+- "⚠️ folder hint missing — root-fallback used" warnings next to a now-pinned `emailContext.folder`
+
+The audit trail becomes noise. The user can't tell what's the current state vs what's historic failure.
+
+## What to clean (per surface)
+
+When a resolution succeeds, in the same turn, prune:
+
+### `<project>/integrations.yml`
+- Replace `<source>.last_discovery_result: 'no-match'` (or `'partial'`, `'ambiguous'`) with `'resolved'`.
+- Remove any `<source>.probe_attempts` / `<source>.probe_history` arrays — those were debugging breadcrumbs, not configuration.
+- Remove inline comments like `# TODO: find this`, `# could not resolve as of YYYY-MM-DD`.
+- Keep `pinned_on` + `pinned_by` (those are durable provenance).
+
+### `<engagement-root>/.project-evidence/m365/m365-mutable.json`
+- Remove entries under `m365Mutable.unresolved.<project>.<source>` if the same key was just resolved into `m365Mutable.knownSections.<project>.<source>`.
+- Replace any `confidence: 'low'` entry with the new `confidence: 'high'` entry on resolution; do not keep both.
+
+### `<engagement-root>/<project>/Evidence/run-log.yml`
+- Update `sources.<src>.coverage_state` from `degraded-list-only` / `unresolved` / `throttled-tooManyRequests` to the new healthy state on the run that succeeded.
+- Keep historical run entries in `runs:` (those are durable history) — but the current `sources.<src>` summary block must reflect TODAY's resolved state, not last run's failure.
+
+### `<project>/bootstrap-status.md`
+- Per the bootstrap-status format contract, status tables show CURRENT durable state. When a resolution fixes a previously-blocked check, update the matching row in `## Preflight Checks` / `## Context Artifact Status` / `## Access Limitations` to `resolved` / `populated` / `cli-available` and remove the previous "blocked" row (don't keep both).
+- Specifically: when an ADO engagement is resolved, change `ado-not-complete` to `resolved` AND delete the `## Current Bootstrap Outcome` note that said `ADO context sync pending: engagement record not found yet`.
+
+## What to KEEP
+
+Cleanup-on-resolution is about pruning **stale state**, not history. The following are durable and never pruned:
+
+- `runs:` array in `run-log.yml` — full run history (timestamp, mode, outcome).
+- Per-user `refresh-reports/<timestamp>_<mode>.md` files — per-run reports per `run-reports.instructions.md`.
+- `learnings/<source>.md` entries — register entries persist; they document the fix, not the failure.
+- `pinned_on` + `pinned_by` audit fields on resolved IDs.
+- Coverage Notes inside evidence files for runs where the boundary truly was empty.
+
+## When NOT to clean
+
+If the user explicitly pinned a `last_discovery_result: 'no-match'` themselves (they said "this project genuinely has no CRM record, stop probing") — leave it. The skill should detect explicit user-set state and not auto-clean.
+
+Heuristic: if `<key>.pinned_by` matches the current user alias and the entry is older than 1 day, treat it as user-authoritative. If it was written by the skill itself in a previous run, it's prune-eligible.
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` deep-mode rule **D9** (added v3.7.6):
+- Warns if `<project>/integrations.yml` has both a resolved ID (`<source>.engagement_id` / `record_id` / `section_id`) AND a stale `<source>.last_discovery_result: 'no-match'`. That combination is impossible after cleanup.
+- Warns if `bootstrap-status.md` shows `ado-not-complete` while `integrations.yml` has `ado.engagement_id` populated.
+
+A flagged file is a doctrine miss to be fixed in the next run, not a hard fail.
+
+## Apply across all pull-* skills
+
+Every `pull-<source>` skill's "Mutable hints to upsert" section MUST also reference this instruction file by relative path. The cleanup is part of the upsert, not a separate phase.

package/plugin/instructions/crm-bootstrap-discovery.instructions.md

@@ -0,0 +1,79 @@
+---
+applyTo: "**/skills/bootstrap-project/**, **/skills/pull-crm/**, **/skills/refresh-project/**"
+---
+
+# CRM bootstrap discovery — HARD rule (kushi v3.11.0+)
+
+## The defect this rule exists to prevent
+
+Bootstrap runs that wrote `boundaries.crm.disabled: true` after a single shallow probe (e.g. WorkIQ-only, or no live Dataverse REST call at all) — when in fact a live `contains(new_title, '<token>')` query would have resolved the record instantly. The result: pull-crm is then never dispatched on subsequent refreshes, the project Evidence/crm/ folder stays empty, and the CRM record drifts unsynced. Discovered 2026-05-18 on the John Deere bootstrap — FE-2026-001791 was missed because the title-first REST probe was never issued.
+
+## The rule
+
+Before `bootstrap-project` (or `refresh-project` on first CRM pull) is allowed to write `boundaries.crm.disabled: true`, the FULL 4-step Dataverse REST resolution sequence from `plugin/skills/pull-crm/SKILL.md#resolution-order-when-crmrecordid-is-unset` MUST be attempted with live tokens against the configured `iscrm.crm.dynamics.com` (or equivalent) endpoint. `disabled: true` is ONLY legitimate when:
+
+1. **Steps 1–4 all returned 0 results** (logged with the exact OData URLs attempted, counts, and timestamps), AND
+2. **Step 5 (ask user)** was actually presented to the user and the user confirmed there is no CRM record, OR the user is unreachable and the project owner explicitly opted to defer.
+
+Any other path that writes `disabled: true` is a defect. The correct fallback for "couldn't reach Dataverse" or "auth failed" is to leave the boundary empty (NOT `disabled: true`) with `reason: 'crm-auth-unavailable-YYYY-MM-DD'` so the next run retries.
+
+## Required execution at bootstrap time
+
+```powershell
+# 1. Acquire Dataverse token (per pull-crm Step Auth)
+$config = Get-Content "<engagement-root>/.project-evidence/crm/config.yml" | ConvertFrom-Yaml
+$token = (az account get-access-token --tenant $config.tenant_id --resource $config.base_url --query accessToken -o tsv --only-show-errors).Trim()
+$headers = @{
+  Authorization = "Bearer $token"
+  Accept = 'application/json'
+  'OData-Version' = '4.0'
+  'OData-MaxVersion' = '4.0'
+  Prefer = 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"'
+}
+
+# 2. Step 1 — Title-first (REQUIRED)
+$url = "$($config.base_url)/api/data/v9.2/$($config.entity.entitySetName)?`$select=$($config.entity.primary_id_attribute),$($config.entity.primary_name_attribute),$($config.entity.request_id_attribute),statecode,statuscode,createdon,modifiedon,_new_customer_value&`$filter=contains($($config.entity.primary_name_attribute),'<token>')&`$top=20"
+# If results >= 1 → present candidates, persist chosen record_id, STOP.
+
+# 3. Step 2 — Account(s) fallback (REQUIRED if Step 1 returns 0)
+# Resolve customer in accounts entity, then for EACH matching account query engagement records.
+# Multiple Deere-style accounts (e.g. JOHN DEERE, DEERE COMPANY, JOHN DEERE COASTRUCTION) MUST all be tried.
+
+# 4. Step 3 — Wide-text fallback (REQUIRED if Step 2 returns 0)
+# contains() on new_businessscenariotechnicalblocker, new_engagedwith, new_engagementobjectives.
+
+# 5. Step 4 — Recent-slice client-rank (REQUIRED if Step 3 returns 0)
+# Pull top 200 by modifiedon desc, rank client-side by token overlap.
+
+# 6. Step 5 — Present top 5 to user; never auto-pick on multi-match.
+```
+
+## Required logging
+
+Every bootstrap (and first-refresh) CRM-discovery run MUST write the attempt trail to `<project>/Evidence/<alias>/refresh-reports/<ts>_bootstrap.md` under a `## CRM resolution attempts` section, including:
+
+| Step | Query | Result count | Outcome |
+|---|---|---|---|
+| 1 | `contains(new_title,'<token>')` | N | resolved / 0-results |
+| 2 | accounts `contains(name,'<token>')` → FE per account | N1+N2+… | resolved / 0-results |
+| 3 | `contains(new_businessscenariotechnicalblocker,'<token>')` etc | N | resolved / 0-results |
+| 4 | recent-slice top 200 client-rank | N | top match score / 0-results |
+| 5 | user presented top 5 candidates | yes/no | picked / declined / deferred |
+
+This is non-negotiable. The trail is the audit that justifies whichever value lands in `boundaries.crm` (`record_ids: [...]` OR empty-with-reason OR `disabled: true`).
+
+## Anti-patterns
+
+1. **Setting `boundaries.crm.disabled: true` without trying live Dataverse REST.** Defect — pull-crm will never run again.
+2. **Trying only WorkIQ for CRM resolution.** WorkIQ summarizes and may miss records; REST is the canonical path.
+3. **Filtering by `statecode` during candidate search.** Hides closed / withdrawn / inactive records. See pull-crm Rule 5.
+4. **Filtering by `new_companyname`.** Not a valid attribute on `new_frontierengineeringtriage`. Customer is `_new_customer_value` lookup. Always returns 0; looks like a permissions problem but is a schema problem.
+5. **Stopping at first account match in Step 2.** Multiple accounts can share a token (Deere example). Iterate ALL.
+6. **Silent fallback to "narrate CRM from email".** Forbidden by `scope-boundaries.instructions.md` Rule 3 and pull-crm hard-prereq.
+
+## Cross-references
+
+- `plugin/skills/pull-crm/SKILL.md#resolution-order-when-crmrecordid-is-unset` — the canonical 4-step sequence (now 5 with user-ask).
+- `plugin/skills/bootstrap-project/SKILL.md` Step 4a — must dispatch this discovery before deciding `disabled`.
+- `plugin/instructions/crm-internal-vs-confirmed.instructions.md` — once resolved, do not over-claim from CRM-only fields.
+- `plugin/instructions/cleanup-on-resolution.instructions.md` — when this discovery resolves a record, prune stale `disabled: true` notes in the same turn.

package/plugin/instructions/crm-internal-vs-confirmed.instructions.md

@@ -0,0 +1,79 @@
+---
+applyTo: "**"
+---
+
+# CRM field values vs confirmed facts — HARD rule (kushi v3.11.0+)
+
+## The rule
+
+**A CRM field value is NEVER automatically a confirmed fact.** A Dataverse field update records an internal decision; it does not prove the decision has been (a) communicated to the customer, (b) approved by deal desk / finance / legal, or (c) confirmed in a customer-facing transcript, note, email, or meeting artifact.
+
+Adapted into kushi from Nova doctrine (see `fde-grounding.instructions.md > CRITICAL: CRM Field Values vs. Confirmed Facts`).
+
+## Three states every CRM-sourced assertion must be classified into
+
+1. **Internal-only decision** — team recorded a direction in a CRM field, but no customer-facing or external-stakeholder evidence confirms it. Status fields commonly look like this (e.g. `Not Yet Requested`, `Pending`, `Evaluating`, `TBD`). **DO NOT** write this as a settled fact in State/, FDE reports, or 6Q.
+2. **Communicated to customer** — there exists a customer-facing transcript / note / email / meeting that postdates the CRM field update and references the decision. Still not final — typically still pending commercial / deal-desk approval.
+3. **Confirmed with all stakeholders** — customer agreement + commercial approval + (where applicable) legal sign-off / signed artifact. Only this state is a settled fact and may be reported as such.
+
+## How to apply recency precedence correctly to CRM fields
+
+- The CRM field's `modifiedon` timestamp shows when the record was **updated**, NOT when the decision was **confirmed**.
+- For every materially important CRM field claim (funding model, scope decision, owner, timeline gate, SI lane, ECIF / ESIF state), **cross-check against the latest customer-facing artifact** in `Evidence/<alias>/{meetings,email,onenote,teams,sharepoint}/` (use `meetings/verbatim/*/transcript.*` first per `meetings-verbatim-required.instructions.md`).
+- If the latest customer-facing artifact predates the CRM field update AND no post-update customer-facing artifact confirms the decision → state explicitly as `internal decision recorded in CRM (<date>), pending customer/deal-desk confirmation (no confirming artifact found post-<date>)`.
+- If a post-update artifact confirms → cite both (CRM date + confirming artifact + date).
+- If a post-update artifact contradicts → mark `Conflicting evidence` and surface to `<project>/State/09_open-questions.md` (full profile) or `<project>/OPEN-QUESTIONS-DRAFT.md` (standard profile).
+
+## Required output classification for State/, FDE reports, consolidation, ask-project answers
+
+Every materially important CRM-sourced assertion in any kushi-generated artifact must be tagged as one of:
+
+- `CRM-only` — internal signal, no external confirmation
+- `Cross-verified` — confirmed by ≥ 1 non-CRM artifact (cite both)
+- `Conflicting evidence` — non-CRM source contradicts CRM/form (cite both, list in open questions)
+
+Acceptable non-CRM confirmation sources (in priority order per kushi precedence):
+
+1. Meeting transcripts (`Evidence/<alias>/meetings/verbatim/*/transcript.*`)
+2. Curated meeting stream notes (`Evidence/<alias>/meetings/stream/*.md`)
+3. OneNote pages
+4. ADO work-item discussions / comments
+5. Emails (sender-domain matching customer)
+6. Teams chats / channels
+7. Approved shared artifacts (SharePoint / Loop / docs)
+
+## Citation format
+
+```
+[source: CRM record FE-XXX field <field-name> · YYYY-MM-DD (internal-only)]
+[source: CRM record FE-XXX field <field-name> · YYYY-MM-DD; cross-verified by Evidence/<alias>/meetings/verbatim/<dir>/transcript.vtt · YYYY-MM-DD]
+[source: CRM record FE-XXX field <field-name> · YYYY-MM-DD; conflicts with Evidence/<alias>/email/snapshot/<file>.md · YYYY-MM-DD — see open questions]
+```
+
+## Worked example
+
+- 2026-03-20 transcript: team exploring funding options.
+- 2026-03-23 transcript: alternative under discussion.
+- 2026-03-26: CRM `new_ecifstatus` updated to `Not Yet Requested`.
+- 2026-04-08 (today): no post-3/26 transcript confirms ECIF with customer or deal desk.
+
+**Correct write-up:**
+> Internal team decision favors ECIF (per CRM 3/26 update) but formal approval from deal desk and customer confirmation are still pending. Latest customer-facing transcript (3/23) predates the CRM decision; no post-decision confirmation found. `[source: CRM record FE-XXX field new_ecifstatus · 2026-03-26 (internal-only)]`
+
+**Incorrect write-up (forbidden):**
+> ECIF is the selected funding model. `[source: CRM record FE-XXX field new_ecifstatus · 2026-03-26]`
+
+## Where this rule binds
+
+- `skills/build-state/` — every CRM-sourced row in `State/01_decisions.md`, `State/05_action-items.md`, `State/06_risks-and-issues.md`, `State/07_timeline-and-milestones.md` must carry the 3-state tag and the cross-check citation chain.
+- `skills/ask-project/` — answers grounded in CRM fields must explicitly distinguish internal-only vs cross-verified; never collapse into a bare assertion.
+- `skills/fde-report/` / `skills/fde-triage/` — FDE Triage Living Reports follow this rule; the `Verification Evidence` section is required for any CRM-sourced gate.
+- `skills/consolidate-evidence/` — when merging across contributors, conflicting CRM-vs-non-CRM evidence becomes a `Conflicting evidence` row, never silently resolved.
+
+## Anti-patterns
+
+1. Treating a CRM `Status` field as proof of customer commitment.
+2. Reading CRM `modifiedon` as the decision-confirmation date.
+3. Claiming "ECIF selected" / "Lane X chosen" / "Customer signed off" from CRM alone with no post-date customer-facing artifact.
+4. Blending CRM internal decision and older customer-facing context into one averaged narrative without flagging the gap.
+5. Dropping the `(internal-only)` tag in citations because it "reads cleaner".