kushi-agents 3.4.1

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

@@ -0,0 +1,52 @@
+---
+applyTo: "**"
+description: "Citation rule — every assertion in every output must carry an inline source citation. No naked claims."
+---
+
+# Citation Ledger (HARD RULE)
+
+Every assertion in EVERY output (Evidence snapshot/stream files, State files 00–09, _Consolidated reports, run-log entries, Open Questions rows, Pending Outbound rows) MUST carry an inline citation. No naked claims. If you cannot cite it, do not write it — write the question into `09_open-questions.md` instead.
+
+## Citation formats
+
+Pick the format that fits the source:
+
+| Source | Format |
+|---|---|
+| M365 stream evidence | `[source: <alias>/<source>/stream/YYYY-MM-DD_<source>-stream.md · YYYY-MM-DD]` |
+| M365 snapshot evidence | `[source: <alias>/<source>/snapshot/<entity>.md as of YYYY-MM-DD]` |
+| CRM field | `[source: CRM <RecordId> field <fieldDisplayName> · YYYY-MM-DD]` |
+| CRM annotation | `[source: CRM <RecordId> annotation by <author> · YYYY-MM-DD]` |
+| ADO field | `[source: ADO #NNNNN field <fieldName> · YYYY-MM-DD]` |
+| ADO comment | `[source: ADO #NNNNN comment by <author> · YYYY-MM-DD]` |
+| SharePoint | `[source: SharePoint <relative/path/file.ext> · YYYY-MM-DD]` |
+| OneNote | `[source: OneNote <Notebook>/<Section>/<Page> · YYYY-MM-DD]` |
+| Meeting | `[source: Meeting "<subject>" transcript · YYYY-MM-DD]` |
+| Email | `[source: Email "<subject>" from <sender> · YYYY-MM-DD]` |
+| Derived/inferred | NEVER acceptable as a final fact. Either cite the underlying source, or move it to `09_open-questions.md` with Fidelity=Low. |
+
+## Where the rule applies
+
+Every single one of:
+
+- **Evidence snapshot/stream files** — every entry has a per-event citation back to the source system.
+- **State/00_overview.md** — every fact in headline, phase, owner, dates, risks block.
+- **State/01_decisions.md** — every decision row + every superseded entry.
+- **State/02_stakeholders.md** — every person, role, contact attribution, and Conflicts row.
+- **State/03_architecture-and-solution.md** — every component, dependency, constraint.
+- **State/04_workshops-and-key-meetings.md** — every meeting entry.
+- **State/05_action-items.md** — Source column populated always.
+- **State/06_risks-and-issues.md** — every risk, mitigation, status update.
+- **State/07_timeline-and-milestones.md** — every milestone date + status.
+- **State/08_artifacts-and-deliverables.md** — every artifact link + author.
+- **State/09_open-questions.md** — every Q-row source + every Resolved row.
+- **_Consolidated/** — provenance tag on every merged claim showing which contributor's evidence file it came from.
+- **run-log.yml** — every history entry references the run that touched it.
+- **Pending Outbound rows** — citation for "why this person should be contacted".
+
+## Snapshot vs stream citation distinction
+
+- Snapshot citations indicate "current truth" — use `as of YYYY-MM-DD`.
+- Stream citations indicate "historical event" — use `· YYYY-MM-DD` (event date).
+
+State files SHOULD cite both where appropriate (e.g. "the architecture is X [snapshot citation] as decided on date Y [stream citation]").

package/plugin/instructions/engagement-root-resolution.instructions.md

@@ -0,0 +1,82 @@
+---
+applyTo: "**"
+description: "How to resolve <engagement-root> — where the user's engagement folders live, and where per-user live configs sit beside them."
+---
+
+# Engagement-root resolution
+
+The **engagement-root** is the parent folder that contains all of the user's engagement subfolders. It is NOT inside the kushi repo and NOT inside `.kushi/`. It is the user's actual work area.
+
+## Resolution order
+
+Resolve `<engagement-root>` in this order — first match wins:
+
+1. **`<USER_HOME>/.copilot/project-evidence.yml`** — read `engagement_root:` field (preferred).
+2. **`customer_workspace/FDEDocs/`** — if the user's workspace has this symlink, follow it. Common in NOVA-style installs.
+3. **Ask the user** once and persist the answer to `<USER_HOME>/.copilot/project-evidence.yml engagement_root`.
+
+## Live config location
+
+Once `<engagement-root>` is known, live filled configs live at:
+
+```
+<engagement-root>/.project-evidence/
+   m365/m365-auth.json
+   m365/m365-mutable.json
+   crm/config.yml
+   ado/config.yml
+   project-evidence.yml         ← optional per-engagement override
+```
+
+This folder is OneDrive-synced (typically) and follows the user across machines.
+
+## Project resolution
+
+Once `<engagement-root>` is known, individual projects are subfolders:
+
+```
+<engagement-root>/<project-1>/
+<engagement-root>/<project-2>/
+<engagement-root>/<project-3>/
+```
+
+Project name resolution (always fuzzy):
+
+1. Match against keys in `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections`.
+2. Match against `active_projects:` in `<USER_HOME>/.copilot/project-evidence.yml`.
+3. Match against actual subfolder names under `<engagement-root>`.
+
+Case-insensitive; ranking `exact > prefix > contains`. Multiple plausible candidates → ask user to pick. Zero candidates AND verb is `bootstrap` → create the folder. Zero candidates AND verb is anything else → ask user.
+
+## Project structure (created on bootstrap)
+
+```
+<engagement-root>/<project>/
+   integrations.yml                   ← project-shared config (CRM record id, ADO area, SP site)
+   Evidence/
+      run-log.yml                     ← per-source watermarks + weekly_files index
+      contributors.yml                ← list of aliases who contribute evidence
+      <alias>/
+         .settings.yml                ← per-(project x user) — search keywords, chat ids, etc.
+         email/{snapshot,stream}/
+         teams/{snapshot,stream}/
+         meetings/{snapshot,stream}/
+         onenote/{snapshot,stream}/
+         sharepoint/{snapshot,stream}/
+         crm/{snapshot,stream}/
+         ado/{snapshot,stream}/
+      _Consolidated/                  ← multi-user merge output
+   State/
+      00_overview.md
+      01_decisions.md
+      02_stakeholders.md
+      03_architecture-and-solution.md
+      04_workshops-and-key-meetings.md
+      05_action-items.md
+      06_risks-and-issues.md
+      07_timeline-and-milestones.md
+      08_artifacts-and-deliverables.md
+      09_open-questions.md
+```
+
+The skill creates missing folders/files on first use; never overwrites existing files without explicit user approval.

package/plugin/instructions/evidence-thoroughness.instructions.md

@@ -0,0 +1,62 @@
+---
+applyTo: "**"
+description: "Evidence Thoroughness Standard — every per-source skill MUST capture full bodies, full transcripts, full message reproduction. Headlines-only is a defect."
+---
+
+# Evidence Thoroughness Standard (HARD RULE)
+
+Evidence files are the **system of record** that State files cite. They MUST be deep enough that a reader can fully reconstruct what happened without going back to Outlook / Teams / OneNote / SharePoint / CRM / ADO. **Headlines-only summaries are a defect.**
+
+## Per-source minimum bar
+
+### Meetings (stream/)
+For every meeting in the window — capture, **as separate named sections under each per-meeting block**:
+- Full attendee list (required + optional + actual + no-shows)
+- Agenda / stated purpose
+- **Detailed Discussion Summary** — multi-paragraph narrative of what was actually discussed end-to-end, not 3 bullet points
+- **Chronological transcript walk-through with verbatim quotes and timestamps** — every substantive exchange, not just 2 highlight quotes
+- **Key Decisions** — every decision with exact wording + who decided + supporting context
+- **Open Questions / Non-Decisions** — questions raised but not resolved, with who raised them and why deferred
+- **Next Steps** — REQUIRED dedicated section. Forward-looking commitments that aren't yet hard action items: "team will gather facts", "Mike will discuss with industry leads", "Microsoft to come back with proposal next week". These are distinct from `Action Items` (which have owner+due) and are critical to State/05_action-items + State/04_workshops-and-key-meetings rendering.
+- **Action Items** — every commitment with owner + due + source-line
+- **Risks, Blockers, Dependencies** — surfaced or escalated in this meeting
+- **Customer Asks** — explicit asks the customer made of Microsoft (resourcing, decisions, timelines, escalations)
+- Every artifact link / shared file / recording / transcript URL
+- **Coverage Notes** — what was retrievable vs what wasn't (transcript missing, chat-only reconstruction, partial recap, etc.)
+
+If transcript is unavailable, document why and pull chat transcript + Copilot recap + meeting chat thread to reconstruct. Per-meeting sub-section is mandatory; one block per meeting. **A 30-line meetings file for a week with 2 meetings is a defect — expect 200+ lines, with the structure above repeated per meeting.** A per-meeting block missing the explicit `Next Steps` section is a defect even if Action Items is present — they capture different things.
+
+### Teams chats (stream/)
+For every thread touched in the window — capture **full message-by-message reproduction** (sender · timestamp · verbatim message text or close paraphrase), not just an outcome line. Group by thread, not by day. Include reactions, file attachments, links, replies. If a thread has 30 messages, reproduce all 30 (collapse only routine acks like 👍 / "thanks").
+
+### Emails (stream/)
+For every substantive thread — capture sender, recipients (to + cc), subject, **full body or close paraphrase**, attachments, and the chain of replies in order. Thread-level grouping. A one-line "X sent Y about Z" entry is insufficient — include enough body to convey what was actually said.
+
+### OneNote (snapshot/ + stream/)
+- snapshot/pages/<page>.md — extract **full page bodies**, not just titles. Last-modified timestamp + author at the top.
+- stream/<week>.md — page-edit events with diff summary.
+
+If Graph delegated-token isn't available, ask the user to paste page content rather than skip.
+
+### SharePoint (snapshot/ + stream/)
+- snapshot/tree.md — full folder tree (no truncation). Mark each entry `[key]` / `[recent]` / `[pin]` / `[skip]` / `[tree-only]` so readers can see why a file was or wasn't expanded.
+- snapshot/files/<path>.md — body summary for: (a) **curated key files** (architecture, decisions, ADRs, deliverables, proposals, SOWs, business cases, roadmaps, plans), PLUS (b) **top-N most-recently-modified files** where N = `sharepoint.snapshot.recent_n` (default 25), PLUS (c) any user pins from `sharepoint.snapshot.always_include`. Per file: full filename (no truncation), changed-by, change-type, size, last-modified, content summary at the same depth bar as a meeting transcript walk-through (decisions, risks, actions, owners, dates, key context).
+- stream/<week>.md — file change events that week.
+
+### CRM/ADO (snapshot/ + stream/)
+- snapshot/<id>.md — every field the API returns, every value.
+- stream/<id>/<week>.md — every field-level change with old → new + actor + timestamp, every comment/discussion verbatim.
+
+## Volume guidance
+
+- Long files are EXPECTED. Compression is the enemy.
+- One file per source per week (stream) — do NOT split into one-file-per-meeting / one-file-per-thread.
+- One file per entity (snapshot) — do NOT consolidate multiple entities into one snapshot.
+
+## Citation density
+
+Every paragraph still needs `[source: …]` citations — thoroughness does NOT relax the citation rule, it intensifies it. See `citation-ledger.instructions.md`.
+
+## Fix-up loop
+
+If the user reads an evidence file and says "this is too light", the skill MUST re-pull from source with deeper extraction and rewrite the file in the same fix-up turn — never defend a thin summary.

package/plugin/instructions/side-by-side-config.instructions.md

@@ -0,0 +1,56 @@
+---
+applyTo: "**"
+description: "Side-by-side config rule — whenever the skill creates or changes a template, it must also write/update the corresponding live filled config. Skeletons stay generic; live files get the actual fact."
+---
+
+# Side-by-side config rule (HARD RULE)
+
+Whenever the skill creates, changes, or extends any template in `<KUSHI_ROOT>/plugin/templates/init/`, it MUST also write the corresponding live file under `<engagement-root>/.project-evidence/`.
+
+Templates stay generic; the live file gets the actual filled-in fact. Never leave the user with only the template — that's a half-done config.
+
+## The two layers
+
+| Layer | Where | Lifecycle |
+|---|---|---|
+| Template (generic) | `<KUSHI_ROOT>/plugin/templates/init/*.template.{json,yml}` | Ships with kushi, never edited per-user |
+| Live filled | `<engagement-root>/.project-evidence/*.{json,yml}` | Per-user, OneDrive-synced, edited by skill + user |
+
+## Discover → upsert immediately
+
+Any time the skill discovers a high-confidence fact about a project (folder id, chat id, OneNote section id, CRM record id, ADO WI id, stakeholder hint, alias) — upsert it into the live mutable file (`<engagement-root>/.project-evidence/m365/m365-mutable.json` under `m365Mutable.knownSections.<project>.<source>`) **in the same turn it was discovered**, with `discoveredOn: <today>` and `confidence: high|medium|low`.
+
+Don't wait until the end of the run.
+
+## Fix-ups count
+
+When the user pushes back on a scoping miss (e.g. "you missed folder `1. Workstream/104. <project>`"), the corrected value MUST be written to the live mutable file before declaring the fix done. The user should never have to repeat the correction on the next run.
+
+## Bookkeeping
+
+- Bump `_meta.last_updated` (and `m365Mutable.metadata.lastUpdated`) on every write.
+- Never write low-confidence guesses. Never overwrite a high-confidence pinned value with a lower-confidence guess.
+
+## Verification
+
+End every bootstrap / fix-up turn by listing the live config files (path + size + last-write time) so the user can see the "done-for-you" state — not just the templates.
+
+## Live config locations
+
+```
+<engagement-root>/.project-evidence/
+   m365/
+      m365-auth.json          ← stable (OneDrive-synced, hand-edited mostly)
+      m365-mutable.json       ← discovered hints, auto-updated by skill
+   crm/
+      config.yml              ← Dataverse env URL, tenant, schema
+   ado/
+      config.yml              ← organization, projects, queries
+   project-evidence.yml       ← (optional) per-engagement override of personal config
+```
+
+## Why outside the kushi repo
+
+- **Multi-machine portability** — OneDrive-synced beside engagement folders, follows the user wherever they install kushi.
+- **Discoverability** — user can see/edit it next to their engagement work, not buried in `~/.copilot/`.
+- **Repo-safe** — kushi is meant to be GitHub-published; live filled configs MUST never be committed.

package/plugin/instructions/snapshot-vs-stream.instructions.md

@@ -0,0 +1,87 @@
+---
+applyTo: "**"
+description: "Snapshot vs Stream — every source has two evidence shapes. Snapshot = current state of entity (replace on refresh). Stream = timestamped events (append-only, weekly buckets)."
+---
+
+# Snapshot vs Stream (HARD RULE)
+
+Every source produces evidence in TWO distinct shapes. Mixing them is a defect.
+
+## The two shapes
+
+| Shape | What it is | Refresh behavior | Filename pattern |
+|---|---|---|---|
+| **snapshot/** | Current state of an entity ("what IS true now?") | Always re-pull, **replace in place** | `<entity-id-or-name>.md` (no date) |
+| **stream/** | Timestamped events ("what happened?") | Incremental from watermark, **append-only**, bucketed by ISO week (Mon–Sun) | `YYYY-MM-DD_<source>-stream.md` (date = Monday of week) |
+
+## Per-source breakdown
+
+| Source | Snapshot? | Stream? | Snapshot entities | Stream events |
+|---|---|---|---|---|
+| Email | — | ✅ | (none — emails ARE events) | messages |
+| Teams chats | ✅ | ✅ | chat roster, member list | messages, file shares |
+| Teams channels | ✅ | ✅ | channel list, tab config | posts, replies |
+| Meetings | ✅ | ✅ | series metadata, recurrence | instances + transcripts |
+| OneNote | ✅ | ✅ | page bodies (full content) | page-edit events |
+| SharePoint | ✅ | ✅ | folder tree, file metadata, key file bodies | file change events, version history |
+| CRM | ✅ | ✅ | record (engagement fields, owner, status) | notes, activities, status-change history |
+| ADO | ✅ | ✅ | work items (fields, parent, area, iteration) | comments, state changes, attachments |
+
+## Storage layout
+
+```
+<engagement-root>/<project>/Evidence/<alias>/
+   email/
+      stream/2026-05-04_email-stream.md
+   teams/
+      snapshot/chat-roster.md
+      stream/2026-05-04_teams-stream.md
+   meetings/
+      snapshot/series-index.md
+      stream/2026-05-04_meetings-stream.md
+   onenote/
+      snapshot/pages/<page-title>.md
+      stream/2026-05-04_onenote-stream.md
+   sharepoint/
+      snapshot/tree.md
+      snapshot/files/<relative-path>.md
+      stream/2026-05-04_sharepoint-stream.md
+   crm/
+      snapshot/<record-id>.md
+      stream/<record-id>/2026-05-04_crm-stream.md
+   ado/
+      snapshot/items/<work-item-id>.md
+      stream/items/<work-item-id>/2026-05-04_ado-stream.md
+   run-log.yml
+```
+
+## Refresh logic
+
+```
+For each source:
+   1. Snapshot pass: re-fetch known entities, write to snapshot/ (idempotent replace).
+   2. Stream pass: read source.watermark from run-log -> fetch events since -> bucket by ISO week -> append/merge into stream/<monday>.md -> update watermark.
+```
+
+## Idempotency rules
+
+- **snapshot/** is always replace-in-place. Latest fact wins. No history (history lives in stream/).
+- **stream/** is append-only within a week file. When merging new events into an existing week file:
+   - dedupe by event ID (message ID, comment ID, transcript timestamp, etc.)
+   - never overwrite existing events (an event that "moved" — was deleted, rescoped, edited — leaves the original record alone; the change shows up as a new event).
+   - if a week file already exists from a prior partial run, mark it `> ⚠️ Partial week (re-run later for full coverage)` until the week is complete.
+
+## Citation distinction
+
+- Snapshot citations indicate "current truth": `[source: <alias>/onenote/snapshot/pages/<page-title>.md as of YYYY-MM-DD]`
+- Stream citations indicate "historical event": `[source: <alias>/onenote/stream/YYYY-MM-DD_onenote-stream.md · message YYYY-MM-DDTHH:MM]`
+
+State files SHOULD cite both where appropriate (e.g. "the architecture is X [snapshot] as decided on date Y [stream]").
+
+## Build-state implications
+
+`build-state` reads from BOTH snapshot/ and stream/:
+- Current truth (entity fields, page bodies, file content) → snapshot/
+- Provenance, history, when/who/why → stream/
+
+`@Kushi state <project>` runs `build-state` ONLY (no source calls), so it can re-render State/ from existing Evidence at any time without hitting M365.

package/plugin/instructions/thoroughness-detector.instructions.md

@@ -0,0 +1,105 @@
+---
+applyTo: "**"
+description: "Thoroughness detector — pull-* skills MUST run this check after writing every evidence file and auto-retry or prompt-paste when the file is thin."
+---
+
+# Thoroughness Detector (HARD RULE)
+
+Every `pull-*` skill MUST run this check after writing each evidence file. A file that fails the detector is a **defect** — it MUST be re-extracted with a richer query or replaced with pasted source content. The skill MUST NOT silently accept a thin file.
+
+This detector enforces `evidence-thoroughness.instructions.md` at runtime. The thoroughness doctrine defines what "full" means; this file defines how to **detect** and **fix** violations.
+
+## Per-source minimum thresholds
+
+Apply the threshold for the source the file belongs to. A file fails if **any** check triggers.
+
+### Email stream (`email/stream/*.md`)
+
+- Per thread block: body text ≥ **400 characters** (not counting headers / metadata / "see original" stubs).
+- Per thread block contains at least one of: `Body:`, `Reply chain`, or a quoted block.
+- File-level: ≥ 1 thread block per substantive subject mentioned in the windowed search results.
+
+### Teams stream (`teams/stream/*.md`)
+
+- Per thread block: reproduces ≥ **5 messages** (or, if thread is shorter, ALL messages — collapse only routine acks 👍 / "thanks").
+- Each reproduced message has `<sender> · <timestamp>` line + verbatim or close-paraphrase text.
+- File-level: rejects "summary-only" files with no message-by-message reproduction.
+
+### OneNote snapshot (`onenote/snapshot/pages/*.md`)
+
+- Page body text ≥ **600 characters** OR contains a `## Page Body` section followed by content (not just a link).
+- Page metadata block (last-modified, author) present.
+
+### OneNote stream (`onenote/stream/*.md`)
+
+- Each page-edit event includes diff summary (what changed) — not just "page updated".
+
+### SharePoint snapshot tree (`sharepoint/snapshot/tree.md`)
+
+- Tree is not truncated (no "…" or "N more" placeholders).
+- Each entry has a status tag: `[key]` / `[recent]` / `[pin]` / `[skip]` / `[tree-only]`.
+
+### SharePoint snapshot file (`sharepoint/snapshot/files/*.md`)
+
+- Body summary ≥ **400 characters** OR explicit `[tree-only]` justification.
+- Has changed-by + change-type + last-modified.
+
+### Meetings stream (`meetings/stream/*.md`)
+
+- Per meeting block contains ALL of the following named sections:
+  - `## Detailed Discussion Summary`
+  - `## Transcript Walk-Through` (or `## Chronological Walk-Through`)
+  - `## Key Decisions`
+  - `## Open Questions` (or `## Open Questions / Non-Decisions`)
+  - `## Next Steps` ← **dedicated section, distinct from Action Items**
+  - `## Action Items`
+- `## Next Steps` MUST be present even if empty (`_None this meeting._`) — missing the section is a defect.
+- Per meeting block: total length ≥ **800 characters**.
+- Action items: every bullet has owner + due (date OR "TBD" with reason) + `[source: …]` citation.
+
+### CRM/ADO snapshot (`crm/snapshot/*.md`, `ado/snapshot/*.md`)
+
+- Snapshot lists ≥ **8 fields** with values (not just an ID + a link).
+
+### CRM/ADO stream (`crm/stream/*.md`, `ado/stream/*.md`)
+
+- Each change event has old-value → new-value + actor + timestamp.
+
+## Red-flag patterns (auto-fail)
+
+Any file containing these strings outside a `## Coverage Notes` block fails:
+
+- `(see original in …)` / `see original email` / `see Teams thread` / `see page` — link-only stubs.
+- `Full body unavailable` / `body not captured` without an accompanying `## Coverage Notes` explaining why.
+- `Summary: …` as the entire body (no detail beneath it).
+- `[redacted]` without justification.
+- `TODO` / `FIXME` left in production evidence.
+
+## Retry policy
+
+When a file fails the detector:
+
+1. **Auto-retry once** with a deeper WorkIQ query. Append `"give me full bodies and full reply chain — not just metadata"` (or source-appropriate equivalent) to the query. Re-write the file.
+2. If the second attempt still fails the detector, emit the **paste-prompt** (see `plugin/templates/paste-prompt.md`) to the user with the specific file path, the failing checks, and ready-to-paste section headers.
+3. Mark the file with `⚠ thoroughness: pending-paste` at the top under `## Source Basis` and log `thoroughness-pending` in `run-log.yml` for that source. Continue the rest of the run — do NOT block.
+
+## Validation block in every evidence file
+
+Every evidence file MUST end with:
+
+```
+## Validation
+
+- [ ] bodies-present
+- [ ] attendees-or-participants-captured       <!-- meetings/teams only -->
+- [ ] next-steps-section-present               <!-- meetings only -->
+- [ ] action-items-have-owner-and-due          <!-- meetings only -->
+- [ ] no-link-only-stubs
+- [ ] coverage-notes-explain-any-gaps
+```
+
+The skill ticks the boxes it can verify automatically; the rest are left for `self-check` and human review.
+
+## Out of scope
+
+This detector does NOT enforce citation density (that's `citation-ledger.instructions.md`) or snapshot-vs-stream placement (that's `snapshot-vs-stream.instructions.md`). It enforces depth-of-capture only.

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

@@ -0,0 +1,47 @@
+---
+applyTo: "**"
+description: "WorkIQ is the required path for all M365 + CRM + ADO source pulls. Graph REST is NOT a routine fallback; ask the user to paste when WorkIQ can't answer."
+---
+
+# WorkIQ-required rule (HARD RULE)
+
+WorkIQ is the **required** path for every source pull. Graph REST has known issues in this workspace (token rejection, OneNote 40001, Dataverse 501/415, SharePoint 403, mailbox throttling) and **MUST NOT** be used as a routine fallback — doing so produces thin metadata-only evidence that violates `evidence-thoroughness.instructions.md`. WorkIQ gives richer extraction (full page bodies, full transcript text, message-by-message thread reproduction).
+
+## Resolution order (per source)
+
+For every source, try in order:
+
+1. **WorkIQ** — `<workiq.cli_path> ask -q "<question>"` (path resolved from `<USER_HOME>/.copilot/project-evidence.yml workiq.cli_path`, otherwise from PATH).
+2. **Ask user to paste** — if WorkIQ is missing, unauthenticated, or returns insufficient content, ask the user to paste the data **verbatim** (NOT summarized). This is a first-class path, not an error.
+3. **Graph REST / `m365_*` host tools** — **last resort only**, used non-blocking with an explicit `➖ partial via Graph REST` marker in the evidence file. Skills MUST NOT silently fall through to Graph when WorkIQ fails; the user must be informed and given a chance to paste.
+
+**Always document which path succeeded** in the evidence file under `## Source Basis`.
+
+If WorkIQ is not installed or not on PATH, the skill MUST surface this immediately with a link to `docs/getting-started/install-workiq.md` rather than degrading to thin Graph-only evidence.
+
+## Per-source preferred WorkIQ queries
+
+| Source | WorkIQ query template |
+|---|---|
+| Email | `Find emails about <project> in folder <folder> between <start> and <end>, give me sender, recipients, full body, and reply chain` |
+| Teams Chats | `Show full message-by-message reproduction of <project> Teams threads between <start> and <end>` |
+| OneNote | `Get full page bodies from OneNote section <section> notebook <notebook> modified between <start> and <end>` |
+| SharePoint | `List SharePoint files for <project> modified between <start> and <end> with author and brief content summary` |
+| Meetings | `Get full transcript and Copilot recap for meeting <subject> on <date>` |
+| CRM | `Get CRM engagement record FE-<id> with all field values, comments, and audit history` |
+| ADO | `Get ADO work items for <project> updated between <start> and <end> with full discussion thread` |
+
+## Pre-flight (every pull-* skill)
+
+Before issuing the first WorkIQ query in a run:
+
+1. `Get-Command workiq` (or the configured `cli_path`). If missing → log `workiq-not-on-path` in `run-log.yml`, write a one-line evidence file pointing at `docs/getting-started/install-workiq.md`, and STOP this source.
+2. Probe `workiq ask -q "ping"`. If EULA prompt → run `workiq accept-eula` once, retry. If auth-failed → log `workiq-auth-failed` and ask user to re-authenticate.
+3. Only after a successful probe, proceed to per-source queries.
+
+## Graph REST — when explicitly allowed
+
+Graph is allowed only as a non-blocking last resort, and only with:
+- An explicit `➖ partial via Graph REST` marker in the evidence file.
+- A `next_step` line telling the user to install/repair WorkIQ for full-fidelity capture next run.
+- Never as a silent default.

package/plugin/plugin.json

@@ -0,0 +1,96 @@
+{
+  "name": "kushi",
+  "description": "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. Host-agnostic. Three install profiles: core (aggregator only), standard (default — adds bootstrap/refresh + FDE authoring), full (adds State/ rollup).",
+  "version": "3.3.0",
+  "author": "ushakrishnan",
+  "repository": "https://github.com/gim-home/kushi",
+  "default_profile": "standard",
+  "profiles": {
+    "core": {
+      "description": "Aggregator only — pull-* + consolidate + ask. No opinionated rollup. The Evidence/ folder is the public contract; suitable for standalone use OR as the producer layer behind an external rollup system.",
+      "skills": [
+        "intro",
+        "self-check",
+        "pull-email",
+        "pull-teams",
+        "pull-meetings",
+        "pull-onenote",
+        "pull-sharepoint",
+        "pull-crm",
+        "pull-ado",
+        "aggregate-project",
+        "consolidate-evidence",
+        "project-status",
+        "ask-project"
+      ],
+      "prompts": [
+        "aggregate",
+        "consolidate",
+        "status",
+        "ask"
+      ],
+      "instructions": "*",
+      "templates": [
+        "snapshot",
+        "weekly"
+      ],
+      "reference_packs": [],
+      "verbs": [
+        "aggregate",
+        "consolidate",
+        "status",
+        "pull",
+        "ask"
+      ]
+    },
+    "standard": {
+      "extends": "core",
+      "description": "Core + bootstrap/refresh orchestrators + FDE authoring (intake, report, triage) and the FDE reference pack. Kushi's default opinion. NO State/ rollup on this profile — Evidence/ is the contract; FDE reports read Evidence/ directly. bootstrap/refresh are profile-aware and skip build-state here.",
+      "skills": [
+        "bootstrap-project",
+        "refresh-project",
+        "fde-intake",
+        "fde-report",
+        "fde-triage"
+      ],
+      "prompts": [
+        "bootstrap",
+        "refresh",
+        "fde-intake",
+        "fde-report",
+        "fde-triage"
+      ],
+      "templates": [
+        "init",
+        "fde"
+      ],
+      "reference_packs": [
+        "fde"
+      ],
+      "verbs": [
+        "bootstrap",
+        "refresh",
+        "fde-intake",
+        "fde-report",
+        "fde-triage"
+      ]
+    },
+    "full": {
+      "extends": "standard",
+      "description": "Standard + State/ rollup. Adds the opinionated outcome-based State/ files (decisions, stakeholders, architecture, action items, risks, timeline, artifacts, open questions) built on top of Evidence/. On this profile, bootstrap/refresh call build-state at the end.",
+      "skills": [
+        "build-state"
+      ],
+      "prompts": [
+        "state"
+      ],
+      "templates": [
+        "state"
+      ],
+      "reference_packs": [],
+      "verbs": [
+        "state"
+      ]
+    }
+  }
+}

package/plugin/prompts/aggregate.prompt.md

@@ -0,0 +1,24 @@
+---
+description: "Aggregate (pull + consolidate) without building State/."
+---
+
+# Aggregate
+
+Run `aggregate-project` for the named project.
+
+This is the **pull-only** verb. Every enabled source is pulled and per-user streams are consolidated, but `build-state` is NOT run. Use this when:
+
+- You want Evidence/ on disk and will render reports with an external system.
+- You're installed at the `core` profile (no build-state present).
+- You want frequent pulls but slower State/ rebuilds.
+
+## Syntax
+
+```
+@Kushi aggregate <project>
+@Kushi aggregate <project> last N days
+@Kushi aggregate <project> since <YYYY-MM-DD>
+@Kushi aggregate <project> <YYYY-MM-DD>..<YYYY-MM-DD>
+```
+
+See `skills/aggregate-project/SKILL.md` for the full sequence and output contract.

package/plugin/prompts/ask.prompt.md

@@ -0,0 +1,16 @@
+---
+name: ask
+description: Read-only Q&A over a bootstrapped project's State/, Evidence/, and snapshot/ files. Cited; no source pulls; no outbound. Auto-routes when you name a project + ask a question.
+---
+
+# /ask
+
+Route to `@Kushi ask <project> <question>`.
+
+Loads the cheapest set of files needed to answer (`State/<topic>.md` first, then latest `Evidence/<alias>/_Consolidated/`, then per-source weekly files, then `external-context/`, then `<project>/SharePoint/snapshot/files/`), emits inline `[source: <alias>/<folder>/<file> · YYYY-MM-DD]` citations, warns if the relevant source is older than `chat.freshness_warn_days` (default 14), and ends with a Confidence line.
+
+Read-only. NEVER triggers a `pull-*` skill — if evidence is stale or missing, offers `@Kushi refresh <project>` and stops.
+
+You don't actually need this prompt — `ask-project` auto-routes whenever your message names a known project and asks a question (what / who / when / status / summarize / etc.). The slash form just provides an explicit handle.
+
+Delegates to `ask-project` skill.

package/plugin/prompts/bootstrap.prompt.md

@@ -0,0 +1,23 @@
+---
+name: bootstrap
+description: First-time setup for a new project — scaffold folders, lay configs side-by-side, do an initial 30-day pull, build State.
+---
+
+# /bootstrap
+
+Route to `@Kushi bootstrap <project>`.
+
+Inputs the agent will resolve:
+- `<project>` — the engagement folder name (fuzzy-match under engagement-root if needed).
+- `<window>` — defaults to 30 days. Override with `last 60 days`, `since 2026-04-01`, or `2026-04-01..2026-05-01`.
+
+Reads:
+- `<USER_HOME>/.copilot/project-evidence.yml` for alias + engagement-root.
+
+Produces:
+- `<engagement-root>/.project-evidence/m365/{m365-auth,m365-mutable}.json` (per-user filled)
+- `<engagement-root>/<project>/integrations.yml`
+- `<engagement-root>/<project>/Evidence/{contributors.yml, run-log.yml, <alias>/.settings.yml, <alias>/{email,teams,meetings,onenote,sharepoint,crm,ado}/{snapshot,stream}/}`
+- `<engagement-root>/<project>/State/{00..09}_*.md`
+
+Delegates to `bootstrap-project` skill. After scaffolding, calls each `pull-<source>` skill, then `build-state`.