kushi-agents 3.4.2 → 3.13.0

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

@@ -1,14 +1,23 @@
 ---
 name: "pull-crm"
-version: "2.0.0"
-description: "Pull CRM (Dataverse) evidence (snapshot: engagement record fields; stream: notes/activities/status changes). Conditional az login per az-auth-conditional rule."
+version: "2.3.1"
+description: "Pull CRM (Dataverse) evidence (snapshot: engagement record VERBATIM long-text fields + ALL annotations with formatted values; stream: notes/activities/status changes). Per-record explicit $select + formatted-value annotations. FDE entity sets use crm-field-manifest.md. v2.3.0: exhaustive 4-step resolution sequence (title → account[s] → wide-text → recent-slice → ask). Anti-patterns codified: no statecode filter, new_companyname is NOT a field, never disable from one shallow probe."
 ---
 
 # Skill: pull-crm
 
+
+> **v3.7.6 contracts** — This skill operates under four HARD-rule doctrines:
+> - `verbatim-by-default.instructions.md` — full bodies/notetext/fields by default; no preview-grade pulls accepted.
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md` immediately.
+> - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale `no-match` / `not yet` notes referencing the prior unresolved state must be rewritten in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/YYYY-MM-DD-HHMM_refresh.md`.
+
+> **Canonical evidence layout** (HARD, kushi v3.12.1+): all artifacts produced by this skill MUST be written under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` — sibling folders under `<project>/` (e.g. `<project>/<source>-context/`, `<project>/<source>/`, `<project>/_Weekly Summaries/`) are FORBIDDEN. See `evidence-layout-canonical.instructions.md`.
+
 Pulls **crm** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
-- **snapshot/** — engagement record with every field the API returns (owner, status, account, dates, custom fields)
+- **snapshot/** — engagement record with EVERY field the API returns (owner, status, account, dates, custom fields), all long-text fields VERBATIM, plus every related annotation (note) verbatim
 - **stream/** — notes added, activities logged, field-level changes (old → new + actor + timestamp)
 
 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`.
@@ -24,19 +33,159 @@ WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thor
 ## Resolution hints (pinned in mutable)
 
 - `crm.recordId` — pinned engagement record GUID (FE-NNNNN-style)
-- `crm.entitySetName` — Dataverse entity set name (e.g. `msdyn_engagements`)
+- `crm.entitySetName` — Dataverse entity set name (e.g. `msfre_engagementsubmissions`, `msdyn_engagements`)
+- `crm.fieldMap` — resolved logical-name map per entity (filled by discovery probe; cached)
+
+## Hard prerequisites (REQUIRED — see `scope-boundaries.instructions.md` Rule 3)
+
+This skill is **HARD-fail** without both:
+
+1. Global config: `<engagement-root>/.project-evidence/crm/config.yml` exists with non-placeholder `environmentUrl`.
+2. Per-project boundary: `<engagement-root>/<project>/integrations.yml#boundaries.crm.record_ids` OR `boundaries.crm.request_ids` is non-empty.
+
+If either is missing, refuse with the exact message:
+
+```
+crm-config-missing — drop a filled config.yml at
+<engagement-root>/.project-evidence/crm/config.yml. See template at
+plugin/templates/init/crm-config.template.yml. Then add boundaries.crm.record_ids
+(or request_ids) to <project>/integrations.yml.
+```
+
+**No "narrate from email" fallback exists in v3.7.0+.** CRM evidence comes from CRM
+or it is absent — Coverage Notes will say so explicitly. Synthesis across sources
+happens at consolidation, not at pull.
+
+## Field manifest dispatch
+
+Before issuing the snapshot fetch, inspect `crm.entitySetName`:
+
+- If it starts with `msfre_` (FDE engagement-submission family) → use `reference-packs/fde/crm-field-manifest.md` for the explicit `$select` list, the annotation `$expand`, and the snapshot file shape. The manifest IS the contract.
+- For any other entity → still use the per-record loop below, but discover the column list from EntityDefinitions metadata once (cache to `crm.fieldMap`) and `$select` every column found (no relying on default projection).
+
+## Dataverse retrieval doctrine (REQUIRED — applies to every REST call below)
+
+Borrowed from production CRM-sync hardening. Every Dataverse REST call in this skill MUST follow these rules, or option-set / lookup fields will render as raw GUIDs and integer codes instead of human labels:
+
+### Rule 1 — Always request formatted values
+
+```powershell
+$headers = @{
+  Authorization = "Bearer $token"
+  Accept = 'application/json'
+  'OData-Version' = '4.0'
+  'OData-MaxVersion' = '4.0'
+  Prefer = 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"'
+}
+```
+
+This makes Dataverse return paired properties like `statuscode@OData.Community.Display.V1.FormattedValue` and `_ownerid_value@OData.Community.Display.V1.FormattedValue` alongside the raw codes/GUIDs.
+
+### Rule 2 — Use `PSObject.Properties[...]` accessor for `@`-named annotation properties
+
+Dotted access fails for property names containing `@`. Always use the indexer:
+
+```powershell
+$ownerDisplay = $row.PSObject.Properties['_ownerid_value@OData.Community.Display.V1.FormattedValue'].Value
+$status       = $row.PSObject.Properties['statuscode@OData.Community.Display.V1.FormattedValue'].Value
+```
+
+### Rule 3 — Inspect one live row before widening
+
+If field names are uncertain (new entity, schema drift, 400 error), fetch a single row first and dump property names. Do NOT keep iterating filters blindly:
+
+```powershell
+$url = "$baseUrl/api/data/$api/${entitySet}?`$orderby=modifiedon desc&`$top=1"
+$row = (Invoke-RestMethod -Uri $url -Headers $headers -Method Get).value | Select-Object -First 1
+$row.PSObject.Properties.Name | Sort-Object
+```
+
+Cache the discovered shape to `crm.fieldMap`.
+
+### Rule 4 — Add one field/filter at a time
+
+If a query returns `400 Could not find a property named ...`, REVERT to the last known-good query shape, then add ONE field/filter and rerun. Do not widen scope past the failure.
+
+### Rule 5 — Always include `statecode` and `statuscode` in candidate searches
 
-## Snapshot pass
+Otherwise inactive/closed records become invisible during ranking.
 
-Write `snapshot/<record-id>.md` per CRM record with EVERY field the API returns (don't editorialize). Last fetched timestamp at top.
+### Rule 6 — Prefer formatted values in rendered output
 
-Write to: `<engagement-root>/<project>/Evidence/<alias>/crm/snapshot/<entity>.md`
+Snapshot files render the formatted display value in the main body. Keep raw GUID / integer code only in `## All other fields` for diagnostic value.
 
-Use template: `templates/snapshot/crm-<kind>.template.md`
+## Resolution order (when `crm.recordId` is unset)
+
+If `boundaries.crm.record_ids` is empty AND a project token is provided, resolve in this order. Persist whichever step resolves to `m365Mutable.knownSections.<project>.crm.recordId` immediately.
+
+**CRITICAL anti-patterns — read before writing any filter:**
+
+- **NEVER add a `statecode` filter** to any candidate-resolution query. The default CRM list view may only show active records, hiding inactive / withdrawn / closed / deferred records. Always query all states and report `statecode`+`statuscode` formatted values per Rule 5 + Rule 6.
+- **`new_companyname` is NOT a valid attribute on `new_frontierengineeringtriage`.** The customer is a navigation lookup (`_new_customer_value`). Filtering on `new_companyname` will always return 0 and the 400 will look like an auth/scope failure. Always resolve customer via the `accounts` entity then `_new_customer_value eq <accountid>`.
+- **Never give up after one shallow probe.** This 4-step sequence is exhaustive — only step 4's user-ask is a stop. If WorkIQ is the only path tried, that is a defect; the Dataverse REST sequence below MUST be attempted before declaring no-match. See `plugin/instructions/crm-bootstrap-discovery.instructions.md`.
+
+1. **Title-first**: filter the entity by its title-equivalent field (FDE: `new_title` or `msfre_name`) `contains '<token>'`, ordered by `modifiedon desc`, top 20.
+2. **Account fallback**: if step 1 returns 0, resolve customer in `accounts` by `name contains '<token>'`. For EACH matching account, query the engagement entity by `_<customerLookup>_value eq <accountId>` (not just the first match — token like "Deere" can resolve to multiple accounts e.g. `JOHN DEERE`, `DEERE COMPANY`, `JOHN DEERE COASTRUCTION`).
+3. **Wide text fallback**: if both above fail, retry contains on the long-text fields most likely to mention the customer by name: `new_businessscenariotechnicalblocker`, `new_engagedwith`, `new_engagementobjectives` (FDE entity). One field per query; combine results.
+4. **Recent-slice client-rank**: if all above fail, pull the most recent 200 records (`$select` minimal: id, title, requestId, customer-formatted, statecode-formatted, statuscode-formatted, modifiedon) and rank client-side by needle match against title / request id / customer display.
+5. **Ask user**: present top 5 candidates (id, title, customer display, status, modifiedon). Never auto-pick on multi-match.
+
+After steps 1–4 all return 0, write the candidate-search trail (queries attempted + result counts) to `Evidence/<alias>/refresh-reports/<ts>_refresh.md#crm-resolution-attempts` so the next refresh has audit. Do NOT silently set `boundaries.crm.disabled: true` — only step 5 (user declines or confirms none) writes `disabled` with `reason: 'no-match-after-full-4-step-resolution-<date>'`.
+
+
+
+For EACH record id in `boundaries.crm.record_ids`:
+
+### Step A — Resolve field map (once per project, cached)
+
+If `m365Mutable.knownSections.<project>.crm.fieldMap` is empty, probe:
+
+```http
+GET /api/data/v9.2/EntityDefinitions(LogicalName='<entity-logical-name>')/Attributes?$select=LogicalName,DisplayName,AttributeType
+```
+
+Persist the resolved attribute list to `crm.fieldMap`. For FDE entities, cross-check against `reference-packs/fde/crm-field-manifest.md`.
+
+### Step B — Fetch the record with explicit $select + annotation $expand
+
+Headers per **Dataverse retrieval doctrine Rule 1** (formatted values).
+
+```http
+GET /api/data/v9.2/<entitySet>(<recordId>)?$select=<every-attribute-from-fieldMap>&$expand=Annotations($select=annotationid,subject,notetext,createdon,_createdby_value,filename,mimetype)
+Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
+```
+
+WorkIQ-first equivalent (when host fallback to REST isn't available):
+
+```
+workiq ask -q "Fetch the FULL Dataverse record from entity set <entitySet> with id <recordId>. Return EVERY field VERBATIM (do not summarize, do not truncate any long-text/Memo field). Then fetch ALL Annotations (notes) related to this record (objectid eq <recordId>). For each annotation return: subject, full notetext verbatim, createdon, createdby name. Output as JSON or markdown table — but do not paraphrase any long-text content."
+```
+
+If the response is summarized (heuristics: any long-text field appears trimmed, an annotation count exceeds the rendered count, phrases like `"and N more notes"` appear): **retry once** with the wording `Return raw field values verbatim, every annotation in full. Do not summarize, do not paginate, do not omit.`
+
+### Step C — Write snapshot file (one per record)
+
+Write `snapshot/<entitySet>/<record-id>.md` with:
+
+- File header (record id, MSX opp, status, owner, last-fetched timestamp).
+- `## Source Basis` — tool used, boundary applied, fieldMap source, annotation count.
+- `## AI Narrative Summary` (3+ paragraphs — REQUIRED FIRST per `evidence-thoroughness.instructions.md`).
+- `## Engagement context` — every long-text field as a verbatim blockquote (see crm-field-manifest.md for the FDE shape).
+- `## All other fields` — 2-column table; empty fields shown as `_(empty)_` so absence is visible.
+- `## Notes (verbatim)` — one `### Note — <subject> (<createdon> by <createdby>)` block per annotation, full `notetext` as a verbatim blockquote, oldest first. NO truncation regardless of length.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/crm/snapshot/<entitySet>/<record-id>.md`
+
+Use template: `templates/snapshot/crm-<kind>.template.md` (FDE entities: shape comes from `reference-packs/fde/crm-field-manifest.md`).
+
+### Step D — Failure handling
+
+- Per-record fetch failed → write the snapshot file with a `❌ record-fetch-failed` marker + `next_step: ask user to paste record fields` and continue to next record.
+- Annotation fetch failed but record fetched → write the record fields, mark `## Notes (verbatim)` with `❌ annotation-fetch-failed — N annotations expected` and continue.
 
 ## Stream pass
 
-Per `evidence-thoroughness.instructions.md`: every annotation verbatim with author + timestamp; every field-level change with old → new + actor + timestamp. Bucketed by ISO week into `stream/<record-id>/<YYYY-MM-DD>_crm-stream.md`.
+Per `evidence-thoroughness.instructions.md`: stream files (per-week) start with an **AI Narrative Summary** covering what changed and what it means, then every annotation verbatim with author + timestamp + every field-level change with old → new + actor + timestamp. Bucketed by ISO week into `stream/<record-id>/<YYYY-MM-DD>_crm-stream.md`.
 
 Write to: `<engagement-root>/<project>/Evidence/<alias>/crm/stream/<YYYY-MM-DD>_crm-stream.md` (date = Monday of the ISO week the events fall in).
 
@@ -46,8 +195,8 @@ If a week file already exists, MERGE (dedupe by event ID, append new events, kee
 
 ## Tools (in order)
 
-1. **WorkIQ** — ````$WorkIQQuery`````
-2. **Host fallback** — Dataverse REST Web API via `az account get-access-token` against the configured tenant (read connection from `<engagement-root>/.project-evidence/crm/config.yml`)
+1. **Dataverse REST Web API** (preferred for snapshot — gives explicit `$select` + `$expand` control) via `az account get-access-token` against the configured tenant. Read connection from `<engagement-root>/.project-evidence/crm/config.yml`.
+2. **WorkIQ** — only when REST is unavailable; phrase queries to demand verbatim long-text + every annotation (see Step B template above). WorkIQ summarizes by default, so use this path only as fallback.
 3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
 4. **Ask user** — paste verbatim source content if all above fail.
 
@@ -57,19 +206,23 @@ Document which path succeeded under `## Source Basis` in each output file.
 
 If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`:
 
-- `crm.recordId` — pinned engagement record GUID (FE-NNNNN-style)
-- `crm.entitySetName` — Dataverse entity set name (e.g. `msdyn_engagements`)
+- `crm.recordId` — pinned engagement record GUID
+- `crm.entitySetName` — Dataverse entity set name
+- `crm.fieldMap` — resolved attribute list (from EntityDefinitions probe)
 
 ## Update run-log
 
 After successful pass:
 - `sources.crm.last_pulled = now`
 - `sources.crm.watermark = now` (stream only; snapshot has no watermark)
-- `sources.crm.item_count = <N>`
+- `sources.crm.records_fetched = <N>`
+- `sources.crm.annotations_fetched = <N>` — total notes captured across all records
+- `sources.crm.records_failed = <N>`
 - For each week touched, add to `weekly_files` index.
 
 ## Stop conditions
 
+- Hard-prereq missing → refuse (see Hard prerequisites above).
 - 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.
+- All paths failed for a given record → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.

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

@@ -1,17 +1,25 @@
 ---
 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."
+version: "2.3.1"
+description: "Pull Email evidence (stream only — emails ARE events). WorkIQ-ONLY per workiq-only.instructions.md (m365_get_email / m365_search_emails / Graph REST FORBIDDEN — near-100% failure in this workspace). Folder-scoped fast path → root-scope WorkIQ fallback. Enumerate-then-fetch via two WorkIQ calls per project. Mutable folder-hint upsert during run. Throttle-aware. User-paste is a first-class fallback, NOT Graph."
 ---
 
 # Skill: pull-email
 
+
+> **v3.7.6 + v3.11.0 contracts** — This skill operates under five HARD-rule doctrines:
+> - `verbatim-by-default.instructions.md` — full bodies/notetext/fields by default; no preview-grade pulls accepted.
+> - **`workiq-only.instructions.md` (v3.11.0)** — email list + body fetch go through WorkIQ ONLY. `m365_get_email`, `m365_search_emails`, `m365_list_emails`, and Graph REST URLs are FORBIDDEN as fallbacks (they fail nearly every call in this workspace). The canonical WorkIQ prompts (folder-scoped enumerate, root-scope fallback, per-message body fetch) are codified in that instruction — do not re-discover them.
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md` immediately.
+> - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale `no-match` / `not yet` notes referencing the prior unresolved state must be rewritten in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/YYYY-MM-DD-HHMM_refresh.md`.
+> - `evidence-layout-canonical.instructions.md` (kushi v3.12.1+) — ALL email artifacts MUST be written under `<project>/Evidence/<alias>/email/{snapshot,stream,_index,_legacy_*}/`. Writing to `<project>/email-context/`, `<project>/email/`, `<project>/_Weekly Summaries/`, or any other sibling path under `<project>/` is a DEFECT.
 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`.
+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
 
@@ -26,50 +34,159 @@ WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thor
 - `emailContext.folder` — full path of the project's email folder
 - `emailContext.folderId` — folder ID for direct lookup
 
-## Snapshot pass
+## Boundaries (REQUIRED — see `scope-boundaries.instructions.md`)
 
-_(no snapshot for email — emails are inherently event-stream)_
+This skill REFUSES to query unless `<engagement-root>/<project>/integrations.yml#boundaries.email` is satisfied:
+
+- `boundaries.email.mailboxes` — REQUIRED, non-empty. Empty = source disabled.
+- `boundaries.email.sender_domains` — optional narrowing.
+- `boundaries.email.subject_keywords` — optional narrowing.
+- `boundaries.date_window_days` — defaults to 30 if absent.
+
+Every WorkIQ ask, every `m365_search_emails` / `m365_list_emails` call, every Graph fallback MUST be scoped to those mailboxes + (if set) sender_domains + subject_keywords. Empty hits inside the boundary → write Coverage Notes citing the limiting key; do NOT widen the scope.
+
+Refusal message when boundary is missing:
+
+```
+email-boundary-missing — add boundaries.email.mailboxes to
+<engagement-root>/<project>/integrations.yml. See doctrine in
+plugin/instructions/scope-boundaries.instructions.md.
+```
+
+## Retrieval order (deterministic — folder fast path → root fallback)
+
+Borrowed from production email-context hardening. WorkIQ is more reliable when the query is folder-scoped to one known project folder than when it scans the whole mailbox. Order:
+
+### Order 1 — Exact project-folder fast path (when hint exists)
+
+If `m365Mutable.knownSections.<project>.emailContext.folder` (or `.folderId`) is set with `confidence >= medium`:
+
+```
+workiq ask -q "Search my Outlook mailbox for emails from <window-start> onward in folder(s) '<projectFolder>' (including all subfolders) related to <project aliases>. Return: sent datetime, subject, sender, recipients, folder path, message link, and a short relevance reason. Do not return NO_RESULTS unless the folder truly has no messages in that range."
+```
+
+If this path returns 0 results AND the same query has succeeded recently in this project's run-log, retry the exact-folder query ONCE before escalating. WorkIQ has been observed to return spurious empty hits on first call.
+
+### Order 2 — Root-scope fallback
+
+Only if Order 1 returns insufficient/empty results after the retry, OR the project has no folder hint, OR multiple plausible hints exist:
+
+```
+workiq ask -q "Search my Outlook mailbox for emails from <window-start> onward in folder(s) <boundaries.email.mailboxes joined> (including all subfolders) related to <project aliases>. Return: sent datetime, subject, sender, recipients, folder path, message link, and a short relevance reason."
+```
+
+### Throttle handling (HARD stop in same run)
+
+If WorkIQ returns `tooManyRequests`, `More than 3 retries performed`, or `We're experiencing high demand`:
+
+- Mark `sources.email.coverage_state = throttled-tooManyRequests` in run-log.
+- Write what enumeration HAS been collected so far to the message-index file with a `⚠️ throttled — partial enumeration` banner.
+- Stop email pulls for this run. Do NOT issue broader mailbox queries.
+- Continue with non-email sources.
+
+### Degraded list-only state
+
+If Step A enumeration succeeds but Step B body fetch fails repeatedly (host + WorkIQ both returning empty / `body-unavailable` for >50% of messages):
+
+- Set `sources.email.coverage_state = degraded-list-only`.
+- Keep the message index with sent date, subject, sender, recipients, folder path, message link as evidence — these ARE usable signals at list level.
+- Mark each affected message with `❌ body-unavailable` in the weekly stream file.
+- Do NOT discard list-level evidence. Do NOT loop on broad fallback queries trying to rescue bodies.
+
+## Two-pass pull (REQUIRED — no single-call summarization)
 
-Write to: `<engagement-root>/<project>/Evidence/<alias>/email/snapshot/<entity>.md`
+Same anti-summarization pattern as `pull-onenote` v2.2.0. WorkIQ summarizes by default — relying on a single "give me all emails this week" call returns a curated subset, not the full set. Doctrine: **enumerate the message list first, then fetch each message body individually.**
 
-Use template: `templates/snapshot/email-<kind>.template.md`
+### Step A — Enumerate the message list
 
-## Stream pass
+For each `boundaries.email.mailboxes[i]` × the date window (and optional sender_domains / subject_keywords):
 
-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.
+```
+workiq ask -q "List EVERY email in mailbox <mb> received between <start> and <end> [filtered to senders @<domain>] [containing subject keyword <kw>]. Return one row per message: messageId, internetMessageId, conversationId, sentDate, fromAddress, toAddresses, ccAddresses, subject, hasAttachments, sizeKB. Do NOT summarize, do NOT omit, do NOT group by thread yet, do NOT add commentary. Flat table only."
+```
+
+If the response is summarized (heuristics: `"and N more"`, `"sample"`, row count noticeably less than expected, message bodies included instead of just the index): **retry once** with `Return as a flat table with no commentary, no grouping, no truncation. Message count must equal the actual count in the date window.`
+
+Persist the enumerated list to `Evidence/<alias>/email/_index/<YYYY-MM-DD>_message-index.md` (date = Monday of the ISO week). This makes the run idempotent + resumable.
+
+### Step B — Per-message body fetch (one WorkIQ call per message)
+
+For each message in the index, ONE WorkIQ call (per `workiq-only.instructions.md`):
+
+```
+workiq ask -q "Get the FULL body of email with messageId <id> (mailbox <mb>). Return: full text body verbatim (no summarization, no truncation), all headers (from, to, cc, bcc, sentDate, subject, conversationId, internetMessageId, references, in-reply-to), attachment list (filename + size + mimetype, do NOT download binary), and any inline images as alt text or skip with marker."
+```
+
+**FORBIDDEN** (per workiq-only): `m365_get_email`, `m365_search_emails`, `m365_list_emails`, Graph REST. Do NOT add them as fallbacks. If WorkIQ body fetch fails, use the doubled-strict retry then user-paste — NEVER fall through to a host m365_* call.
+
+If body comes back < 200 chars or includes phrases like `"unable to retrieve"`, `"body unavailable"`, `"truncated"`: doubled-strict retry once with `Return the raw email body, no summary, no truncation. If you cannot return the full body, say "body-unavailable" exactly and nothing else.` On second failure, record that message as `❌ body-unavailable` in the weekly stream file + continue (or prompt user to paste — first-class evidence path per workiq-only).
+
+### Step C — Group by conversationId into threads
+
+After all bodies fetched, group messages by `conversationId`. For each thread:
+
+- Sort by `sentDate` ascending.
+- Write a `## Thread: <subject>` block in the weekly stream file with:
+  - **AI Narrative Summary (REQUIRED FIRST, 3+ paragraphs)** — conversation arc, who's pushing what, decisions, asks, tone (per `evidence-thoroughness.instructions.md`).
+  - One `### Message <N> — <fromAddress> (<sentDate>)` block per message with: full headers (to/cc/subject), full body verbatim as a blockquote, attachment list.
+- Append the thread block to the weekly file (`<YYYY-MM-DD>_email-stream.md`, date = Monday of the ISO week).
+
+## Snapshot pass
+
+_(no snapshot for email — emails are inherently event-stream)_
+
+## Stream pass output
 
 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).
 
+Write the message index to: `<engagement-root>/<project>/Evidence/<alias>/email/_index/<YYYY-MM-DD>_message-index.md`.
+
 Use template: `templates/weekly/email-summary.template.md`
 
-If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+If a week file already exists, MERGE (dedupe by `internetMessageId`, append new threads, keep existing).
+
+## Tools (WorkIQ ONLY — per `workiq-only.instructions.md`)
 
-## Tools (in order)
+1. **WorkIQ (`workiq ask`)** — the ONLY allowed path for both enumeration (Step A) and per-message body fetch (Step B). Always include the boundary keys + the verbatim/no-summary phrasing. Use the canonical prompts codified in `plugin/instructions/workiq-only.instructions.md` (Email Bodies section) — do NOT re-derive them.
+2. **Ask user (paste verbatim)** — first-class fallback when WorkIQ doubled-strict retry fails or returns `body-unavailable`. NOT a degradation; coverage.md labels it `Source: User paste on <ISO>`.
 
-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.
+**FORBIDDEN** for this skill (per workiq-only.instructions.md): `m365_get_email`, `m365_search_emails`, `m365_list_emails`, `m365_list_mail_folders`, `m365_search_mail`, Graph REST `https://graph.microsoft.com/v1.0/me/messages*`, Graph REST `https://graph.microsoft.com/v1.0/me/mailFolders*`. These tools have a near-100% failure rate in this workspace. Calling them is a DEFECT; coverage.md must NOT show them in the attempt trail.
 
-Document which path succeeded under `## Source Basis` in each output file.
+Document the WorkIQ request-id + the exact prompt + which boundary was applied under `## Source Basis` in each output file (per workiq-only coverage.md requirements).
 
 ## Mutable hints to upsert (during the run, not at the end)
 
-If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`:
+If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`. Mandatory in EVERY run mode (bootstrap, refresh, retry):
 
-- `emailContext.folder` — full path of the project's email folder
+- `emailContext.folder` — full path of the project's email folder (upsert only when `confidence >= medium`)
 - `emailContext.folderId` — folder ID for direct lookup
+- `emailContext.lastFastPathUsed` — boolean; whether Order 1 succeeded this run
+
+Upsert only confident folder mappings. Do not write low-confidence guesses — that pollutes the hint cache and degrades future fast-path success.
 
 ## 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>`
+- `sources.email.watermark = now`
+- `sources.email.coverage_state = ok | degraded-list-only | throttled-tooManyRequests | unavailable`
+- `sources.email.retrieval_path = fast-folder | fast-folder-retry | root-fallback`
+- `sources.email.messages_enumerated = <N>` — total messages discovered in scope
+- `sources.email.messages_fetched = <N>` — total messages with full body captured
+- `sources.email.messages_failed = <N>` — `body-unavailable` count
+- `sources.email.threads = <N>` — number of conversations grouped
 - For each week touched, add to `weekly_files` index.
 
+## Depth bar (per `evidence-thoroughness.instructions.md`)
+
+The pre-Step-C anti-summary doctrine + the Step-C AI Narrative Summary per thread together produce the depth users expect. Empty thread bodies are a defect — if Step B couldn't fetch a body, the message gets a `❌ body-unavailable` marker, NOT a paraphrase from the index row.
+
+**Completeness bar:** `messages_enumerated` should equal `messages_fetched + messages_failed`. Drift surfaces in run-log; consolidate skill renders it as a Coverage Note.
+
 ## Stop conditions
 
+- Boundary missing → refuse (see Boundaries above).
 - 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.
+- Enumeration step (Step A) failed → write `_index/<date>_message-index.md` with failure marker, log to run-log errors, do NOT proceed to per-message loop.
+- Per-message fetch failed → record marker, continue.
+- All paths failed → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.