kushi-agents 5.6.4 → 5.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.6.4",
+  "version": "5.7.0",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/instructions/bootstrap-status-format.instructions.md

@@ -1,151 +1,151 @@
----
-applyTo: "**"
-excludeAgent: "code-review"
----
-
-# Bootstrap Status Artifact — Format Contract
-
-When `bootstrap-project` (or any full refresh / retry workflow) finishes a project run, it MUST write `<project>/Evidence/<alias>/bootstrap-status.md` using the format below. This file is the **per-user fast orientation artifact** for the project — what was bootstrapped, what durable context now exists, what stage the engagement is in, what gaps remain. It is NOT a transcript of the run.
-
-> **v5.4.4+ — per-user path.** The bootstrap-status artifact is **per-user authored** under `Evidence/<alias>/bootstrap-status.md` per `multi-user-shared-files.instructions.md` § "Per-user authored files". A cross-contributor rollup lives at `<project>/_Consolidated/bootstrap-status.md`, written deterministically by `consolidate-evidence` (Step 5). The pre-v5.4.4 root-level `<project>/bootstrap-status.md` is owned by `consolidate-evidence` only; writers MUST NOT touch it. Legacy projects are auto-migrated by `migrate-per-user-files`.
-
-> **v4.4.2 contracts** — every `Status` cell in this artifact MUST come from the closed taxonomy in `status-taxonomy.instructions.md`. Direct-path failures that were recovered by a documented fallback MUST be rendered as `completed-via-fallback` per `fallback-status-reporting.instructions.md`, not `failed` / `blocked`. The pre-v4.4.2 ad-hoc strings (`populated`, `unsynced`, `degraded`, `partial-cap`, etc.) are mapped onto the taxonomy in `status-taxonomy.instructions.md §1`.
-
-## Required section order
-
-```
-# Bootstrap Status
-
-- Bootstrap Date: YYYY-MM-DD HH:MM TZ
-- Project: <name>
-- Customer Hint: <token used to resolve>
-- Mode: bootstrap | refresh | retry | force
-- Lookback Window: <days>
-
-## Preflight Checks
-
-| Check | Status | Notes |
-|---|---|---|
-| `.kushi/config/shared/integrations.yml` filled | resolved \| blocked-auth \| missing | ... |
-| `.kushi/config/shared/integrations.yml` filled | ... | ... |
-| `<project>/integrations.yml` boundaries present | ... | ... |
-| `az` CLI tenant matches | cli-available \| blocked-auth | ... |
-
-## Context Artifact Status
-
-| Artifact | Status | Notes |
-|---|---|---|
-| `crm/snapshot/<entity>/<id>.md` | populated \| unsynced \| degraded \| partial-template | <annotation count> |
-| `ado/snapshot/engagement-<id>.md` | populated \| ado-not-complete | <tree size> |
-| `ado/snapshot/items/*.md` | populated \| skipped \| ado-not-complete | <N items> |
-| `onenote/snapshot/<section>/*.md` | populated \| degraded | <pages enumerated/failed> |
-| `email/_index/<week>_message-index.md` | populated \| degraded-list-only \| throttled-tooManyRequests | <N enumerated> |
-| `email/stream/<week>_email-stream.md` | populated \| degraded-list-only | <N threads> |
-| `teams/...` | ... | ... |
-
-## Current Bootstrap Outcome
-
-- One-line current state per source.
-- CRM stage: <plain-language interpretation of statuscode> (`internal-only` per `evidence-confidence-ladder`).
-- ADO linkage: pinned engagement <id> | pending pick from N candidates | `ado-not-complete`.
-- Notable gaps: ...
-
-## Access Limitations
-
-| System | Status | Reason | Workaround |
-|---|---|---|---|
-| ADO | resolved | — | — |
-| CRM | blocked-auth | tenant mismatch | `az login --tenant <id>` |
-| Email | throttled-tooManyRequests | WorkIQ rate-limited | retry next refresh |
-
-## Deferred Retries (kushi v4.4.1+, per `deferred-retry-on-workiq-fail.instructions.md`)
-
-Omit this section entirely if `<project>/Evidence/<alias>/_deferred-retries/` is empty across all contributors.
-
-| Source | Target | Attempts | Marker | First seen | Discovered by |
-|---|---|---|---|---|---|
-| meetings | "JD FDE Intake" 2026-05-13 | 1 | `Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml` | 2026-05-20 | ushak |
-| onenote | "Architecture overview" | 2 | `Evidence/ushak/_deferred-retries/2026-05-19-0810_onenote_throttled.yml` | 2026-05-19 | ushak |
-
-Markers older than 5 attempts auto-promote to `OPEN-QUESTIONS-DRAFT.md`. The next `refresh` drains the queue (Step 2a in `refresh-project/SKILL.md`) — do NOT manually retry by calling `m365_get_*` / Graph; those are forbidden per `workiq-only.instructions.md`.
-
-## Bootstrap Status
-
-ONE final line, normalized:
-- `bootstrap-complete`
-- `bootstrap-complete-with-coverage-gaps`
-- `bootstrap-blocked — <primary reason>`
-- `refresh-complete`
-- `refresh-complete-with-coverage-gaps`
-```
-
-## Normalized status vocabulary
-
-Use these exact strings everywhere (table cells, run-log, narrative):
-
-- `resolved` — check passed
-- `cli-available` — required CLI is installed and authenticated
-- `blocked-auth` — auth missing/failed
-- `partial-template` — file exists but only template scaffolding written
-- `unsynced` — file does not contain real data yet
-- `populated` — file contains real fetched data
-- `degraded` / `degraded-list-only` — partial fetch (e.g. email body-unavailable for some messages)
-- `throttled-tooManyRequests` — source rate-limited
-- `ado-not-complete` — engagement record not found yet OR ADO linkage missing
-- `completed-with-coverage-gaps` — final outcome with explicit gaps recorded
-
-## Multi-contributor safety (kushi v5.4.4+)
-
-Per `multi-user-shared-files.instructions.md`, this file is **per-user authored** at `<project>/Evidence/<alias>/bootstrap-status.md` and the consolidated cross-contributor view lives at `<project>/_Consolidated/bootstrap-status.md` (written by `consolidate-evidence` Step 5):
-
-1. **Writers target the per-user path only.** Every `bootstrap-project` / `refresh-project` run writes its own `Evidence/<alias>/bootstrap-status.md`. There is no read-modify-write contention — each alias owns its file.
-2. **No `Contributors who have bootstrapped this project` section on the per-user file.** That section is reconstructed in the `_Consolidated/bootstrap-status.md` rollup, which lists every contributor with their per-user file's `Last Run` / `Mode` / `Outcome`.
-3. **Conflict-copies on the per-user file are extremely rare** (only the owning alias writes it). If they do appear, the alias's next bootstrap absorbs them and deletes them per the universal merge rules.
-4. **The final one-line status** on the per-user file is for the most recent run by that alias only.
-
-### Required `## Run summary` section on the per-user file
-
-Append immediately after `## Bootstrap Status`:
-
-```
-## Run summary
-
-| Alias | Display Name | Last Run | Mode | Outcome |
-|---|---|---|---|---|
-| ushak | Usha Kandregula | 2026-05-27 09:42 EDT | bootstrap | bootstrap-complete-with-coverage-gaps |
-```
-
-`consolidate-evidence` Step 5 reads every `Evidence/<alias>/bootstrap-status.md`, harvests its `## Run summary` row, and emits a merged `## Contributors who have bootstrapped this project` table into `_Consolidated/bootstrap-status.md`.
-
-## Sections to AVOID in bootstrap-status
-
-Do NOT keep these in `bootstrap-status.md` (they belong elsewhere or become stale):
-
-- `Fallback Inputs Used` → run-log only
-- `Evidence & Current Context` → State files
-- `FDE Fitness Assessment` → State/00_overview.md
-- `Source Coverage` → already covered by Access Limitations
-- `Recommended Actions` → State/05_action-items.md or Open Questions/
-- long historical retry logs → run-log only
-
-## Stable-summary test
-
-When deciding whether a detail belongs in `bootstrap-status.md`, ask: **"Does this help a future reader understand the current durable project state?"** If it's mainly describing how this one run unfolded, push it to `update-status.md` (per-run history) or the run-log instead.
-
-## ADO-not-complete note
-
-When a bootstrap cannot resolve the ADO Engagement WI, include in `## Current Bootstrap Outcome`:
-
-> ADO context sync pending: engagement record not found yet; bootstrap is usable with CRM/transcript context and should be revisited after ADO engagement creation or when the candidate WI is pinned to `integrations.yml#ado.engagement_id`.
-
-And reflect `ado-not-complete` in the relevant Context Artifact Status rows.
-
-## Relationship to other artifacts
-
-- Detailed CRM content → `crm-context/record-profile.md` + `crm/snapshot/`
-- Detailed ADO tree → `ado/snapshot/tree.md` + per-item files
-- Detailed transcripts → `meeting-transcripts/index.md`
-- Per-run history → `update-status.md` (project-local)
-- Cross-source synthesis → `State/`
-
-`bootstrap-status.md` summarizes; it never duplicates these artifacts.
+---
+applyTo: "**"
+excludeAgent: "code-review"
+---
+
+# Bootstrap Status Artifact — Format Contract
+
+When `bootstrap-project` (or any full refresh / retry workflow) finishes a project run, it MUST write `<project>/Evidence/<alias>/bootstrap-status.md` using the format below. This file is the **per-user fast orientation artifact** for the project — what was bootstrapped, what durable context now exists, what stage the engagement is in, what gaps remain. It is NOT a transcript of the run.
+
+> **v5.4.4+ — per-user path.** The bootstrap-status artifact is **per-user authored** under `Evidence/<alias>/bootstrap-status.md` per `multi-user-shared-files.instructions.md` § "Per-user authored files". A cross-contributor rollup lives at `<project>/_Consolidated/bootstrap-status.md`, written deterministically by `consolidate-evidence` (Step 5). The pre-v5.4.4 root-level `<project>/bootstrap-status.md` is owned by `consolidate-evidence` only; writers MUST NOT touch it. Legacy projects are auto-migrated by `migrate-per-user-files`.
+
+> **v4.4.2 contracts** — every `Status` cell in this artifact MUST come from the closed taxonomy in `status-taxonomy.instructions.md`. Direct-path failures that were recovered by a documented fallback MUST be rendered as `completed-via-fallback` per `fallback-status-reporting.instructions.md`, not `failed` / `blocked`. The pre-v4.4.2 ad-hoc strings (`populated`, `unsynced`, `degraded`, `partial-cap`, etc.) are mapped onto the taxonomy in `status-taxonomy.instructions.md §1`.
+
+## Required section order
+
+```
+# Bootstrap Status
+
+- Bootstrap Date: YYYY-MM-DD HH:MM TZ
+- Project: <name>
+- Customer Hint: <token used to resolve>
+- Mode: bootstrap | refresh | retry | force
+- Lookback Window: <days>
+
+## Preflight Checks
+
+| Check | Status | Notes |
+|---|---|---|
+| `.kushi/config/shared/integrations.yml` filled | resolved \| blocked-auth \| missing | ... |
+| `.kushi/config/shared/integrations.yml` filled | ... | ... |
+| `<project>/integrations.yml` boundaries present | ... | ... |
+| `az` CLI tenant matches | cli-available \| blocked-auth | ... |
+
+## Context Artifact Status
+
+| Artifact | Status | Notes |
+|---|---|---|
+| `crm/snapshot/<entity>/<id>.md` | populated \| unsynced \| degraded \| partial-template | <annotation count> |
+| `ado/snapshot/engagement-<id>.md` | populated \| ado-not-complete | <tree size> |
+| `ado/snapshot/items/*.md` | populated \| skipped \| ado-not-complete | <N items> |
+| `onenote/snapshot/<section>/*.md` | populated \| degraded | <pages enumerated/failed> |
+| `email/_index/<week>_message-index.md` | populated \| degraded-list-only \| throttled-tooManyRequests | <N enumerated> |
+| `email/stream/<week>_email-stream.md` | populated \| degraded-list-only | <N threads> |
+| `teams/...` | ... | ... |
+
+## Current Bootstrap Outcome
+
+- One-line current state per source.
+- CRM stage: <plain-language interpretation of statuscode> (`internal-only` per `evidence-confidence-ladder`).
+- ADO linkage: pinned engagement <id> | pending pick from N candidates | `ado-not-complete`.
+- Notable gaps: ...
+
+## Access Limitations
+
+| System | Status | Reason | Workaround |
+|---|---|---|---|
+| ADO | resolved | — | — |
+| CRM | blocked-auth | tenant mismatch | `az login --tenant <id>` |
+| Email | throttled-tooManyRequests | WorkIQ rate-limited | retry next refresh |
+
+## Deferred Retries (kushi v4.4.1+, per `deferred-retry-on-workiq-fail.instructions.md`)
+
+Omit this section entirely if `<project>/Evidence/<alias>/_deferred-retries/` is empty across all contributors.
+
+| Source | Target | Attempts | Marker | First seen | Discovered by |
+|---|---|---|---|---|---|
+| meetings | "JD FDE Intake" 2026-05-13 | 1 | `Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml` | 2026-05-20 | ushak |
+| onenote | "Architecture overview" | 2 | `Evidence/ushak/_deferred-retries/2026-05-19-0810_onenote_throttled.yml` | 2026-05-19 | ushak |
+
+Markers older than 5 attempts auto-promote to `OPEN-QUESTIONS-DRAFT.md`. The next `refresh` drains the queue (Step 2a in `refresh-project/SKILL.md`) — do NOT manually retry by calling `m365_get_*` / Graph; those are forbidden per `workiq-only.instructions.md`.
+
+## Bootstrap Status
+
+ONE final line, normalized:
+- `bootstrap-complete`
+- `bootstrap-complete-with-coverage-gaps`
+- `bootstrap-blocked — <primary reason>`
+- `refresh-complete`
+- `refresh-complete-with-coverage-gaps`
+```
+
+## Normalized status vocabulary
+
+Use these exact strings everywhere (table cells, run-log, narrative):
+
+- `resolved` — check passed
+- `cli-available` — required CLI is installed and authenticated
+- `blocked-auth` — auth missing/failed
+- `partial-template` — file exists but only template scaffolding written
+- `unsynced` — file does not contain real data yet
+- `populated` — file contains real fetched data
+- `degraded` / `degraded-list-only` — partial fetch (e.g. email body-unavailable for some messages)
+- `throttled-tooManyRequests` — source rate-limited
+- `ado-not-complete` — engagement record not found yet OR ADO linkage missing
+- `completed-with-coverage-gaps` — final outcome with explicit gaps recorded
+
+## Multi-contributor safety (kushi v5.4.4+)
+
+Per `multi-user-shared-files.instructions.md`, this file is **per-user authored** at `<project>/Evidence/<alias>/bootstrap-status.md` and the consolidated cross-contributor view lives at `<project>/_Consolidated/bootstrap-status.md` (written by `consolidate-evidence` Step 5):
+
+1. **Writers target the per-user path only.** Every `bootstrap-project` / `refresh-project` run writes its own `Evidence/<alias>/bootstrap-status.md`. There is no read-modify-write contention — each alias owns its file.
+2. **No `Contributors who have bootstrapped this project` section on the per-user file.** That section is reconstructed in the `_Consolidated/bootstrap-status.md` rollup, which lists every contributor with their per-user file's `Last Run` / `Mode` / `Outcome`.
+3. **Conflict-copies on the per-user file are extremely rare** (only the owning alias writes it). If they do appear, the alias's next bootstrap absorbs them and deletes them per the universal merge rules.
+4. **The final one-line status** on the per-user file is for the most recent run by that alias only.
+
+### Required `## Run summary` section on the per-user file
+
+Append immediately after `## Bootstrap Status`:
+
+```
+## Run summary
+
+| Alias | Display Name | Last Run | Mode | Outcome |
+|---|---|---|---|---|
+| ushak | Usha Kandregula | 2026-05-27 09:42 EDT | bootstrap | bootstrap-complete-with-coverage-gaps |
+```
+
+`consolidate-evidence` Step 5 reads every `Evidence/<alias>/bootstrap-status.md`, harvests its `## Run summary` row, and emits a merged `## Contributors who have bootstrapped this project` table into `_Consolidated/bootstrap-status.md`.
+
+## Sections to AVOID in bootstrap-status
+
+Do NOT keep these in `bootstrap-status.md` (they belong elsewhere or become stale):
+
+- `Fallback Inputs Used` → run-log only
+- `Evidence & Current Context` → State files
+- `FDE Fitness Assessment` → State/00_overview.md
+- `Source Coverage` → already covered by Access Limitations
+- `Recommended Actions` → State/05_action-items.md or Open Questions/
+- long historical retry logs → run-log only
+
+## Stable-summary test
+
+When deciding whether a detail belongs in `bootstrap-status.md`, ask: **"Does this help a future reader understand the current durable project state?"** If it's mainly describing how this one run unfolded, push it to `update-status.md` (per-run history) or the run-log instead.
+
+## ADO-not-complete note
+
+When a bootstrap cannot resolve the ADO Engagement WI, include in `## Current Bootstrap Outcome`:
+
+> ADO context sync pending: engagement record not found yet; bootstrap is usable with CRM/transcript context and should be revisited after ADO engagement creation or when the candidate WI is pinned to `integrations.yml#ado.engagement_id`.
+
+And reflect `ado-not-complete` in the relevant Context Artifact Status rows.
+
+## Relationship to other artifacts
+
+- Detailed CRM content → `crm-context/record-profile.md` + `crm/snapshot/`
+- Detailed ADO tree → `ado/snapshot/tree.md` + per-item files
+- Detailed transcripts → `meeting-transcripts/index.md`
+- Per-run history → `update-status.md` (project-local)
+- Cross-source synthesis → `State/`
+
+`bootstrap-status.md` summarizes; it never duplicates these artifacts.

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

@@ -1,131 +1,131 @@
----
-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 Northwind bootstrap — every source row read `blocked-config` despite extensive Northwind 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. `Northwind`). 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/<alias>/_discovery/<YYYY-MM-DD>_<source>_discovery.yml`** with the per-row metadata (`discovered_by`, `discovered_at`, `needs_review`, `query`, `request_id`, `confidence`). The sidecar lives **inside the contributor's alias folder** because discovery results are inherently per-identity (each contributor sees a different mailbox / chat / meeting set). 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 | Northwind | "In my Inbox..." | 7 | 7 | 0 | ushak |
-   | teams | Northwind | "In my Teams chats..." | 14 | 10 | 4 | ushak |
-   | meetings | Northwind | "In my calendar..." | 3 | 3 | 0 | ushak |
-   | sharepoint | Northwind | "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" |
-| **WorkIQ punted — no surface for this source** (sharepoint sites, teams channels — v4.8.1 empirical) | no | `unresolved` (annotated `discovery-empty-no-workiq-surface`) | `user-action` | yes — cite that this source has no known WorkIQ discovery surface and direct the user to manual configuration (the per-source doctrine has the exact wording) |
-| 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 sibling `Evidence/<other-alias>/_discovery/` folders already have 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 files are per-contributor-folder-per-source-per-date** — each contributor writes only into their own `Evidence/<alias>/_discovery/` folder. Filenames are NOT suffixed with `-<alias>` (folder already namespaces the owner). On the same day, contributors `ushak` and `stand` produce `Evidence/ushak/_discovery/2026-05-26_email_discovery.yml` and `Evidence/stand/_discovery/2026-05-26_email_discovery.yml` respectively — no collision possible. 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`.
-4. **NEVER write to another contributor's `Evidence/<other-alias>/_discovery/` folder.** Reading other aliases' discovery sidecars (e.g. to merge already-confirmed candidates into the shared boundary) is allowed and expected; writing into them is forbidden.
-
-## 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** ("Northwind" → "Northwind 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.
+---
+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 Northwind bootstrap — every source row read `blocked-config` despite extensive Northwind 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. `Northwind`). 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/<alias>/_discovery/<YYYY-MM-DD>_<source>_discovery.yml`** with the per-row metadata (`discovered_by`, `discovered_at`, `needs_review`, `query`, `request_id`, `confidence`). The sidecar lives **inside the contributor's alias folder** because discovery results are inherently per-identity (each contributor sees a different mailbox / chat / meeting set). 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 | Northwind | "In my Inbox..." | 7 | 7 | 0 | ushak |
+   | teams | Northwind | "In my Teams chats..." | 14 | 10 | 4 | ushak |
+   | meetings | Northwind | "In my calendar..." | 3 | 3 | 0 | ushak |
+   | sharepoint | Northwind | "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" |
+| **WorkIQ punted — no surface for this source** (sharepoint sites, teams channels — v4.8.1 empirical) | no | `unresolved` (annotated `discovery-empty-no-workiq-surface`) | `user-action` | yes — cite that this source has no known WorkIQ discovery surface and direct the user to manual configuration (the per-source doctrine has the exact wording) |
+| 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 sibling `Evidence/<other-alias>/_discovery/` folders already have 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 files are per-contributor-folder-per-source-per-date** — each contributor writes only into their own `Evidence/<alias>/_discovery/` folder. Filenames are NOT suffixed with `-<alias>` (folder already namespaces the owner). On the same day, contributors `ushak` and `stand` produce `Evidence/ushak/_discovery/2026-05-26_email_discovery.yml` and `Evidence/stand/_discovery/2026-05-26_email_discovery.yml` respectively — no collision possible. 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`.
+4. **NEVER write to another contributor's `Evidence/<other-alias>/_discovery/` folder.** Reading other aliases' discovery sidecars (e.g. to merge already-confirmed candidates into the shared boundary) is allowed and expected; writing into them is forbidden.
+
+## 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** ("Northwind" → "Northwind 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.