kushi-agents 3.4.1 → 3.12.1

package/README.md

@@ -6,6 +6,10 @@
 
 > A multi-skill GitHub Copilot agent for grounded engagement evidence — across Email, Teams, Meetings, OneNote, SharePoint, Dataverse (CRM), and Azure DevOps.
 
+> **KUSHI** — **K**nowledge **U**nification for **S**takeholder **H**andoff & **I**nsight.
+>
+> *Also: Kushi (குஷி) is Tamil for "happiness" — the kind you feel when every "what was decided?" question has a cited answer in seconds.*
+
 📖 **Full docs: https://gim-home.github.io/kushi/**
 
 ## The essence: aggregate, then answer
@@ -26,6 +30,33 @@ The split is deliberate: aggregation is **heavy, scheduled, replayable**; answer
 
 See [Concepts → Aggregate, then Answer](https://gim-home.github.io/kushi/concepts/aggregate-and-answer/) for the full pattern.
 
+## Two-way sync to ADO — preview shipped
+
+Kushi can now **propose updates back to ADO** from the cited evidence it already has. Two skills under the opt-in `preview` profile:
+
+- ✅ **`propose-ado-update`** — fully working, read-only. Reads the latest `_Consolidated/` evidence and writes `<project>/ado-updates/<date>/proposed.md` with a field-update preview + Discussion comment + per-bullet citations + per-item confidence scores. Safe to run on the same Monday-9am schedule as `refresh`.
+- ✅ **`apply-ado-update`** — preview-stub. Re-fetches live ADO state, runs the approval gate, writes a `planned.jsonl` of what *would* be PATCH/POST'd. Real ADO calls land in v0.1.x once the proposal format is validated against multiple projects.
+
+```text
+> @Kushi propose ado Acme
+
+  #4821  Status: Active → Resolved
+         Evidence: Email 2026-05-12 from Priya — "shipped to prod Monday"
+         Confidence: high
+
+  #4837  AssignedTo: Sam → Priya
+         Evidence: Teams 2026-05-11 — "I'll take this one over from Sam"
+         Confidence: medium
+
+Apply [a]ll · [s]elect · [n]one?
+```
+
+**Safety guarantees** — preview-first diffs, approval gate or per-project allowlist, ledger with reverse op for every applied write, hard tenant-allowlist guard, no bulk migrations, no CRM writes (ADO first).
+
+Try it: `npx kushi-agents --clawpilot --profile preview` · How-to: [Two-way ADO update](https://gim-home.github.io/kushi/how-to/two-way-ado-update/) · Roadmap: [`docs/concepts/roadmap.md`](docs/concepts/roadmap.md).
+
+---
+
 ## Three install profiles
 
 Kushi ships in three tiers. Pick how much you take — the default (`standard`) matches v2.x behavior end-to-end.
@@ -37,9 +68,9 @@ Kushi ships in three tiers. Pick how much you take — the default (`standard`)
 | **`full`** | standard + `state` (renders the opinionated `State/` rollup) | You want everything, including the outcome-based State/ files. |
 
 ```bash
-npx github:gim-home/kushi --clawpilot                       # default = standard
-npx github:gim-home/kushi --clawpilot --profile core        # aggregator only
-npx github:gim-home/kushi --clawpilot --profile full        # everything
+npx kushi-agents --clawpilot                       # default = standard
+npx kushi-agents --clawpilot --profile core        # aggregator only
+npx kushi-agents --clawpilot --profile full        # everything
 ```
 
 The Evidence/ folder produced by every profile is a **stable public contract** — external systems can read from it without depending on Kushi internals. See [Concepts → Profiles and report packs](https://gim-home.github.io/kushi/concepts/profiles-and-packs/) and the [Evidence contract](https://gim-home.github.io/kushi/reference/evidence-contract/).
@@ -58,6 +89,8 @@ The Evidence/ folder produced by every profile is a **stable public contract**
 | `fde-intake` | standard+ | n/a | Capture the 6 FDE intake questions → `Reports/00-FDE-Intake-<project>.md` (updated in place). |
 | `fde-report` | standard+ | n/a | FDE report generator. 5 shapes: `weekly` (default), `short`, `long`, `fitness`, `stage-readiness`. |
 | `fde-triage` | standard+ | n/a | 7-file FDE triage bundle at `Reports/triage/<YYYY-MM-DD>/`. File 07 merges across re-runs. |
+| `propose-ado` | **preview** | n/a | Read-only ADO update proposal from latest `_Consolidated/` → `ado-updates/<date>/proposed.md`. Safe to schedule. No ADO writes. |
+| `apply-ado` | **preview** | n/a | Gated apply skill. v0.1.0-preview is dry-mode only (writes `planned.jsonl`); real ADO PATCH/POST lands in v0.1.x. |
 
 See [Quickstart](https://gim-home.github.io/kushi/getting-started/quickstart/) for the full workflow.
 
@@ -85,7 +118,7 @@ To switch profiles later, re-run with `--force` (cleanly handles downgrades):
 npx kushi-agents --clawpilot --profile core --force
 ```
 
-> **Internal GitHub install (Microsoft org members)**: `npx github:gim-home/kushi …` works identically and pulls straight from the private repo without going through npm.
+> **Bleeding-edge from GitHub (Microsoft org members only)**: `npx github:gim-home/kushi …` works identically and pulls straight from the source repo — useful for testing pre-release commits. Stick to `npx kushi-agents` for everything else.
 
 See [Install](https://gim-home.github.io/kushi/getting-started/install/) for flags, prerequisites, and per-user config.
 
@@ -146,13 +179,17 @@ See [docs/reference/where-things-live.md](docs/reference/where-things-live.md) f
 
 ## Contributing
 
-Before committing changes to the plugin payload, run the self-check:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide — repo layout, dev environment setup, the pre-commit checklist (self-check + mkdocs + npm pack), commit conventions, and how to add new skills/instructions/templates.
+
+Quick pre-commit check:
 
 ```powershell
 pwsh plugin/skills/self-check/run.ps1 -Deep
+mkdocs build --strict
+npm pack --dry-run
 ```
 
-It validates frontmatter, agent inventory, prompt → skill routing, cross-links, the verbs table in this README, and the layout diagram in `docs/reference/where-things-live.md`.
+The self-check validates frontmatter, agent inventory, prompt → skill routing, profile manifest, reference packs, cross-links, the verbs table in this README, and the layout diagram in `docs/reference/where-things-live.md`. Full reference: [docs/reference/self-check.md](docs/reference/self-check.md).
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kushi-agents",
-  "version": "3.4.1",
-  "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-first, host-agnostic.",
+  "version": "3.12.1",
+  "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
     "kushi-agents": "./bin/cli.mjs"
@@ -17,9 +17,21 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "jsdom": "^29.1.1",
     "jsonc-parser": "^3.3.1"
   },
-  "keywords": ["vscode", "copilot", "agents", "kushi", "project-evidence", "workiq", "m365", "ai", "cli"],
+  "keywords": [
+    "vscode",
+    "copilot",
+    "agents",
+    "kushi",
+    "project-evidence",
+    "workiq",
+    "m365",
+    "ai",
+    "cli"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gim-home/kushi.git"

package/plugin/agents/kushi.agent.md

@@ -1,147 +1,155 @@
----
-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". |
+---
+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 kushi-agents --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` |
+| **`preview`** *(opt-in)* | standard + `propose-ado-update`, `apply-ado-update` | standard + `propose-ado`, `apply-ado` |
+
+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>/` |
+| `@Kushi propose ado <project>` | **preview** | n/a (read-only) | `propose-ado-update` — generates `<engagement-root>/ado-updates/<YYYY-MM-DD>/proposed.md` from latest `_Consolidated/`. NO ADO writes. |
+| `@Kushi apply ado <project>` | **preview** | n/a (gated) | `apply-ado-update` — gated apply skill. v0.1.0-preview is dry-mode only (writes `planned.jsonl`, no real ADO calls). Governed by `update-ledger.instructions.md`. |
+
+**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-only** (M365 sources) — `instructions/workiq-only.instructions.md` (supersedes the deprecated `workiq-first.instructions.md`). Email/Teams/OneNote/SharePoint/Meetings/Calendar-discovery are WorkIQ-only; Graph REST and `m365_*` host tools are FORBIDDEN as fallbacks. CRM/ADO remain on their direct REST paths.
+- **Canonical evidence layout** (v3.12.1+) — `instructions/evidence-layout-canonical.instructions.md`. Every per-source artifact lives under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/`. Sibling source-output folders under `<project>/` (e.g. `<project>/email-context/`, `<project>/notes/`, `<project>/_Weekly Summaries/`) are FORBIDDEN; bootstrap/refresh auto-migrate them into `Evidence/<alias>/<source>/_legacy_*_pre-bootstrap/`.
+- **Scope & Boundaries** — `instructions/scope-boundaries.instructions.md`. Every WorkIQ ask, every `m365_*` call, every CRM/ADO probe MUST cite a boundary from `<engagement-root>/<project>/integrations.yml#boundaries.<source>`. Empty boundary = source disabled (no silent widening).
+- **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 kushi-agents --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. **Per `auth-and-retry.instructions.md §6`: if any source has `last_status` in {failed, partial, skipped-auth} with a retryable signature, auto-prompt the user with "Retry failed sources now?" — show per-source signatures and items count. Non-retryable signatures surface actionable guidance instead.** (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. |
+| `propose-ado-update` | **preview** | Read-only generator of `ado-updates/<date>/proposed.md` for an ADO Initiative (FDE Status Summary field + Discussion comment). No ADO writes. Safe to schedule. |
+| `apply-ado-update` | **preview** | Gated apply skill — the only code path authorized to write to ADO. v0.1.0-preview is dry-mode only (writes `planned.jsonl`). Governed by `update-ledger.instructions.md`. |
+
+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-misc` | User-curated `external-links.txt` (Loop, web, files, PDFs, GitHub) | ✅ | ✅ |
+| `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/ado-bootstrap-discovery.instructions.md

@@ -0,0 +1,111 @@
+---
+applyTo: "**/skills/bootstrap-project/**, **/skills/pull-ado/**, **/skills/refresh-project/**"
+---
+
+# ADO bootstrap discovery — HARD rule (kushi v3.11.0+)
+
+## The defect this rule exists to prevent
+
+Bootstrap runs that wrote `boundaries.ado.disabled: true` after a single shallow probe (or no probe at all) — declaring "no ADO engagement discovered" without ever issuing a live WIQL query against `dev.azure.com/IndustrySolutions`. Result: pull-ado is never dispatched, the project Evidence/ado/ stays empty, and when an Engagement work item later appears nothing notices. Mirror of the CRM defect documented in `crm-bootstrap-discovery.instructions.md` (JD bootstrap 2026-05-18).
+
+## The rule
+
+`boundaries.ado.disabled: true` is **forbidden at bootstrap** — even when zero records exist for the project. The correct disposition when ADO has no engagement yet is:
+
+```yaml
+boundaries:
+  ado:
+    # No engagement work item exists yet — keep the boundary EMPTY and retryable.
+    # Discovery will re-run on every refresh until something matches.
+    area_paths: []
+    work_item_ids: []
+    last_discovery_attempt: 'YYYY-MM-DD'
+    last_discovery_result: 'no-match'
+    last_discovery_queries:
+      - 'WIQL: Engagement title CONTAINS <token>'
+      - 'WIQL: title CONTAINS <token> across all WI types'
+      - 'WIQL: tags CONTAINS <slug>'
+      - 'WIQL: Custom.ISCRMRequestId = <fe-id>'
+    next_retry_on: 'next refresh'
+```
+
+`disabled: true` is reserved for the explicit case "user confirmed this project will NEVER have an ADO engagement" — and even then prefer leaving the boundary empty with `reason: 'user-opted-out-<date>'` so the discovery probe still runs (cheap) and surfaces if reality changes.
+
+## Why ADO is different from CRM
+
+| Aspect | CRM | ADO |
+|---|---|---|
+| Record existence at bootstrap | Usually exists (FDE Intake creates it before kickoff) | Often does NOT exist yet (work item is created when active delivery starts, sometimes weeks after intake) |
+| Bootstrap failure mode | Defect (record IS there; shallow probe missed it) | Expected (record genuinely not there yet) |
+| Correct disposition | Resolve via 4-step REST sequence | Run discovery, record `no-match`, KEEP RETRYING on every refresh |
+| `disabled: true` legitimate? | Only after exhaustive 5-step sequence + user-ask | Only after user explicit opt-out |
+
+For John Deere on 2026-05-18: the CRM record (FE-2026-001791) exists and was missed (defect). The ADO engagement work item does NOT exist yet (expected; intake just happened 2026-05-13). Both currently land as `disabled: true` because bootstrap treats them the same — that's the defect this rule fixes.
+
+## Required execution at bootstrap time
+
+After ADO config presence + auth probe succeed:
+
+1. **WIQL probe 1 — Engagement-type by title**:
+   ```sql
+   SELECT [System.Id],[System.Title],[System.State],[System.AreaPath],[System.Tags],[System.CreatedDate],[System.ChangedDate]
+   FROM workitems
+   WHERE [System.TeamProject] = '<defaultProject>'
+     AND [System.WorkItemType] = 'Engagement'
+     AND ([System.Title] CONTAINS '<token1>' OR [System.Title] CONTAINS '<token2>')
+     AND [System.State] <> 'Removed'
+   ORDER BY [System.ChangedDate] DESC
+   ```
+   Tokens = each word/phrase from the project name (e.g. for "John Deere": tokens `John Deere`, `Deere`, `JDDO`, `JDIS`).
+
+2. **WIQL probe 2 — Any WI type by title (catches Activity-only patterns or wrong-typed engagements)**:
+   ```sql
+   SELECT [System.Id],[System.Title],[System.WorkItemType],[System.State],[System.AreaPath]
+   FROM workitems
+   WHERE [System.TeamProject] = '<defaultProject>'
+     AND [System.Title] CONTAINS '<token>'
+     AND [System.State] <> 'Removed'
+     AND [System.CreatedDate] > '<2-years-ago>'
+   ```
+
+3. **WIQL probe 3 — Tag fallback**:
+   ```sql
+   WHERE [System.Tags] CONTAINS '<slug>'
+   ```
+   Slug = lowercased token, hyphenated (`john-deere`, `deere`, `jddo`).
+
+4. **WIQL probe 4 — CRM cross-link (if CRM record_id was resolved)**:
+   ```sql
+   WHERE [Custom.ISCRMRequestId] = '<request_id>'
+   ```
+   E.g. `Custom.ISCRMRequestId = 'FE-2026-001791'`. Single most reliable probe when CRM is linked.
+
+5. **Disposition**:
+   - **1 unique match**: persist `work_item_ids: [<id>]` + `engagement_id: <id>` + the resolved area path into `area_paths`. Run pull-ado in step 4b.
+   - **N matches**: present top 5 candidates (id, title, state, areaPath, createdDate, link); ask user to pick. Never auto-pick.
+   - **0 matches across all 4 probes**: write the empty-boundary block above with `last_discovery_result: 'no-match'` and the queries attempted. **DO NOT** write `disabled: true`. Add a one-liner to OPEN-QUESTIONS-DRAFT.md noting that ADO will keep retrying on each refresh.
+
+## Required logging
+
+Every bootstrap (and first-refresh) ADO-discovery run MUST write the attempt trail to `<project>/Evidence/<alias>/refresh-reports/<ts>_bootstrap.md` under a `## ADO resolution attempts` section, including the exact WIQL bodies, response counts, and final disposition. Same structure as CRM in `crm-bootstrap-discovery.instructions.md`.
+
+## Retry behavior on subsequent refreshes
+
+`refresh-project` MUST re-run the discovery sequence when `boundaries.ado.work_item_ids` is empty AND `last_discovery_result == 'no-match'` AND `last_discovery_attempt` is older than the current run. If a record now matches → resolve, persist, run pull-ado. If still no match → update `last_discovery_attempt` and continue. Refresh-project NEVER writes `disabled: true` autonomously; only a user opt-out (via integrations.yml#boundaries.ado.user_opted_out: true) prevents the retry.
+
+## Anti-patterns
+
+1. **Writing `boundaries.ado.disabled: true` at bootstrap when no ADO record exists yet.** FORBIDDEN. The correct disposition is empty-boundary + `last_discovery_result: 'no-match'`. Use `disabled: true` only on explicit user opt-out (and even then prefer empty-with-reason).
+2. **Stopping after WIQL probe 1.** All 4 probes (Engagement-typed, any-typed, tag, CRM-cross-link) must run before disposition.
+3. **Auto-picking from multi-match.** Never. Always present top 5 to user.
+4. **Skipping the retry on refresh.** When boundary is empty + last_result=no-match, refresh MUST re-probe — that's the whole point of using empty over disabled.
+5. **Hiding the attempt trail.** The exact WIQL bodies and counts MUST land in the bootstrap refresh-report; "couldn't find anything" without queries is unauditable.
+6. **Skipping discovery because CRM is empty too.** ADO and CRM are independent registries. JD's ADO work item could be created before its CRM record was even known to bootstrap, or vice versa.
+
+## Cross-references
+
+- `plugin/skills/pull-ado/SKILL.md` — Step 1 resolution order; this instruction wraps the bootstrap-time version.
+- `plugin/skills/bootstrap-project/SKILL.md` Step 4 — must dispatch this discovery before any disposition.
+- `plugin/skills/refresh-project/SKILL.md` — must re-run when boundary is empty + no-match.
+- `plugin/instructions/crm-bootstrap-discovery.instructions.md` — sibling rule for CRM (different failure-mode, same pattern).
+- `plugin/instructions/cleanup-on-resolution.instructions.md` — when discovery resolves a previously empty boundary, prune the stale `no-match` notes in the same turn.