kushi-agents 4.8.3 → 5.0.0

package/plugin/instructions/evidence-layout-canonical.instructions.md

@@ -30,13 +30,13 @@ For every project under `<engagement-root>/`:
       .settings.yml
       refresh-reports/
       open-questions/
-      ado/        { snapshot/ , stream/ }
-      crm/        { snapshot/ , stream/ }
-      email/      { snapshot/ , stream/ , _index/ , _legacy_*/ }
-      meetings/   { snapshot/ , stream/ , verbatim/ }
-      onenote/    { snapshot/ , stream/ , refresh-reports/ }
-      sharepoint/ { snapshot/ , stream/ }
-      teams/      { snapshot/ , stream/ }
+      ado/        { weekly/ , _index/ }                                     # legacy-read: snapshot/, stream/
+      crm/        { weekly/ , _index/ }                                     # legacy-read: snapshot/, stream/
+      email/      { weekly/ , _index/ , _legacy_*/ }                        # legacy-read: snapshot/, stream/
+      meetings/   { weekly/ , _index/ , verbatim/ }                         # verbatim/ is required (expiring source); legacy-read: snapshot/, stream/
+      onenote/    { weekly/ , _index/ , refresh-reports/ }                  # legacy-read: snapshot/, stream/
+      sharepoint/ { weekly/ , _index/ }                                     # legacy-read: snapshot/, stream/
+      teams/      { weekly/ , _index/ }                                     # legacy-read: snapshot/, stream/
   State/                         # rendered by build-state (read-only outcome)
   Reports/                       # rendered by aggregate / fde-report (read-only)
   integrations.yml               # per-project boundaries (scope-boundaries.instructions.md)
@@ -44,21 +44,27 @@ For every project under `<engagement-root>/`:
 
 `Evidence/` and `<alias>/` are the **only** levels a pull skill may create under `<project>/`. Nothing else.
 
+**v4.9.0 shape change:** pull-* skills now write a single `weekly/` folder per source + a thin
+`_index/entities.yml`, per `weekly-csc.instructions.md`. The old `snapshot/` + `stream/`
+folders are **legacy** — readers may still read them (for graceful migration), but no new
+writes go to them. `meetings/verbatim/<dir>/` is kept (the only expiring source). See
+`weekly-csc.instructions.md` for the writer/reader contracts.
+
 ### Rule 2 — Sibling source-output folders under `<project>/` are FORBIDDEN
 
 Concretely, a pull skill MUST NOT create or write to any of these (representative — list is illustrative, not exhaustive):
 
 | Forbidden path | Canonical replacement |
 |---|---|
-| `<project>/email-context/` | `<project>/Evidence/<alias>/email/snapshot/` + `stream/` |
+| `<project>/email-context/` | `<project>/Evidence/<alias>/email/weekly/` |
 | `<project>/email/` (at project root) | `<project>/Evidence/<alias>/email/` |
-| `<project>/notes/` | `<project>/Evidence/<alias>/onenote/snapshot/pages/` |
-| `<project>/_Weekly Summaries/` | `<project>/Evidence/<alias>/<source>/stream/` |
+| `<project>/notes/` | `<project>/Evidence/<alias>/onenote/weekly/` |
+| `<project>/_Weekly Summaries/` | `<project>/Evidence/<alias>/<source>/weekly/` |
 | `<project>/Meetings/` (at project root) | `<project>/Evidence/<alias>/meetings/` |
 | `<project>/Teams/` (at project root) | `<project>/Evidence/<alias>/teams/` |
 | `<project>/SharePoint/` (at project root) | `<project>/Evidence/<alias>/sharepoint/` |
 | `<project>/CRM/`, `<project>/ADO/` (at project root) | `<project>/Evidence/<alias>/{crm,ado}/` |
-| any `<project>/<source>-context/`, `<project>/<source>-summary/`, etc. | `<project>/Evidence/<alias>/<source>/snapshot/` |
+| any `<project>/<source>-context/`, `<project>/<source>-summary/`, etc. | `<project>/Evidence/<alias>/<source>/weekly/` |
 
 `State/`, `Reports/`, `integrations.yml` are the **only** top-level siblings of `Evidence/` that pull/refresh skills are allowed to leave alone (they are written by `build-state`, `aggregate-project`, and bootstrap respectively — not by pull-* skills).
 
@@ -103,7 +109,9 @@ Together they guarantee that two contributors running the same verb on the same
 
 ## Cross-references
 
-- `snapshot-vs-stream.instructions.md` — the two shapes inside each `<source>/` folder.
+- `weekly-csc.instructions.md` — the v4.9.0 layout inside each `<source>/` folder (weekly/ + _index/).
+- `snapshot-vs-stream.instructions.md` — DEPRECATED v4.9.0; legacy two-folder model.
+- `comprehensive-structured-capture.instructions.md` — the v4.9.0 block shape inside weekly/ files.
 - `scope-boundaries.instructions.md` — what each source is allowed to query (orthogonal: scope vs path).
 - `side-by-side-config.instructions.md` — config files (mutable hints, integrations.yml) live under `<workspace>/.kushi/config/` (v4.4.0+, was `<engagement-root>/.project-evidence/`).
 - `run-reports.instructions.md` — every layout-migration MUST appear in the refresh report.

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/guided-tour.instructions.md

@@ -0,0 +1,100 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Guided tour. Auto-generated week-in-review markdown walkthrough at `<project>/State/tour.md`. Score: `recency_weight × cross_ref_count`. recency_weight = exp(-days_since_last_touched / 14). cross_ref_count = degree in the graph. DFS through edges in priority order (decides → action-item-tracks → discusses → references → others). Default top-N = 10 (configurable via `m365Mutable.tour.topN`)."
+---
+
+# Guided Tour — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+After link-entities + build-state, the project has a graph and a wiki, but
+nothing tells a reader **where to start**. The tour is a small ranked
+walkthrough that picks the most-recent, highest-degree entities and DFS-walks
+their connections in order of edge importance.
+
+## Output
+
+- **Path:** `<engagement-root>/<project>/State/tour.md`
+- **Producer:** `tour` skill.
+- **Idempotency:** fully regenerated each run.
+- **Empty case:** if `_graph/project-graph.json` has zero nodes, `tour.md` is
+  written with a single line: `_No graph nodes — run @Kushi refresh first._`
+
+## Scoring
+
+For each node N in the graph:
+
+```
+days_since = max(0, today - last_touched_iso)        # in whole days, UTC
+recency_weight = exp(- days_since / 14)              # 14-day half-life ≈ ln(2)/14 ≈ 0.0495
+cross_ref_count = degree(N)                          # in + out edges, dedupe by edge identity
+score(N) = recency_weight × cross_ref_count
+```
+
+Sort nodes by `score` descending. Take the top-N (default 10; configurable
+via `m365Mutable.tour.topN` in the user's per-project mutable config).
+
+## DFS ordering
+
+Tour stops are emitted in DFS order starting from the highest-scored node:
+
+1. Start with the highest-scored unvisited node → emit it as the next stop.
+2. Pick the next node by walking that node's edges in **edge priority order**:
+   1. `decides`
+   2. `action-item-tracks`
+   3. `discusses`
+   4. `references`
+   5. (any other kind in `entity-graph.instructions.md` taxonomy)
+   Within a priority bucket, prefer the edge whose target has the highest
+   unvisited `score`.
+3. Skip nodes already visited (cycle break).
+4. If the DFS hits a dead end before reaching N stops, restart from the
+   next-highest-scored unvisited node.
+5. Stop after N stops emitted.
+
+## Per-stop markdown shape
+
+```markdown
+## <ordinal>. <Node title>
+
+> _Why this matters:_ <one-line synthesis — recency + degree + dominant edge
+> kind, e.g. "Touched 3 days ago; ties together 5 ADO items and 2 CRM
+> opportunities."_
+
+- **Source:** `<source>` · last touched `YYYY-MM-DD`
+- **Cite:** [`<alias>/<source>/weekly/<file>#<anchor>`](<relative path>)
+- **Related State pages:** [[slug-a]] · [[slug-b]] · …
+```
+
+Citations MUST resolve on disk (D23.tour enforces this).
+
+## Header
+
+The file starts with:
+
+```markdown
+---
+kushi_tour: true
+generated_at: <ISO-8601 UTC>
+generated_by_alias: <alias>
+top_n: <N>
+score_basis: "recency_weight × cross_ref_count (14-day half-life)"
+---
+
+# Guided Tour — <project>
+
+> _Auto-generated week-in-review. <N> top entities by recency × cross-reference count._
+```
+
+## Self-check
+
+`D23.tour` enforces:
+
+- If `_graph/project-graph.json` has ≥ 1 node, `State/tour.md` exists.
+- Every tour stop's citation resolves to an existing weekly file + anchor.
+
+## Cross-references
+
+- `entity-graph.instructions.md` — source of nodes + edge taxonomy.
+- `karpathy-state-layout.instructions.md` — `[[wikilink]]` resolution rules
+  used by per-stop "Related State pages".

package/plugin/instructions/host-portability.instructions.md

@@ -0,0 +1,77 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Host portability contract. `plugin/agents/kushi.agent.md` is the single source of truth for the multi-host top-level agent contract. Per-skill `plugin/skills/<n>/SKILL.md` files are host-portable (Claude Code skills, Clawpilot, Codex AGENTS.md, Copilot custom agents, Cursor, Gemini CLI). The install scripts mirror agent.md → SKILL.md for hosts that discover via SKILL.md (e.g. Clawpilot). No code changes are required by this doctrine — it is a contract write-up."
+---
+
+# Host Portability — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+Kushi is shipped through several distinct host surfaces:
+
+- **GitHub Copilot** (VS Code) — discovers via `.github/copilot-instructions.kushi.md`.
+- **Clawpilot** (a Copilot fork) — discovers via `~/.copilot/m-skills/kushi/SKILL.md`.
+- **Claude Code** — discovers via the Claude Code skills system (per-skill
+  `SKILL.md` in a known location).
+- **Codex / OpenAI Agents SDK** — discovers via `AGENTS.md` at the project root.
+- **Cursor** — discovers via `.cursor/rules/*.md`.
+- **Gemini CLI** — discovers via per-skill markdown.
+
+All of these surfaces consume the **same** prose. v5.0.0 formalizes that one
+file is the source of truth and the install scripts mirror it where required.
+
+## Source of truth
+
+`plugin/agents/kushi.agent.md` is the canonical top-level agent contract. It
+describes the verbs, the routing, the global rules, and the references to
+every skill / instruction / prompt.
+
+Every other host-facing entry point (the live install's `SKILL.md`, the
+`.github/copilot-instructions.kushi.md` shim, the `AGENTS.md` written into a
+project's `State/`) is **derived** from this file via:
+
+1. `src/main.mjs` — mirrors `plugin/agents/kushi.agent.md` →
+   `~/.copilot/m-skills/kushi/SKILL.md` during `npx kushi-agents
+   --clawpilot` install. See the existing top-of-file comment in
+   `src/main.mjs`:
+
+   > `// Mirror agents/kushi.agent.md as top-level SKILL.md for Clawpilot discovery.`
+
+2. `plugin/templates/state/CLAUDE.template.md` / `AGENTS.template.md` —
+   per-project agent doc, written by `build-state` into `<project>/State/`.
+   The two templates are byte-identical (see
+   `karpathy-state-layout.instructions.md`); both reiterate "this is a kushi
+   project, use `[[wikilinks]]`, cite `Evidence/<alias>/<source>/weekly/...`
+   for every claim."
+
+Self-check `D4` already enforces byte-identical parity between
+`plugin/agents/kushi.agent.md` and the live install's `SKILL.md`.
+
+## Per-skill portability
+
+Every per-skill `plugin/skills/<n>/SKILL.md` is host-portable by construction:
+
+- Frontmatter (`name`, `version`, `description`) matches the Claude Code
+  skills system and the Clawpilot skills system.
+- Skill prose uses relative markdown links (`../../instructions/<x>.md`) that
+  resolve regardless of which host root the file is rendered under.
+- No host-specific tool names appear in the SKILL.md body. Tool dispatch
+  happens through neutral verbs (`WorkIQ`, `m365_*`) that each host wires up
+  in its own way.
+
+## No code changes
+
+This doctrine introduces **no** new code or mirror behavior. The install
+scripts already do the right thing; v5.0.0 simply documents the contract so
+future hosts can be added by:
+
+1. Reading `plugin/agents/kushi.agent.md`.
+2. Pointing the new host's discovery at that file (or a mirrored copy).
+3. Re-running self-check to confirm `D4` still passes.
+
+## Cross-references
+
+- `kushi-config-root.instructions.md` — config layout is also host-portable
+  (vscode `<workspace>/.kushi/` vs Clawpilot `~/.copilot/m-skills/kushi/`).
+- `karpathy-state-layout.instructions.md` — per-project `State/CLAUDE.md` +
+  `State/AGENTS.md` are the per-project portability mirror.

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

@@ -138,7 +138,7 @@ Edit these files later if anything changes:
   • <workspace>/.kushi/config/user/m365-auth.json
       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