kushi-agents 4.4.4 → 4.8.0

package/plugin/instructions/customer-hint-discovery.instructions.md

@@ -0,0 +1,129 @@
+---
+applyTo: "**/skills/bootstrap-project/**, **/skills/pull-email/**, **/skills/pull-teams/**, **/skills/pull-meetings/**, **/skills/pull-sharepoint/**, **/skills/refresh-project/**"
+description: "Customer-hint discovery sweep — bootstrap MUST attempt WorkIQ-driven discovery for every source whose boundary is empty before declaring blocked-config. Mirrors crm-bootstrap-discovery + loop-bootstrap-discovery pattern. Kushi v4.8.0+."
+---
+
+# Customer-hint discovery sweep (HARD RULE — kushi v4.8.0+)
+
+## The defect this rule exists to prevent
+
+Bootstrap runs that scaffold an empty `<project>/integrations.yml#boundaries.*` and immediately declare every source `blocked-config` — without ever asking WorkIQ "who/what mentions this customer?". The result: a fresh project bootstrap finishes with 0 evidence pulled, the user is told to hand-populate mailboxes / chat IDs / channel IDs / meeting join URLs / SharePoint sites, and the entire value proposition of "bootstrap a project from a customer hint" collapses to a config form. Discovered 2026-05-26 on the HCA bootstrap — every source row read `blocked-config` despite extensive HCA email / Teams / meeting history in the tenant.
+
+## The rule
+
+Before `bootstrap-project` (or `refresh-project` on a first pull) is allowed to write `last_status: blocked-config` for **email, teams, meetings, or sharepoint**, the per-source customer-hint discovery sweep defined in the matching doctrine MUST be attempted with the customer hint + lookback window:
+
+| Source | Doctrine file (mandatory) |
+|---|---|
+| email | `email-bootstrap-discovery.instructions.md` |
+| teams | `teams-bootstrap-discovery.instructions.md` |
+| meetings | `meetings-bootstrap-discovery.instructions.md` |
+| sharepoint | `sharepoint-bootstrap-discovery.instructions.md` |
+| onenote | `bootstrap-project/SKILL.md#step-4a` (already shipped v4.7.x — display-name driven) |
+| loop | `loop-bootstrap-discovery.instructions.md` (already shipped v4.6.0) |
+| crm | `crm-bootstrap-discovery.instructions.md` (already shipped v3.11.0) |
+| ado | `ado-bootstrap-discovery.instructions.md` |
+
+`blocked-config` is ONLY legitimate when:
+
+1. **The sweep ran** and returned 0 candidates → status is `unresolved` (sweep succeeded but no hits), not `blocked-config`. Use `discovery-empty` annotation in the per-source notes.
+2. **The sweep COULD not run** because a prerequisite is genuinely missing (e.g. CRM/ADO need `<workspace>/.kushi/config/shared/integrations.yml` populated, SharePoint local-folder enumeration needs a local OneDrive sync path the customer hint cannot infer). In that case, `blocked-config` is correct, and the per-source `next_step` MUST cite the specific missing config field.
+
+Any other path that writes `blocked-config` without attempting the sweep is a **defect**.
+
+## Required inputs
+
+- `<customer-hint>` — verbatim string the user provided at bootstrap invocation (e.g. `HCA`). Captured by `bootstrap-project` Step 0/1 and persisted to `<project>/bootstrap-status.md` under `Customer Hint:`. Used VERBATIM in v4.8.0 — no fuzzy expansion (deferred to v4.9.0).
+- `<lookback-days>` — defaults to **90** for discovery (longer than the 30-day pull window so historical chats / series still surface). Configurable via `<workspace>/.kushi/config/user/m365-mutable.json#bootstrap.discoveryLookbackDays`.
+- `<project>` — engagement name (already resolved).
+- `<alias>` — current contributor.
+
+## Required outputs
+
+For each source whose sweep runs:
+
+1. **Append discovered IDs / URLs / paths to `<engagement-root>/<project>/integrations.yml#boundaries.<source>.<key>`** as plain strings (existing pull-* skills consume strings — do NOT change the array element type). Idempotent: deduplicate by exact-string equality.
+
+2. **Write a sidecar discovery record to `<engagement-root>/<project>/Evidence/_discovery/<YYYY-MM-DD>_<source>_discovery.yml`** with the per-row metadata (`discovered_by`, `discovered_at`, `needs_review`, `query`, `request_id`, `confidence`). Schema:
+
+   ```yaml
+   source: email | teams | meetings | sharepoint
+   project: <project>
+   customer_hint: '<hint>'
+   lookback_days: 90
+   discovered_at: '<ISO-8601>'
+   discovered_by: <alias>
+   query: '<exact WorkIQ prompt>'
+   workiq_request_id: '<request-id from response>'
+   total_candidates_found: <N>
+   candidates_persisted: <M>     # ≤ 10 after cap
+   candidates_deferred: <N - M>  # written to OPEN-QUESTIONS-DRAFT.md
+   results:
+     - value: '<string written to boundary>'
+       label: '<human-readable label>'
+       confidence: high | medium | low
+       needs_review: true
+   ```
+
+3. **If `total_candidates_found > 10`**, persist the top 10 by recency to the boundary and append the remaining N–10 to `<project>/OPEN-QUESTIONS-DRAFT.md` under `## Discovery sweep — candidates over cap` with one row per candidate.
+
+4. **Add a `## Discovery Sweep Results` section to `<project>/bootstrap-status.md`** after `## Context Artifact Status`. Table shape:
+
+   ```
+   ## Discovery Sweep Results
+
+   | Source | Hint | Query attempted | Candidates found | Persisted | Deferred | Discovered by |
+   |---|---|---|---|---|---|---|
+   | email | HCA | "In my Inbox..." | 7 | 7 | 0 | ushak |
+   | teams | HCA | "In my Teams chats..." | 14 | 10 | 4 | ushak |
+   | meetings | HCA | "In my calendar..." | 3 | 3 | 0 | ushak |
+   | sharepoint | HCA | "In my SharePoint sites..." | 0 | 0 | 0 | ushak |
+   ```
+
+## Behavior matrix (per source)
+
+| Sweep result | `boundaries.<source>.<key>` written? | `last_status` | `retry_signal` | Open Questions written? |
+|---|---|---|---|---|
+| 0 candidates | no | `unresolved` (annotated `discovery-empty`) | `user-action` | yes — "Discovery sweep for `<source>` returned 0 hits for `<hint>`; widen hint or seed `boundaries.<source>.<key>` manually" |
+| 1–10 candidates | yes (all) | `completed-with-coverage-gaps` (because rows are `needs_review`) | `watch` | only if any row low-confidence |
+| > 10 candidates | yes (top 10 by recency) | `completed-with-coverage-gaps` | `watch` | yes — "Discovery sweep returned >10 candidates; review the deferred list" |
+| Sweep query failed (WorkIQ error / classified per `fallback-status-reporting.instructions.md`) | no | `deferred` (write marker per `deferred-retry-on-workiq-fail.instructions.md`) | `retry` | no — next refresh will drain |
+| Prerequisite genuinely missing (e.g. CRM shared config empty) | no | `blocked-config` | `user-action` | yes — cite specific missing field |
+
+## Multi-contributor safety
+
+When the boundary already has rows from another alias (or the sidecar `Evidence/_discovery/` already has entries):
+
+1. **Append-only** — the new alias's sweep adds rows that are not already present (dedupe by exact-string equality on the boundary value). Never remove or rewrite another alias's row.
+2. **Sidecar file is per-source-per-date** — multiple contributors on the same day produce separate sidecar files (`2026-05-26_email_discovery-ushak.yml`, `2026-05-26_email_discovery-stand.yml`). Bootstrap-status's Discovery Sweep Results table shows one row per source × alias.
+3. **`Discovered by` column in bootstrap-status's per-source Context Artifact Status row** cites the most recent discovering alias. Preserve other aliases' rows in `## Contributors who have bootstrapped this project` per `multi-user-shared-files.instructions.md`.
+
+## Rerun behavior
+
+When the user re-runs bootstrap on a project that already has populated boundaries:
+
+| Boundary state | Sweep behavior |
+|---|---|
+| Empty | Run sweep (full discovery). |
+| Has rows, none `needs_review: true` (all confirmed) | **Skip sweep.** Boundary is gospel — do not re-discover. |
+| Has rows, some `needs_review: true` (sidecar shows confidence < high) | Run sweep. Merge new candidates by ID. Promote previously-discovered candidates from `needs_review: true` → `false` only if user has manually confirmed (i.e. removed the `needs_review` flag from the sidecar). |
+| User passes `--force-rediscover` | Run sweep regardless of state. Merge new candidates; never delete user-confirmed rows. |
+
+## Forbidden behaviors
+
+1. **Declaring `blocked-config` without running the sweep first** for email/teams/meetings/sharepoint — see "The defect" above. CRM/ADO have their own mandates in `crm-bootstrap-discovery` / `ado-bootstrap-discovery`.
+2. **Auto-narrowing the customer hint** ("HCA" → "HCA Healthcare Inc"). Use the hint verbatim. Smart-expansion is v4.9.0.
+3. **Discovering across all sources in one mega-query.** Each source has its own narrow WorkIQ prompt (see per-source doctrines). Mega-queries punt to Graph and return empty.
+4. **Inferring local OneDrive sync paths from the hint** for SharePoint `local_folders[]`. Discovery populates `site_urls[]` only.
+5. **Calling Graph / `m365_*` directly for discovery.** Per `workiq-only.instructions.md` the four sources covered here use WorkIQ exclusively. The only allowed `m365_*` exceptions remain `m365_list_chat_messages` (parallel structured dump per pull-teams) and the per-source carve-outs already named in their pull-* SKILLs.
+
+## References
+
+- `crm-bootstrap-discovery.instructions.md` — the original "must-attempt-before-declaring-disabled" doctrine; this file mirrors its pattern for the WorkIQ-driven sources.
+- `loop-bootstrap-discovery.instructions.md` — Loop-specific discovery + registry shape.
+- `scope-boundaries.instructions.md` — the broader partial-determinism contract; this doctrine is the discovery-time enabler that makes boundaries achievable.
+- `workiq-only.instructions.md` — what discovery is NOT allowed to call (Graph, m365_* for content).
+- `status-taxonomy.instructions.md` — the closed-set status vocabulary; `unresolved` + `discovery-empty` annotation vs. `blocked-config`.
+- `fallback-status-reporting.instructions.md` — how to classify WorkIQ punts during the sweep.
+- `multi-user-shared-files.instructions.md` — append-only rules for the boundary file.
+- `bootstrap-status-format.instructions.md` — where `## Discovery Sweep Results` slots in the report.

package/plugin/instructions/email-bootstrap-discovery.instructions.md

@@ -0,0 +1,105 @@
+---
+applyTo: "**/skills/bootstrap-project/**, **/skills/pull-email/**, **/skills/refresh-project/**"
+description: "Outlook mail folder discovery — single approved WorkIQ phrasing that scans recent Inbox/subfolder contents for the customer hint, ranks folders by hit-density, writes top candidates into mailboxes[]. Source-specific subset of customer-hint-discovery."
+---
+
+# Email bootstrap discovery (kushi v4.8.0+)
+
+Governed by `customer-hint-discovery.instructions.md` — read that file first for the orchestration contract, rerun rules, multi-contributor merge behavior, and behavior matrix.
+
+## What this sweep populates
+
+| Boundary key | Element shape | Example |
+|---|---|---|
+| `boundaries.email.mailboxes[]` | string — mail folder path relative to mailbox root | `"Inbox"`, `"Inbox/HCA"`, `"FDE/HCA Intake"` |
+
+Optional narrowing fields (`sender_domains[]`, `subject_keywords[]`) are NOT populated by the sweep — they are user-supplied narrowing.
+
+## Approved WorkIQ query (the ONLY shape that returns this data)
+
+Issued ONCE per bootstrap, per project:
+
+```
+workiq ask -q "In my Outlook mail folders, find the top mail folders that contain emails mentioning '<HINT>' received in the last <N> days. Return a flat table with: folder path (from mailbox root), message count, most recent received date. Sort by message count descending. Do not summarize. Do not truncate. Flat table only."
+```
+
+Substitution rules:
+
+- `<HINT>` = the verbatim customer hint from `bootstrap-status.md#Customer Hint` (e.g. `HCA`).
+- `<N>` = `m365-mutable.json#bootstrap.discoveryLookbackDays` (default 90).
+
+The phrasing is **natural-language by folder content** — empirically the only shape that returns folder paths. WorkIQ punts on any other shape (see Forbidden phrasings).
+
+## Forbidden phrasings (will fail empirically — do NOT emit)
+
+| Forbidden phrasing | Why it fails |
+|---|---|
+| `"List all my Outlook mail folders. Return folder name and folderId for each."` | Enumerate-verb on the folder space punts to `m365_list_mail_folders` / Graph and returns Graph-Explorer guidance instead of data. |
+| `"Search Microsoft 365 for mail folders matching '<hint>'."` | Structured-search verb routes to summary mode, not folder data. |
+| `"What is the folder ID for the '<name>' folder in my mailbox?"` | ID-lookup question punts to Graph. |
+| `"Get the mail folder hierarchy from my Outlook account."` | Hierarchy verb returns prose, not folder paths. |
+| `"$filter=displayName eq '<name>'"` (OData syntax embedded in the query) | Filter syntax fails — WorkIQ does not pass through OData. |
+
+## Parsing the response
+
+WorkIQ returns a markdown table. Parse rows where `folder path` is non-empty and `message count >= 1`:
+
+1. Trim each folder path (no leading/trailing slashes).
+2. Deduplicate against existing `boundaries.email.mailboxes[]`.
+3. Cap at top 10 by `message count`.
+4. The remainder (if any) goes to `<project>/OPEN-QUESTIONS-DRAFT.md` per the orchestration doctrine.
+5. Confidence ranking:
+   - `high` — folder path explicitly contains the hint (case-insensitive substring), e.g. `Inbox/HCA Intake` for hint `HCA`.
+   - `medium` — message count ≥ 10 AND folder is a known well-known root (`Inbox`, `Sent Items`, `Archive`).
+   - `low` — everything else.
+
+## Sidecar file shape
+
+Written to `<engagement-root>/<project>/Evidence/_discovery/<YYYY-MM-DD>_email_discovery-<alias>.yml`:
+
+```yaml
+source: email
+project: '<project>'
+customer_hint: '<HINT>'
+lookback_days: 90
+discovered_at: '<ISO-8601>'
+discovered_by: '<alias>'
+query: 'In my Outlook mail folders, find the top mail folders that contain emails mentioning ''<HINT>'' received in the last 90 days. ...'
+workiq_request_id: '<request-id>'
+total_candidates_found: 7
+candidates_persisted: 7
+candidates_deferred: 0
+results:
+  - value: 'Inbox/HCA Intake'
+    label: 'Inbox/HCA Intake (245 messages, last 2026-05-25)'
+    confidence: high
+    needs_review: true
+  - value: 'Inbox'
+    label: 'Inbox (87 messages, last 2026-05-26)'
+    confidence: medium
+    needs_review: true
+```
+
+`needs_review: true` is set on EVERY row by default. The user clears it manually after confirming the folder.
+
+## Bootstrap-status row
+
+The Discovery Sweep Results table row (per `customer-hint-discovery.instructions.md`):
+
+```
+| email | <HINT> | "In my Outlook mail folders..." | 7 | 7 | 0 | <alias> |
+```
+
+## When this sweep does NOT run
+
+- The user already populated `boundaries.email.mailboxes[]` with at least one entry that does NOT carry `needs_review: true` in the sidecar — boundary is gospel; skip sweep.
+- The active profile disables email (`m365-mutable.json#sources.email.enabled = false`) — write `last_status: not-applicable`.
+- WorkIQ itself is unreachable (signed out, EULA pending, CLI missing) — write `last_status: blocked-auth`, retry_signal `user-action`. Do NOT write `blocked-config`.
+
+## References
+
+- `customer-hint-discovery.instructions.md` — orchestration contract.
+- `pull-email/SKILL.md` — what consumes `boundaries.email.mailboxes[]` (folder fast-path + root fallback).
+- `workiq-only.instructions.md` — why m365_list_mail_folders / Graph are forbidden.
+- `deferred-retry-on-workiq-fail.instructions.md` — marker shape when sweep returns a WorkIQ error.
+- `status-taxonomy.instructions.md` — `unresolved` vs. `blocked-config` distinction.

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

@@ -82,4 +82,8 @@ Case-insensitive; ranking `exact > prefix > contains`. Multiple plausible candid
       09_open-questions.md
 ```
 
-The skill creates missing folders/files on first use; never overwrites existing files without explicit user approval.
+The skill creates missing folders/files on first use; never overwrites existing files without explicit user approval.
+
+## References (v4.4.7)
+
+- Project-name resolution implements the universal fuzzy contract in fuzzy-disambiguation.instructions.md.

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

@@ -129,4 +129,106 @@ Before writing any per-entity block (meeting / thread / email / page / file / re
 - [ ] **Next Steps** section is present (distinct from Action Items)
 - [ ] All other structured sub-sections (Decisions / Action Items / Risks / Open Questions / Customer Asks) come AFTER, not instead of
 - [ ] Verbatim transcript / message reproduction / page body is still present (the AI summary does not replace it)
-- [ ] Empty sections explicitly say `_None surfaced._`, never omitted
+- [ ] Empty sections explicitly say `_None surfaced._`, never omitted
+
+<!-- merged from evidence-thoroughness.instructions.md (v4.4.9) -->
+## Detection algorithm
+
+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/fuzzy-disambiguation.instructions.md

@@ -0,0 +1,97 @@
+---
+applyTo: "**"
+description: "Universal fuzzy-match contract — whenever a kushi skill needs to map a user-given name (project, OneNote section, SharePoint site, Teams chat, ADO area, CRM record, mailbox folder, meeting topic) to a concrete identifier, it MUST use the same ranked-candidate flow with ask_user disambiguation on ambiguity. Eliminates inconsistent matching across sources."
+---
+
+# Fuzzy Disambiguation (HARD RULE, v4.4.7+)
+
+Every kushi skill that maps a **string the user typed** (or pulled from config) to a **concrete ID/path/record** in an external system goes through this exact flow. No per-source improvisation.
+
+## Why this exists
+
+Different sources used different matching heuristics: `engagement-root-resolution` did `exact > prefix > contains` and prompted on ambiguity; `pull-onenote` Step A did its own section-name fuzz; `pull-teams` matched chat topics manually; `pull-crm` accepted whichever Dataverse row came back first. Result: same project name resolved to different things across sources, and users were silently sent to the wrong artifact.
+
+## The flow (applies to ALL sources)
+
+1. **Candidate list.** Pull every plausible target from the source (notebooks under the user's account, chats in the last 60d, project folders under engagement-root, etc.). Cap at 50 candidates.
+
+2. **Score and rank** with this fixed lexicographic order:
+   - **exact** (case-insensitive equality) — score 1000
+   - **prefix** (target startsWith query) — score 800 − (target.length − query.length)
+   - **contains** (target.includes query) — score 500 − distance-from-start
+   - **token-overlap** (query and target share ≥ 1 whitespace-split token, case-insensitive) — score 300 + matchedTokens × 10
+   - **levenshtein** (within 2 edits) — score 100 + (3 − distance) × 10
+   - else — score 0 (drop)
+
+3. **Decision rule** (uses top 5 scored candidates):
+   | Situation | Action |
+   |---|---|
+   | Top candidate score ≥ 800 AND #2 score ≤ top × 0.7 | **Auto-pick top**. Echo: `✓ Resolved '<query>' → '<picked>' (<source-id>) [score=<n>, confidence=high]`. Continue. |
+   | Top candidate score ≥ 300 AND #2 score ≤ top × 0.7 AND in `--non-interactive` mode | **Auto-pick top with warning**. Echo: `⚠ Auto-picked '<query>' → '<picked>' (<source-id>) [score=<n>, confidence=medium]. Re-run interactively to confirm.` |
+   | Top ≥ 1 candidate AND interactive | **`ask_user` with options**. See "Disambiguation prompt shape" below. |
+   | Zero candidates above score 100 | **`ask_user` with type-in-an-id option**. After 1 failed retry → write `unresolved-<source>` to run-log + tracking; continue with the source-level coverage gap. |
+
+4. **Persist the resolution** to the appropriate registry so the next run is direct:
+   - Project name → `m365-mutable.json#m365Mutable.knownSections.<project>` (per `m365-id-registry.instructions.md`)
+   - OneNote section/notebook → `m365-mutable.json#m365Mutable.knownSections.<project>.onenote.<section>`
+   - SharePoint site → `<project>/integrations.yml#sharepoint.siteId` + `siteName`
+   - Teams chat → `<alias>/.settings.yml#teams.chatIds[]`
+   - ADO area → `<project>/integrations.yml#ado.areaPath`
+   - CRM record → `<project>/integrations.yml#crm.recordId`
+   - Mailbox folder name → `<workspace>/.kushi/config/user/m365-auth.json#emailContext.folders[]` (already canonical names)
+
+   Persistence happens INSIDE the pull skill that resolved it, in the same run.
+
+## Disambiguation prompt shape (ALWAYS the same)
+
+```
+🤔 Multiple matches for '<query>' in <source>:
+
+  1) <candidate-1-display-name> · <secondary-context>   [score=<n>]
+  2) <candidate-2-display-name> · <secondary-context>   [score=<n>]
+  3) <candidate-3-display-name> · <secondary-context>   [score=<n>]
+  4) Type a different name / ID
+  5) Skip this source for now (write unresolved-<source> to run-log)
+
+Which one matches '<query>'?
+```
+
+Render via `ask_user` (preferred) when the host supports it. Fallback: chat-message prompt with the same shape.
+
+- "Secondary context" is whatever disambiguates **the same display name appearing twice**: notebook owner, site URL host, ADO project, CRM account name, meeting organizer + date, etc.
+- The chosen option is **persisted immediately** (see step 4). No re-prompt for the same query in the same project.
+
+## Retry-once contract
+
+If `ask_user` returns option 4 (type-in) and the typed value still doesn't resolve in step 1, retry ONCE with the new query, then fall through to option 5 (skip + write `unresolved-<source>`). Never loop forever.
+
+## Where this rule applies (HARD inventory)
+
+| Surface | Query | Resolves to |
+|---|---|---|
+| `engagement-root-resolution` Step "project name" | user's project arg | `<engagement-root>/<project>/` folder |
+| `pull-onenote` Step A | section name from `m365-mutable.json` or new ask | OneNote `sectionId` + `notebookId` (write to id-registry) |
+| `pull-sharepoint` Step "resolve site" | site name / URL hint | `siteId` + `webUrl` (write to project `integrations.yml`) |
+| `pull-teams` Step "scope chats" | chat topic / member name | `chatId[]` (write to alias `.settings.yml`) |
+| `pull-meetings` Step "scope meetings" | meeting subject pattern | meeting candidates by joinUrl (no persistence — meeting-scoped) |
+| `pull-crm` Step "resolve record" | account / project name | Dataverse `engagementRecordId` (write to project `integrations.yml`) |
+| `pull-ado` Step "resolve area" | area name | ADO `areaPath` (write to project `integrations.yml`) |
+| `pull-email` Step "resolve mailbox folders" | folder name | canonical folder display-name (write to `m365-auth.json`) |
+| `ask-project` Step "resolve project" | user's project arg in question | same as engagement-root-resolution |
+
+## What NOT to do
+
+- Do NOT silently pick the first candidate when score-gap is `< 0.7`. Always disambiguate.
+- Do NOT prompt with the legacy "Enter the exact name:" free-text — always present a ranked list first.
+- Do NOT re-prompt for the same query in the same run after the user picked an answer. Cache it for this run AND persist for next-run direct lookup.
+- Do NOT use per-source thresholds. The above scoring is universal.
+
+## Self-check enforcement
+
+**D17 — Fuzzy disambiguation cite.** Every `pull-*` SKILL.md whose source has fuzzy name → ID resolution (`pull-onenote`, `pull-sharepoint`, `pull-teams`, `pull-crm`, `pull-ado`, `pull-email`) MUST reference `fuzzy-disambiguation.instructions.md` in its body. Plus `engagement-root-resolution.instructions.md` and `ask-project` SKILL.md.
+
+## References
+
+- `engagement-root-resolution.instructions.md` — the originating "ask user on ambiguity" pattern (project-name resolution). v4.4.7+ this rule is the universal generalization.
+- `m365-id-registry.instructions.md` — destination registries for persisted resolutions.
+- `multi-user-shared-files.instructions.md` — `m365-mutable.json` writes go through the SharePoint conflict-absorb pattern.

package/plugin/instructions/identity-resolution.instructions.md

@@ -71,3 +71,79 @@ Per `deferred-retry-on-workiq-fail.instructions.md`, identity resolution NEVER b
 * `deferred-retry-on-workiq-fail.instructions.md` — failure-mode contract.
 * `engagement-root-resolution.instructions.md` — `projects_root` resolution (separate from identity).
 * `templates/init/project-evidence.template.yml` — defaults to `<auto>` for these three fields.
+
+---
+
+## v4.4.5 extension — `setup` skill is the single source of truth for ALL onboarding questions
+
+The `setup` skill (added v4.4.4) extends this doctrine beyond identity to cover the full onboarding question set. `bootstrap-project` MUST NOT re-ask any question that `setup` already answered.
+
+### Fields managed by `setup`
+
+| File | Field | Required? | Auto-resolved from |
+|---|---|---|---|
+| `project-evidence.yml` | `identity.alias` / `display_name` / `email` | YES | WorkIQ "Who am I?" |
+| `project-evidence.yml` | `identity_status`, `identity_verified_at` | YES | written by setup |
+| `project-evidence.yml` | `projects_root` | YES | cwd-ancestor detection; otherwise prompt |
+| `project-evidence.yml` | `default_onenote_notebook` | **OPTIONAL** | user prompt; value `<skip>` = OneNote disabled |
+| `project-evidence.yml` | `active_projects[]` | YES (list, may be empty) | the project arg if dispatched from `bootstrap <project>`; otherwise leave existing |
+| `project-evidence.yml` | `workiq.cli_path` | OPTIONAL | only written when discovered via PATH/fallback, not already pinned |
+| `m365-auth.json` | `_meta.owner` | YES | `<identity.email>` |
+| `m365-auth.json` | `oneNote.defaultLinkOwner` | YES (when OneNote enabled) | `<identity.email>` — the user's own UPN, since OneNote queries default to the user's personal notebook |
+| `m365-auth.json` | `oneNote.defaultNotebookId` | **NOT WRITTEN (kushi v4.7.3+)** | Per `workiq-onenote-query-shape.instructions.md`, WorkIQ has no notebook-ID lookup surface — any such probe punts to Graph Explorer. Setup persists `defaultNotebookName` only; section IDs are discovered per-section at bootstrap/refresh time using the natural-language WorkIQ pattern. |
+| `m365-auth.json` | `oneNote.enabled` | YES | `false` when user chose `<skip>` for the notebook name |
+| `m365-auth.json` | `emailContext.folders[]` | OPTIONAL | user prompt: comma-sep list / `all` / blank. `all` or blank → `[]` (full mailbox) |
+| `m365-auth.json` | `sharePointContext.localProjectsRoot` | YES | mirrors `<projects_root>` |
+
+### Auto-EULA + sign-in detection
+
+`pingWorkIQ()` in `src/check-workiq.mjs` auto-runs `workiq accept-eula` (idempotent) when the first `workiq ask -q "ping"` returns empty OR mentions EULA/license, then retries the ping. Only if BOTH attempts return empty does the installer surface a "Sign in by running `workiq ask -q \"Who am I?\"` in a new terminal" hint.
+
+The `setup` skill does the deeper recovery (3-retry loop with `ask_user` choices).
+
+### OneNote — optional + auto-resolve
+
+- User chose `<skip>` → set `oneNote.enabled: false`, leave all other OneNote fields blank, OneNote source becomes a no-op (reported as `not-applicable` in run logs).
+- User gave a notebook name → query WorkIQ for `{notebookId, notebookSourceDoc, notebookSpoBaseUrl}`. Persist all three. If WorkIQ returns empty, leave `defaultNotebookId: ""` with a `_defaultNotebookId_note` and let `pull-onenote` Step A do per-section discovery.
+- `defaultLinkOwner` is ALWAYS the user's own UPN unless the user explicitly overrides (shared/team-owned notebook case).
+
+### Mailbox folders — multi-value with "all" sentinel
+
+Question text (only asked once, only by `setup`, only when `emailContext.folders` is empty or `["__FILL_ME_IN__"]`):
+
+> Which mailbox folders should kushi search for email evidence?
+> • Enter a comma-separated list (e.g. `Inbox, Archive, Projects/HCA`)
+> • Type `all` to search the FULL mailbox (slower — every refresh scans everything)
+> • Press Enter to leave blank (equivalent to `all`)
+
+Both `all` and blank persist as `[]`. ALWAYS print after persisting:
+
+> Note: empty list = scan the full mailbox on every refresh (slower). Add specific folders later via `.kushi/config/user/m365-auth.json#emailContext.folders` to speed runs up.
+
+### Active projects — don't ask, use what was asked
+
+- **Dispatched from `bootstrap <project>`** → append `<project>` to `active_projects` (don't replace).
+- **Standalone `setup`** → leave `active_projects` untouched; just print the file pointer.
+- **`setup --reconfigure`** → ask the user explicitly, default = current list.
+
+### "Where to edit this later" footer (REQUIRED on every setup run)
+
+```
+Edit these files later if anything changes:
+  • <workspace>/.kushi/config/user/project-evidence.yml
+      identity, projects_root, default_onenote_notebook, active_projects, workiq.cli_path
+  • <workspace>/.kushi/config/user/m365-auth.json
+      OneNote defaults, email folder list, SharePoint root
+  • <workspace>/.kushi/config/shared/integrations.yml   (team-wide; commit changes)
+      CRM environmentUrl + tenantId, ADO organization + project
+
+To re-walk every question (overwrites all answers):
+  @Kushi setup --reconfigure
+```
+
+Render the file paths as clickable `file:///` URIs when the host (VS Code, Clawpilot) supports them.
+
+### `bootstrap-project` Step 0 contract
+
+`bootstrap-project` Step 0 dispatches to `setup` only when `identity_status` is missing or `skipped-*`. It NEVER directly asks for identity, OneNote name/ID, mailbox folders, or `projects_root`. If `identity_status: verified` is set, Step 0 is a no-op and bootstrap proceeds directly to Step 1.
+

package/plugin/instructions/issue-recovery.instructions.md

@@ -0,0 +1,58 @@
+---
+applyTo: "**"
+description: "Universal Issue Recovery Rule. When a workflow exposes a reusable problem in the repo-owned surface (skill text, instruction, prompt, config, supporting code), fix the smallest correct artifact first — don't just report and continue. Prefer durable fixes over one-off workarounds. After the fix, re-run the narrowest failed check before continuing. Never use memory as a substitute for correcting the workflow surface."
+---
+
+# Issue Recovery Rule (v4.5.1)
+
+A universal rule for every kushi skill that hits an external service (M365 via WorkIQ, Dataverse via az CLI, ADO via az boards, OneNote via Playwright, etc.) AND for every workflow that consumes evidence (aggregate-project, ask-project, fde-report).
+
+## The rule
+
+When a run exposes a reusable problem in the repo-owned ADO/CRM/M365/OneNote/SharePoint/Meetings/Email surface:
+
+1. **Fix the smallest correct repo-owned artifact first** when feasible.
+   - Skill text (`plugin/skills/<name>/SKILL.md`)
+   - Instruction file (`plugin/instructions/*.instructions.md`)
+   - Prompt (`plugin/prompts/*.prompt.md`)
+   - Config template (`plugin/templates/init/*.template.*`)
+   - Supporting code (`plugin/skills/<name>/*.mjs`, `plugin/lib/*.ps1`, `src/*.mjs`)
+   - Reference pack (`plugin/reference-packs/<pack>/*.md`)
+2. **Prefer a durable fix over a one-off workaround** when the issue will affect the next run too. Per-run workarounds (chat-only retries, ad-hoc filter changes that aren't persisted) are escalation paths, not solutions.
+3. **After the fix, rerun the narrowest failed check** before continuing the broader workflow steps. E.g. if pull-onenote failed Pre-flight C URL completeness, fix the canonical URL doctrine + re-run Pre-flight C only; don't re-run the whole bootstrap.
+4. **Record the minimum useful guardrail in the run report + learnings** AFTER the fix is confirmed. Per `capture-learnings.instructions.md` for the source-specific learnings file; per `run-reports.instructions.md` for the per-run narrative.
+5. **Do NOT use memory as a substitute** for correcting the workflow surface. If an issue happened once, the fix lives in the repo. Memory captures user preferences and decisions, not workflow defects.
+
+## Examples (correct application)
+
+| Symptom | Wrong response | Right response |
+|---|---|---|
+| pull-onenote returns auth-required on every project after a URL-formula change | Add retry loop to runner.mjs | Fix `pull-onenote/SKILL.md` Pre-flight C to ban synthesized URLs (per learnings/onenote.md) — durable across every project |
+| pull-ado finds zero comments because comments/history is empty; attachment has the discussion | Skip this run / mark as no-coverage | Emit `evidence_source_kind: attachment-fallback` in coverage notes; `aggregate-project` reads it; user knows the discussion lives in an attachment, not comments. Update `pull-ado/SKILL.md` if the fallback path itself is missing |
+| pull-crm finds the engagement record but the bootstrap discovery skipped it because of a 401 | Add a per-run retry in the orchestrator | Fix the auth-and-retry pattern in `auth-and-retry.instructions.md` if the retry shape is broken; or fix the `crm-bootstrap-discovery.instructions.md` if the 401 means the user has a different tenant than the config says |
+| Workspace template missing a field that user keeps having to add by hand | Document the workaround in CHANGELOG | Update the template at `plugin/templates/init/*.template.*` so the next user gets the right shape from `setup` Step 2 |
+
+## Examples (wrong application — don't do these)
+
+- ❌ **"Just store this in memory so I don't forget next time."** Memory is for user preferences and engagement-specific decisions, not workflow defects. If the same issue happens again, the fix must already be in the repo.
+- ❌ **"Hot-patch the live install but skip the repo edit."** Live install fixes are temporary; repo is the source of truth. Self-check D4 will surface the drift.
+- ❌ **"Add a one-off filter for this project to avoid the bad data."** Per-project filters belong in the project's `integrations.yml#boundaries.*`. Doctrine fixes belong in the repo.
+
+## Scope (which skills MUST cite this rule)
+
+The Issue Recovery Rule applies to every skill that runs against an external service AND to every consumer of their evidence:
+
+| Skill | Cite required | Why |
+|---|---|---|
+| `pull-email`, `pull-teams`, `pull-meetings`, `pull-onenote`, `pull-sharepoint`, `pull-crm`, `pull-ado`, `pull-misc` | ✅ | External service failures expose doctrine gaps |
+| `aggregate-project`, `consolidate-evidence` | ✅ | Consumers — they discover when capture quality is poor |
+| `bootstrap-project`, `refresh-project` | ✅ | Orchestrators — they observe per-source gate outcomes |
+| `setup`, `self-check`, `intro` | ➖ | Internal-state skills; no external service surface |
+| `ask-project`, `project-status`, `fde-*` | ➖ | Read-only over local evidence; defects surface via gate, not directly |
+
+## References
+
+- `per-source-verification-gate.instructions.md` — the per-source gate exposes the symptoms this rule responds to.
+- `capture-learnings.instructions.md` — where the post-fix learning gets appended.
+- `run-reports.instructions.md` — where the run-specific narrative records the fix.
+- `fallback-status-reporting.instructions.md` — when an attachment-fallback or comments-empty path was used, how to surface it in status.