kushi-agents 3.4.1

package/plugin/skills/intro/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: "intro"
+version: "2.1.0"
+description: "Use when a user asks about Kushi, what it does, what its skills are, or wants a hands-on tour. Offers a quick overview OR an interactive walkthrough of every kushi verb (including Q&A and FDE authoring) with copy-and-send demo prompts."
+triggers:
+  - "what is kushi"
+  - "what can kushi do"
+  - "tell me about kushi"
+  - "kushi intro"
+  - "introduce yourself"
+  - "what are your skills"
+  - "show me kushi"
+  - "how does kushi work"
+  - "kushi help"
+  - "demo yourself"
+  - "i'm new to kushi"
+---
+
+# intro
+
+Introduce Kushi to new users and demonstrate every verb hands-on. When a user asks "What is Kushi?", "What can it do?", "How does this work?", or any equivalent identity / capability / onboarding question, this skill activates and offers two modes:
+
+1. **Quick Overview** — a scannable summary of every verb and skill (≈ 30 seconds to read).
+2. **Interactive Walkthrough** — a guided tour where the user runs each verb against a real (or fictional) project, one at a time, with ready-to-send prompts.
+
+## Principles
+
+- **User chooses the format.** Always offer both modes — never assume which one the user wants.
+- **Show, don't tell.** In interactive mode, each verb is demonstrated with a real prompt against a real project (or a fictional one if no projects are bootstrapped yet).
+- **One moment at a time.** Present one verb demo at a time. Wait for the user before advancing.
+- **Low commitment.** The user can exit at any point — say so at the start.
+- **No jargon on first contact.** Assume the user has never seen Kushi before. Define snapshot/stream/watermark/run-log on first use.
+- **Honesty about state.** If no projects are bootstrapped yet, the demo proposes a fictional project (e.g. `Contoso Discovery`) so the user can see verbs work without committing real data.
+
+## Trigger Detection
+
+Activate this skill when the user's request matches any of:
+
+- Identity: "Who are you?", "What is Kushi?", "Tell me about yourself"
+- Capability: "What can you do?", "What are your skills?", "What's the difference between bootstrap and refresh?"
+- Onboarding: "I'm new to Kushi", "How do I get started?", "Help me learn Kushi", "kushi help"
+- Demo: "Show me Kushi", "Walk me through it", "Demo yourself"
+
+Do **not** activate when the user has already asked for a specific verb (e.g. "kushi bootstrap AGCO") — in that case, route directly to that verb.
+
+## Response Mode Selection
+
+When triggered, present this exact opening, then wait:
+
+> I'm **Kushi** — a multi-source project evidence agent. I capture **snapshots** (current state of entities like meetings, OneNote pages, ADO items) and **streams** (timestamped events) across Email, Teams, Meetings, OneNote, SharePoint, CRM, and ADO, then either let you ask cited questions over that Evidence — or render an outcome-based **State** view (on the `full` profile) — or author **FDE engagement reports** grounded in an FDE reference pack.
+>
+> Three install profiles: `core` (aggregator only), `standard` (default — adds bootstrap/refresh + FDE authoring), `full` (adds State/ rollup).
+>
+> How would you like to learn what I can do?
+>
+> **1 — Quick Overview** — scannable summary of every verb and skill (reply `1` or `overview`)
+> **2 — Interactive Walkthrough** — guided tour where you run each verb hands-on (reply `2` or `walkthrough`)
+
+Accept these as equivalent:
+
+- `1`, `one`, `overview`, `quick`, `summary` → Mode 1
+- `2`, `two`, `walkthrough`, `interactive`, `demo`, `tour`, `hands-on` → Mode 2
+
+---
+
+## Mode 1: Quick Overview
+
+Present this verbatim:
+
+> ## Kushi at a glance
+>
+> **Identity.** Kushi is a single Copilot agent backed by 15 specialized skills. Instead of orchestrating WorkIQ + m365 + ADO + CRM yourself, you give kushi a verb and a project name, and it routes through the right pulls, consolidates, renders state, and answers cited Q&A — citing every assertion back to its source file.
+>
+> **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 `YYYY-MM-DD_<source>-stream.md`). State files cite both. Snapshot answers *"what IS true now?"* Stream answers *"when did it happen?"*
+>
+> ### Verbs
+>
+> | Verb | Profile | Default window | What it does |
+> |---|---|---|---|
+> | `kushi aggregate <project>` | core+ | since last watermark | Pull-only orchestrator — runs every `pull-*` + consolidate. No State/. |
+> | `kushi bootstrap <project>` | standard+ | last 30 days | First-time setup — lays configs side-by-side, scaffolds folders, runs initial pull. Builds State/ on `full` only. |
+> | `kushi refresh <project>` | standard+ | since last watermark (fallback 7d) | Incremental pull driven by run-log watermarks. Builds State/ on `full` only. |
+> | `kushi refresh <project> last N days` | standard+ | N days | Override window. |
+> | `kushi state <project>` | **full** | n/a | Re-render `State/` from existing `Evidence/` (no source pulls). |
+> | `kushi consolidate <project> last N days` | core+ | N days | Merge per-user streams into `_Consolidated/`. |
+> | `kushi status <project>` | core+ | n/a | Read-only run-log inspector. |
+> | `kushi ask <project> <question>` | core+ | n/a | **Cited Q&A** over Evidence/ (+ State/ on full). Auto-routes when you name a project + ask a question — no `kushi ask` prefix needed. |
+> | `kushi pull <source> for <project> [window]` | core+ | as supplied | Run one `pull-<source>` skill in isolation. |
+> | `kushi fde-intake <project>` | **standard+** | n/a | Author/update the FDE Intake document (`Reports/00-FDE-Intake-<project>.md`). |
+> | `kushi fde-report <project> [shape]` | **standard+** | n/a | Generate an FDE report in one of 5 shapes: `weekly` (default) / `short` / `long` / `fitness` / `stage-readiness`. |
+> | `kushi fde-triage <project>` | **standard+** | n/a | Produce the full 7-file FDE Triage bundle. |
+> | `kushi self-check` | all | n/a | Validate skills, instructions, prompts, and live install consistency. |
+> | `kushi intro` (this) | all | n/a | This walkthrough. |
+>
+> ### Skills (18)
+>
+> | Domain | Skill | Profile | Snapshot? | Stream? |
+> |---|---|---|---|---|
+> | **Orchestrators** | `aggregate-project` | core+ | — | — |
+> | | `bootstrap-project` | standard+ | — | — |
+> | | `refresh-project` | standard+ | — | — |
+> | | `build-state` | **full** | — | — |
+> | | `consolidate-evidence` | core+ | — | — |
+> | | `project-status` | core+ | — | — |
+> | **Per-source pulls** | `pull-email` | core+ | — | ✅ |
+> | | `pull-teams` | core+ | ✅ | ✅ |
+> | | `pull-meetings` | core+ | ✅ | ✅ |
+> | | `pull-onenote` | core+ | ✅ | ✅ |
+> | | `pull-sharepoint` | core+ | ✅ | ✅ |
+> | | `pull-crm` | core+ | ✅ | ✅ |
+> | | `pull-ado` | core+ | ✅ | ✅ |
+> | **Consumer (Q&A)** | `ask-project` | core+ | reads both | — |
+> | **FDE authoring** | `fde-intake` | standard+ | reads both | — |
+> | | `fde-report` | standard+ | reads both | — |
+> | | `fde-triage` | standard+ | reads both | — |
+> | **Meta** | `self-check` | all | — | — |
+> | | `intro` | all | — | — |
+>
+> ### Core rules (apply to every skill)
+>
+> - **WorkIQ-first** — if WorkIQ is reachable, use it; only fall back to host m365 tools if it is not.
+> - **Citation Ledger** — every assertion in any output cites `[source: <alias>/<folder>/<file> · YYYY-MM-DD]`.
+> - **Side-by-side config** — every skeleton config is paired with a live filled file in the same folder.
+> - **NEVER reach out** — Kushi never sends outbound messages. Recommendations land in `State/09_open-questions.md`.
+> - **Engagement-root resolution** — single root (default `OneDrive\ISE\Engagement Assets`) holds all projects.
+>
+> ### Want to go deeper?
+>
+> - Reply `walkthrough` for the interactive guided tour (≈ 5 min).
+> - Reply `bootstrap <project name>` to start a real engagement.
+> - Or just describe what you need — I'll route it to the right verb.
+
+---
+
+## Mode 2: Interactive Walkthrough
+
+### Pre-flight
+
+Before opening, check whether any project is already bootstrapped:
+
+1. Read `~/.copilot/project-evidence.yml` (personal config). If `active_projects` has entries, pick the most recent as the demo target — substitute that name into `{{active_project}}` placeholders below.
+2. If none, propose a fictional project named **Contoso Discovery** and tell the user that Try-it prompts will use that name; they can substitute their own at any time.
+
+### Navigation Keywords
+
+After every demo moment, list:
+
+- `next` (or `n`) — advance to the next moment.
+- `skip` (or `s`) — jump to the next moment without trying this one.
+- `done` (or `d`, `exit`, `quit`) — exit the walkthrough; show the cheat sheet.
+- `try` (or `t`) — actually run the Try-it prompt now (kushi will execute it for the active project).
+
+### Opening
+
+> Great — let's tour Kushi end-to-end. Each step:
+>
+> - Explains **one verb** in plain language.
+> - Gives you a **ready-to-send prompt** in a code block — copy-paste it, or just reply `try` and I'll run it for you.
+> - Waits for `next` / `skip` / `done` before advancing.
+>
+> Demo target for this tour: **{{active_project}}**. (Substitute any project name in the Try-it prompts.)
+>
+> Reply `next` (or just say "let's go") to begin.
+
+### Demo Moments
+
+Present in order. After each moment, append the navigation block.
+
+---
+
+**Moment 1 — Snapshot vs Stream (the foundation)**
+
+> **The single most important rule in Kushi.** Every per-source skill writes two kinds of evidence:
+>
+> - **Snapshot** = current state of one entity. One file per entity. Replaced on every refresh. No date in filename. Example: `Evidence/{{alias}}/Teams-Chats/snapshot/roster.md` always shows the *current* member list of the project chat — not who was in it three weeks ago.
+> - **Stream** = timestamped events. One file per ISO week. Append-only. Dated filename. Example: `Evidence/{{alias}}/Email/stream/2026-05-04_email-stream.md` shows every email received during the week of May 4.
+>
+> State files (e.g. `02_stakeholders.md`) cite snapshots for *current* facts and streams for *temporal* claims like "decision made on May 5".
+
+Reply `next` to see how to bootstrap a project, or `done` to exit.
+
+---
+
+**Moment 2 — Bootstrap a new project**
+
+> **`bootstrap-project`** — first-time setup for an engagement. Lays configs side-by-side, scaffolds `Evidence/` and `State/` folders, asks you to confirm sources, then runs the initial 30-day pull across every enabled source.
+
+**Try it** — copy and send (or reply `try`):
+
+```
+kushi bootstrap {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 3 — Refresh with a watermark**
+
+> **`refresh-project`** — incremental pull driven by `Evidence/run-log.yml` watermarks. If the last successful pull was Monday 9 AM, refresh picks up everything since then. No window arg = "since last watermark", with a 7-day fallback if no watermark exists.
+
+**Try it — default (since last watermark):**
+
+```
+kushi refresh {{active_project}}
+```
+
+**Try it — explicit window:**
+
+```
+kushi refresh {{active_project}} last 14 days
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 4 — Pull one source in isolation**
+
+> **`pull-<source>`** — run a single per-source skill without touching the others. Useful when you only care about new ADO items, or you want to backfill OneNote pages without re-pulling email. Each `pull-*` skill is **WorkIQ-first** and writes to your alias subfolder under `Evidence/<alias>/<source>/`.
+
+**Try it — pull just email:**
+
+```
+kushi pull email for {{active_project}} last 7 days
+```
+
+**Try it — pull just ADO work items:**
+
+```
+kushi pull ado for {{active_project}} last 30 days
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 5 — Render State from existing Evidence**
+
+> **`build-state`** — re-render every file under `State/` from existing `Evidence/`, **without any source pulls**. Use this when you want to see how the state view changes after manually editing evidence, or when you've consolidated streams from multiple contributors and want a fresh outcome view.
+>
+> State output is outcome-based — `00_overview.md`, `01_decisions.md`, `02_stakeholders.md`, `03_architecture.md`, `04_workshops.md`, `05_actions.md`, `06_risks.md`, `07_timeline.md`, `08_artifacts.md`, `09_open-questions.md`. Every assertion cites the evidence file + date it came from.
+
+**Try it:**
+
+```
+kushi state {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 6 — Consolidate multi-user evidence**
+
+> **`consolidate-evidence`** — merge per-user streams into `Evidence/_Consolidated/`. Only needed if multiple contributors are pulling for the same project. The consolidated file tags each entry with the contributor alias so provenance is preserved.
+
+**Try it:**
+
+```
+kushi consolidate {{active_project}} last 7 days
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 7 — Inspect the run-log**
+
+> **`project-status`** — read-only inspector for `Evidence/run-log.yml`. Shows per-source watermarks, last successful run, and any failures. Use it before kicking off a refresh to see what kushi will pull.
+
+**Try it:**
+
+```
+kushi status {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 8 — Ask the project (cited Q&A)**
+
+> **`ask-project`** — read-only natural-language Q&A over what's already been captured. Loads the cheapest set of files needed (Evidence/ first; State/ on `full`), cites every assertion `[source: <alias>/<folder>/<file> · YYYY-MM-DD]`, warns if the relevant source is older than 14 days, and ends with a Confidence verdict.
+>
+> **Auto-routes — no prefix needed.** Just name a project and ask a question. The slash form (`/ask`) and the explicit `kushi ask` are also accepted.
+>
+> **Never** triggers a `pull-*`. If evidence is stale or missing, it offers `kushi refresh <project>` and stops.
+
+**Try it — explicit form:**
+
+```
+kushi ask {{active_project}} what's the status?
+```
+
+**Try it — auto-routed (no prefix):**
+
+```
+what's the MACC for {{active_project}} and is it confirmed?
+```
+
+```
+who is the EM on {{active_project}}?
+```
+
+```
+summarize {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 9 — FDE Intake (first-artifact authoring)**
+
+> **`fde-intake`** — author or update the FDE Intake document at `Reports/00-FDE-Intake-<project>.md`. It is the first artifact in any FDE engagement and is consumed by FDE Triage to decide which team is best suited and whether the engagement is billable.
+>
+> Grounded in **two sources**: the project's Evidence/ + the FDE reference pack (`intake-questions.md`, `report-doctrine.md`, `core-fde-reference.md`). Embeds inline `> ⚠️ VALIDATION WARNING — Rule X.Y` blockquotes wherever Evidence is silent.
+>
+> **Standard + Full profiles only.**
+
+**Try it:**
+
+```
+kushi fde-intake {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 10 — FDE Report (5 shapes)**
+
+> **`fde-report`** — generate an FDE-shaped engagement report. One skill, five shapes:
+>
+> - `weekly` (default) — internal status, 1–2 pages.
+> - `short` — customer-facing, sanitized (no MACC / MS staffing / CRM IDs).
+> - `long` — incoming-crew handoff, 3–5 pages.
+> - `fitness` — 10-row FDE Fitness scorecard + verdict.
+> - `stage-readiness` — "should we advance to the next FDE stage?" check.
+>
+> Read-only against Evidence; no outbound. Apply all 9 doctrine rules.
+
+**Try it — weekly default:**
+
+```
+kushi fde-report {{active_project}}
+```
+
+**Try it — fitness scorecard:**
+
+```
+kushi fde-report {{active_project}} fitness
+```
+
+**Try it — stage-readiness check:**
+
+```
+kushi fde-report {{active_project}} stage-readiness
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 11 — FDE Triage (full 7-file bundle)**
+
+> **`fde-triage`** — produce the full FDE Triage bundle: 7 companion files at `Reports/triage/<YYYY-MM-DD>/`:
+>
+> 1. `00-fde-analysis.md` — concise FDE analysis (entry point)
+> 2. `01-fde-fitness.md` — 10-row fitness scorecard
+> 3. `02-risk-analysis.md` — risks bucketed into 8 reference-pack categories
+> 4. `03-6Q.md` — 6-question engagement framing
+> 5. `04-readiness-checklist.md` — **mobilization readiness** (distinct from stage readiness)
+> 6. `05-executive-consolidated-report.md` — leadership readout
+> 7. `06-global-opportunity-and-reuse.md` — repeatability lens
+> 8. `07-validation-warnings-checklist.md` — central tracker (open / resolved / NA)
+>
+> Re-runs preserve user-edited statuses in file 07.
+
+**Try it:**
+
+```
+kushi fde-triage {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 12 — Self-check before committing**
+
+> **`self-check`** — Kushi has its own consistency checker. Before you commit changes to the kushi repo (or after editing an instruction file), run self-check to verify every skill is in the agent inventory, every prompt routes to a real skill, every cross-link resolves, and the live `~/.copilot/m-skills/kushi/` install matches the repo. Run it as a markdown report (default), JSON for CI (`-Json`), or with deeper hash + schema checks (`-Deep`). Cross-OS: on macOS/Linux use `./run.sh` (requires `pwsh` 7+).
+
+**Try it — quick:**
+
+```
+kushi self-check
+```
+
+**Try it — deep + strict for CI (Windows):**
+
+```
+pwsh plugin/skills/self-check/run.ps1 -Deep -StrictExit
+```
+
+**Try it — deep + strict for CI (macOS / Linux):**
+
+```
+./plugin/skills/self-check/run.sh -Deep -StrictExit
+```
+
+Reply `next` to see the closing cheat sheet, or `done` to exit.
+
+---
+
+### Closing
+
+> That's the full tour. Cheat sheet:
+>
+> | What you want | What to say |
+> |---|---|
+> | First-time engagement setup | `kushi bootstrap <project>` |
+> | Catch up since last pull | `kushi refresh <project>` |
+> | Backfill a custom range | `kushi refresh <project> last N days` |
+> | One source only | `kushi pull <source> for <project>` |
+> | Re-render state files (full only) | `kushi state <project>` |
+> | Merge contributors | `kushi consolidate <project>` |
+> | Inspect run-log | `kushi status <project>` |
+> | **Ask a question (cited Q&A)** | `kushi ask <project> <question>` — or just say it naturally |
+> | First-artifact FDE Intake | `kushi fde-intake <project>` |
+> | FDE report (5 shapes) | `kushi fde-report <project> [shape]` |
+> | Full FDE Triage bundle (7 files) | `kushi fde-triage <project>` |
+> | Pre-commit validation | `kushi self-check` (or `-Deep`) |
+> | This tour again | `kushi intro` |
+>
+> You can also describe what you need in plain language — kushi will route to the right verb. Reply `restart` to retake the tour, or just ask me anything.
+
+---
+
+## Validation Rules
+
+- Rule 1.1: Trigger detection must match before activating — never activate if the user has already asked for a specific verb.
+- Rule 1.2: Mode selection must always present BOTH options — never auto-route to one mode.
+- Rule 1.3: In walkthrough mode, each moment must wait for `next` / `skip` / `done` / `try` before advancing — never auto-advance.
+- Rule 1.4: `done` must work at every moment — never trap the user.
+- Rule 1.5: Try-it prompts must use the active project name from `~/.copilot/project-evidence.yml`, OR the placeholder `Contoso Discovery` if no projects are configured. Never invent a real-sounding project name.
+- Rule 1.6: Skill descriptions in this file must match `kushi.agent.md` and the live `SKILL.md` files — `self-check` D-checks catch drift.
+- Rule 1.7: Demo moments must reflect the actual verb count in `kushi.agent.md`. If a verb is added or removed, this file must be updated in the same commit (`self-check` warns on drift).

package/plugin/skills/project-status/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: "project-status"
+version: "2.0.0"
+description: "Show the run-log status for a project: per-source watermarks, last-pulled, item counts, weekly_files index, recent errors. No source calls."
+---
+
+# Skill: project-status
+
+Run this when the user says: "status of `<X>`", "@Kushi status `<X>`", "what was the last refresh for `<X>`", "show run-log for `<X>`".
+
+## Inputs
+
+- `<project>` — project to inspect.
+
+## Steps
+
+### Step 1 — Read run-log
+
+Read `<engagement-root>/<project>/Evidence/run-log.yml`.
+
+### Step 2 — Display per-source table
+
+```
+| Source     | Last Pulled         | Watermark           | Items | Status |
+|------------|---------------------|---------------------|-------|--------|
+| email      | 2026-05-07 17:14    | 2026-05-07 17:14:00 | 247   | ✅      |
+| teams      | 2026-05-07 17:14    | 2026-05-07 17:14:00 | 89    | ✅      |
+| onenote    | 2026-05-07 17:14    | 2026-05-07 17:14:00 | 12    | ✅      |
+| sharepoint | 2026-05-07 17:15    | 2026-05-07 17:15:00 | 34    | ✅      |
+| meetings   | 2026-05-07 17:15    | 2026-05-07 17:15:00 | 18    | ✅      |
+| crm        | 2026-05-07 17:15    | (snapshot)          | 6     | ✅      |
+| ado        | 2026-05-07 17:15    | 2026-05-07 17:15:00 | 23    | ✅      |
+```
+
+### Step 3 — Display weekly_files index
+
+```
+| Week       | Sources covered                                           |
+|------------|-----------------------------------------------------------|
+| 2026-04-13 | email, teams, meetings                                    |
+| 2026-04-20 | email, teams, onenote, meetings                           |
+| 2026-04-27 | email, teams, onenote, sharepoint, meetings               |
+| 2026-05-04 | email, teams, onenote, sharepoint, meetings               |
+```
+
+### Step 4 — Recent errors
+
+Scan run-log `history` for entries where `status != ok` in the last 5 runs. Display per source.
+
+### Step 5 — Suggest next action
+
+- If all watermarks within last 24h → "All sources fresh. No action needed."
+- If any watermark > 7d old → "Consider `@Kushi refresh `<X>`` to catch up."
+- If errors in recent runs → "Recent errors in `<source>`. Consider `@Kushi refresh `<X>` --source <source>`."
+
+## Triggers
+
+- "status of `<X>`"
+- "@Kushi status `<X>`"
+- "what was the last refresh for `<X>`"
+- "show run-log for `<X>`"

package/plugin/skills/pull-ado/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: "pull-ado"
+version: "2.0.0"
+description: "Pull ADO evidence (snapshot: work-item fields; stream: comments + state changes + history). Conditional az login per az-auth-conditional rule."
+---
+
+# Skill: pull-ado
+
+Pulls **ado** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — work item with all fields (title, type, area, iteration, parent, state, assignee, custom fields)
+- **stream/** — comments verbatim + state changes (old → new) + field changes + attachments — per work item
+
+WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
+
+## Inputs
+
+- `<project>` — already-resolved project name.
+- `<alias>` — current contributor.
+- `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
+- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
+
+## Resolution hints (pinned in mutable)
+
+- `ado.engagementId` — pinned engagement work-item ID
+- `ado.queryId` — saved query ID for the project
+- `ado.areaPath` / `ado.iterationPath` — for filtering
+
+## Snapshot pass
+
+Write `snapshot/items/<id>.md` per work item with every field. Top header: id, title, type, state, parent, area, iteration, assignee, last fetched.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/ado/snapshot/<entity>.md`
+
+Use template: `templates/snapshot/ado-<kind>.template.md`
+
+## Stream pass
+
+Per `evidence-thoroughness.instructions.md`: every comment verbatim with author + timestamp; every state change; every field change. Bucketed by ISO week into `stream/items/<id>/<YYYY-MM-DD>_ado-stream.md`.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/ado/stream/<YYYY-MM-DD>_ado-stream.md` (date = Monday of the ISO week the events fall in).
+
+Use template: `templates/weekly/ado-summary.template.md`
+
+If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+
+## Tools (in order)
+
+1. **WorkIQ** — ````$WorkIQQuery`````
+2. **Host fallback** — ADO REST API via `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798` (read connection/queries from `<engagement-root>/.project-evidence/ado/config.yml`)
+3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
+4. **Ask user** — paste verbatim source content if all above fail.
+
+Document which path succeeded under `## Source Basis` in each output file.
+
+## Mutable hints to upsert (during the run, not at the end)
+
+If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`:
+
+- `ado.engagementId` — pinned engagement work-item ID
+- `ado.queryId` — saved query ID for the project
+- `ado.areaPath` / `ado.iterationPath` — for filtering
+
+## Update run-log
+
+After successful pass:
+- `sources.ado.last_pulled = now`
+- `sources.ado.watermark = now` (stream only; snapshot has no watermark)
+- `sources.ado.item_count = <N>`
+- For each week touched, add to `weekly_files` index.
+
+## Stop conditions
+
+- Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
+- Multiple plausible candidates → ask user to pick, persist answer.
+- WorkIQ fails AND host fallback fails AND Graph fails → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.

package/plugin/skills/pull-crm/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: "pull-crm"
+version: "2.0.0"
+description: "Pull CRM (Dataverse) evidence (snapshot: engagement record fields; stream: notes/activities/status changes). Conditional az login per az-auth-conditional rule."
+---
+
+# Skill: pull-crm
+
+Pulls **crm** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — engagement record with every field the API returns (owner, status, account, dates, custom fields)
+- **stream/** — notes added, activities logged, field-level changes (old → new + actor + timestamp)
+
+WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
+
+## Inputs
+
+- `<project>` — already-resolved project name.
+- `<alias>` — current contributor.
+- `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
+- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
+
+## Resolution hints (pinned in mutable)
+
+- `crm.recordId` — pinned engagement record GUID (FE-NNNNN-style)
+- `crm.entitySetName` — Dataverse entity set name (e.g. `msdyn_engagements`)
+
+## Snapshot pass
+
+Write `snapshot/<record-id>.md` per CRM record with EVERY field the API returns (don't editorialize). Last fetched timestamp at top.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/crm/snapshot/<entity>.md`
+
+Use template: `templates/snapshot/crm-<kind>.template.md`
+
+## Stream pass
+
+Per `evidence-thoroughness.instructions.md`: every annotation verbatim with author + timestamp; every field-level change with old → new + actor + timestamp. Bucketed by ISO week into `stream/<record-id>/<YYYY-MM-DD>_crm-stream.md`.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/crm/stream/<YYYY-MM-DD>_crm-stream.md` (date = Monday of the ISO week the events fall in).
+
+Use template: `templates/weekly/crm-summary.template.md`
+
+If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+
+## Tools (in order)
+
+1. **WorkIQ** — ````$WorkIQQuery`````
+2. **Host fallback** — Dataverse REST Web API via `az account get-access-token` against the configured tenant (read connection from `<engagement-root>/.project-evidence/crm/config.yml`)
+3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
+4. **Ask user** — paste verbatim source content if all above fail.
+
+Document which path succeeded under `## Source Basis` in each output file.
+
+## Mutable hints to upsert (during the run, not at the end)
+
+If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`:
+
+- `crm.recordId` — pinned engagement record GUID (FE-NNNNN-style)
+- `crm.entitySetName` — Dataverse entity set name (e.g. `msdyn_engagements`)
+
+## Update run-log
+
+After successful pass:
+- `sources.crm.last_pulled = now`
+- `sources.crm.watermark = now` (stream only; snapshot has no watermark)
+- `sources.crm.item_count = <N>`
+- For each week touched, add to `weekly_files` index.
+
+## Stop conditions
+
+- Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
+- Multiple plausible candidates → ask user to pick, persist answer.
+- WorkIQ fails AND host fallback fails AND Graph fails → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.