kushi-agents 4.8.2 → 4.9.0

package/plugin/skills/build-state/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: "build-state"
-version: "2.0.0"
-description: "Render <project>/State/*.md from existing Evidence (snapshot/ + stream/). No source pulls — pure re-render. Latest fact wins on conflicts. Every assertion cited. Always updates Open Questions."
+version: "3.0.0"
+description: "Render <project>/State/*.md from existing Evidence (v4.9.0+). 3-step reader fallback: _index/entities.yml → weekly/*.md → legacy snapshot/ + stream/. No source pulls — pure re-render. Latest fact wins on conflicts. Every assertion cited. Always updates Open Questions."
 ---
 
 # Skill: build-state
 
+## v4.9.0 — Reader fallback chain (HARD RULE; per `weekly-csc.instructions.md`)
+
+For every `<alias>/<source>/` accessed:
+
+1. **Primary**: read `Evidence/<alias>/<source>/_index/entities.yml`. For each entity needed, pull `latest_csc_file` + `latest_csc_block_offset`; open the weekly file and read the CSC block by entity anchor.
+2. **Secondary (no _index/, but weekly/ exists)**: walk `Evidence/<alias>/<source>/weekly/*.md` newest-first; parse `## <name> {#<anchor>}` headings; build an in-memory entity index for this query.
+3. **Legacy fallback (pre-v4.9.0)**: if `weekly/` is empty BUT `snapshot/` or `stream/` exist, read those. Cite as legacy.
+
+Citation form in this skill's output:
+- **New (v4.9.0)**: `[source: <alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md#<entity-anchor> · <iso-ts>]`
+- **Legacy (reading from snapshot/+stream/)**: append ` (legacy pre-v4.9.0 layout)` after the citation.
+
+Mark the answer / output footer with `Source-layout: weekly-csc | weekly-csc-plus-legacy | legacy-only` so the user knows whether a refresh would update the layout.
+
+Readers MUST NOT delete or modify legacy folders. Migration is out of scope for v4.9.0.
+
 Run this when the user says: "regenerate state for `<X>`", "rebuild State", "@Kushi state `<X>`". This skill makes NO source calls — it only reads Evidence and writes State.
 
 ## Inputs
@@ -16,9 +32,10 @@ Run this when the user says: "regenerate state for `<X>`", "rebuild State", "@Ku
 
 ### Step 1 — Read all Evidence
 
-For the resolved `<project>`:
-- Walk `Evidence/<alias>/<source>/snapshot/**/*.md` (current truth per entity).
-- Walk `Evidence/<alias>/<source>/stream/**/*.md` (chronological events).
+For the resolved `<project>`, apply the v4.9.0 fallback chain for each `<alias>/<source>/`:
+- **Primary**: read `Evidence/<alias>/<source>/_index/entities.yml`; load entities via `latest_csc_file` + offset.
+- **Secondary**: if no `_index/`, walk `Evidence/<alias>/<source>/weekly/*.md` newest-first.
+- **Legacy fallback**: if `weekly/` is empty, read `Evidence/<alias>/<source>/snapshot/**/*.md` (current truth per entity) and `Evidence/<alias>/<source>/stream/**/*.md` (chronological events). Cite as `(legacy pre-v4.9.0 layout)`.
 - Walk `Evidence/_Consolidated/**/*.md` (multi-user merged where present).
 
 ### Step 2 — For each State file (00–08), regenerate
@@ -58,12 +75,18 @@ Update `<project>/State/09_open-questions.md`:
 Top of every State file:
 
 ```markdown
-> _As of: YYYY-MM-DD HH:mm. Regenerated by @Kushi build-state. Source: Evidence/ snapshots + streams._
+> _As of: YYYY-MM-DD HH:mm. Regenerated by @Kushi build-state. Source: Evidence/ weekly CSC + legacy snapshots + streams._
 ```
 
+`Source-layout: weekly-csc | weekly-csc-plus-legacy | legacy-only` (append to banner to reflect which layout was actually read).
+
 ## Triggers
 
 - "regenerate state for `<X>`"
 - "rebuild state"
 - "@Kushi state `<X>`"
-- "re-render State after I fixed `<file>`"
+- "re-render State after I fixed `<file>`"
+
+## Changelog
+
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.

package/plugin/skills/consolidate-evidence/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: "consolidate-evidence"
-version: "2.0.0"
-description: "Merge per-contributor evidence (snapshot + stream) into Evidence/_Consolidated/ for a window. Provenance tags on every merged claim. Used by refresh-project and bootstrap-project when multiple contributors exist."
+version: "3.0.0"
+description: "Merge per-contributor evidence into Evidence/_Consolidated/ for a window (v4.9.0+). 3-step reader fallback per source: _index/entities.yml → weekly/*.md → legacy snapshot/ + stream/. Provenance tags on every merged claim. Used by refresh-project and bootstrap-project when multiple contributors exist."
 ---
 
 # Skill: consolidate-evidence
 
+## v4.9.0 — Reader fallback chain (HARD RULE; per `weekly-csc.instructions.md`)
+
+For every `<alias>/<source>/` accessed:
+
+1. **Primary**: read `Evidence/<alias>/<source>/_index/entities.yml`. For each entity needed, pull `latest_csc_file` + `latest_csc_block_offset`; open the weekly file and read the CSC block by entity anchor.
+2. **Secondary (no _index/, but weekly/ exists)**: walk `Evidence/<alias>/<source>/weekly/*.md` newest-first; parse `## <name> {#<anchor>}` headings; build an in-memory entity index for this query.
+3. **Legacy fallback (pre-v4.9.0)**: if `weekly/` is empty BUT `snapshot/` or `stream/` exist, read those. Cite as legacy.
+
+Citation form in this skill's output:
+- **New (v4.9.0)**: `[source: <alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md#<entity-anchor> · <iso-ts>]`
+- **Legacy (reading from snapshot/+stream/)**: append ` (legacy pre-v4.9.0 layout)` after the citation.
+
+Mark the answer / output footer with `Source-layout: weekly-csc | weekly-csc-plus-legacy | legacy-only` so the user knows whether a refresh would update the layout.
+
+Readers MUST NOT delete or modify legacy folders. Migration is out of scope for v4.9.0.
+
 Run this when multiple contributors have evidence and the user wants a single merged view per source per week. Triggers from `refresh-project` automatically when `Evidence/contributors.yml` lists >1 alias with recent evidence; or directly via `@Kushi consolidate <X> last 7 days`.
 
 ## Inputs
@@ -17,11 +33,14 @@ Run this when multiple contributors have evidence and the user wants a single me
 
 ### Step 1 — Identify contributors with evidence in the window
 
-Read `Evidence/contributors.yml`. For each alias, check if `Evidence/<alias>/*/stream/<weeks-in-window>.md` exists.
+Read `Evidence/contributors.yml`. For each alias, apply the v4.9.0 fallback chain per source:
+- **Primary**: check `Evidence/<alias>/<source>/_index/entities.yml` for entries with `last_touched` in the window.
+- **Secondary**: if no `_index/`, check if `Evidence/<alias>/<source>/weekly/*.md` files exist covering the window.
+- **Legacy fallback**: if `weekly/` is empty, check `Evidence/<alias>/*/stream/<weeks-in-window>.md`.
 
 ### Step 2 — For each (week × source) in the window
 
-Read all per-contributor stream files for that (week, source). Merge into:
+Apply the fallback chain: read per-contributor weekly CSC files (`Evidence/<alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md`) for that (week, source); fall back to legacy stream files (`Evidence/<alias>/<source>/stream/`) if no weekly/ file exists. Merge into:
 `Evidence/_Consolidated/<source>/<YYYY-MM-DD>_consolidated.md`
 
 Merge rules:
@@ -49,3 +68,7 @@ Append a `consolidation_runs:` entry: `{ window, contributors, files_written }`.
 ## Issue Recovery
 
 When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+
+## Changelog
+
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.

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

@@ -1,19 +1,75 @@
 ---
 name: "pull-ado"
-version: "2.3.2"
-description: "Pull ADO evidence as an engagement TREE (parent Engagement + every child WI). Per-item discussion comments + revision history (verbatim). Deterministic resolution; no parent-only summaries. Per ado-engagement-tree.instructions.md."
+version: "3.0.0"
+description: "v3.0.0 (kushi v4.9.0): Pull ADO evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_ado-csc.md. One block per work item touched that week, upserted in _index/entities.yml. ADO REST + tree expansion UNCHANGED — only output shape changes. WI fields → CSC sections (AssignedTo→Participants, Description→Topics, State changes→Decisions, Comments→Q&A+Who Said What, etc.). No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
 ---
 
 # Skill: pull-ado
 
 
-> **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.
+> **v4.9.0 contracts** — This skill operates under these HARD-rule doctrines:
+> - **`comprehensive-structured-capture.instructions.md`** — CSC block shape (canonical sections, bullets only, no prose).
+> - **`weekly-csc.instructions.md`** — weekly/ + _index/ writer contract; multi-user safety.
+> - `workiq-only.instructions.md` — when WorkIQ is used, the CSC canonical prompts (§ "CSC canonical prompts (kushi v4.9.0+)") apply. **ADO REST remains the preferred path** for fields + comments + updates + tree expansion.
+> - `ado-engagement-tree.instructions.md` — tree expansion + per-item discussion + revision pulls UNCHANGED.
+> - `evidence-thoroughness.instructions.md` (v2.0.0) — per-source minimum bullet thresholds; `low_signal: true` flag.
+> - `citation-ledger.instructions.md` — citation format.
 > - `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.
+> - `cleanup-on-resolution.instructions.md` — stale `no-match` / `not yet` notes are rewritten on resolution.
 > - `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`.
+> - `evidence-layout-canonical.instructions.md` — `weekly/` + `_index/` are canonical in v4.9.0+.
+> - `scope-boundaries.instructions.md` — boundaries gate.
+> - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
+> - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
+
+## 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`:
+
+- **Output target** (single file per source per ISO week):
+  `<engagement-root>/<project>/Evidence/<alias>/ado/weekly/<YYYY-MM-DD>_ado-csc.md`
+  where `<YYYY-MM-DD>` is the **Monday** of the ISO week the WI was touched.
+  Empty weeks produce no file.
+
+- **Block shape (per WI touched that week)**: one CSC block per work item under `## <WI title> {#<entity-anchor>}` with canonical section order: Source basis → Coverage window → Last touched → Participants → Topics Discussed → Q&A → Who Said What → Decisions → Dates & Numbers Shared → Action Items → Next Steps → Open Questions → Risks/Blockers/Dependencies → Customer Asks → Artifacts/Links → Coverage Notes. Bullets only — no prose paragraphs.
+
+- **Entity id (canonical for this source)**: `ado://org=<org>/project=<project>/workitemid=<int>`
+
+- **ADO REST + tree expansion UNCHANGED**: Step 1 (resolve Engagement WI ID) + Step 2 (expand tree) + Step 3 (per-item fetch: core fields + paginated discussion comments + revision history + attachments) all unchanged. Only the OUTPUT SHAPE changes — the REST contract is identical.
+
+- **_index/entities.yml upsert** (per-contributor, per-source): on every write, upsert one row per WI:
+  ```yaml
+  - id: 'ado://org=<org>/project=<project>/workitemid=<int>'
+    display_name: '<WI title>'
+    entity_anchor: '<slug>'
+    latest_csc_file: 'weekly/<YYYY-MM-DD>_ado-csc.md'
+    latest_csc_block_offset: <line>
+    last_touched: <ISO>            # use System.ChangedDate
+    first_seen: <ISO>              # use System.CreatedDate
+    weeks_touched: [<YYYY-MM-DD>, ...]
+    status: captured | body-not-exposed | unavailable | deferred
+    low_signal: false | true
+  ```
+  Path: `<engagement-root>/<project>/Evidence/<alias>/ado/_index/entities.yml`.
+
+- **Idempotency**: same WI, same week, two runs → REPLACE the block in place (CSC reflects end-of-week state). Same WI, different weeks → each week's file gets its own block.
+
+- **No body-fetch loop**: drop the AI Narrative Summary requirement and the dedicated verbatim comment-block reproduction. Comments are surfaced as Q&A and Who Said What bullets with citation; revisions surface as Decisions / Dates & Numbers. CSC bullets cite the ADO REST request URL.
+
+- **Legacy `snapshot/` and `stream/` folders**: NOT written by this skill in v4.9.0. Pre-v4.9.0 folders on disk are left alone; readers fall back to them when `weekly/` is empty.
+
+### Source-specific notes (ado — REST stays)
+
+- **ADO REST + tree expansion unchanged** (Steps 1–3 below). Hard prereqs unchanged; auth block unchanged; WIQL resolution unchanged; pagination of comments unchanged.
+- **Output shape**: one CSC block per WI in `weekly/<Monday>_ado-csc.md`. The tree structure (parent + children) is preserved by surfacing each WI as its own entity block + cross-linking parent/child WIs in each block's `Artifacts/Links` section.
+- **Map WI fields → CSC sections**:
+  - AssignedTo + commenters → **Participants**
+  - Title + description + acceptance criteria → **Topics Discussed**
+  - State changes (System.State revisions) → **Decisions**
+  - Iteration dates, story points, effort → **Dates & Numbers Shared**
+  - Discussion comments → **Q&A** (when Q-and-A pattern detected) + **Who Said What**
+  - Tags, related WIs, parent-child links, attachment metadata → **Artifacts/Links**
+- Entity id: `ado://org=<org>/project=<project>/workitemid=<int>`.
 
 Pulls **ado** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
@@ -187,6 +243,8 @@ From `$item.relations` where `rel = 'AttachedFile'` — record `name`, `resource
 
 ### 3e — Write per-item snapshot file
 
+> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. The ADO REST fetches (3a–3d) still run; only the file write changes. Kept for historical reference; not executed.
+
 `<engagement-root>/<project>/Evidence/<alias>/ado/snapshot/items/<id>.md` (parent gets `engagement-<id>.md` at the snapshot root):
 
 - Header: id, type, title, state, areaPath, parent, assignee, last fetched.
@@ -199,17 +257,19 @@ From `$item.relations` where `rel = 'AttachedFile'` — record `name`, `resource
 
 ## Step 4 — Stream pass
 
+> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. Kept for historical reference; not executed.
+
 After all snapshots written, build the weekly stream from comments + updates whose `createdDate` / `revisedDate` fall in `<window>`. Bucket by Monday-of-ISO-week into `stream/<YYYY-MM-DD>_ado-stream.md` with AI Narrative Summary first then the verbatim entries grouped by WI.
 
 If a week file exists, MERGE (dedupe by `comment.id` and `update.rev`).
 
 ## Tools (in order)
 
-1. **WorkIQ** — discovery only (asking "is there an Engagement WI for HCA?" before doing the WIQL). Never used for discussion-comment fetch — it summarizes.
+1. **WorkIQ** — discovery only (asking "is there an Engagement WI for HCA?" before doing the WIQL). When used for CSC, use the CSC canonical prompts from `workiq-only.instructions.md` § 'CSC canonical prompts (kushi v4.9.0+)'. The pre-v4.9.0 verbatim prompts are LEGACY (kept only for pull-meetings Half A). Never used for discussion-comment fetch — it summarizes.
 2. **ADO REST** — REQUIRED for fields + comments + updates + tree expansion (preferred path). Auth block above.
 3. **Ask user** — paste verbatim source content if REST returns 401 / 404 / persistent 5xx after 2 retries (3s/6s).
 
-Document which path succeeded under `## Source Basis` in each output file.
+Document which path succeeded under `Source basis` (in the CSC block).
 
 ## Mutable hints to upsert (during the run, not at the end)
 
@@ -249,3 +309,19 @@ After successful pass:
 ## Issue Recovery
 
 When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+
+## Depth bar (per `evidence-thoroughness.instructions.md` v2.0.0)
+
+Per-source minimum bullet thresholds replace the v4.8 AI Narrative Summary depth bar. For ADO work items: **≥ 8 material bullets, ≥ 4 sections populated** (must include Participants (assignee + reporter), Topics, Action Items or Next Steps, Artifacts).
+
+An entity that cannot meet the threshold is flagged `low_signal: true` in `_index/entities.yml` and rendered as heading + Coverage Notes only — do NOT pad.
+
+## Changelog
+
+- **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>_ado-csc.md`) + per-contributor `_index/entities.yml`. snapshot/items/ +
+  stream/ writes removed. ADO REST + tree expansion (Steps 1–3) UNCHANGED — only output shape
+  changes. WI fields mapped to CSC sections (AssignedTo→Participants, Description→Topics, State
+  changes→Decisions, Comments→Q&A+Who Said What, 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.

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

@@ -1,19 +1,76 @@
 ---
 name: "pull-crm"
-version: "2.3.2"
-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."
+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."
 ---
 
 # 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.
+> **v4.9.0 contracts** — This skill operates under these HARD-rule doctrines:
+> - **`comprehensive-structured-capture.instructions.md`** — CSC block shape (canonical sections, bullets only, no prose).
+> - **`weekly-csc.instructions.md`** — weekly/ + _index/ writer contract; multi-user safety.
+> - `workiq-only.instructions.md` — when WorkIQ is used, the CSC canonical prompts (§ "CSC canonical prompts (kushi v4.9.0+)") apply. **Dataverse REST remains the preferred path for CRM** (gives explicit `$select` + `$expand` control).
+> - `evidence-thoroughness.instructions.md` (v2.0.0) — per-source minimum bullet thresholds; `low_signal: true` flag.
+> - `citation-ledger.instructions.md` — citation format.
 > - `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.
+> - `cleanup-on-resolution.instructions.md` — stale `no-match` / `not yet` notes are rewritten on resolution.
 > - `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`.
+> - `evidence-layout-canonical.instructions.md` — `weekly/` + `_index/` are canonical in v4.9.0+.
+> - `scope-boundaries.instructions.md` — boundaries gate.
+> - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
+> - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
+
+## 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`:
+
+- **Output target** (single file per source per ISO week):
+  `<engagement-root>/<project>/Evidence/<alias>/crm/weekly/<YYYY-MM-DD>_crm-csc.md`
+  where `<YYYY-MM-DD>` is the **Monday** of the ISO week the record was modified.
+  Empty weeks produce no file.
+
+- **Block shape (per record touched that week)**: one CSC block under `## <Record title> {#<entity-anchor>}` with canonical section order: Source basis → Coverage window → Last touched → Participants → Topics Discussed → Decisions → Dates & Numbers Shared → Action Items → Next Steps → Open Questions → Risks/Blockers/Dependencies → Customer Asks → Artifacts/Links → Coverage Notes. (Q&A and Who Said What omitted per CSC per-source applicability.) Bullets only — no prose paragraphs.
+
+- **Entity id (canonical for this source)**: `crm://entity=<logicalName>/id=<guid>`
+
+- **Dataverse REST retrieval doctrine (Rules 1–6) UNCHANGED**: formatted-values annotations, `PSObject.Properties[...]` indexer, one-row inspect-before-widen, one-field-at-a-time, always include `statecode`/`statuscode`, prefer formatted values in rendered output. Only the OUTPUT SHAPE changes — the REST contract is identical.
+
+- **_index/entities.yml upsert** (per-contributor, per-source): on every write, upsert one row per record:
+  ```yaml
+  - id: 'crm://entity=<logicalName>/id=<guid>'
+    display_name: '<record title>'
+    entity_anchor: '<slug>'
+    latest_csc_file: 'weekly/<YYYY-MM-DD>_crm-csc.md'
+    latest_csc_block_offset: <line>
+    last_touched: <ISO>            # use record.modifiedon
+    first_seen: <ISO>              # use record.createdon
+    weeks_touched: [<YYYY-MM-DD>, ...]
+    status: captured | body-not-exposed | unavailable | deferred
+    low_signal: false | true
+  ```
+  Path: `<engagement-root>/<project>/Evidence/<alias>/crm/_index/entities.yml`.
+
+- **Idempotency**: same record, same week, two runs → REPLACE the block in place (CSC reflects end-of-week state). Same record, different weeks → each week's file gets its own block.
+
+- **No body-fetch loop**: drop the AI Narrative Summary requirement and the dedicated verbatim long-text dump. Long-text fields are surfaced as bulleted Topics Discussed entries; annotations become sub-bullets under Topics + entries in Who Said What (note author + first material sentence). CSC bullets cite the Dataverse REST request-id / WorkIQ request-id.
+
+- **Legacy `snapshot/` and `stream/` folders**: NOT written by this skill in v4.9.0. Pre-v4.9.0 folders on disk are left alone; readers fall back to them when `weekly/` is empty.
+
+### Source-specific notes (crm — REST stays)
+
+- **Dataverse REST retrieval doctrine (Rules 1–6) unchanged** (see below). The 4-step resolution sequence (title → account[s] → wide-text → recent-slice → ask) and anti-patterns (no `statecode` filter at discovery; `new_companyname` is NOT a field; never disable from one shallow probe) all UNCHANGED.
+- **Output shape changes**: instead of `snapshot/<entitySet>/<record-id>.md` + `stream/<YYYY-MM-DD>_crm-stream.md`, write **one CSC block per record** in `weekly/<Monday>_crm-csc.md`.
+- **Map record fields → CSC sections**:
+  - Owner + contacts + assignedTo → **Participants**
+  - Long-text engagement fields (objectives, scenario, blockers) → **Topics Discussed**
+  - `statecode`/`statuscode` changes, decisions captured in notes → **Decisions**
+  - `createdon`/`modifiedon`, dollar amounts, percentages → **Dates & Numbers Shared**
+  - Annotations (notes) added in week → **Topics Discussed** sub-bullets + **Who Said What** (note author + first material sentence). _(Who Said What is normally omitted for crm per per-source table, but annotations are the carve-out where attribution is material — render only when present.)_
+  - Open questions in notes → **Open Questions**
+  - Customer-stated requirements → **Customer Asks**
+  - Related records → **Artifacts/Links**
+- Entity id: `crm://entity=<logicalName>/id=<guid>`.
 
 Pulls **crm** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
@@ -176,6 +233,8 @@ If the response is summarized (heuristics: any long-text field appears trimmed,
 
 ### 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).
@@ -196,6 +255,8 @@ Use template: `templates/snapshot/crm-<kind>.template.md` (FDE entities: shape c
 
 ## 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).
@@ -206,12 +267,12 @@ If a week file already exists, MERGE (dedupe by event ID, append new events, kee
 
 ## Tools (in order)
 
-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 `<workspace>/.kushi/config/shared/integrations.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.
+1. **Dataverse REST Web API** (preferred — gives explicit `$select` + `$expand` control) via `az account get-access-token` against the configured tenant. Read connection from `<workspace>/.kushi/config/shared/integrations.yml`. Doctrine Rules 1–6 above MUST be followed.
+2. **WorkIQ** — only when REST is unavailable. Use CSC canonical prompts from `workiq-only.instructions.md` § 'CSC canonical prompts (kushi v4.9.0+)'. The pre-v4.9.0 verbatim prompts are LEGACY (kept only for pull-meetings Half A).
 3. **Graph REST** — last resort, soft-fail per `auth-and-retry.instructions.md`.
 4. **Ask user** — paste verbatim source content if all above fail.
 
-Document which path succeeded under `## Source Basis` in each output file.
+Document which path succeeded under `Source basis` (in the CSC block) and in run-log.
 
 ## Mutable hints to upsert (during the run, not at the end)
 
@@ -247,3 +308,19 @@ After successful pass:
 ## Issue Recovery
 
 When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+
+## Depth bar (per `evidence-thoroughness.instructions.md` v2.0.0)
+
+Per-source minimum bullet thresholds replace the v4.8 AI Narrative Summary depth bar. For CRM records: **≥ 12 material bullets, ≥ 5 sections populated** (must include Participants, Dates & Numbers, Next Steps, Customer Asks, Artifacts).
+
+An entity that cannot meet the threshold is flagged `low_signal: true` in `_index/entities.yml` and rendered as heading + Coverage Notes only — do NOT pad.
+
+## Changelog
+
+- **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.

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

@@ -1,19 +1,68 @@
 ---
 name: "pull-email"
-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."
+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."
 ---
 
 # 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.
+> **v4.9.0 contracts** — This skill operates under these HARD-rule doctrines:
+> - **`comprehensive-structured-capture.instructions.md`** — CSC block shape (canonical sections, bullets only, no prose).
+> - **`weekly-csc.instructions.md`** — weekly/ + _index/ writer contract; multi-user safety.
+> - **`workiq-only.instructions.md`** — email enumeration + per-thread CSC capture go through WorkIQ ONLY via the CSC canonical prompts (§ "CSC canonical prompts (kushi v4.9.0+)"). `m365_get_email`, `m365_search_emails`, `m365_list_emails`, and Graph REST URLs remain FORBIDDEN.
+> - `evidence-thoroughness.instructions.md` (v2.0.0) — per-source minimum bullet thresholds; `low_signal: true` flag for shallow entities.
+> - `citation-ledger.instructions.md` — citation format.
 > - `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.
+> - `cleanup-on-resolution.instructions.md` — stale `no-match` / `not yet` notes are rewritten on resolution.
 > - `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.
+> - `evidence-layout-canonical.instructions.md` — `weekly/` + `_index/` are canonical in v4.9.0+.
+> - `scope-boundaries.instructions.md` — boundaries gate.
+> - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
+> - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
+
+## 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`:
+
+- **Output target** (single file per source per ISO week):
+  `<engagement-root>/<project>/Evidence/<alias>/email/weekly/<YYYY-MM-DD>_email-csc.md`
+  where `<YYYY-MM-DD>` is the **Monday** of the ISO week the entities were touched.
+  Empty weeks produce no file.
+
+- **Block shape (per entity touched that week)**: one CSC block under `## <Entity title> {#<entity-anchor>}` with canonical section order: Source basis → Coverage window → Last touched → Participants → Topics Discussed → Q&A → Who Said What → Decisions → Dates & Numbers Shared → Action Items → Next Steps → Open Questions → Risks/Blockers/Dependencies → Customer Asks → Artifacts/Links → Coverage Notes. Bullets only — no prose paragraphs. Inapplicable sections omitted; empty-but-applicable sections rendered as `_None surfaced._`.
+
+- **Entity id (canonical for this source)**: `email://conversation_id=<conversationId>`
+
+- **WorkIQ prompts**: REPLACED by the CSC canonical prompts in `workiq-only.instructions.md` § "CSC canonical prompts (kushi v4.9.0+)". Do NOT use the v4.8 verbatim prompts.
+
+- **_index/entities.yml upsert** (per-contributor, per-source): on every write, upsert one row per entity:
+  ```yaml
+  - id: 'email://conversation_id=<conversationId>'
+    display_name: '<thread subject>'
+    entity_anchor: '<slug>'
+    latest_csc_file: 'weekly/<YYYY-MM-DD>_email-csc.md'
+    latest_csc_block_offset: <line>
+    last_touched: <ISO>
+    first_seen: <ISO>
+    weeks_touched: [<YYYY-MM-DD>, ...]
+    status: captured | body-not-exposed | unavailable | deferred
+    low_signal: false | true
+  ```
+  Path: `<engagement-root>/<project>/Evidence/<alias>/email/_index/entities.yml`.
+
+- **Idempotency**: same entity, same week, two runs → REPLACE the block in place (current-week CSC reflects end-of-week state). Same entity, different weeks → each week's file gets its own block.
+
+- **No body-fetch loop**: drop the per-message verbatim body fetch and the AI Narrative Summary requirement. CSC bullets sourced directly from WorkIQ CSC output.
+
+- **Legacy `snapshot/` and `stream/` folders**: NOT written by this skill in v4.9.0. Pre-v4.9.0 folders on disk are left alone (no migration); readers fall back to them when `weekly/` is empty.
+
+### Source-specific notes (email)
+
+- Step A enumeration WorkIQ prompt is unchanged (lists conversations in scope).
+- Replace per-message body fetch with **one CSC call per conversationId** using the CSC canonical email prompt.
+- Persist message-index to `_index/message-index_<YYYY-MM-DD>.md` (optional — `_index/entities.yml` is the authoritative current-state file).
+- Drop "Group by conversationId" + AI Narrative Summary references (legacy below).
 Pulls **email** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
 - **snapshot/** — (none — emails ARE events, no snapshot)
@@ -137,10 +186,14 @@ After all bodies fetched, group messages by `conversationId`. For each thread:
 
 ## Snapshot pass
 
+> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. Kept for historical reference; not executed.
+
 _(no snapshot for email — emails are inherently event-stream)_
 
 ## Stream pass output
 
+> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. Kept for historical reference; not executed.
+
 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`.
@@ -151,7 +204,7 @@ If a week file already exists, MERGE (dedupe by `internetMessageId`, append new
 
 ## Tools (WorkIQ ONLY — per `workiq-only.instructions.md`)
 
-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.
+1. **WorkIQ (`workiq ask`)** — the ONLY allowed path for both enumeration (Step A) and per-thread CSC capture. Use CSC canonical prompts from `workiq-only.instructions.md` § 'CSC canonical prompts (kushi v4.9.0+)'. The pre-v4.9.0 verbatim prompts are LEGACY (kept only for pull-meetings Half A).
 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>`.
 
 **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.
@@ -181,11 +234,13 @@ After successful pass:
 - `sources.email.threads = <N>` — number of conversations grouped
 - For each week touched, add to `weekly_files` index.
 
-## Depth bar (per `evidence-thoroughness.instructions.md`)
+## Depth bar (per `evidence-thoroughness.instructions.md` v2.0.0)
+
+Per-source minimum bullet thresholds replace the v4.8 AI Narrative Summary depth bar. For email threads: **≥ 8 material bullets, ≥ 4 sections populated** (must include Participants, Topics, Action Items or Next Steps, Decisions or Q&A).
 
-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.
+An entity that cannot meet the threshold is flagged `low_signal: true` in `_index/entities.yml` and rendered as heading + Coverage Notes only — do NOT pad.
 
-**Completeness bar:** `messages_enumerated` should equal `messages_fetched + messages_failed`. Drift surfaces in run-log; consolidate skill renders it as a Coverage Note.
+**Completeness bar:** `messages_enumerated` should equal the sum of conversations captured + `body-not-exposed` + `deferred`. Drift surfaces in run-log; consolidate skill renders it as a Coverage Note.
 
 ## Stop conditions
 
@@ -204,3 +259,12 @@ The pre-Step-C anti-summary doctrine + the Step-C AI Narrative Summary per threa
 ## Issue Recovery
 
 When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+
+## Changelog
+
+- **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.