kushi-agents 3.4.1

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

@@ -0,0 +1,75 @@
+---
+name: "pull-email"
+version: "2.0.0"
+description: "Pull Email evidence (stream only — emails ARE events). WorkIQ-first. Scopes to configured project email folder per m365-mutable hints."
+---
+
+# Skill: pull-email
+
+Pulls **email** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — (none — emails ARE events, no snapshot)
+- **stream/** — messages with full body, sender, recipients, attachments, reply chain — grouped by thread
+
+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)
+
+- `emailContext.folder` — full path of the project's email folder
+- `emailContext.folderId` — folder ID for direct lookup
+
+## Snapshot pass
+
+_(no snapshot for email — emails are inherently event-stream)_
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/email/snapshot/<entity>.md`
+
+Use template: `templates/snapshot/email-<kind>.template.md`
+
+## Stream pass
+
+Per `evidence-thoroughness.instructions.md`: every substantive thread gets sender + recipients (to+cc) + subject + **full body or close paraphrase** + attachments + reply chain in order. Group by thread.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/email/stream/<YYYY-MM-DD>_email-stream.md` (date = Monday of the ISO week the events fall in).
+
+Use template: `templates/weekly/email-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** — `m365_search_emails` / `m365_list_emails` scoped to `m365Auth.emailContext.folders`
+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`:
+
+- `emailContext.folder` — full path of the project's email folder
+- `emailContext.folderId` — folder ID for direct lookup
+
+## Update run-log
+
+After successful pass:
+- `sources.email.last_pulled = now`
+- `sources.email.watermark = now` (stream only; snapshot has no watermark)
+- `sources.email.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-meetings/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: "pull-meetings"
+version: "2.1.0"
+description: "Pull Meetings evidence (snapshot: series-index; stream: per-meeting transcripts + decisions + actions). WorkIQ-first; falls back to chat reconstruction when transcripts don't exist."
+---
+
+# Skill: pull-meetings
+
+Pulls **meetings** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — series-index.md listing all recurring meeting series for this project (subject, recurrence, organizer, current attendees)
+- **stream/** — per-meeting blocks: attendees (req/opt/actual), agenda, **chronological transcript walk-through with verbatim quotes + timestamps**, decisions, actions, open questions, artifact links
+
+Auth + retry + error logging per `auth-and-retry.instructions.md`. 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`.
+
+## 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 (`calendarContext.subjectKeywords`, `calendarContext.knownSeries`).
+
+## Discovery (snapshot pass)
+
+1. `m365_list_meetings` over the window with `subjectKeywords` filter (post-filter — Graph search is relevance-ranked, not exact).
+2. For each match: capture `id`, `subject`, `start`, `end`, `organizer`, `joinUrl`. Persist to mutable as `calendarContext.knownSeries[]`.
+3. Cross-reference with Teams chat IDs from `pull-teams` (meeting chat IDs of form `19:meeting_…@thread.v2`). Each match enriches with attendee roster + chat ID.
+
+Write `snapshot/series-index.md` listing all matched series. Updated every refresh (organizers/attendees may change).
+
+## Per-meeting stream pass — path cascade
+
+For EACH meeting in the window, attempt to capture transcript text via this cascade. Apply retry pattern per `auth-and-retry.instructions.md`. Record errors[] entry for each path attempted.
+
+1. **WorkIQ**: `Get full transcript and Copilot recap for meeting "<subject>" on <date>`.
+2. **`m365_get_transcript`** with the meeting's `joinUrl`.
+3. **Reconstruction from chat** (NOT a failure — first-class fallback). When transcripts simply don't exist (transcription was off, or VTT not yet attached), reconstruct evidence from:
+   - Meeting chat thread: `m365_list_chat_messages(chatId)` — captured already by `pull-teams`.
+   - Pre/post-meeting context messages.
+   - Any Copilot recap card posted to the chat.
+   Mark the per-meeting block `Source basis: reconstructed from meeting chat (no transcript)`. This is **evidence**, not a gap.
+4. **Ask user**: paste verbatim transcript or notes if all above produced nothing usable.
+
+A meeting block built from chat reconstruction with attendees + key decisions + actions is **valid evidence**. Do NOT mark such a meeting as `failed`. Mark it `partial` only if NO source produced any content (no transcript AND no chat messages).
+
+## Stream pass
+
+Per `evidence-thoroughness.instructions.md`: every meeting in the window gets a full per-meeting block. **A 30-line meetings file for a week with 2 meetings is a defect — expect 200+ lines.**
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/Meetings/stream/<YYYY-MM-DD>_meetings-stream.md` (date = Monday of the ISO week).
+
+Use template: `templates/weekly/meetings-summary.template.md`
+
+If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+
+## Mutable hints to upsert (during the run, not at the end)
+
+If discovered, immediately write to `m365Mutable.knownSections.<project>.calendarContext` with `discoveredOn` + `confidence`:
+
+- `subjectKeywords` — keywords that successfully matched
+- `knownSeries[]` — `{id, subject, joinUrl, chatId}` for each resolved meeting
+
+## Update run-log
+
+After the pass:
+- `sources.meetings.last_run = now`
+- `sources.meetings.last_status = ok | partial | failed | skipped-auth`
+- `sources.meetings.watermark_to = now`
+- `sources.meetings.items_pulled = <N meetings with at least chat-reconstruction>`
+- `sources.meetings.errors = [...]` per `auth-and-retry.instructions.md` schema. Use signature `transcripts-not-generated` with `action_taken: reconstructed-from-chat` when relevant — do NOT use `failed`.
+- For each week touched, add to `weekly_files` index.
+
+## Stop conditions
+
+- Subject keyword resolution returns 0 candidates → ask user once for keywords, persist to mutable, continue.
+- A meeting has neither transcript NOR chat messages → write `❌ no source available` block, log error, continue.
+- All paths failed for ALL meetings in the window → mark source `failed`, write a single `❌ all paths failed` evidence file with actionable next step.

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

@@ -0,0 +1,82 @@
+---
+name: "pull-onenote"
+version: "2.1.0"
+description: "Pull OneNote evidence (snapshot: full page bodies; stream: page-edit events). WorkIQ-only per workspace auth policy — Graph OneNote is unreliable."
+---
+
+# Skill: pull-onenote
+
+Pulls **onenote** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — full page bodies — one file per page with last-modified + author + verbatim body content
+- **stream/** — page-edit events with diff summary (created/modified/renamed/deleted)
+
+Auth + retry + error logging per `auth-and-retry.instructions.md`. WorkIQ-only 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`.
+
+## 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, query in this priority order)
+
+1. `one_sectionFileId` — drive item ID of the project's section file (e.g. AGCO.one) — narrowest, use first
+2. `one_sectionName` — display name (typically `<Project>.one`)
+3. Project alias keyword search — last resort
+
+## Path cascade (HARD — per `auth-and-retry.instructions.md`)
+
+1. **WorkIQ** (only supported path here per `workiq-first.instructions.md` — workspace policy disables Graph `/me/onenote/*`):
+   - **Pre-flight**: `Get-Command workiq`. If missing → log `workiq-not-on-path` + ask user. Probe `workiq ask -q "ping"`; if EULA prompt → run `workiq accept-eula` once, retry.
+   - Then query with the **narrowest available** hint:
+     - Have `one_sectionFileId`? Query: `Get full page bodies from OneNote section with sectionFileId <id> modified between <start> and <end>`.
+     - Have `one_sectionName` only? Query: `Get full page bodies from OneNote section <section> in notebook <notebook> modified between <start> and <end>`.
+     - Neither? Query: `Find OneNote pages or sections that mention <project> or <project-aliases>. Return page titles, section names, last modified dates, and direct links.`
+2. Apply retry pattern (max 2 retries, 3s/6s backoff). Throttling → narrow scope once (sectionFileId if available), then stop.
+3. **Do NOT attempt Graph `/me/onenote/*`** — workspace policy: OneNote via Graph repeatedly fails 401 here. Record `graph-skipped-by-policy` if Graph is the only remaining option.
+4. If WorkIQ exhausts → write evidence file with `❌ all paths failed` marker and `next_step: ask user to paste page text from <section>`.
+
+## Snapshot pass
+
+Write `snapshot/pages/<page-title>.md` per page with full verbatim body (NOT title only). Header: `Page: <title>` / `Section: <section>` / `Last modified: <ts> by <author>`.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/OneNote/snapshot/<entity>.md`
+
+Use template: `templates/snapshot/onenote-<kind>.template.md`
+
+## Stream pass
+
+Page-edit events for the window. Each event: page, edit type (created/modified/renamed), editor, timestamp, brief diff summary.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/OneNote/stream/<YYYY-MM-DD>_onenote-stream.md` (date = Monday of the ISO week the events fall in).
+
+Use template: `templates/weekly/onenote-summary.template.md`
+
+If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+
+## Mutable hints to upsert (during the run, not at the end)
+
+If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`:
+
+- `one_sectionFileId` — drive item ID of the project's section file
+- `one_sectionName` — display name
+- `one_sectionWebUrl` — direct link
+
+## Update run-log
+
+After the pass:
+- `sources.onenote.last_run = now`
+- `sources.onenote.last_status = ok | partial | failed | skipped-auth`
+- `sources.onenote.watermark_to = now` (stream only; snapshot has no watermark)
+- `sources.onenote.items_pulled = <N>`
+- `sources.onenote.errors = [...]` per `auth-and-retry.instructions.md` schema
+- 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.
+- All paths failed → write evidence file with `❌ all paths failed` + actionable `next_step`, log to run-log errors, continue with rest of run.

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

@@ -0,0 +1,85 @@
+---
+name: "pull-sharepoint"
+version: "2.0.0"
+description: "Pull SharePoint evidence (snapshot: folder tree + key file bodies; stream: file change events). WorkIQ-first; also walks local synced folder for metadata without auth."
+---
+
+# Skill: pull-sharepoint
+
+Pulls **sharepoint** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — tree.md (full folder tree) + files/<path>.md (key files with full extracted content)
+- **stream/** — file change events (created/modified/renamed/deleted) with author + size + brief content summary
+
+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)
+
+- `sharePoint.localFolder` — local OneDrive-synced path
+- `sharePoint.siteUrl` — SP site URL
+- `sharePoint.driveId` — Graph drive ID for direct access
+
+## Snapshot pass
+
+Write `snapshot/tree.md` (full folder hierarchy, no truncation) and `snapshot/files/<relative-path>.md` for each file selected for body extraction. The selected set is the **union** of:
+
+1. **Curated key files** — anything matching `architecture`, `decision`, `adr`, `deliverable`, `proposal`, `statement of work`, `sow`, `business case`, `roadmap`, `plan` in the filename or top-level folder name. These are always extracted.
+2. **Top-N most-recently-modified files** under the project's SharePoint folder, where N = `sharepoint.snapshot.recent_n` from the user's `.settings.yml` (default **25**, configurable to 0 to disable). This captures the live working tail without exploding on large team sites.
+3. **User pins** — anything listed under `sharepoint.snapshot.always_include` in `.settings.yml` (relative paths or substrings).
+
+For every selected file write: full filename (NO truncation), changed-by, change-type, size, last-modified-datetime, and a concise content summary (decisions, risks, actions, owners, dates, key context — same depth bar as the meetings transcript walk-through). Apply `path_excludes` from `.settings.yml` to skip noise (`_Archive`, `Old`, etc.) before counting toward N.
+
+`snapshot/tree.md` always lists the full hierarchy regardless of which files got body extraction; mark each file with one of `[key]`, `[recent]`, `[pin]`, `[skip]`, or `[tree-only]` so the reader can see why a file was or wasn't expanded.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/sharepoint/snapshot/<entity>.md`
+
+Use template: `templates/snapshot/sharepoint-<kind>.template.md`
+
+## Stream pass
+
+File change events for the window with full filename, change type, author, timestamp, size, content summary. Apply `sharepoint.path_includes` / `path_excludes` / `author_filter` from .settings.yml.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/sharepoint/stream/<YYYY-MM-DD>_sharepoint-stream.md` (date = Monday of the ISO week the events fall in).
+
+Use template: `templates/weekly/sharepoint-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** — `m365_search_files` / `m365_list_files`; `helpers/sharepoint-pull.ps1` (uses `az account get-access-token --resource https://graph.microsoft.com`); also walk local synced folder under `sharePoint.localFolder` for metadata (no auth needed)
+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`:
+
+- `sharePoint.localFolder` — local OneDrive-synced path
+- `sharePoint.siteUrl` — SP site URL
+- `sharePoint.driveId` — Graph drive ID for direct access
+
+## Update run-log
+
+After successful pass:
+- `sources.sharepoint.last_pulled = now`
+- `sources.sharepoint.watermark = now` (stream only; snapshot has no watermark)
+- `sources.sharepoint.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-teams/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: "pull-teams"
+version: "2.0.0"
+description: "Pull Teams chat + channel evidence (snapshot: chat roster; stream: messages with full message-by-message reproduction). WorkIQ-first."
+---
+
+# Skill: pull-teams
+
+Pulls **teams** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — chat roster + member list per chat the user is part of for this project
+- **stream/** — messages with full message-by-message reproduction — sender, timestamp, verbatim text, reactions, attachments, replies — grouped by thread
+
+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)
+
+- `teamsChatContext.chatIds` — list of pinned chat IDs (skip discovery if present)
+- `teamsChatContext.chatHints` / `channelHints` / `participantHints` — fuzzy discovery terms
+
+## Snapshot pass
+
+Write `snapshot/chat-roster.md` listing each chat (id, topic, members) and `snapshot/chats/<chat-id>.md` per chat with member list + tabs.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/teams/snapshot/<entity>.md`
+
+Use template: `templates/snapshot/teams-<kind>.template.md`
+
+## Stream pass
+
+Per `evidence-thoroughness.instructions.md`: every thread touched in window gets full message-by-message reproduction. Group by thread, not by day. If a thread has 30 messages, reproduce all 30.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/teams/stream/<YYYY-MM-DD>_teams-stream.md` (date = Monday of the ISO week the events fall in).
+
+Use template: `templates/weekly/teams-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** — `m365_list_chats` + `m365_list_chat_messages` scoped by `chatIds` from mutable
+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`:
+
+- `teamsChatContext.chatIds` — list of pinned chat IDs (skip discovery if present)
+- `teamsChatContext.chatHints` / `channelHints` / `participantHints` — fuzzy discovery terms
+
+## Update run-log
+
+After successful pass:
+- `sources.teams.last_pulled = now`
+- `sources.teams.watermark = now` (stream only; snapshot has no watermark)
+- `sources.teams.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/refresh-project/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: "refresh-project"
+version: "2.1.0"
+description: "Incremental refresh for an already-bootstrapped project. Reads run-log watermarks, pulls only what is new since last run per source, splits stream output by ISO week, replaces snapshots in place. Builds State/ only on `full` profile (skipped on `standard`). Defaults to since-watermark (fallback 7d if first refresh)."
+---
+
+# Skill: refresh-project
+
+Run this when the user says any of: "refresh `<X>`", "do it all for `<X>`" (when project already bootstrapped), "weekly extract for `<X>`", "update `<X>`", "pull `<X>` since `<date>`".
+
+## Profile-aware behavior
+
+As of Kushi v3.3.0:
+
+- On `standard` profile (default) — Step 4 (build-state) is **skipped**.
+- On `full` profile — Step 4 runs and `State/` is rebuilt if new evidence landed.
+
+Profile is read from `kushi-install.json#profile` next to the agent file. Default `standard` if absent.
+
+## Inputs
+
+- `<project>` — already-bootstrapped project (fuzzy-matched).
+- `<window>` — one of:
+  - (default) since per-source watermark in run-log
+  - `last N days` — override window for all sources
+  - `since YYYY-MM-DD` — from date until today
+  - `YYYY-MM-DD..YYYY-MM-DD` — explicit range (backfill)
+- (optional) `<source>` — limit to one source (otherwise all enabled).
+
+## Steps
+
+### Step 1 — Resolve project + read run-log
+
+- Fuzzy-match `<project>` per `engagement-root-resolution.instructions.md`.
+- Read `<engagement-root>/<project>/Evidence/run-log.yml`.
+- For each source, compute effective window:
+  - If user supplied window override → use that.
+  - Else if `sources.<src>.watermark` exists → use `(watermark, today)`.
+  - Else (first refresh after bootstrap, or new source) → fallback to `last 7 days`.
+
+### Step 2 — Per-source dispatch
+
+For each enabled source (or just the requested one), call its `pull-<source>` skill with the effective window.
+
+Each `pull-*` skill is responsible for:
+- Snapshot pass (always re-fetch known entities).
+- Stream pass (incremental from watermark, bucketed by ISO week, append-only merge).
+- Updating `sources.<src>.watermark`, `sources.<src>.last_pulled`, `sources.<src>.item_count` in run-log.
+- Updating `weekly_files` index in run-log.
+
+### Step 3 — Consolidate (if multi-user)
+
+If `Evidence/contributors.yml` lists more than one alias and any of them have new evidence in the window, dispatch `consolidate-evidence` for the same window.
+
+### Step 4 — Build state (FULL PROFILE ONLY)
+
+If `kushi-install.json#profile` is `full` → dispatch `build-state` if any source had ANY new data this run (new snapshot diffs or new stream events). Otherwise skip with note "no new evidence — state unchanged".
+
+If `standard` (or `core`) → **skip this step**. Note in the run summary: *"State/ rollup skipped (profile = `standard`). To enable, re-install with `npx github:gim-home/kushi --clawpilot --profile full --force`."*
+
+### Step 5 — Run summary
+
+Display:
+- Per-source table: items pulled, weeks affected, errors.
+- Side-by-side mutable hints written this run (per `side-by-side-config.instructions.md`).
+- New Open Questions opened/resolved/staled.
+
+## Watermark semantics
+
+- Watermarks are stored in `Evidence/run-log.yml` per source (not per week).
+- Snapshot pulls do NOT use watermarks — always full re-fetch.
+- Stream pulls advance the watermark to `now` AFTER successful merge.
+- Failed streams leave the watermark UNCHANGED so the next refresh retries from the same point.
+
+## Idempotency
+
+Re-running refresh with the same window is safe:
+- Snapshots replace in place (no harm).
+- Stream events dedupe by event ID — duplicates are dropped.
+
+## Triggers
+
+- "refresh `<X>`"
+- "do it all for `<X>`" (when project already exists)
+- "weekly extract for `<X>`"
+- "update `<X>`"
+- "pull `<X>` since `<date>`"
+- "refresh `<X>` last `<N>` days"
+- "backfill `<X>` from `<from>` to `<to>`"

package/plugin/skills/self-check/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: "self-check"
+version: "2.0.0"
+description: "Pre-commit / pre-push validator. Checks that Kushi's skills, instructions, prompts, agent definition, templates, and key docs are all internally consistent. Source of truth is the file system. Findings are warnings with concrete fixes — never blocking."
+---
+
+# Skill: self-check
+
+Validate Kushi's documentation surfaces against the file system before committing or pushing. The set of directories under `plugin/skills/` (each with a `SKILL.md`) is the canonical inventory; everything else must reference them correctly.
+
+User triggers: "self-check", "run self-check", "pre-commit check", "validate kushi", "are all skills documented?", "check docs consistency".
+
+## Principles
+
+- **Source of truth is the file system.** Never derive the skill / instruction / prompt list from any markdown file.
+- **Fail with fixes, not just errors.** Every finding includes a concrete suggestion (snippet to paste, path to add, link to repair).
+- **Non-blocking.** Findings are warnings. The user decides whether to commit.
+- **Minimal noise.** Surface only gaps. Do not echo passing checks.
+- **Deterministic.** A companion script (`run.ps1`) produces the same results as the agent walkthrough.
+
+## What gets checked
+
+Checks split into **core** (always run) and **deep** (opt-in).
+
+### Core checks
+
+| # | Check | Source of truth | Target | Failure shape |
+|---|-------|-----------------|--------|---------------|
+| C1 | Frontmatter completeness | `plugin/skills/<n>/SKILL.md` | each skill | missing `name`, `version`, or `description` |
+| C2 | Skill name matches directory | `plugin/skills/<dir>/` | frontmatter `name:` | mismatch |
+| C3 | Skills inventoried in agent | `plugin/skills/` | `plugin/agents/kushi.agent.md` "Skills" / verb routing | skill missing from agent |
+| C4 | Prompts route to real skills | `plugin/prompts/*.prompt.md` | `plugin/skills/` | prompt names a skill that doesn't exist |
+| C5 | Instructions referenced | `plugin/instructions/*.instructions.md` | any SKILL.md / agent.md | orphan instruction |
+| C6 | Cross-links resolve | every `[...](path)` in plugin md | filesystem | broken relative link |
+| C7 | Verbs table matches prompts | `plugin/prompts/` | `README.md` verbs table | verb missing/extra in README |
+| C8 | Distribution layout | `plugin/` (post-install mirror) | `docs/reference/where-things-live.md` | top-level item missing from layout diagram |
+| C9 | Profiles manifest valid | `plugin/plugin.json` `profiles{}` | filesystem | profile references skill/prompt/instruction that doesn't exist; `default_profile` not declared |
+
+### Deep checks (opt-in)
+
+| # | Check | What it validates |
+|---|-------|-------------------|
+| D1 | Template references | every `templates/<x>` mentioned in a SKILL.md exists |
+| D2 | Snapshot/stream coverage | each `pull-<source>` skill cites `snapshot-vs-stream.instructions.md` and writes both shapes (or explicitly states stream-only) |
+| D3 | WorkIQ-first hygiene | each `pull-<source>` skill names WorkIQ as tool #1 and host fallback as tool #2 |
+| D4 | Live install sync | if `~/.copilot/m-skills/kushi/` exists, its `SKILL.md` is byte-identical to `plugin/agents/kushi.agent.md` |
+| D5 | skills-metadata.json sync | if `~/.copilot/m-skills/skills-metadata.json` lists `kushi`, its description matches the live `SKILL.md` frontmatter |
+| D6 | Side-by-side rule cited | every SKILL.md that touches user config references `side-by-side-config.instructions.md` |
+| D7 | Live install manifest | if `~/.copilot/m-skills/kushi/kushi-install.json` exists, its skill list matches the resolved profile chain from `plugin.json` (no missing, no extras) |
+
+## Execution flow (agent path)
+
+1. **Run `run.ps1`.** From the kushi repo root: `pwsh plugin/skills/self-check/run.ps1` (omit `-Deep` to skip D-checks). The script prints a JSON summary of findings.
+2. **If `run.ps1` is unavailable** (e.g. running outside the repo), perform the checks inline using `glob` + `grep` + `view` per the algorithm below.
+3. **Render findings** as a single results table per surface, followed by a per-finding fix block.
+4. **Offer deep checks** with an `m_ask_user` prompt:
+
+   | Label | Action |
+   |---|---|
+   | ✅ Run deep checks | Re-run with `-Deep` |
+   | ⏭️ Skip | Show final summary |
+
+5. **Final verdict.**
+   - All clear → `✅ Kushi is internally consistent. Safe to commit.`
+   - Any gaps → `⚠️ Found <N> gap(s) across <M> surface(s). Review findings above.`
+
+## Algorithm (per check)
+
+### C1 — Frontmatter completeness
+
+For each `plugin/skills/<dir>/SKILL.md`: parse YAML frontmatter (text between leading `---` lines). Required keys: `name`, `version`, `description`.
+
+> ⚠️ self-check C1 — Skill `<dir>` is missing required frontmatter key `<key>`. Add it before the first `---` separator.
+
+### C2 — Skill name matches directory
+
+For each skill: `frontmatter.name` (case-insensitive) must equal directory name.
+
+> ⚠️ self-check C2 — Directory `<dir>/` declares `name: "<name>"`. Rename one or the other so they match.
+
+### C3 — Skills inventoried in agent
+
+`plugin/agents/kushi.agent.md` must contain a backtick-wrapped reference to every skill directory name. Look in any markdown table column or any inline `\`<name>\`` token.
+
+> ⚠️ self-check C3 — Skill `<dir>` is not listed in the kushi agent. Suggested row for the routing table:
+>
+> `| <verb> | <dir> | <one-line description from frontmatter> |`
+
+### C4 — Prompts route to real skills
+
+For each `plugin/prompts/*.prompt.md`: extract any reference of the form `` `<skill-name>` `` or `delegates to <skill-name>` (case-insensitive). Each must exist as a directory under `plugin/skills/`.
+
+> ⚠️ self-check C4 — Prompt `<file>` references skill `<name>` which does not exist under `plugin/skills/`. Either create the skill or update the prompt.
+
+### C5 — Instructions referenced
+
+For each `plugin/instructions/*.instructions.md`: at least one SKILL.md OR `plugin/agents/kushi.agent.md` must reference it by filename (with or without path).
+
+> ⚠️ self-check C5 — Instruction `<file>` is not referenced anywhere. Either delete it or add a "## References" line to the relevant skill(s).
+
+### C6 — Cross-links resolve
+
+For every markdown link with a relative target (`](./...)`, `](../...)`, or `](path/...)` not starting with `http`) inside `plugin/**/*.md`: target must exist on disk relative to the file containing it.
+
+> ⚠️ self-check C6 — `<source-file>:<line>` links to `<target>` which does not exist. Update or remove the link.
+
+### C7 — Verbs table matches prompts
+
+`README.md` contains a "Verbs" / "Quick start" table. Every `plugin/prompts/<verb>.prompt.md` must have a row in that table; every row in the table must have a corresponding prompt file.
+
+> ⚠️ self-check C7 — Verb `<v>` exists as `plugin/prompts/<v>.prompt.md` but is missing from README's verbs table. Suggested row:
+>
+> `| \`<v>\` | <default window> | <one-line description> |`
+
+### C8 — Distribution layout matches docs
+
+`docs/reference/where-things-live.md` contains an ASCII tree of `plugin/`. Every top-level subdirectory and notable file under `plugin/` must appear; every entry in the tree must exist on disk.
+
+> ⚠️ self-check C8 — `plugin/<x>` exists but is missing from the docs/reference/where-things-live.md tree. Add an entry under section "1. This repo".
+
+### D-checks: see `run.ps1` for the exact regexes.
+
+## Validation rules
+
+- **R1** Source of truth is always the file system; never the markdown.
+- **R2** Match skill names case-insensitively; match directories case-sensitively (Windows is forgiving but git is not on case-only renames).
+- **R3** Deep checks (D1–D6) are always opt-in. Never run them automatically.
+- **R4** Findings must include an actionable fix snippet — never report a gap without telling the user how to repair it.
+- **R5** Do not echo passing checks. Final summary table shows the count per surface; the body shows only gaps.
+- **R6** If run.ps1 fails (missing PowerShell, etc.), fall back to the inline algorithm and document the fallback path used.
+
+## Output format
+
+```
+### Self-Check Results — Kushi v<version> @ <YYYY-MM-DD HH:mm>
+
+| Surface                          | Core | Deep |
+|----------------------------------|------|------|
+| Frontmatter (C1, C2)             | ✅ / ⚠️ N | n/a |
+| Agent inventory (C3)             | ✅ / ⚠️ N | n/a |
+| Prompts (C4, C7)                 | ✅ / ⚠️ N | n/a |
+| Instructions (C5, D6)            | ✅ / ⚠️ N | ✅ / ⚠️ N |
+| Cross-links (C6)                 | ✅ / ⚠️ N | n/a |
+| Layout (C8)                      | ✅ / ⚠️ N | n/a |
+| Templates (D1)                   | n/a  | ✅ / ⚠️ N |
+| Snapshot/Stream (D2)             | n/a  | ✅ / ⚠️ N |
+| WorkIQ-first hygiene (D3)        | n/a  | ✅ / ⚠️ N |
+| Live install sync (D4, D5)       | n/a  | ✅ / ⚠️ N |
+
+<findings, one block per finding>
+```
+
+## Triggers (verb routing)
+
+This skill is not invoked by `@Kushi <verb>` — it's a meta-skill. Triggers:
+
+- "kushi self-check"
+- "self-check kushi"
+- "validate kushi"
+- "pre-commit check"
+- "are all kushi skills documented?"
+
+## References
+
+- `instructions/citation-ledger.instructions.md` (findings cite source files / line numbers)
+- `instructions/side-by-side-config.instructions.md` (D6 enforces this rule for skills that read/write user config)