kushi-agents 4.8.2 → 4.9.0

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

@@ -1,234 +1,128 @@
----
-applyTo: "**"
-description: "Evidence Thoroughness Standard — every per-source skill MUST capture full bodies, full transcripts, full message reproduction. Headlines-only is a defect."
----
-
-# Evidence Thoroughness Standard (HARD RULE)
-
-Evidence files are the **system of record** that State files cite. They MUST be deep enough that a reader can fully reconstruct what happened without going back to Outlook / Teams / OneNote / SharePoint / CRM / ADO. **Headlines-only summaries are a defect.**
-
-> **Orthogonal to scope:** depth (this file) and scope (`scope-boundaries.instructions.md`) are independent. Boundaries declare *where Kushi is allowed to look*; depth declares *how completely it captures what it found*. A skill must satisfy BOTH: refuse if the boundary is missing, then capture at full depth inside the boundary. Coverage Notes blocks at the bottom of every entity MUST enumerate which boundaries were applied (per Rule 4 of `scope-boundaries.instructions.md`).
-
-## Universal rule — AI Narrative Summary required FIRST
-
-Every per-entity block (per meeting, per email thread, per Teams thread, per OneNote page, per SharePoint key file, per CRM/ADO record) MUST open with an **`### AI Narrative Summary`** sub-section before any structured sub-sections (Decisions / Actions / Risks / etc.).
-
-The AI Narrative Summary:
-- Is a **multi-paragraph prose summary** (minimum 3 paragraphs for any non-trivial entity; 5+ paragraphs for substantive meetings, threads, or pages) that captures **every detail discussed** — context, what was said by whom, the reasoning, the back-and-forth, side-tangents, soft commitments, sentiment, and any nuance — not just the outcomes.
-- Reads like a thorough briefing for someone who wasn't there. A reader who only reads the AI Narrative Summary should be able to answer "what happened, why, who pushed which view, what's the tone, what's still unresolved?" without scrolling further.
-- Is generated AFTER the full extraction (transcript / body / page content) is in hand, so it can faithfully cover **everything** — not summarized from headlines.
-- Carries inline `[source: …]` citations to the same evidence the structured sub-sections cite. No uncited paragraphs.
-- Is NOT a replacement for the structured sub-sections (Decisions, Action Items, Risks, etc.) or the verbatim transcript walk-through / message reproduction. It is **additional**, placed first, so a busy reader gets the full picture before drilling into structure.
-
-A per-entity block that has structured sub-sections but no AI Narrative Summary is a defect. A 2-paragraph "summary" that only lists outcomes is a defect — it must capture the discussion, not just the result.
-
-## Universal rule — full discussion capture (HARD)
-
-Beyond the narrative summary, every per-entity block MUST also explicitly capture, as separate named sub-sections, the following — even when some are empty (write `_None surfaced._` rather than omit the section, so a reader knows it was checked):
-
-- **Questions Asked & Answered** — every question raised + the answer given (or "left open"), with who asked and who answered. Format as `Q: … — A: … [source: … · ts]`. Includes clarifying questions, challenge questions, status questions, asks for data, asks for opinion. **A meeting with zero captured Q&A is a defect** unless the meeting was a one-way readout (and even then, capture the Q&A from the Q&A portion at the end).
-- **Discussion Points (Bulleted, with Detail)** — every distinct topic touched, as a bullet, with a 2–5-line nested detail block per bullet covering: what was said, by whom, what positions surfaced, what arguments were made, what was concluded (or "deferred"). Not a one-line list — every bullet has nested detail.
-- **Decisions** — every decision with exact wording + who decided + supporting context + what was rejected.
-- **Plans (Current State)** — the plan as it stands at the end of the entity (meeting / thread / page). What is intended to happen, by when, by whom.
-- **Changes to Plans** — every adjustment to a previously-stated plan (whether stated earlier in the same meeting/thread or carried in from prior evidence): old plan → new plan + why it changed + who drove the change. Critical for tracing how an engagement evolves.
-- **Next Steps** — forward-looking commitments that aren't yet hard action items. Distinct from Action Items (those have owner+due). Capture even soft signals: "team will look into X", "we'll circle back next week".
-- **Action Items** — every commitment with owner + due + source-line.
-- **Open Questions / Non-Decisions** — questions raised but not resolved, with who raised them and why deferred. Distinct from "Questions Asked & Answered" (which captures resolved Q&A in this entity).
-- **Risks, Blockers, Dependencies** — surfaced or escalated.
-- **Customer Asks** — explicit asks the customer made of Microsoft.
-
-The existence of a section is mandatory; populating it is conditional on the source. **Empty sections must be written explicitly as `_None surfaced._`** so a reader can distinguish "checked and empty" from "skipped".
-
-## Per-source minimum bar
-
-### Meetings (stream/)
-For every meeting in the window — capture, **as separate named sections under each per-meeting block**, in this order (every section MUST be present; if empty, write `_None surfaced._`):
-- **AI Narrative Summary** (REQUIRED FIRST per the universal rule above) — 5+ paragraphs covering the whole meeting end-to-end: context coming in, what was discussed in what order, who took which position, the reasoning behind each position, the back-and-forth, soft / forward-looking signals, sentiment, what landed and what stayed open. Cite the transcript timestamps inline.
-- Full attendee list (required + optional + actual + no-shows)
-- Agenda / stated purpose
-- **Detailed Discussion Summary** — multi-paragraph structured narrative of what was actually discussed end-to-end, organized by topic (the AI Narrative Summary is chronological/holistic; this section is topic-organized; both are required)
-- **Discussion Points (Bulleted, with Detail)** — every distinct topic, as a bullet with nested 2–5-line detail block (positions, arguments, what was concluded)
-- **Questions Asked & Answered** — every Q raised + the A given (or "left open"), `Q: … — A: …` format, with attribution
-- **Chronological transcript walk-through with verbatim quotes and timestamps** — every substantive exchange, not just 2 highlight quotes
-- **Plans (Current State)** — the plan as it stands at end of meeting
-- **Changes to Plans** — old plan → new plan + why + who drove the change
-- **Key Decisions** — every decision with exact wording + who decided + supporting context + what was rejected
-- **Open Questions / Non-Decisions** — questions raised but not resolved, with who raised them and why deferred
-- **Next Steps** — REQUIRED dedicated section. Forward-looking commitments that aren't yet hard action items: "team will gather facts", "Mike will discuss with industry leads", "Microsoft to come back with proposal next week". These are distinct from `Action Items` (which have owner+due) and are critical to State/05_action-items + State/04_workshops-and-key-meetings rendering.
-- **Action Items** — every commitment with owner + due + source-line
-- **Risks, Blockers, Dependencies** — surfaced or escalated in this meeting
-- **Customer Asks** — explicit asks the customer made of Microsoft (resourcing, decisions, timelines, escalations)
-- Every artifact link / shared file / recording / transcript URL
-- **Coverage Notes** — what was retrievable vs what wasn't (transcript missing, chat-only reconstruction, partial recap, etc.)
-
-If transcript is unavailable, document why and pull chat transcript + Copilot recap + meeting chat thread to reconstruct. Per-meeting sub-section is mandatory; one block per meeting. **A 30-line meetings file for a week with 2 meetings is a defect — expect 400+ lines, with the structure above repeated per meeting.** A per-meeting block missing the explicit `Next Steps`, `Plans`, `Changes to Plans`, `Discussion Points`, or `Questions Asked & Answered` sections is a defect even if Action Items is present — they capture different things.
-- **Key Decisions** — every decision with exact wording + who decided + supporting context
-- **Open Questions / Non-Decisions** — questions raised but not resolved, with who raised them and why deferred
-- **Next Steps** — REQUIRED dedicated section. Forward-looking commitments that aren't yet hard action items: "team will gather facts", "Mike will discuss with industry leads", "Microsoft to come back with proposal next week". These are distinct from `Action Items` (which have owner+due) and are critical to State/05_action-items + State/04_workshops-and-key-meetings rendering.
-- **Action Items** — every commitment with owner + due + source-line
-- **Risks, Blockers, Dependencies** — surfaced or escalated in this meeting
-- **Customer Asks** — explicit asks the customer made of Microsoft (resourcing, decisions, timelines, escalations)
-- Every artifact link / shared file / recording / transcript URL
-- **Coverage Notes** — what was retrievable vs what wasn't (transcript missing, chat-only reconstruction, partial recap, etc.)
-
-If transcript is unavailable, document why and pull chat transcript + Copilot recap + meeting chat thread to reconstruct. Per-meeting sub-section is mandatory; one block per meeting. **A 30-line meetings file for a week with 2 meetings is a defect — expect 200+ lines, with the structure above repeated per meeting.** A per-meeting block missing the explicit `Next Steps` section is a defect even if Action Items is present — they capture different things.
-
-### Teams chats (stream/)
-For every thread touched in the window — capture, in this order per thread:
-- **AI Narrative Summary** (REQUIRED FIRST) — 3+ paragraph prose covering what the thread is about, the conversation arc, who took which position, sentiment, what landed and what stayed open. Cite messages inline.
-- **Full message-by-message reproduction** (sender · timestamp · verbatim message text or close paraphrase), not just an outcome line. Group by thread, not by day. Include reactions, file attachments, links, replies. If a thread has 30 messages, reproduce all 30 (collapse only routine acks like 👍 / "thanks").
-- **Decisions / Action Items / Open Questions / Risks** captured by the thread.
-
-### Emails (stream/)
-For every substantive thread — capture, in this order per thread:
-- **AI Narrative Summary** (REQUIRED FIRST) — 3+ paragraph prose: what the thread is about, who's pushing what, the back-and-forth, what was decided / asked / committed / left open, tone. Cite messages inline.
-- Sender, recipients (to + cc), subject, **full body or close paraphrase** for every message in the chain in order, attachments. Thread-level grouping. A one-line "X sent Y about Z" entry is insufficient — include enough body to convey what was actually said.
-- **Decisions / Action Items / Open Questions / Risks** surfaced by the thread.
-
-### OneNote (snapshot/ + stream/)
-- `snapshot/pages/<page>.md` — start with **AI Narrative Summary** (REQUIRED FIRST, 3+ paragraphs covering what the page is about, structure, key points, anything noteworthy), then extract **full page bodies**, not just titles. Last-modified timestamp + author at the top.
-- `stream/<week>.md` — for each page-edit event: a 1–2 paragraph **AI Narrative Summary** of what changed and why it matters, then the diff summary itself.
-
-If Graph delegated-token isn't available, ask the user to paste page content rather than skip.
-
-### SharePoint (snapshot/ + stream/)
-- `snapshot/tree.md` — full folder tree (no truncation). Mark each entry `[key]` / `[recent]` / `[pin]` / `[skip]` / `[tree-only]` so readers can see why a file was or wasn't expanded.
-- `snapshot/files/<path>.md` — start with **AI Narrative Summary** (REQUIRED FIRST, 3+ paragraphs: what the file is, what it argues / proposes / records, key positions, audience, why it matters), then a body summary at the same depth bar as a meeting transcript walk-through (decisions, risks, actions, owners, dates, key context). Bodies for: (a) **curated key files** (architecture, decisions, ADRs, deliverables, proposals, SOWs, business cases, roadmaps, plans), PLUS (b) **top-N most-recently-modified files** where N = `sharepoint.snapshot.recent_n` (default 25), PLUS (c) any user pins from `sharepoint.snapshot.always_include`. Per file: full filename (no truncation), changed-by, change-type, size, last-modified.
-- `stream/<week>.md` — file change events that week, each with a short **AI Narrative Summary** of what the change was and why it matters.
-
-### CRM/ADO (snapshot/ + stream/)
-- `snapshot/<id>.md` — start with **AI Narrative Summary** (REQUIRED FIRST, 3+ paragraphs: the engagement / work item story so far, current stage, who owns it, what's at stake, latest status note in plain prose), then every field the API returns, every value.
-- `stream/<id>/<week>.md` — for the week as a whole: an **AI Narrative Summary** (REQUIRED FIRST) of what changed and what it means, then every field-level change with old → new + actor + timestamp, every comment / discussion verbatim.
-
-## Volume guidance
-
-- Long files are EXPECTED. Compression is the enemy.
-- One file per source per week (stream) — do NOT split into one-file-per-meeting / one-file-per-thread.
-- One file per entity (snapshot) — do NOT consolidate multiple entities into one snapshot.
-
-## Citation density
-
-Every paragraph still needs `[source: …]` citations — thoroughness does NOT relax the citation rule, it intensifies it. See `citation-ledger.instructions.md`.
-
-## Fix-up loop
-
-If the user reads an evidence file and says "this is too light" or "I don't like the depth" or "more detail" or "full AI summary" — the skill MUST re-pull from source with deeper extraction and rewrite the file in the same fix-up turn — never defend a thin summary. Specifically: if the fix-up complaint is about the AI Narrative Summary being thin, expand it to 5+ paragraphs with full discussion coverage, not just outcomes.
-
-## Pre-write checklist (every per-source skill)
-
-Before writing any per-entity block (meeting / thread / email / page / file / record), confirm:
-
-- [ ] AI Narrative Summary is the FIRST sub-section
-- [ ] It is multi-paragraph (3+ for non-trivial; 5+ for substantive meetings/threads/pages)
-- [ ] It captures discussion + reasoning + sentiment, not just outcomes
-- [ ] It carries inline `[source: …]` citations
-- [ ] **Questions Asked & Answered** section is present (populated or `_None surfaced._`)
-- [ ] **Discussion Points (Bulleted, with Detail)** section is present — each bullet has nested 2–5-line detail
-- [ ] **Plans (Current State)** section is present
-- [ ] **Changes to Plans** section is present
-- [ ] **Next Steps** section is present (distinct from Action Items)
-- [ ] All other structured sub-sections (Decisions / Action Items / Risks / Open Questions / Customer Asks) come AFTER, not instead of
-- [ ] Verbatim transcript / message reproduction / page body is still present (the AI summary does not replace it)
-- [ ] Empty sections explicitly say `_None surfaced._`, never omitted
-
-<!-- merged from evidence-thoroughness.instructions.md (v4.4.9) -->
-## Detection algorithm
-
-Every `pull-*` skill MUST run this check after writing each evidence file. A file that fails the detector is a **defect** — it MUST be re-extracted with a richer query or replaced with pasted source content. The skill MUST NOT silently accept a thin file.
-
-This detector enforces `evidence-thoroughness.instructions.md` at runtime. The thoroughness doctrine defines what "full" means; this file defines how to **detect** and **fix** violations.
+---
+applyTo: kushi-agents
+priority: high
+version: 2.0.0
+---
 
-## Per-source minimum thresholds
-
-Apply the threshold for the source the file belongs to. A file fails if **any** check triggers.
-
-### Email stream (`email/stream/*.md`)
-
-- Per thread block: body text ≥ **400 characters** (not counting headers / metadata / "see original" stubs).
-- Per thread block contains at least one of: `Body:`, `Reply chain`, or a quoted block.
-- File-level: ≥ 1 thread block per substantive subject mentioned in the windowed search results.
-
-### Teams stream (`teams/stream/*.md`)
-
-- Per thread block: reproduces ≥ **5 messages** (or, if thread is shorter, ALL messages — collapse only routine acks 👍 / "thanks").
-- Each reproduced message has `<sender> · <timestamp>` line + verbatim or close-paraphrase text.
-- File-level: rejects "summary-only" files with no message-by-message reproduction.
-
-### OneNote snapshot (`onenote/snapshot/pages/*.md`)
-
-- Page body text ≥ **600 characters** OR contains a `## Page Body` section followed by content (not just a link).
-- Page metadata block (last-modified, author) present.
-
-### OneNote stream (`onenote/stream/*.md`)
-
-- Each page-edit event includes diff summary (what changed) — not just "page updated".
-
-### SharePoint snapshot tree (`sharepoint/snapshot/tree.md`)
-
-- Tree is not truncated (no "…" or "N more" placeholders).
-- Each entry has a status tag: `[key]` / `[recent]` / `[pin]` / `[skip]` / `[tree-only]`.
-
-### SharePoint snapshot file (`sharepoint/snapshot/files/*.md`)
+# Evidence Thoroughness — Bullets-Only Depth Bar (v4.9.0)
 
-- Body summary ≥ **400 characters** OR explicit `[tree-only]` justification.
-- Has changed-by + change-type + last-modified.
+> **v4.9.0:** This doctrine replaces the "AI Narrative Summary (multi-paragraph prose)"
+> bar from v3.x/v4.8. The new bar is **Comprehensive Structured Capture (CSC)** — see
+> [`comprehensive-structured-capture.instructions.md`](./comprehensive-structured-capture.instructions.md).
+>
+> CSC is **bullets only, no prose paragraphs anywhere**. This file defines the
+> per-source **minimum bullet thresholds** and **per-source enforcement rules**
+> that distinguish a thorough CSC block from a thin/lazy one.
 
-### Meetings stream (`meetings/stream/*.md`)
+## Why a depth bar exists
 
-- Per meeting block contains ALL of the following named sections:
-  - `## Detailed Discussion Summary`
-  - `## Transcript Walk-Through` (or `## Chronological Walk-Through`)
-  - `## Key Decisions`
-  - `## Open Questions` (or `## Open Questions / Non-Decisions`)
-  - `## Next Steps` ← **dedicated section, distinct from Action Items**
-  - `## Action Items`
-- `## Next Steps` MUST be present even if empty (`_None this meeting._`) — missing the section is a defect.
-- Per meeting block: total length ≥ **800 characters**.
-- Action items: every bullet has owner + due (date OR "TBD" with reason) + `[source: …]` citation.
+Pull skills will, by default, race to the shallowest possible output: a 1-line
+title, a sender, a date, no detail. That output is useless for State/, useless
+for Q&A, useless for consolidation.
 
-### CRM/ADO snapshot (`crm/snapshot/*.md`, `ado/snapshot/*.md`)
+The depth bar makes "shallow CSC" a **defect**, not a tradeoff.
 
-- Snapshot lists ≥ **8 fields** with values (not just an ID + a link).
+## Hard rule
 
-### CRM/ADO stream (`crm/stream/*.md`, `ado/stream/*.md`)
+Every CSC entity block MUST satisfy the per-source minimum bullet thresholds
+below. If an entity is genuinely shallow (e.g., a 1-line "thanks" email),
+write it as a coverage-notes-only block — do NOT pad with fabricated bullets.
 
-- Each change event has old-value → new-value + actor + timestamp.
-
-## Red-flag patterns (auto-fail)
-
-Any file containing these strings outside a `## Coverage Notes` block fails:
-
-- `(see original in …)` / `see original email` / `see Teams thread` / `see page` — link-only stubs.
-- `Full body unavailable` / `body not captured` without an accompanying `## Coverage Notes` explaining why.
-- `Summary: …` as the entire body (no detail beneath it).
-- `[redacted]` without justification.
-- `TODO` / `FIXME` left in production evidence.
-
-## Retry policy
-
-When a file fails the detector:
-
-1. **Auto-retry once** with a deeper WorkIQ query. Append `"give me full bodies and full reply chain — not just metadata"` (or source-appropriate equivalent) to the query. Re-write the file.
-2. If the second attempt still fails the detector, emit the **paste-prompt** (see `plugin/templates/paste-prompt.md`) to the user with the specific file path, the failing checks, and ready-to-paste section headers.
-3. Mark the file with `⚠ thoroughness: pending-paste` at the top under `## Source Basis` and log `thoroughness-pending` in `run-log.yml` for that source. Continue the rest of the run — do NOT block.
-
-## Validation block in every evidence file
-
-Every evidence file MUST end with:
-
-```
-## Validation
-
-- [ ] bodies-present
-- [ ] attendees-or-participants-captured       <!-- meetings/teams only -->
-- [ ] next-steps-section-present               <!-- meetings only -->
-- [ ] action-items-have-owner-and-due          <!-- meetings only -->
-- [ ] no-link-only-stubs
-- [ ] coverage-notes-explain-any-gaps
-```
-
-The skill ticks the boxes it can verify automatically; the rest are left for `self-check` and human review.
-
-## Out of scope
+## Per-source minimum thresholds
 
-This detector does NOT enforce citation density (that's `citation-ledger.instructions.md`) or snapshot-vs-stream placement (that's `snapshot-vs-stream.instructions.md`). It enforces depth-of-capture only.
+Counts are TOTAL material bullets across all sections of the block (excluding
+the heading line and `_None surfaced._` placeholders). Citation lines do not
+count as separate bullets.
+
+| Source | Min bullets per block | Min sections populated | Notes |
+|---|---|---|---|
+| meetings | 25 | 6 | Must include Topics, Q&A or Who Said What, Decisions or Next Steps, Action Items, Participants, Artifacts |
+| email (thread) | 8 | 4 | Must include Participants, Topics, Action Items or Next Steps, Decisions or Q&A |
+| teams (chat thread) | 6 | 3 | Must include Participants, Topics, Q&A or Action Items |
+| teams (channel post) | 5 | 3 | Must include Participants, Topics, plus one of Q&A / Decisions / Action Items |
+| onenote (page) | 10 | 4 | Must include Topics, Dates & Numbers or Decisions, Action Items or Next Steps, Artifacts |
+| sharepoint (doc) | 8 | 3 | Must include Topics, Artifacts, plus one of Decisions / Customer Asks / Dates & Numbers |
+| crm (opportunity/account) | 12 | 5 | Must include Participants, Dates & Numbers, Next Steps, Customer Asks, Artifacts |
+| ado (work item) | 8 | 4 | Must include Participants (assignee + reporter), Topics, Action Items or Next Steps, Artifacts |
+
+If the entity truly cannot meet the bar (e.g., 2-message chat about lunch):
+write **only** the heading + a `Coverage Notes` section explaining why, and
+flag `low-signal: true` in `_index/entities.yml`. Do not pad.
+
+## Per-section depth rules
+
+- **Topics Discussed**: at least one bullet per distinct subject in the entity.
+  A 45-minute meeting that covers 6 subjects MUST have at least 6 topic bullets.
+  "Various topics discussed" is a defect.
+- **Q&A**: capture every question that was asked AND answered. Format:
+  `Q (asker): ... → A (responder): ... [citation]`. Unanswered questions
+  belong in `Open Questions`, not `Q&A`.
+- **Who Said What**: curated to material statements only (positions stated,
+  commitments made, disagreements voiced). Typical: 3–10 entries per
+  50-message thread. NOT a verbatim utterance log.
+- **Dates & Numbers Shared**: every number, date, dollar amount, percentage,
+  count, deadline, version, or SKU mentioned. Format: `<value> — <context> [citation]`.
+- **Action Items**: each bullet MUST have owner + due (or `owner: unassigned`,
+  `due: unspecified`). Missing both fields = defect.
+- **Next Steps**: forward-looking commitments without strict owner+due. Distinct
+  from Action Items.
+- **Customer Asks**: every explicit customer request (feature, capacity, support,
+  pricing, timeline). One bullet per ask.
+
+## Coverage Notes are mandatory when
+
+- WorkIQ returned partial data (truncation, payload-too-large, retry-deferred).
+- Body was unavailable for an entity (write `Source basis: unavailable`).
+- Participant list was inferred from a forwarded thread (note `Participants inferred from forward chain`).
+- An entity was discovered by another contributor and the current contributor
+  could not reach it (defer per `defer-on-permission.instructions.md`).
+
+## Detector (used by `self-check/run.ps1`)
+
+Deep checks D11–D15 enforce this doctrine. Summary:
+
+- **D11**: Every `weekly/YYYY-MM-DD_<source>-csc.md` has ≥ 1 entity heading.
+- **D12**: Every entity block's section order matches the canonical order
+  defined in `comprehensive-structured-capture.instructions.md`.
+- **D14 (prose detector)**: No line in a weekly CSC file may exceed 220
+  characters without starting with `-`, `*`, `#`, `>`, `|`, or `` ` ``.
+  Heuristic: such lines are prose paragraphs and indicate v4.8.x narrative
+  summary leakage.
+- **D15 (no-omission detector)**: Forbidden phrases anywhere in a weekly
+  CSC block outside a `Coverage Notes` section:
+  - `and N more` / `and N others`
+  - `key highlights only`
+  - `sample of` / `subset of`
+  - `N of M shown` / `truncated`
+  - `summary above`
+  Their presence = defect; the block must be re-pulled with broader scope or
+  the missing items must be enumerated.
+- **D11.depth**: For each entity heading, count material bullets (lines
+  starting `- ` or `* ` inside a non-coverage section). Compare to per-source
+  threshold above. If below threshold AND `low-signal: true` is NOT set in
+  `_index/entities.yml`, emit a defect.
+
+## What this REPLACES
+
+- v4.8.x "AI Narrative Summary (3+ paragraphs, ≥ 800 chars per entity)" — **gone**.
+  Prose paragraphs anywhere in a weekly CSC file are a D14 defect.
+- v4.8.x "verbatim body required; if missing, the entity is partial" — **gone**.
+  A CSC block stands on its own. Verbatim is only required for meetings
+  (sibling `verbatim/` folder, audit-only — see
+  [`meetings-verbatim-required.instructions.md`](./meetings-verbatim-required.instructions.md)).
+
+## What this DOES NOT change
+
+- WorkIQ-first stays mandatory. CSC bullets must be sourced from WorkIQ output.
+- Citation-per-material-bullet stays mandatory.
+- Defer-on-permission stays mandatory — if WorkIQ cannot reach an entity,
+  defer with marker, do not fabricate from adjacent evidence.
+- Meetings still require a sibling raw `verbatim/<dir>/` folder for the audit
+  trail (Teams retention purges recordings ~60 days).
+
+## Related
+
+- [`comprehensive-structured-capture.instructions.md`](./comprehensive-structured-capture.instructions.md) — canonical CSC block schema
+- [`weekly-csc.instructions.md`](./weekly-csc.instructions.md) — layout + `_index/`
+- [`evidence-layout-canonical.instructions.md`](./evidence-layout-canonical.instructions.md) — folder tree
+- [`meetings-verbatim-required.instructions.md`](./meetings-verbatim-required.instructions.md) — meetings audit folder

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

@@ -85,13 +85,13 @@ The `setup` skill (added v4.4.4) extends this doctrine beyond identity to cover
 | `project-evidence.yml` | `identity.alias` / `display_name` / `email` | YES | WorkIQ "Who am I?" |
 | `project-evidence.yml` | `identity_status`, `identity_verified_at` | YES | written by setup |
 | `project-evidence.yml` | `projects_root` | YES | cwd-ancestor detection; otherwise prompt |
-| `project-evidence.yml` | `default_onenote_notebook` | **OPTIONAL** | user prompt; value `<skip>` = OneNote disabled |
+| `project-evidence.yml` | `default_onenote_notebook` | **DEPRECATED (display-only as of v4.8.3)** | display-only mirror of `m365-auth.json#oneNote.defaultNotebookName`. NEVER gates OneNote. The `<skip>` sentinel is deprecated. |
 | `project-evidence.yml` | `active_projects[]` | YES (list, may be empty) | the project arg if dispatched from `bootstrap <project>`; otherwise leave existing |
 | `project-evidence.yml` | `workiq.cli_path` | OPTIONAL | only written when discovered via PATH/fallback, not already pinned |
 | `m365-auth.json` | `_meta.owner` | YES | `<identity.email>` |
 | `m365-auth.json` | `oneNote.defaultLinkOwner` | YES (when OneNote enabled) | `<identity.email>` — the user's own UPN, since OneNote queries default to the user's personal notebook |
 | `m365-auth.json` | `oneNote.defaultNotebookId` | **NOT WRITTEN (kushi v4.7.3+)** | Per `workiq-onenote-query-shape.instructions.md`, WorkIQ has no notebook-ID lookup surface — any such probe punts to Graph Explorer. Setup persists `defaultNotebookName` only; section IDs are discovered per-section at bootstrap/refresh time using the natural-language WorkIQ pattern. |
-| `m365-auth.json` | `oneNote.enabled` | YES | `false` when user chose `<skip>` for the notebook name |
+| `m365-auth.json` | `oneNote.enabled` | YES | **default `true` (kushi v4.8.3+).** Single source of truth — the only field that gates OneNote across kushi. Set to `false` ONLY when the contributor explicitly opts out via `setup` or by hand. The legacy `project-evidence.yml#default_onenote_notebook == "<skip>"` sentinel is deprecated and no longer consulted. |
 | `m365-auth.json` | `emailContext.folders[]` | OPTIONAL | user prompt: comma-sep list / `all` / blank. `all` or blank → `[]` (full mailbox) |
 | `m365-auth.json` | `sharePointContext.localProjectsRoot` | YES | mirrors `<projects_root>` |
 
@@ -101,10 +101,12 @@ The `setup` skill (added v4.4.4) extends this doctrine beyond identity to cover
 
 The `setup` skill does the deeper recovery (3-retry loop with `ask_user` choices).
 
-### OneNote — optional + auto-resolve
+### OneNote — enabled by default, single switch (kushi v4.8.3+)
 
-- User chose `<skip>` → set `oneNote.enabled: false`, leave all other OneNote fields blank, OneNote source becomes a no-op (reported as `not-applicable` in run logs).
-- User gave a notebook name → query WorkIQ for `{notebookId, notebookSourceDoc, notebookSpoBaseUrl}`. Persist all three. If WorkIQ returns empty, leave `defaultNotebookId: ""` with a `_defaultNotebookId_note` and let `pull-onenote` Step A do per-section discovery.
+- **Default:** `m365Auth.oneNote.enabled: true`. OneNote is opt-out, not opt-in.
+- **Single source of truth:** `m365Auth.oneNote.enabled` is the ONLY field that gates OneNote across kushi. Downstream skills (`pull-onenote`, `bootstrap-project` Step 4) MUST NOT inspect `project-evidence.yml#default_onenote_notebook` to decide whether to run OneNote.
+- User explicitly opted out → set `oneNote.enabled: false`, leave other OneNote fields blank, OneNote source becomes a no-op (reported as `not-applicable` in run logs). Re-enable by hand-editing `m365-auth.json` (`enabled: true`) or by running `setup --reconfigure`.
+- User gave a notebook name (or accepted the `ISE Work` default) → keep `enabled: true`, persist `defaultNotebookName`. Do NOT query WorkIQ for the notebook ID (per `workiq-onenote-query-shape.instructions.md` — no notebook-inventory surface). Section IDs are discovered per-section at bootstrap/refresh time.
 - `defaultLinkOwner` is ALWAYS the user's own UPN unless the user explicitly overrides (shared/team-owned notebook case).
 
 ### Mailbox folders — multi-value with "all" sentinel
@@ -131,11 +133,12 @@ Both `all` and blank persist as `[]`. ALWAYS print after persisting:
 ```
 Edit these files later if anything changes:
   • <workspace>/.kushi/config/user/project-evidence.yml
-      identity, projects_root, default_onenote_notebook, active_projects, workiq.cli_path
+      identity, projects_root, active_projects, workiq.cli_path
+      (default_onenote_notebook is display-only since v4.8.3 — edit m365-auth.json to enable/disable)
   • <workspace>/.kushi/config/user/m365-auth.json
-      OneNote defaults, email folder list, SharePoint root
+      OneNote enable/disable + notebook name (oneNote.enabled, oneNote.defaultNotebookName), email folder list, SharePoint root
   • <workspace>/.kushi/config/shared/integrations.yml   (team-wide; commit changes)
-      CRM environmentUrl + tenantId, ADO organization + project
+      CRM environment_url + tenant_id, ADO organization + project (ships pre-filled with Microsoft IS defaults since v4.8.4)
 
 To re-walk every question (overwrites all answers):
   @Kushi setup --reconfigure

package/plugin/instructions/meetings-verbatim-required.instructions.md

@@ -5,6 +5,8 @@ description: "HARD rule — meetings are an EXPIRING evidence class. Every meeti
 
 # Meetings verbatim is REQUIRED (HARD RULE, v3.10.0)
 
+> **v4.9.0 update**: the curated artifact moved from `meetings/snapshot/` or `meetings/stream/<week>.md` per-meeting blocks (prose + transcript walk-through) to `meetings/weekly/<week>_meetings-csc.md` per-meeting CSC blocks (bullets) per `comprehensive-structured-capture.instructions.md`. The verbatim folder requirement is **unchanged** — it remains required for every meeting because the source expires.
+
 Meetings differ from every other evidence class in one critical way: **the source expires.**
 
 - Teams recordings are deleted by tenant retention (default 60 days for many tenants; sometimes shorter).
@@ -18,10 +20,10 @@ Email bodies, OneNote pages, SharePoint files, CRM records, and ADO work items a
 
 For every meeting captured by `pull-meetings`, the skill MUST produce **two** outputs, not one:
 
-1. **Curated snapshot** — `Evidence/<alias>/Meetings/snapshot/<slug>.md` (existing) or `Evidence/<alias>/Meetings/stream/<week>_meetings-stream.md` per-meeting block (existing). 7-section doctrine summary. Human-readable.
-2. **Verbatim folder** — `Evidence/<alias>/Meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` (NEW, REQUIRED). Raw immutable artifacts that survive source expiry.
+1. **Curated CSC block** — `Evidence/<alias>/meetings/weekly/<YYYY-MM-DD>_meetings-csc.md` per-meeting block in CSC shape per `comprehensive-structured-capture.instructions.md` (v4.9.0+). Bulleted, query-able, human-readable. (Pre-v4.9.0: `Evidence/<alias>/meetings/snapshot/<slug>.md` or `stream/<week>_meetings-stream.md` — legacy-read OK.)
+2. **Verbatim folder** — `Evidence/<alias>/meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` (REQUIRED). Raw immutable artifacts that survive source expiry.
 
-A per-meeting block in `stream/` that has NO sibling `verbatim/<...>/` folder is a **defect**, even if the curated block is rich and well-cited. Self-check rule **D13** enforces this in deep mode.
+A per-meeting CSC block in `weekly/` that has NO sibling `verbatim/<...>/` folder is a **defect**, even if the curated block is rich and well-cited. Self-check rule **D13** enforces this in deep mode.
 
 ## "Verbatim" means the FULL TRANSCRIPT TEXT — not just chat (HARD RULE)
 
@@ -173,4 +175,4 @@ The curated snapshot is the assertion; the verbatim file is the evidence. The tw
 
 ## Apply
 
-`pull-meetings/SKILL.md` v2.2.0+ MUST cite this instruction in its front contracts blockquote. Templates `meetings-stream.template.md` and `meetings-series-index.template.md` MUST reference the verbatim/ folder location. Template `meeting-verbatim.template.md` defines the standard contents of a verbatim folder.
+`pull-meetings/SKILL.md` v2.2.0+ MUST cite this instruction in its front contracts blockquote. Template `meetings-weekly-csc.template.md` (v4.9.0+) MUST reference the verbatim/ folder location per CSC block; legacy templates `meetings-stream.template.md` and `meetings-series-index.template.md` are kept for reader compatibility but no longer written by pull-meetings v2.5.0+. Template `meeting-verbatim.template.md` defines the standard contents of a verbatim folder (unchanged).

package/plugin/instructions/scope-boundaries.instructions.md

@@ -57,7 +57,7 @@ returns evidence over the same surface — no run-to-run drift.
 
 | Skill | Hard prerequisite | Failure message (verbatim) |
 |---|---|---|
-| `pull-crm` | `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `crm.environmentUrl` | `crm-config-missing — fill the crm: block in <workspace>/.kushi/config/shared/integrations.yml. See plugin/templates/init/integrations.template.yml.` |
+| `pull-crm` | `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `crm.environment_url` (ships pre-filled as `https://iscrm.crm.dynamics.com` since kushi v4.8.4) | `crm-config-missing — the crm: block in <workspace>/.kushi/config/shared/integrations.yml has been emptied. Reset from plugin/templates/init/integrations.template.yml.` |
 | `pull-ado` | `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `ado.organization` AND `ado.defaultProject` | `ado-config-missing — fill the ado: block in <workspace>/.kushi/config/shared/integrations.yml. See plugin/templates/init/integrations.template.yml.` |
 | `propose-ado-update` | both above + `integrations.yml ado.engagement_id > 0` | per `propose-ado-update/SKILL.md` Prerequisites table |
 

package/plugin/instructions/snapshot-vs-stream.instructions.md

@@ -1,6 +1,30 @@
 ---
 applyTo: "**"
-description: "Snapshot vs Stream — every source has two evidence shapes. Snapshot = current state of entity (replace on refresh). Stream = timestamped events (append-only, weekly buckets)."
+description: "DEPRECATED in kushi v4.9.0 — replaced by weekly-csc.instructions.md. Sources no longer split into snapshot/ + stream/; every source now writes a single weekly/ CSC file per ISO-week plus a _index/entities.yml. Legacy snapshot/+stream/ folders remain readable but no new writes go to them."
+---
+
+# ⚠️ DEPRECATED in v4.9.0 — see `weekly-csc.instructions.md`
+
+The two-folder model (`snapshot/` = current state, `stream/` = events) caused two recurring
+problems:
+
+1. **Empty snapshot/ folders** when WorkIQ refused bulk verbatim or `m365_get_email`
+   tool-errored — users perceived these as "kushi captured nothing".
+2. **Awkward queries** — answering "what happened this week?" required reading two folders
+   per source × 7 sources = 14 reads per query.
+
+**v4.9.0 replacement:** every source writes ONE artifact shape — weekly CSC files at
+`Evidence/<alias>/<source>/weekly/YYYY-MM-DD_<source>-csc.md`, plus a per-source
+`_index/entities.yml` for current-state lookup. Each weekly file contains one CSC block per
+entity touched that week, self-contained (current state + this-week's events). See
+`weekly-csc.instructions.md`.
+
+**Reader fallback:** build-state / ask-project / consolidate-evidence still READ legacy
+`snapshot/` + `stream/` folders when `weekly/` is empty for that source (graceful migration —
+no rewrites). New writes go to `weekly/` only.
+
+**Below this line: historical content, no longer normative for writes.**
+
 ---
 
 # Snapshot vs Stream (HARD RULE)

package/plugin/instructions/verbatim-by-default.instructions.md

@@ -1,6 +1,26 @@
 ---
 applyTo: "**"
-description: "Verbatim-by-default rule — every pull-* skill captures full bodies and full content as the default mode. Headlines / one-line summaries / 'preview only' are defects. The user does NOT have to ask for detail; detail is the contract."
+description: "DEPRECATED in kushi v4.9.0 — replaced by comprehensive-structured-capture.instructions.md (CSC). Raw verbatim bodies are no longer the default depth bar; CSC bullets are. This file is retained as historical reference and is no longer normative."
+---
+
+# ⚠️ DEPRECATED in v4.9.0 — see `comprehensive-structured-capture.instructions.md`
+
+This doctrine required every pull-* skill to capture **raw verbatim bodies** (full email body,
+full transcript line-by-line, full OneNote page body) plus multi-paragraph AI Narrative
+Summaries. In practice this failed (WorkIQ payload-too-large for OneNote, `m365_get_email`
+~100% tool-error rate, Teams transcripts often not generated). Empty `snapshot/` folders +
+200-char previews were the result.
+
+**v4.9.0 replacement:** every per-entity evidence block is now a **Comprehensive Structured
+Capture (CSC)** — bulleted sections capturing every material fact with citations, but no raw
+prose / verbatim body. See `comprehensive-structured-capture.instructions.md`.
+
+**Audit-only exception:** meetings keep a raw `verbatim/<dir>/transcript.txt` audit folder
+because Teams recordings expire (tenant retention). All other sources drop the raw-verbatim
+requirement entirely. See `meetings-verbatim-required.instructions.md` (still active).
+
+**Below this line: historical content, no longer normative.**
+
 ---
 
 # Verbatim-by-default (HARD RULE)