kushi-agents 5.0.0 → 5.0.2

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

@@ -1,7 +1,7 @@
 ---
 name: "pull-crm"
-version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull CRM (Dataverse) evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_crm-csc.md. One block per record modified that week, upserted in _index/entities.yml. Dataverse REST retrieval doctrine (Rules 1-6) UNCHANGED — only output shape changes. Record fields → CSC sections (owner→Participants, long-text→Topics, statecode→Decisions, etc.). No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
+version: "3.0.1"
+description: "USE WHEN refresh-project / bootstrap-project dispatches CRM source OR the user says \"pull CRM for <X>\" AND the project has integrations.yml#boundaries.crm.entity_uri or hint set. DO NOT USE for non-kushi Dataverse queries. Capability: pulls CRM (Dataverse) evidence as CSC blocks written to weekly/YYYY-MM-DD_crm-csc.md, one block per record/contact touched, upserted in _index/entities.yml. WorkIQ-only; CRM-internal-vs-confirmed rule applies."
 ---
 
 # Skill: pull-crm
@@ -21,6 +21,14 @@ description: "v3.0.0 (kushi v4.9.0): Pull CRM (Dataverse) evidence as Comprehens
 > - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
 > - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
 
+## Gotchas
+
+- **CRM internal-vs-confirmed rule** — never assert a field as "confirmed by the customer" unless it appears in a customer-authored note / email / meeting transcript. Internal-only fields render as `(internal Dataverse note)`. See `crm-internal-vs-confirmed.instructions.md`.
+- **Shallow probe can falsely declare `crm.disabled: true`** — empty Dataverse probe responses are NOT proof the source is disabled. Re-test via WorkIQ with a known account name before flagging disabled.
+- **Record URLs include environment ID** — `crm://entity=account&id=<guid>&env=<env-id>`. Different environments mean different entities; never collapse cross-env records into one anchor.
+- **Opportunity stage changes are stream events, not snapshot** — each stage transition writes a CSC bullet under "Dates & Numbers" with the timestamp; the snapshot stage is the latest.
+- **Bulk-enumerate phrasings punt to admin Graph** — `"list all accounts in Dataverse"` returns nothing useful. Always scope to a hint (account name, opportunity number) per `crm-bootstrap-discovery.instructions.md`.
+
 ## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
 
 Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
@@ -70,8 +78,8 @@ Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructi
   - Open questions in notes → **Open Questions**
   - Customer-stated requirements → **Customer Asks**
   - Related records → **Artifacts/Links**
-- Entity id: `crm://entity=<logicalName>/id=<guid>`.
-
+- Entity id: `crm://entity=<logicalName>/id=<guid>`.
+
 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), all long-text fields VERBATIM, plus every related annotation (note) verbatim
@@ -133,137 +141,29 @@ Before issuing the snapshot fetch, inspect `crm.entitySetName`:
 
 ## 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
-
-Otherwise inactive/closed records become invisible during ranking.
-
-### Rule 6 — Prefer formatted values in rendered output
-
-Snapshot files render the formatted display value in the main body. Keep raw GUID / integer code only in `## All other fields` for diagnostic value.
+> **Load `references/dataverse-doctrine.md`** for the 6 retrieval rules (formatted-value headers, PSObject indexer, one-row inspect, one-field-at-a-time, statecode inclusion, formatted-value rendering), the 4-step resolution sequence when `crm.recordId` is unset, anti-patterns, and the per-record Step A/B/D fetch procedure. Load when issuing any Dataverse REST call or resolving an unknown record ID.
 
 ## 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>'`.
-
+> **Load `references/dataverse-doctrine.md`** § "Resolution order" for the full 5-step title-first → account → wide-text → recent-slice → ask-user resolution sequence, anti-patterns (no statecode filter, no `new_companyname`), and audit trail rules.
 
 
 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`.
+If `m365Mutable.knownSections.<project>.crm.fieldMap` is empty, probe EntityDefinitions. Persist 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)
-
-> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. The Dataverse REST fetch (Step A + Step B) still runs; only the file write changes. Kept for historical reference; not executed.
-
-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.
+Headers per Dataverse retrieval doctrine Rule 1 (formatted values). Use `$expand=Annotations`. WorkIQ fallback available when REST host is unavailable.
 
-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`).
+> **Load `references/dataverse-doctrine.md`** § "Per-record fetch" for the full REST URL templates, WorkIQ-equivalent prompt, summarization-detection heuristics, and retry wording.
 
 ### 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
-
-> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. Kept for historical reference; not executed.
-
-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).
-
-Use template: `templates/weekly/crm-summary.template.md`
-
-If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+- Per-record fetch failed → write evidence file with `❌ record-fetch-failed` marker + `next_step: ask user to paste record fields`, continue.
+- Annotation fetch failed but record fetched → write record fields, mark `❌ annotation-fetch-failed`, continue.
 
 ## Tools (in order)
 
@@ -298,11 +198,11 @@ After successful pass:
 - Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
 - Multiple plausible candidates → ask user to pick, persist answer.
 - All paths failed for a given record → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.
-
-## References (v4.4.7)
-
-- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
-- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
 
 
 ## Issue Recovery
@@ -317,10 +217,24 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
 
 ## Changelog
 
+- **v3.0.1 (kushi v5.0.1, 2026-05-26)**: agentskills.io spec-compliance pass. Extracted Dataverse
+  retrieval doctrine (Rules 1–6, 4-step resolution, Step A/B/D procedure) →
+  `references/dataverse-doctrine.md`; legacy snapshot/stream file format →
+  `references/legacy-shape.md`. SKILL.md trimmed from 343 to ~210 lines. Behaviour unchanged;
+  load-on-trigger pointers added.
 - **v3.0.0 (kushi v4.9.0, 2026-05-26)**: BREAKING. Output is now a single weekly CSC file per ISO week
   (`weekly/<YYYY-MM-DD>_crm-csc.md`) + per-contributor `_index/entities.yml`. snapshot/`<entitySet>`/
   + stream/ writes removed. Dataverse REST retrieval doctrine (Rules 1–6) and 4-step resolution
   UNCHANGED — only output shape changes. Record fields mapped to CSC sections
   (Owner→Participants, long-text→Topics, statecode→Decisions, etc.). AI Narrative Summary requirement
   removed. Legacy snapshot/+stream/ folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-crm`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/pull-crm/references/dataverse-doctrine.md

@@ -0,0 +1,108 @@
+# references/dataverse-doctrine.md (pull-crm)
+
+> **Load this file when** issuing Dataverse REST calls — i.e., when you need the 6 retrieval rules (formatted values, PSObject indexer, one-row inspect, one-field-at-a-time, statecode inclusion, formatted-value preference) and the 4-step resolution sequence for unknown record IDs.
+
+## Dataverse retrieval doctrine (REQUIRED — applies to every REST call)
+
+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
+
+Otherwise inactive/closed records become invisible during ranking.
+
+### Rule 6 — Prefer formatted values in rendered output
+
+Snapshot files render the formatted display value in the main body. Keep raw GUID / integer code only in `## All other fields` for diagnostic value.
+
+## 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>'`.
+
+## Per-record fetch (Step A–B)
+
+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 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.

package/plugin/skills/pull-crm/references/legacy-shape.md

@@ -0,0 +1,28 @@
+# references/legacy-shape.md (pull-crm)
+
+> **Load this file when** maintaining or reading pre-v4.9.0 `snapshot/` or `stream/` CRM evidence files — i.e., when legacy evidence exists on disk and you need to understand the prior snapshot format (AI Narrative Summary, per-record file layout, annotation rendering) or stream format.
+
+## Step C — Write snapshot file (LEGACY, pre-v4.9.0)
+
+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`).
+
+## Stream pass (LEGACY, pre-v4.9.0)
+
+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).
+
+Use template: `templates/weekly/crm-summary.template.md`
+
+If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).

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

@@ -1,7 +1,7 @@
 ---
 name: "pull-email"
-version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull Email evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_email-csc.md. One block per email thread touched that week, upserted in _index/entities.yml. WorkIQ-ONLY via CSC canonical prompts. No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
+version: "3.0.1"
+description: "USE WHEN refresh-project / bootstrap-project dispatches Email source OR the user says \"pull email for <X>\" AND the project has integrations.yml#boundaries.email folder/keyword set. DO NOT USE for general inbox triage. Capability: pulls Email evidence as CSC blocks written to weekly/YYYY-MM-DD_email-csc.md, one block per conversation touched, upserted in _index/entities.yml. WorkIQ-only — Graph m365_* is FORBIDDEN as fallback."
 ---
 
 # Skill: pull-email
@@ -21,6 +21,14 @@ description: "v3.0.0 (kushi v4.9.0): Pull Email evidence as Comprehensive Struct
 > - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
 > - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
 
+## Gotchas
+
+- **WorkIQ-only — `m365_get_email` / `m365_search_emails` / Graph REST are FORBIDDEN as fallbacks.** Per `workiq-only.instructions.md`. If WorkIQ returns `throttled` or `degraded`, log it and retry on the next refresh — never fall back to Graph.
+- **Conversation IDs collapse threads — message IDs do not** — the canonical email entity id is `email://conversation_id=<id>`. One CSC block per conversation per week; individual messages roll up into the block''s "Who Said What" section.
+- **Forbidden bulk-enumerate phrasings** — bulk "list … mail folders", folder-ID lookups, and structured-field mail-folder searches all punt to Graph. Use the customer-hint discovery sweep per `email-bootstrap-discovery.instructions.md` (which holds the canonical forbidden list).
+- **Shared mailboxes need explicit boundary entries** — emails from a shared mailbox the contributor has delegated access to do NOT appear in `me/messages`. Add `boundaries.email.shared_mailboxes: [...]` and dispatch one WorkIQ call per shared mailbox.
+- **HTML body bodies leak tracking pixels into citations** — the CSC writer strips `<img>` tags and inline base64 before persisting; if a weekly file shows `data:image/...` in a citation, the stripper regressed — re-pull that conversation with the current writer.
+
 ## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
 
 Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
@@ -108,81 +116,13 @@ 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.
+> **Load `references/retrieval-order.md`** for the full folder-scoped fast path WorkIQ prompt, root-scope fallback, throttle-handling rules (HARD stop), and degraded list-only state logic. Load when dispatching the email enumeration query.
 
 ## Two-pass pull (REQUIRED — no single-call summarization)
 
-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.**
-
-### Step A — Enumerate the message list
-
-For each `boundaries.email.mailboxes[i]` × the date window (and optional sender_domains / subject_keywords):
+> **Load `references/two-pass-pull.md`** for the Step A enumeration prompt, Step B per-message body fetch prompt with doubled-strict retry, summarization-detection heuristics, and Step C thread-grouping procedure. Load when executing the pull after retrieval order is determined.
 
-```
-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).
+Doctrine summary: **enumerate the message list first (Step A), then fetch each message body individually (Step B), then group by conversationId (Step C).** Single-call summarization is a defect.
 
 ## Snapshot pass
 
@@ -249,11 +189,11 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
 - 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.
-
-## References (v4.4.7)
-
-- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
-- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
 
 
 ## Issue Recovery
@@ -262,9 +202,23 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
 
 ## Changelog
 
+- **v3.0.1 (kushi v5.0.1, 2026-05-26)**: agentskills.io spec-compliance pass. Extracted retrieval
+  order (folder fast path, root fallback, throttle handling, degraded state) →
+  `references/retrieval-order.md`; two-pass pull procedure (Steps A/B/C prompts, retry wording,
+  grouping) → `references/two-pass-pull.md`. SKILL.md trimmed from 287 to ~200 lines. Behaviour
+  unchanged; load-on-trigger pointers added.
 - **v3.0.0 (kushi v4.9.0, 2026-05-26)**: BREAKING. Output is now a single weekly CSC file per ISO week
   (`weekly/<YYYY-MM-DD>_email-csc.md`) + per-contributor `_index/entities.yml`. snapshot/ and stream/
   writes removed. WorkIQ prompts switched to CSC canonical prompts. AI Narrative Summary requirement
   removed (CSC bulleted sections carry the load). Verbatim body-fetch loop removed.
   Legacy snapshot/+stream/ folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-email`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/pull-email/references/retrieval-order.md

@@ -0,0 +1,43 @@
+# references/retrieval-order.md (pull-email)
+
+> **Load this file when** executing the email retrieval (Order 1 exact-folder fast path vs Order 2 root-scope fallback) — i.e., when you need the exact WorkIQ prompt for folder-scoped vs root-scoped queries, throttle handling rules, and the degraded list-only state logic.
+
+## 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 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.

package/plugin/skills/pull-email/references/two-pass-pull.md

@@ -0,0 +1,41 @@
+# references/two-pass-pull.md (pull-email)
+
+> **Load this file when** executing the per-mailbox enumeration (Step A), per-message body fetch (Step B), or thread-grouping (Step C) — i.e., when you need the exact WorkIQ prompt templates, summarization-detection heuristics, doubled-strict retry wording, and the legacy grouping procedure.
+
+## Two-pass pull (REQUIRED — no single-call summarization)
+
+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.**
+
+### Step A — Enumerate the message list
+
+For each `boundaries.email.mailboxes[i]` × the date window (and optional sender_domains / subject_keywords):
+
+```
+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).