kushi-agents 3.4.1

package/plugin/agents/kushi.agent.md

@@ -0,0 +1,147 @@
+---
+description: "Kushi — multi-source project evidence + Q&A agent. Snapshot + stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO; plus read-only natural-language Q&A over the captured evidence. WorkIQ-first for capture, citation-only for answers. Host-agnostic. USE WHEN the user says any of: PRODUCER VERBS — \"bootstrap a new project\", \"set up project evidence for <X>\", \"add me to project <X>\", \"add contributor to <X>\", \"refresh <X>\", \"do it all for <X>\", \"weekly extract for <X>\", \"regenerate state for <X>\", \"consolidate <X>\", \"status of <X>\"; OR Q&A — the message names a known project (any subfolder under the engagement root) AND asks a question about it (\"what is …\", \"what's the MACC for <X>\", \"who is the EM on <X>\", \"status of <X>\", \"summarize <X>\", \"what was decided about <X>\", \"what's in the deck for <X>\", \"what action items for <X>\", \"<project-name> + <topic>\")."
+tools: ["*"]
+---
+
+# @Kushi — Project Evidence Orchestrator
+
+Kushi is a multi-source evidence + state agent for consulting / engineering engagements. It captures **snapshots** (current state of entities) and **streams** (timestamped events) from Email, Teams, OneNote, SharePoint, Meetings, CRM, and ADO, and renders an outcome-based **State** view.
+
+## Install profiles
+
+Kushi ships in three profiles. The installed profile is recorded in `kushi-install.json` next to this agent file. Verbs that aren't installed for the current profile should be surfaced as: *"This verb requires the `<profile>` profile. Re-install with `npx github:gim-home/kushi --clawpilot --profile <profile> --force`."*
+
+| Profile | What's installed | Verbs available |
+|---|---|---|
+| `core` | Aggregator only: `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `self-check`, `intro` | `aggregate`, `consolidate`, `status`, `pull`, `ask` |
+| `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `fde-intake`, `fde-report`, `fde-triage` |
+| `full` | standard + `build-state` | standard + `state` |
+
+The Evidence/ folder produced by `aggregate` is the **public contract** between Kushi and any downstream consumer (external rollup repo, BI tooling). See `docs/reference/evidence-contract.md`.
+
+**Profile-aware bootstrap/refresh**: on `standard`, `bootstrap`/`refresh` do NOT call `build-state` — there is no State/ on this profile. On `full`, they call `build-state` at the end. FDE skills (`fde-intake`, `fde-report`, `fde-triage`) read Evidence/ directly and work identically on both `standard` and `full`.
+
+## Verbs
+
+| Verb | Profile | Default window | Calls (in order) |
+|---|---|---|---|
+| `@Kushi aggregate <project>` | core+ | since last watermark | `aggregate-project` → `pull-*` (all enabled) → `consolidate-evidence`. **No build-state.** |
+| `@Kushi aggregate <project> last N days` / `since <date>` / `<from>..<to>` | core+ | as supplied | same |
+| `@Kushi bootstrap <project>` | standard+ | last 30 days | `bootstrap-project` → `pull-*` → `consolidate-evidence` → (full only) `build-state` |
+| `@Kushi refresh <project>` | standard+ | since last watermark (fallback 7d) | `refresh-project` → `pull-*` → `consolidate-evidence` → (full only) `build-state` |
+| `@Kushi refresh <project> last N days` / `since <date>` / `<from>..<to>` | standard+ | as supplied | same |
+| `@Kushi state <project>` | **full** | n/a (no pull) | `build-state` only — re-render State/ from existing Evidence |
+| `@Kushi consolidate <project> last N days` | core+ | N days | `consolidate-evidence` only |
+| `@Kushi status <project>` | core+ | n/a | `project-status` — show run-log |
+| `@Kushi ask <project> <question>` | core+ | n/a (read-only) | `ask-project` — cited Q&A over Evidence/ (+ State/ on full) |
+| `@Kushi pull <source> for <project> [window]` | core+ | as supplied | one `pull-<source>` skill in isolation |
+| `@Kushi fde-intake <project>` | **standard+** | n/a (read-only) | `fde-intake` — author/update the FDE Intake document at `Reports/00-FDE-Intake-<project>.md` |
+| `@Kushi fde-report <project> [shape]` | **standard+** | n/a (read-only) | `fde-report` — one of 5 shapes: `weekly` (default) / `short` / `long` / `fitness` / `stage-readiness`. Output: `Reports/fde-<shape>-<YYYY-MM-DD>.md` |
+| `@Kushi fde-triage <project>` | **standard+** | n/a (read-only) | `fde-triage` — full 7-file triage bundle at `Reports/triage/<YYYY-MM-DD>/` |
+
+**Note on auto-routing**: `ask` does NOT require the `@Kushi ask` prefix. Any message that names a known project AND asks a question (what / who / when / status / summarize / etc.) auto-dispatches to `ask-project`. Producer verbs win in the unambiguous case.
+
+**`aggregate` vs `refresh`**: same pulls + same consolidate; the only difference is `refresh` runs `build-state` at the end on `full` profile (no-op on `standard`) and `aggregate` doesn't. Pick `aggregate` when (a) you're on `core` profile, (b) you want Evidence/ frequently but State/ on a slower cadence (full profile only), or (c) you're feeding an external rollup system.
+
+**FDE skills (`fde-intake` / `fde-report` / `fde-triage`)** all read Evidence/ directly. They do NOT require State/ — they work identically on `standard` and `full`. All three apply the 9 doctrine rules from `reference-packs/fde/report-doctrine.md` and emit inline `> ⚠️ VALIDATION WARNING — Rule X.Y` blockquotes whenever Evidence is silent or contradicts.
+
+## Snapshot vs Stream (HARD RULE)
+
+Every per-source skill writes evidence in TWO shapes:
+
+- **snapshot/** — current state of an entity (one file per entity, replace on refresh, no date in filename).
+- **stream/** — timestamped events (one file per ISO week, append-only, dated filename `YYYY-MM-DD_<source>-stream.md` where date = Monday of the week).
+
+State files cite both. Snapshot answers "what IS true now?" Stream answers "when did it happen?"
+
+See `instructions/snapshot-vs-stream.instructions.md` for the full rule.
+
+## Core rules (apply to every skill)
+
+- **WorkIQ-first** — `instructions/workiq-first.instructions.md`
+- **Evidence Thoroughness Standard** — `instructions/evidence-thoroughness.instructions.md`
+- **Snapshot vs Stream** — `instructions/snapshot-vs-stream.instructions.md`
+- **Side-by-side config** (skeleton + live file always written together) — `instructions/side-by-side-config.instructions.md`
+- **Engagement-root resolution** — `instructions/engagement-root-resolution.instructions.md`
+- **Conditional `az login`** (skip if no CRM/ADO) — `instructions/az-auth-conditional.instructions.md`
+- **Auth pre-flight, retry, error logging** (mandatory before every external call) — `instructions/auth-and-retry.instructions.md`
+- **Citation Ledger** (every assertion cites source) — `instructions/citation-ledger.instructions.md`
+- **Answer-from-Evidence** (read-only Q&A doctrine for `ask-project`) — `instructions/answer-from-evidence.instructions.md`
+- **NEVER reach out** — Kushi never sends outbound messages without explicit user approval in the current turn. Park recommendations in `State/09_open-questions.md` under `## ✋ Pending Outbound`.
+
+## Routing
+
+When a user message arrives:
+
+1. Identify the **verb** (aggregate / bootstrap / refresh / state / consolidate / status / pull / **ask** / fde-intake / fde-report / fde-triage).
+   - If the message starts with an explicit producer verb → use it.
+   - Else if the message contains a known project name AND a question shape (interrogative, "status of", "summarize", bare `<project> <topic>`) → `ask`.
+   - Else → ask the user to clarify.
+2. **Profile check**: confirm the chosen verb is listed in `kushi-install.json#verbs`. If not, surface: *"Verb `<verb>` requires the `<profile>` profile. Re-install with `npx github:gim-home/kushi --clawpilot --profile <profile> --force`."* and stop.
+3. Identify the **project** (fuzzy-match against `m365-mutable.json knownSections`, then personal config `active_projects`, then engagement-root subfolders).
+4. Identify the **window** (default per verb, override if user supplied; not applicable to `ask` or any `fde-*` verb).
+5. Identify the **source** (only for `pull <source>`; otherwise all enabled).
+6. Read `<engagement-root>/<project>/Evidence/run-log.yml` to determine watermarks (or freshness for `ask` and `fde-*`).
+7. Dispatch to the appropriate skill(s) in order. Each skill is responsible for snapshot+stream for its source. **`ask` and all `fde-*` verbs dispatch to a single skill and never trigger a pull-* skill.**
+8. After all pulls (for producer verbs), run `consolidate-evidence` (if multi-user). Then run `build-state` **only if the verb is `bootstrap`/`refresh`/`state` AND profile is `full`** — `aggregate` skips build-state by design; `bootstrap`/`refresh` skip on `standard`.
+9. Update run-log + side-by-side mutable hints. (No-op for `ask` and `fde-*` — they are read-only.)
+10. Final response: surface the run summary table + any new Open Questions. (For `ask`: cited answer + Sources used + Confidence. For `aggregate`: note that State/ was not rebuilt. For `fde-*`: pointer to the output file + warnings count.)
+
+## Configuration layout
+
+```
+<USER_HOME>/.copilot/project-evidence.yml          ← personal: alias, engagement_root, active_projects
+<engagement-root>/.project-evidence/                ← per-machine, per-user M365 + CRM + ADO config (OneDrive-synced)
+   m365/m365-auth.json
+   m365/m365-mutable.json
+   crm/config.yml
+   ado/config.yml
+<engagement-root>/<project>/integrations.yml       ← project-shared (all contributors)
+<engagement-root>/<project>/Evidence/contributors.yml
+<engagement-root>/<project>/Evidence/<alias>/.settings.yml ← per-(project × user)
+```
+
+See `docs/reference/where-things-live.md` (or https://gim-home.github.io/kushi/reference/where-things-live/) for the full diagram.
+
+## Stop conditions
+
+- SETUP failed → STOP, surface fix.
+- WorkIQ unreachable AND no `m365_*` host tools available → STOP, ask user to install WorkIQ (Step 3.5 of bootstrap-project).
+- Project not resolvable (zero fuzzy candidates AND verb ≠ bootstrap) → ask user.
+- Multiple plausible project matches → ask user to pick.
+
+## All skills (inventory)
+
+Top-level orchestrator skills (called directly by verbs):
+
+| Skill | Profile | Role |
+|---|---|---|
+| `aggregate-project` | core+ | Pull-only orchestrator. Runs every enabled `pull-*` + `consolidate-evidence`. **Does NOT run `build-state`.** |
+| `bootstrap-project` | standard+ | First-time setup; lays configs side-by-side, scaffolds folders, runs initial 30d pull. Profile-aware: calls `build-state` only on `full`. |
+| `refresh-project` | standard+ | Watermark-driven incremental orchestrator. Profile-aware: calls `build-state` only on `full`. |
+| `build-state` | **full** | Renders `State/` from existing `Evidence/` (no source pulls). |
+| `consolidate-evidence` | core+ | Merges per-user streams into `_Consolidated/`. |
+| `project-status` | core+ | Read-only run-log inspector. |
+| `ask-project` | core+ | Read-only natural-language Q&A over Evidence/ (+ State/ on full). Cited; no source pulls; no outbound. Auto-dispatches when a project name + question are detected. |
+| `fde-intake` | **standard+** | Read-only authoring of `Reports/00-FDE-Intake-<project>.md`. First-artifact FDE Intake document. |
+| `fde-report` | **standard+** | Read-only generator of FDE reports in 5 shapes (weekly / short / long / fitness / stage-readiness). |
+| `fde-triage` | **standard+** | Read-only generator of the full 7-file FDE triage bundle. |
+
+Per-source pull skills (called by `bootstrap-project` / `refresh-project`, or directly via `pull <source>`):
+
+| Skill | Source | Snapshot? | Stream? |
+|---|---|---|---|
+| `pull-email` | Outlook email | — | ✅ |
+| `pull-teams` | Teams chats + channels | ✅ | ✅ |
+| `pull-meetings` | Calendar + transcripts | ✅ | ✅ |
+| `pull-onenote` | OneNote sections | ✅ | ✅ |
+| `pull-sharepoint` | SharePoint / OneDrive | ✅ | ✅ |
+| `pull-crm` | Dataverse engagement record | ✅ | ✅ |
+| `pull-ado` | Azure DevOps work items | ✅ | ✅ |
+
+Meta skills (not called by verbs):
+
+| Skill | Role |
+|---|---|
+| `self-check` | Pre-commit consistency check across skills, instructions, prompts, and docs. Run with `pwsh plugin/skills/self-check/run.ps1` (or `./run.sh` on macOS/Linux) or by asking "kushi self-check". |
+| `intro` | Self-introduction + interactive walkthrough. Triggered by "what is kushi", "what can you do", "kushi intro", "i'm new to kushi", "kushi help". |

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

@@ -0,0 +1,73 @@
+# Answer-from-Evidence Doctrine
+
+Applies to: `ask-project` and any future read-only Q&A skill.
+
+## Core principle
+
+A Kushi answer is a **citation-backed projection** of the project corpus, not a generative summary. If the corpus does not support an assertion, the assertion does not appear in the answer.
+
+## The five rules
+
+### 1. Read-only at answer time
+
+`ask-project` MUST NOT call `pull-*`, WorkIQ, Graph, CRM live, or ADO live during answering. The corpus is whatever the producer skills have already written to disk. If the corpus is stale or missing, surface that fact and offer a refresh — do not silently fix it.
+
+### 2. Project boundary is absolute
+
+Every file read during a single answer MUST live under the resolved `<engagement-root>/<project>/` (or `TempAssets/<project>/`) folder. Reading another project's evidence to enrich an answer is a doctrine violation. If the user asks a comparison question, run the answer twice (once per project) and merge in the response, citing each side separately.
+
+### 3. State/ before Evidence/ before snapshot/ before external-context/
+
+Default load order:
+
+1. `State/<topic>.md` — already curated, already cited; cheapest.
+2. `Evidence/<alias>/_Consolidated/<latest>.md` — cross-source merge of recent activity.
+3. `Evidence/<alias>/<source>/<latest>.md` — per-source weekly stream.
+4. `Evidence/<alias>/<source>/snapshot/...` — current-state-of-entity files.
+5. `external-context/*.md` — out-of-band summaries (OneNote pulls, ad-hoc captures).
+6. `<project>/SharePoint/snapshot/files/<path>.md` — AI-summarized doc bodies (use only for doc-content questions).
+
+Stop reading as soon as the answer is supported by ≥1 cited source. Do NOT read every file under the project.
+
+### 4. Citation is per-assertion, not per-paragraph
+
+Every fact, decision, name, date, $ figure, status, or claim carries an inline `[source: <alias>/<folder>/<file> · YYYY-MM-DD]` citation. The date is the **evidence date** (when the source was captured / written), not today. CRM and ADO citations use the record-ID form: `[source: CRM record FE-XXXX field <name> · YYYY-MM-DD]` or `[source: ADO #NNN field <name> · YYYY-MM-DD]`.
+
+Aggregate "sources used" footer is allowed but does NOT replace inline cites.
+
+### 5. Three honest exits
+
+When the corpus is insufficient, the answer MUST end in one of:
+
+- **"I don't have evidence for that."** — corpus is silent on the question.
+- **"Evidence is stale."** — last pull older than `chat.freshness_warn_days`; offer refresh.
+- **"Evidence conflicts."** — two cited sources disagree; show both, mark confidence low, point at `09_open-questions.md`.
+
+Inventing, smoothing-over, or guessing is forbidden.
+
+## Confidence rubric
+
+| Level | Required conditions |
+|---|---|
+| **high** | Answer is from `State/*.md` (already curated) OR ≥2 corroborating Evidence files; AND freshness ≤14d. |
+| **medium** | Single-source Evidence file; OR State file older than underlying Evidence change; OR freshness 14–30d. |
+| **low** | Snapshot/summary inference only; OR freshness >30d; OR cited sources disagree. |
+
+`ask-project` MUST emit a one-line confidence verdict at the end of every non-trivial answer.
+
+## What ask-project never does
+
+- Write any file (no logging answers back to disk; that's a future enhancement).
+- Send any outbound message.
+- Trigger a `pull-*` skill.
+- Cross project boundaries.
+- Answer without citations.
+- Predict, forecast, or extrapolate beyond what evidence states.
+
+## 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).
+- **`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

@@ -0,0 +1,116 @@
+---
+applyTo: "**"
+description: "Auth pre-flight, token reuse, retry, and structured error logging for every external service call. Skipping any of this causes silent 401 loops and false 'no evidence' reports."
+---
+
+# Auth, Retry, and Error Logging — Always-On
+
+Every kushi skill that calls an external service (Graph / m365_*, WorkIQ, Dataverse / CRM, ADO, SharePoint) MUST follow this. Do not skip the pre-flight just because "auth probably works".
+
+> **See also:** `azure-auth-patterns.instructions.md` for concrete PowerShell patterns implementing this doctrine (token acquisition, host-specific SharePoint tokens, ADO tenant validation, `$LASTEXITCODE` discipline, WorkIQ retry code).
+
+---
+
+## 1. Service pre-flight (mandatory)
+
+Before the first call to a given service in a run, run the matching pre-flight. Failure → record `errors[]` entry with `phase: preflight`, mark that source `❌ skipped (auth)`, continue with the rest of the run.
+
+| 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. |
+| 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`. |
+
+---
+
+## 2. Token reuse
+
+Acquire each token **once per run**, store in a named variable, reuse for every call to that service. On HTTP 401 mid-run: re-acquire **once** and retry the failed call. Still 401 → record `errors[]` and stop calling that service this run.
+
+---
+
+## 3. Retry pattern (transient failures only)
+
+```
+maxRetries = 2
+attempt = 0
+do:
+  attempt++
+  result = call()
+  if exit_ok and not transient_error_signature(result): return result
+  if attempt > maxRetries: record errors[] and stop
+  sleep(3 * attempt)  # 3s, 6s
+```
+
+**Transient signatures** (eligible for retry): `Server error`, `Unexpected error`, exit code != 0 with empty stderr, HTTP 5xx, HTTP 401 (once only after token re-acquire).
+
+**Throttling signatures** (DO NOT retry the same query): `tooManyRequests`, `More than 3 retries performed`, `high demand`. Record `throttled-tooManyRequests`, narrow scope ONCE if a narrower query exists, then stop and continue with other sources.
+
+**Permanent signatures** (DO NOT retry): `Sorry, I can't` (copyright/blocked transcript), HTTP 403 `accessDenied`, HTTP 404, HTTP 400 with field-level error. Record and continue.
+
+---
+
+## 4. Structured error log (run-log.yml)
+
+Every failure — preflight, transient, throttled, permanent — appends an entry to `sources.<source>.errors[]` in the project's `Evidence/run-log.yml`. Schema:
+
+```yaml
+sources:
+  <source>:
+    last_run: '<ISO>'
+    last_status: 'ok' | 'partial' | 'failed' | 'skipped-auth'
+    errors:
+      - ts: '<ISO>'
+        phase: 'preflight' | 'snapshot' | 'stream' | 'token-acquire'
+        path: 'workiq' | 'graph' | 'm365_*' | 'dataverse' | 'ado-rest' | 'sharepoint-rest'
+        signature: 'workiq-eula-required' | 'graph-401-notes-scope' | 'tool-error' | 'throttled-tooManyRequests' | 'no-match' | 'transcripts-not-generated' | '<other>'
+        attempts: <int>
+        retried: true|false
+        action_taken: 'fell-back-to-host' | 'skipped' | 'narrowed-scope-and-retried' | 'recorded-and-continued'
+        next_step: '<actionable next thing for a future run or user>'
+        details: '<short message>'
+```
+
+The skill MUST set `last_status` based on errors:
+- No errors → `ok`
+- Errors but some evidence written → `partial`
+- All paths failed, no evidence → `failed`
+- Preflight failed → `skipped-auth`
+
+---
+
+## 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.
+
+| 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 |
+
+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`.
+
+---
+
+## 6. Try-again UX
+
+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).
+
+---
+
+## 7. Never silent
+
+If a source is partially broken, the run summary table MUST display the status per source with the next-step:
+
+```
+| source | status | items | next_step |
+| onenote | partial | 0 | Run `workiq accept-eula` once, then re-run `kushi pull onenote <project>` |
+| meetings | partial | 2 | Transcripts not generated for YYYY-MM-DD meetings; reconstructed from chat. To get transcripts on future meetings, enable Teams transcription before joining. |
+```

package/plugin/instructions/az-auth-conditional.instructions.md

@@ -0,0 +1,39 @@
+---
+applyTo: "**"
+description: "Conditional az login — only required if CRM/ADO are enabled. M365-only users via WorkIQ never need az login. Failures are soft warnings, not hard stops."
+---
+
+# Conditional az login
+
+The skill calls `az account get-access-token` only when CRM (Dataverse) or ADO are configured. WorkIQ does not require `az login`. Most M365-only users will never need to run `az login`.
+
+## Decision logic
+
+```
+crm_enabled = Test-Path <engagement-root>/.project-evidence/crm/config.yml
+ado_enabled = Test-Path <engagement-root>/.project-evidence/ado/config.yml
+
+if (NOT crm_enabled AND NOT ado_enabled):
+    Skip az check entirely. Display "az sign-in skipped (no CRM/ADO configured)".
+else:
+    Try `az account show` (no browser pop-up).
+    If signed-in: continue.
+    If NOT signed-in: prompt user with command suggestion (NOT auto-launch):
+        "az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47"
+        After they sign in, re-run.
+    If signed-in but token request fails (403, etc.): SOFT WARNING.
+        - CRM/ADO sources will be skipped this run.
+        - All M365 sources via WorkIQ continue normally.
+        - Append a `## Auth Notes` section to the run summary listing what was skipped.
+```
+
+## Tenant ID
+
+The Microsoft tenant ID for ADO + CRM JIT auth is `72f988bf-86f1-41af-91ab-2d7cd011db47`. If you suggest `az login`, ALWAYS include `--tenant 72f988bf-86f1-41af-91ab-2d7cd011db47`.
+
+## Never block on az failures
+
+If `az login` fails or token acquisition fails:
+- Display the error.
+- Mark CRM/ADO sources as `❌ skipped (auth)` in the run summary.
+- CONTINUE the rest of the run. Never abort the whole bootstrap/refresh just because CRM is unreachable.

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

@@ -0,0 +1,226 @@
+---
+applyTo: "**"
+description: "Concrete PowerShell patterns for Azure CLI auth, token acquisition, host-specific SharePoint tokens, ADO tenant validation, and WorkIQ retry. Companion to auth-and-retry / az-auth-conditional / workiq-first."
+---
+
+# Azure Auth Patterns — Concrete How-To
+
+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.
+
+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.
+
+---
+
+## 1. Session pre-check (always run first)
+
+Before any token acquisition, verify the Azure CLI session and capture the active identity:
+
+```powershell
+$accountJson = az account show --output json --only-show-errors 2>&1
+if ($LASTEXITCODE -ne 0) {
+    throw "Azure CLI session not found. Run: az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47"
+}
+$account = $accountJson | ConvertFrom-Json
+Write-Host "Active tenant: $($account.tenantId) | Account: $($account.user.name)"
+```
+
+Per `az-auth-conditional`: if neither CRM nor ADO is enabled for this engagement, **skip this entire section** and proceed directly to WorkIQ. M365-only users never need `az login`.
+
+---
+
+## 2. Token acquisition — per service
+
+Acquire each token **once per run** (per `auth-and-retry.instructions.md §2`). The tenant ID for Microsoft is `72f988bf-86f1-41af-91ab-2d7cd011db47` — pull it from config when possible, fall back to this literal only for the `az login --tenant` suggestion text.
+
+### 2.1 CRM / Dataverse
+
+```powershell
+$crmConfig   = Get-Content "$engagementRoot\.project-evidence\crm\config.yml" -Raw | ConvertFrom-Yaml  # or JSON variant
+$tenant      = $crmConfig.tenantId
+$crmBaseUrl  = $crmConfig.baseUrl
+$crmToken    = (az account get-access-token --tenant $tenant --resource $crmBaseUrl --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($crmToken)) {
+    throw "Failed to get CRM token (exit $LASTEXITCODE). Run: az login --tenant $tenant"
+}
+$crmHeaders = @{
+    Authorization      = "Bearer $crmToken"
+    Accept             = 'application/json'
+    'OData-Version'    = '4.0'
+    'OData-MaxVersion' = '4.0'
+    Prefer             = 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"'
+}
+```
+
+### 2.2 Azure DevOps
+
+ADO's resource is the constant `499b84ac-1321-427f-aa17-267ca6975798` (Visual Studio Team Services). Read it from config — never hardcode:
+
+```powershell
+$adoConfig = Get-Content "$engagementRoot\.project-evidence\ado\config.yml" -Raw | ConvertFrom-Yaml
+$tenant    = $adoConfig.tenantId
+$adoRes    = $adoConfig.resource   # 499b84ac-1321-427f-aa17-267ca6975798
+$adoToken  = (az account get-access-token --tenant $tenant --resource $adoRes --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($adoToken)) {
+    throw "Failed to get ADO token (exit $LASTEXITCODE). Run: az login --tenant $tenant"
+}
+$adoHeaders = @{ Authorization = "Bearer $adoToken"; Accept = 'application/json'; 'Content-Type' = 'application/json' }
+```
+
+### 2.3 SharePoint / OneDrive — **host-specific** (critical)
+
+SharePoint tokens are bound to a hostname. **Do not assume the configured default host applies to every link.** Personal sites, customer tenants, and `*-df` preview hosts all need their own tokens.
+
+Derive the resource from the target URL's origin and acquire the token for that exact host:
+
+```powershell
+$targetUrl  = '<sharepoint-or-onedrive-url>'
+$targetUri  = [Uri]$targetUrl
+$spResource = "$($targetUri.Scheme)://$($targetUri.Host)"
+$spToken    = (az account get-access-token --tenant $tenant --resource $spResource --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($spToken)) {
+    throw "Failed to get SharePoint token for host $spResource (exit $LASTEXITCODE). Run: az login --tenant $tenant"
+}
+$spHeaders = @{ Authorization = "Bearer $spToken"; Accept = 'application/json' }
+```
+
+Hosts commonly seen in this workspace: `microsoft-my.sharepoint.com`, `microsoft-my.sharepoint-df.com`, `microsofteur-my.sharepoint.com`, customer tenant `*.sharepoint.com`.
+
+#### SharePoint URL traps — browser vs. canonical API
+
+A raw browser-facing SharePoint URL is often the **wrong endpoint** for bearer-token retrieval:
+
+- `/_layouts/15/Doc.aspx?...`, `?web=1`, and Office share links (`/:x:/`, `/:p:/`, `/:w:/`, `/:b:/`) are browser shells or share URLs — **not** the canonical file-read API.
+- A raw `401` from those URLs does NOT prove Azure CLI auth is broken.
+- **For share links** → prefer Microsoft Graph `shares/{shareId}/driveItem` with `Prefer: redeemSharingLink`.
+- **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
+
+**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.
+
+```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/"
+}
+# Prefer narrowest WorkIQ query: one_sectionFileId > one_sectionName > project-alias keyword search.
+```
+
+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.
+
+---
+
+## 3. ADO tenant validation (before any ADO call)
+
+Allowed tenants are config-driven, not hardcoded. Validate before the first ADO call:
+
+```powershell
+# $account from Section 1
+$adoConfig      = Get-Content "$engagementRoot\.project-evidence\ado\config.yml" -Raw | ConvertFrom-Yaml
+$allowedTenants = @($adoConfig.allowedTenantIds)
+$currentTenant  = $account.tenantId
+if ($allowedTenants.Count -gt 0 -and $allowedTenants -notcontains $currentTenant) {
+    throw "Current tenant '$currentTenant' is not allowed for ADO. Allowed: $($allowedTenants -join ', '). Run: az login --tenant $($allowedTenants[0])"
+}
+```
+
+If validation fails, record `errors[]` with `signature: ado-tenant-mismatch` and mark the ADO source `❌ skipped (auth)` per `auth-and-retry §4` — do not abort the whole run.
+
+---
+
+## 4. Mandatory $LASTEXITCODE pattern
+
+Check `$LASTEXITCODE` immediately after every `az` invocation. Never proceed with a null or empty result. Always pipe `2>&1` so stderr is captured into error messages, and use `--only-show-errors` on token calls to keep informational banners out of the token value:
+
+```powershell
+$result = az <command> --output json --only-show-errors 2>&1
+if ($LASTEXITCODE -ne 0) {
+    throw "az command failed (exit $LASTEXITCODE): $result"
+}
+```
+
+---
+
+## 5. WorkIQ availability + retry (concrete)
+
+Per `workiq-first.instructions.md` and `auth-and-retry.instructions.md §3`. Before the first WorkIQ call per run:
+
+```powershell
+if (-not (Get-Command workiq -ErrorAction SilentlyContinue)) {
+    throw "workiq CLI not found on PATH. WorkIQ queries cannot proceed. See install-workiq.md."
+}
+```
+
+Retry loop (transient errors only — throttling is NOT a retry case):
+
+```powershell
+$maxRetries = 2
+$attempt    = 0
+$output     = $null
+do {
+    $attempt++
+    $output = (workiq ask -q $query 2>&1 | Out-String).Trim()
+    $isTransient = ($LASTEXITCODE -ne 0) -or ($output -match '^(Error:\s+Unexpected error|Server error)')
+    $isThrottled = ($output -match 'tooManyRequests|More than 3 retries performed|high demand')
+    if ($isThrottled) {
+        # Do NOT retry the same query. Narrow once if possible, else record and continue.
+        throw "WorkIQ throttled — record 'throttled-tooManyRequests' and move on per auth-and-retry §3."
+    }
+    if (-not $isTransient) { break }
+    if ($attempt -gt $maxRetries) {
+        throw "WorkIQ failed after $attempt attempt(s): $output"
+    }
+    Start-Sleep -Seconds (3 * $attempt)
+} while ($true)
+```
+
+---
+
+## 6. Token reuse + mid-run 401 recovery
+
+Per `auth-and-retry §2`: acquire each token once, reuse it. On HTTP 401 mid-run, **re-acquire once** and retry the failed call. If still 401, record `errors[]` with `signature: token-401-after-reacquire` and stop calling that service.
+
+```powershell
+# Mid-run 401 — re-acquire then retry once
+$crmToken = (az account get-access-token --tenant $tenant --resource $crmBaseUrl --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+$crmHeaders.Authorization = "Bearer $crmToken"
+# retry the failed call ONCE
+```
+
+---
+
+## 7. Failure signature reference
+
+Maintained alongside `auth-and-retry §3` (canonical) — quick lookup:
+
+| Symptom | Likely cause | Recovery |
+|---------|--------------|----------|
+| `az account show` non-zero | Not logged in | `az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47` |
+| Token empty / whitespace | Expired session or parse issue | Re-login, re-acquire |
+| HTTP 401 on API call | Token expired mid-run | Re-acquire once (§6), retry once |
+| HTTP 401 on SharePoint URL | Token for wrong host | Re-acquire for exact URL origin (§2.3); if still 401, record `blocked-host-or-permissions-401` |
+| Browser SP URL 401, but Graph shares / SP REST 403 | Wrong retrieval surface; canonical API exposed real permission failure | Stop retrying browser URL; classify as share/permission problem |
+| OneNote via Graph 401/40001 | Wrong path | Switch to WorkIQ, narrowest query first (`one_sectionFileId`) |
+| ADO tenant mismatch | Wrong-tenant session | `az login --tenant <allowed>` (§3) |
+| Dataverse 400 OData | Invalid field / filter | Revert to known-good query; add filters one at a time |
+| WorkIQ exits non-zero (transient) | Server hiccup | Retry pattern (§5), max 2 retries |
+| WorkIQ `tooManyRequests` | Throttling | Narrow scope once; else record `throttled-tooManyRequests` and stop |
+| WorkIQ "Sorry, I can't" | Blocked/copyright | Record `skipped-blocked`, continue |
+
+---
+
+## 8. Config source of truth
+
+| Service | Config file (engagement-scoped) |
+|---------|---------------------------------|
+| Dynamics 365 / CRM | `<engagement-root>/.project-evidence/crm/config.yml` |
+| Azure DevOps | `<engagement-root>/.project-evidence/ado/config.yml` |
+| Microsoft Graph / M365 / OneNote | `<engagement-root>/.project-evidence/m365/m365-mutable.json` + `<engagement-root>/.project-evidence/m365/m365-auth.json` |
+| WorkIQ CLI path | `~/.copilot/project-evidence.yml` (user-scoped) |
+| Global integrations (optional) | `~/.copilot/integrations/{crm,ado}/` |
+
+Always read tenant IDs, resource URLs, org URLs, and allowed-tenant lists from these files at the start of each run. **Never hardcode them in skills or prompts.** The only acceptable literal in instructions/prompts is the public Microsoft tenant ID `72f988bf-86f1-41af-91ab-2d7cd011db47` in the user-facing `az login --tenant ...` suggestion text.