kushi-agents 3.4.2 → 3.13.0

package/plugin/instructions/crm-internal-vs-confirmed.instructions.md

@@ -0,0 +1,79 @@
+---
+applyTo: "**"
+---
+
+# CRM field values vs confirmed facts — HARD rule (kushi v3.11.0+)
+
+## The rule
+
+**A CRM field value is NEVER automatically a confirmed fact.** A Dataverse field update records an internal decision; it does not prove the decision has been (a) communicated to the customer, (b) approved by deal desk / finance / legal, or (c) confirmed in a customer-facing transcript, note, email, or meeting artifact.
+
+Adapted into kushi from Nova doctrine (see `fde-grounding.instructions.md > CRITICAL: CRM Field Values vs. Confirmed Facts`).
+
+## Three states every CRM-sourced assertion must be classified into
+
+1. **Internal-only decision** — team recorded a direction in a CRM field, but no customer-facing or external-stakeholder evidence confirms it. Status fields commonly look like this (e.g. `Not Yet Requested`, `Pending`, `Evaluating`, `TBD`). **DO NOT** write this as a settled fact in State/, FDE reports, or 6Q.
+2. **Communicated to customer** — there exists a customer-facing transcript / note / email / meeting that postdates the CRM field update and references the decision. Still not final — typically still pending commercial / deal-desk approval.
+3. **Confirmed with all stakeholders** — customer agreement + commercial approval + (where applicable) legal sign-off / signed artifact. Only this state is a settled fact and may be reported as such.
+
+## How to apply recency precedence correctly to CRM fields
+
+- The CRM field's `modifiedon` timestamp shows when the record was **updated**, NOT when the decision was **confirmed**.
+- For every materially important CRM field claim (funding model, scope decision, owner, timeline gate, SI lane, ECIF / ESIF state), **cross-check against the latest customer-facing artifact** in `Evidence/<alias>/{meetings,email,onenote,teams,sharepoint}/` (use `meetings/verbatim/*/transcript.*` first per `meetings-verbatim-required.instructions.md`).
+- If the latest customer-facing artifact predates the CRM field update AND no post-update customer-facing artifact confirms the decision → state explicitly as `internal decision recorded in CRM (<date>), pending customer/deal-desk confirmation (no confirming artifact found post-<date>)`.
+- If a post-update artifact confirms → cite both (CRM date + confirming artifact + date).
+- If a post-update artifact contradicts → mark `Conflicting evidence` and surface to `<project>/State/09_open-questions.md` (full profile) or `<project>/OPEN-QUESTIONS-DRAFT.md` (standard profile).
+
+## Required output classification for State/, FDE reports, consolidation, ask-project answers
+
+Every materially important CRM-sourced assertion in any kushi-generated artifact must be tagged as one of:
+
+- `CRM-only` — internal signal, no external confirmation
+- `Cross-verified` — confirmed by ≥ 1 non-CRM artifact (cite both)
+- `Conflicting evidence` — non-CRM source contradicts CRM/form (cite both, list in open questions)
+
+Acceptable non-CRM confirmation sources (in priority order per kushi precedence):
+
+1. Meeting transcripts (`Evidence/<alias>/meetings/verbatim/*/transcript.*`)
+2. Curated meeting stream notes (`Evidence/<alias>/meetings/stream/*.md`)
+3. OneNote pages
+4. ADO work-item discussions / comments
+5. Emails (sender-domain matching customer)
+6. Teams chats / channels
+7. Approved shared artifacts (SharePoint / Loop / docs)
+
+## Citation format
+
+```
+[source: CRM record FE-XXX field <field-name> · YYYY-MM-DD (internal-only)]
+[source: CRM record FE-XXX field <field-name> · YYYY-MM-DD; cross-verified by Evidence/<alias>/meetings/verbatim/<dir>/transcript.vtt · YYYY-MM-DD]
+[source: CRM record FE-XXX field <field-name> · YYYY-MM-DD; conflicts with Evidence/<alias>/email/snapshot/<file>.md · YYYY-MM-DD — see open questions]
+```
+
+## Worked example
+
+- 2026-03-20 transcript: team exploring funding options.
+- 2026-03-23 transcript: alternative under discussion.
+- 2026-03-26: CRM `new_ecifstatus` updated to `Not Yet Requested`.
+- 2026-04-08 (today): no post-3/26 transcript confirms ECIF with customer or deal desk.
+
+**Correct write-up:**
+> Internal team decision favors ECIF (per CRM 3/26 update) but formal approval from deal desk and customer confirmation are still pending. Latest customer-facing transcript (3/23) predates the CRM decision; no post-decision confirmation found. `[source: CRM record FE-XXX field new_ecifstatus · 2026-03-26 (internal-only)]`
+
+**Incorrect write-up (forbidden):**
+> ECIF is the selected funding model. `[source: CRM record FE-XXX field new_ecifstatus · 2026-03-26]`
+
+## Where this rule binds
+
+- `skills/build-state/` — every CRM-sourced row in `State/01_decisions.md`, `State/05_action-items.md`, `State/06_risks-and-issues.md`, `State/07_timeline-and-milestones.md` must carry the 3-state tag and the cross-check citation chain.
+- `skills/ask-project/` — answers grounded in CRM fields must explicitly distinguish internal-only vs cross-verified; never collapse into a bare assertion.
+- `skills/fde-report/` / `skills/fde-triage/` — FDE Triage Living Reports follow this rule; the `Verification Evidence` section is required for any CRM-sourced gate.
+- `skills/consolidate-evidence/` — when merging across contributors, conflicting CRM-vs-non-CRM evidence becomes a `Conflicting evidence` row, never silently resolved.
+
+## Anti-patterns
+
+1. Treating a CRM `Status` field as proof of customer commitment.
+2. Reading CRM `modifiedon` as the decision-confirmation date.
+3. Claiming "ECIF selected" / "Lane X chosen" / "Customer signed off" from CRM alone with no post-date customer-facing artifact.
+4. Blending CRM internal decision and older customer-facing context into one averaged narrative without flagging the gap.
+5. Dropping the `(internal-only)` tag in citations because it "reads cleaner".

package/plugin/instructions/evidence-confidence-ladder.instructions.md

@@ -0,0 +1,66 @@
+---
+applyTo: "**"
+excludeAgent: "code-review"
+---
+
+# Evidence Confidence Ladder — Always-On
+
+When Kushi (or any consumer of Kushi evidence) makes a claim about a customer's decision, status, funding, scope, owner, or commitment, that claim must be tagged with one of three confidence states. Treat the lower two as provisional. **Do not collapse them into "decided" just because a structured field shows a value.**
+
+## The three states
+
+### 1. `internal-only` (lowest confidence)
+
+A field, note, or status reflects an **internal team decision recorded in a system of record**. The customer has not been formally informed; deal-desk / commercial / legal approval is not in evidence.
+
+- Examples: a CRM `statuscode` updated to `Not Yet Requested`, an option-set field flipped, an internal CRM annotation added by an MS team member.
+- Render: `internal-only — recorded in CRM <date> by <owner>; no customer-facing confirmation in evidence`.
+
+### 2. `communicated` (medium confidence)
+
+The decision has been **shared with the customer or external stakeholder** in a meeting, email, Teams chat, or shared artifact. Acknowledgment is on record. Commercial / legal / deal-desk approval may still be pending.
+
+- Examples: latest meeting transcript shows the customer accepting the direction; an email from MS to customer + reply acknowledgment.
+- Render: `communicated — confirmed in <transcript|email|teams> on <date>; commercial/legal approval pending`.
+
+### 3. `confirmed` (full confidence)
+
+All required parties have agreed and the commitment is documented in a signed / approved / executed artifact (signed SOW, approved ECIF, executed amendment, deal-desk-approved record).
+
+- Render: `confirmed — <artifact> dated <date>; signed/approved by <party>`.
+
+## How to assign the state
+
+When synthesizing across sources, walk the cross-check:
+
+1. Is there a CRM/ADO field that asserts the claim? → at minimum `internal-only`.
+2. Is there a customer-facing transcript / email / Teams message **dated AFTER the field update** that confirms the same direction? → upgrade to `communicated`.
+3. Is there an executed/approved artifact (signed contract, deal-desk approval log, signed SOW) covering the claim? → upgrade to `confirmed`.
+
+If the latest customer-facing evidence **predates** the CRM/ADO field update, you cannot upgrade past `internal-only` on that field alone — the team's internal direction has changed but no post-decision external confirmation is on record yet.
+
+## Examples (anti-patterns to avoid)
+
+**Wrong:** "ECIF is the selected funding model." (based on CRM field flip dated 3/26 with no post-3/26 transcript).
+
+**Right:** "Internal team decision favors ECIF (CRM field updated 3/26 — `internal-only`). Latest customer-facing transcript (3/23) predates this decision; no `communicated` evidence yet. Deal-desk approval is also not in evidence."
+
+**Wrong:** "Solution architect is X." (based on a `_new_fdelead_value` lookup).
+
+**Right:** "Solution architect assigned in CRM as X (`internal-only`, recorded 3/26). No transcript or email confirms X has met the customer in that role yet."
+
+## Where this shows up in Kushi outputs
+
+- **`State/02_decisions.md`** — every row gets a `## Confidence` column with one of the three labels + the citing artifact for the upgrade (or absence thereof).
+- **`State/03_funding.md`** (when present) — funding selections are particularly prone to `internal-only` masquerading as `confirmed`. Always show the ladder.
+- **`State/06_risks.md`** — a risk that depends on a `confirmed` state but is currently `internal-only` or `communicated` should be flagged as such.
+- **`Open Questions/`** — every claim that sits at `internal-only` or `communicated` and matters to a downstream gate should generate an Open Question for the next refresh window.
+- **`ask-project` answers** — the model must surface the confidence label inline, never paraphrase a `communicated` decision as `final`.
+
+## Cross-reference with date-precedence
+
+This doctrine is orthogonal to the date-recency precedence in `ado-engagement-tree.instructions.md` and `fde-grounding`-style precedence (newer dated source wins). Confidence is about **what kind of evidence exists**, not which is newest. A newer `internal-only` field flip does NOT supersede an older `communicated` confirmation of the same direction — it just adds a follow-up question: did the customer get re-confirmed after the latest internal change?
+
+## Always-on
+
+This instruction applies to every Kushi skill that synthesizes across sources (`consolidate`, `state-update`, `ask-project`) and to any external consumer rendering Kushi evidence into a report.

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

@@ -0,0 +1,115 @@
+---
+applyTo: "**"
+description: "Evidence layout is CANONICAL — every per-source artifact lives under <engagement-root>/<project>/Evidence/<alias>/<source>/{snapshot,stream,_index,_legacy,refresh-reports}/. Writing source artifacts to any other path under <project>/ (e.g. <project>/email-context/, <project>/notes/, <project>/_Weekly Summaries/, <project>/email/) is a DEFECT."
+---
+
+# Evidence Layout — Canonical (HARD RULE)
+
+Multi-contributor projects depend on a **single, predictable, per-source, per-alias** evidence tree. The moment a pull skill writes to a sibling folder under `<project>/` (e.g. `<project>/email-context/`), four things break:
+
+1. **Multi-user collision** — another contributor's pull cannot find or merge it.
+2. **Consolidation breaks** — `consolidate-evidence` walks `Evidence/*/<source>/` and silently drops anything outside.
+3. **State rebuilds wrong** — `build-state` reads only the canonical tree; rogue folders become invisible.
+4. **Run-log drift** — `run-log.yml` watermarks point at the canonical path; a legacy folder makes the run "ok" but the data isn't where the doctrine says.
+
+This file is the **hard rule** every pull-/refresh-/bootstrap- skill MUST honor.
+
+## The contract
+
+### Rule 1 — All per-source artifacts live under `Evidence/<alias>/<source>/`
+
+For every project under `<engagement-root>/`:
+
+```
+<engagement-root>/<project>/
+  Evidence/                      # ← ALL contributor evidence lives here
+    contributors.yml
+    run-log.yml
+    _Consolidated/               # output of consolidate-evidence (cross-alias)
+    <alias>/                     # one per contributor (e.g. "ushak/")
+      .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/ }
+  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)
+```
+
+`Evidence/` and `<alias>/` are the **only** levels a pull skill may create under `<project>/`. Nothing else.
+
+### 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/` (at project root) | `<project>/Evidence/<alias>/email/` |
+| `<project>/notes/` | `<project>/Evidence/<alias>/onenote/snapshot/pages/` |
+| `<project>/_Weekly Summaries/` | `<project>/Evidence/<alias>/<source>/stream/` |
+| `<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/` |
+
+`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).
+
+### Rule 3 — Legacy / pre-bootstrap folders are migrated, not deleted
+
+When a pull or refresh skill encounters a non-canonical source-output folder under `<project>/`:
+
+1. **Move** the folder verbatim into `Evidence/<alias>/<source>/_legacy_<original-folder-name>_pre-bootstrap/` (preserve file mtimes; do not edit contents).
+2. **Log** the move in the contributor's `refresh-reports/<YYYY-MM-DD-HHMM>_refresh.md` under a `## Layout migrations` section: source path → destination path → file count.
+3. **Note** the migration as a `runs:` entry in `Evidence/run-log.yml` with `type: layout-migration` and `status: ok`.
+4. **Do not delete** anything until the user explicitly acks in the next session.
+
+If alias is ambiguous (legacy folder pre-dates multi-user), default to the current contributor's alias and add a one-liner to `Evidence/<alias>/open-questions/layout.md` so the consolidation step can re-attribute later.
+
+### Rule 4 — `consolidate-evidence`, `build-state`, and `aggregate-project` only read the canonical tree
+
+By contract, downstream skills walk:
+
+- `Evidence/*/email/`, `Evidence/*/teams/`, `Evidence/*/meetings/`, `Evidence/*/onenote/`, `Evidence/*/sharepoint/`, `Evidence/*/crm/`, `Evidence/*/ado/`
+
+Anything outside these paths is invisible to them — by design. The path IS the contract. There is no "also scan sibling folders" fallback.
+
+### Rule 5 — Self-check enforces the rule (`self-check D14`)
+
+`plugin/skills/self-check/run.ps1` -Deep MUST detect any `<project>/<sibling>/` folder under engagement roots where:
+
+- `<sibling>` is not in the allow-list `@('Evidence','State','Reports','.kushi','.kushi-reference','.project-evidence','.vscode')`, AND
+- `<sibling>` contains markdown files matching the per-source patterns (`*-summary.md`, `*-stream.md`, `*-context*`, `current-state.md`, `index.md`, etc.).
+
+When detected → emit a D14 finding with the canonical replacement path from Rule 2.
+
+## Why this is HARD, not "preferred"
+
+Multi-contributor evidence only works if every pull writes to the **same path** another contributor's pull would write to. The instant one skill writes to `<project>/email-context/` and another writes to `Evidence/ushak/email/`, the project has two parallel realities — and `build-state` will quietly use only one of them. That's a citation-integrity defect, not a cosmetic one.
+
+This rule is the layout half of the partial-determinism contract:
+
+- `scope-boundaries.instructions.md` → user controls **what** is queried.
+- `evidence-layout-canonical.instructions.md` (this file) → doctrine controls **where** the result lands.
+
+Together they guarantee that two contributors running the same verb on the same project produce evidence in the same place, scoped to the same boundary, regardless of which one ran first.
+
+## Cross-references
+
+- `snapshot-vs-stream.instructions.md` — the two shapes inside each `<source>/` folder.
+- `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) — also outside `<project>/`, but under `<engagement-root>/.project-evidence/`.
+- `run-reports.instructions.md` — every layout-migration MUST appear in the refresh report.
+- `cleanup-on-resolution.instructions.md` — once a legacy folder is migrated, all stale references in older summaries/notes get rewritten in the same turn.
+- `bootstrap-project/SKILL.md` — creates the canonical tree on first run.
+- `refresh-project/SKILL.md` — migrates any non-canonical folders it finds before pulling.
+- All `pull-*/SKILL.md` — write ONLY under `Evidence/<alias>/<source>/`.
+- `consolidate-evidence/SKILL.md`, `build-state/SKILL.md`, `aggregate-project/SKILL.md` — read ONLY from the canonical tree.
+- `self-check/run.ps1` D14 — enforces detection.

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

@@ -7,14 +7,61 @@ description: "Evidence Thoroughness Standard — every per-source skill MUST cap
 
 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**:
+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 narrative of what was actually discussed end-to-end, not 3 bullet points
+- **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.
@@ -27,25 +74,31 @@ For every meeting in the window — capture, **as separate named sections under
 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 **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").
+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 sender, recipients (to + cc), subject, **full body or close paraphrase**, attachments, and the chain of replies in order. Thread-level grouping. A one-line "X sent Y about Z" entry is insufficient — include enough body to convey what was actually said.
+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 — extract **full page bodies**, not just titles. Last-modified timestamp + author at the top.
-- stream/<week>.md — page-edit events with diff summary.
+- `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 — body summary 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, content summary at the same depth bar as a meeting transcript walk-through (decisions, risks, actions, owners, dates, key context).
-- stream/<week>.md — file change events that week.
+- `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 — every field the API returns, every value.
-- stream/<id>/<week>.md — every field-level change with old → new + actor + timestamp, every comment/discussion verbatim.
+- `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
 
@@ -59,4 +112,21 @@ Every paragraph still needs `[source: …]` citations — thoroughness does NOT
 
 ## Fix-up loop
 
-If the user reads an evidence file and says "this is too light", 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.
+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

package/plugin/instructions/full-view-gate.instructions.md

@@ -0,0 +1,91 @@
+---
+applyTo: "**"
+excludeAgent: "code-review"
+---
+
+# Full-View Gate — Always-On
+
+When a prompt asks Kushi to characterize a project's current state — analysis, synthesis, summary, status, risks, recommendations, next steps, readiness, or "what's going on with X" — Kushi MUST first walk the standard source set and record the disposition of each category in the current session. Do not answer from partial local context if a broader retrieval path exists for that project.
+
+## Scope
+
+This gate applies whenever the question is about a project / customer / engagement under the engagement root, including prompts that don't explicitly say "refresh" or "report":
+
+- "what's the status of HCA"
+- "summarize ABN AMRO"
+- "what are the risks on Hovnanian"
+- "what's been decided about funding for Lilly"
+- "next steps for AGCO"
+- "what did the customer say in the last meeting about X"
+- any `/kushi ask-project <project> <question>` invocation
+
+It does NOT apply to:
+- generic code questions
+- repository maintenance
+- requests scoped explicitly to a single artifact ("read this one file and summarize")
+
+## The standard source set
+
+For every applicable project, walk this set and record one disposition per category:
+
+1. **CRM** (Dataverse — see `pull-crm`)
+2. **ADO** (engagement tree — see `pull-ado` + `ado-engagement-tree.instructions.md`)
+3. **Email**
+4. **Teams chats**
+5. **OneNote**
+6. **SharePoint / external linked artifacts**
+7. **Meeting transcripts**
+
+## Accepted dispositions
+
+Each category in the session output must carry one of:
+
+- `retrieved` — pulled in this session (or read from fresh evidence written in the last refresh window)
+- `cached-fresh` — last evidence on disk is within the freshness window (default 14 days)
+- `cached-stale` — last evidence on disk is older than the freshness window; warn user
+- `not-present-for-project` — boundaries explicitly disable this source for the project (e.g. `boundaries.ado.area_paths: []`)
+- `attempted-but-blocked — <reason>` — concrete reason (auth, throttling, source unavailable)
+- `available-but-not-yet-ingested` — a retrieval path was checked and concrete remaining work was identified
+
+Carrying forward an old bootstrap state without re-checking is not allowed. If you don't know, the disposition is `unknown — gate not walked`.
+
+## Rendering the gate
+
+In any synthesized output (state files, ask-project answers, consolidated reports), include a small Source Basis block:
+
+```
+## Source Basis (gate walked YYYY-MM-DD HH:MM)
+
+| Source | Disposition | Notes |
+|---|---|---|
+| CRM | retrieved | 1 record, 12 annotations |
+| ADO | retrieved | engagement #97007 + 7 children, 34 comments |
+| Email | cached-fresh | last pull 2026-05-09 |
+| Teams chats | attempted-but-blocked — throttled-tooManyRequests | retry in next refresh |
+| OneNote | retrieved | 17 pages, 0 failed |
+| SharePoint | not-present-for-project | boundaries.sharepoint.sites: [] |
+| Transcripts | cached-stale (last 21d) | refresh recommended |
+```
+
+## "Full view" claim rule
+
+Do NOT describe the answer as a "full picture", "complete view", "grounded customer state", or equivalent **unless** every applicable source category in the gate has a disposition of `retrieved`, `cached-fresh`, or `not-present-for-project`. Anything else means the view has known gaps — say so.
+
+## Cross-workflow rule
+
+This gate applies even when the task is framed as:
+- "synthesize this"
+- "draft the executive summary"
+- "produce the follow-on artifact"
+- "what should we do next"
+- "give me the top 3 risks"
+
+If the output characterizes customer reality, walk the gate first.
+
+## Citation rule
+
+Every material claim in a gated output must carry an inline citation. Per `citation-ledger.instructions.md`. If a claim is based only on CRM and lacks non-CRM confirmation, label it per `evidence-confidence-ladder.instructions.md` (likely `internal-only`).
+
+## Intent
+
+Stop ad-hoc questions from skipping OneNote / email / transcripts / ADO discussions just because the question matched a quick-answer pattern. The gate is cheap to walk (most categories will be `cached-fresh` if a recent refresh ran) and expensive to skip.