kushi-agents 3.4.2 → 3.12.1

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.

package/plugin/instructions/m365-id-registry.instructions.md

@@ -0,0 +1,134 @@
+---
+applyTo:
+  - "plugin/skills/bootstrap-project/**"
+  - "plugin/skills/refresh-project/**"
+  - "plugin/skills/pull-*/**"
+priority: HARD
+---
+
+# M365 ID Registry — discover once, consume deterministically
+
+**Doctrine:** Bootstrap discovers; refresh consumes. Refresh runs MUST NOT re-discover canonical M365 identifiers — that is the source of "it worked the first time but not the second" non-determinism.
+
+## The registry
+
+`<engagement-root>/.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>` is the **single source of truth** for canonical M365 identifiers per project.
+
+Schema (populate every key the source supports):
+
+```jsonc
+"<projectKey>": {
+  // OneNote
+  "one_sectionName":         "<displayName>.one",
+  "one_sectionFileId":       "<wdsectionfileid GUID>",       // primary, extracted from Doc.aspx URL fragment
+  "one_sectionGroupId":      "<wdsectiongroupid GUID>",      // when boundary is a section group
+  "one_sectionOneNoteGuid":  "<wdsectiononenoteguid GUID>",  // alternate
+  "one_sectionPath":         "/<group>/<section>.one",
+  "one_sectionWebUrl":       "<full Doc.aspx URL>",
+  "one_notebookSourceDoc":   "<notebook sourceDoc GUID>",
+  "one_notebookName":        "<notebook display name>",        // browser path needs display name
+  "one_notebookSpoBaseUrl":  "https://<tenant>.sharepoint(-df)?.com/personal/<upn>",  // browser path
+  "one_pages": [                                              // per-page retry registry (dual-ID schema, pull-onenote v2.6.0)
+    {
+      "title":           "<page title>",
+      "wdpartid":        "<SharePoint search-index page GUID — used by WorkIQ>",
+      "webPageId":       "<OneNote-for-Web page GUID — used by browser scrape>",
+      "lastModified":    "<as reported by source>",
+      "last_status":     "captured | user-pasted | auth-required | workiq-degraded | BODY-NOT-EXPOSED | short-suspect | enumeration-only",
+      "captured_via":    "browser | workiq | user-paste",
+      "attempts":        0,
+      "last_attempt_at": "<ISO-8601>",
+      "snapshot_path":   "Evidence/<alias>/onenote/snapshot/pages/<safe-title>.md",
+      "captured_at":     "<ISO-8601, only when last_status ∈ {captured, user-pasted}>"
+    }
+  ],
+  // Email
+  "emailContext":            "Inbox/<folder-path>",
+  // Teams
+  "teamsChatContext": {
+    "chatHints":         ["..."],
+    "channelHints":      ["..."],
+    "participantHints":  ["..."]
+  },
+  // SharePoint
+  "sp_siteId":   "<siteId>",
+  "sp_webId":    "<webId>",
+  "sp_listId":   "<listId>",
+  "sp_path":     "/<site>/<library>/<folder>",
+  // CRM
+  "crm_envUrl":     "<env>.crm.dynamics.com",
+  "crm_entitySet":  "<entityset>",
+  "crm_recordId":   "<guid>",
+  "crm_requestId":  "<FE-YYYY-NNNNNN>",
+  // ADO
+  "ado_org":           "<orgName>",
+  "ado_project":       "<projectName>",
+  "ado_engagementId":  "<int>",
+  "ado_workItemIds":   [<int>, ...],
+  // Misc — user-curated link list (pull-misc v0.1.0+)
+  "misc_links": [                                              // per-link retry registry
+    {
+      "type":             "loop | web | learn | pdf | github | file | onenote | sharepoint | ado",
+      "owner":            "<as in external-links.txt>",
+      "title":            "<as in external-links.txt>",
+      "url":              "<as in external-links.txt>",
+      "notes":            "<as in external-links.txt>",
+      "last_status":      "captured | placeholder | auth-required | fetch-failed | skipped-binary | removed | not-yet-attempted | delegated",
+      "captured_via":     "browser | http | file | delegated",
+      "delegated_to":     "pull-onenote | pull-sharepoint | pull-ado",
+      "http_status":      200,
+      "content_type":     "text/html",
+      "char_count":       12345,
+      "etag":             "<HTTP ETag>",
+      "last_modified_http":"<HTTP Last-Modified>",
+      "attempts":         0,
+      "last_attempt_at":  "<ISO-8601>",
+      "captured_at":      "<ISO-8601, only when last_status=captured>",
+      "snapshot_path":    "Evidence/<alias>/misc/snapshot/<safe-type>__<safe-title>.md"
+    }
+  ]
+}
+```
+
+## Bootstrap contract (HARD)
+
+For every enabled source, bootstrap MUST:
+
+1. **Probe** WorkIQ / source-native API with the user-supplied seed (folder name, channel name, request id, work item id) using the per-source discovery procedure in `pull-<source>/SKILL.md` § "Bootstrap discovery".
+2. **Validate** by re-issuing the source's Step A enumerate query against the resolved ID. The resolved ID is accepted ONLY if the validate query returns ≥ 1 row.
+3. **Persist** the resolved IDs to `m365-mutable.json#knownSections.<projectKey>` AND mirror them into the corresponding `boundaries.<source>.*` keys in `<project>/integrations.yml`.
+4. **Record** one line per source in `bootstrap-status.md`: `<source>: resolved <key>=<value> via seed "<seed>" (<count> items enumerated)`.
+5. If discovery fails after trying all alternate identifiers documented in the per-source SKILL, write the source as `disabled` in `integrations.yml`, park the question in `OPEN-QUESTIONS-DRAFT.md` (or `State/09_open-questions.md`), and continue. Never write speculative or partial IDs.
+
+## Refresh contract (HARD)
+
+Every refresh MUST:
+
+1. **Read** `m365-mutable.json#knownSections.<projectKey>` first. If the entry is missing or the per-source key is empty → DO NOT probe. Re-dispatch through `bootstrap-project` for that source's discovery only, then resume.
+2. **Pass the canonical IDs to each pull-* skill in the form that skill's WorkIQ queries actually use.** Different sources need different forms:
+   - **OneNote (corrected v3.8.0):** PRIMARY path is browser-scrape via Playwright with persisted profile (returns reliable verbatim bodies — 16/16 captured for HCA on 2026-05-14 vs WorkIQ's 1/18). FALLBACK path is WorkIQ natural-language by display name (used only when Playwright profile is auth-expired). Per-page identifiers are stored in BOTH forms: `webPageId` (used by browser-scrape navigation) AND `wdpartid` (used by WorkIQ correlation and stream events). See `pull-onenote/SKILL.md` v2.6.0 § "Empirical contract" and `learnings/onenote.md` 2026-05-14 for proof. The v3.7.8 wdsectionfileid-filter doctrine and the v3.7.9 WorkIQ-primary doctrine are both retracted.
+   - **Email / Teams / SharePoint / CRM / ADO:** the registry IDs are passed as documented in each pull-* skill — typically as Graph IDs in API calls, not WorkIQ prose.
+   - **Misc (pull-misc v0.1.0+):** the link list is the user-curated `<project>/external-links.txt` file. Refresh re-parses the file every run, matches existing `misc_links[]` entries by `(type, url)` tuple, marks deleted entries as `removed` (preserves snapshot), creates new entries as `not-yet-attempted`, and routes per-type to runner branches (browser for loop, http for web/learn/docs/pdf/github, file for local, delegated for onenote/sharepoint/ado). See `pull-misc/SKILL.md` § "Step A — enumerate".
+3. **Never re-discover.** A refresh that probes WorkIQ with seeds (folder name, channel name) instead of canonical IDs is a defect. The only exception is the cleanup-on-resolution path documented in `cleanup-on-resolution.instructions.md`, which UPSERTS newly-resolved IDs into the registry mid-run.
+
+### Browser-fields self-heal exception (kushi v3.10.0+, OneNote-only)
+
+OneNote requires FIVE registry fields to drive the Playwright runner — not just the WorkIQ `wdsectionfileid`. Pre-doctrine registry entries (bootstrapped before kushi v3.10.0) and entries written from synthesized URL templates are missing or wrong on `one_notebookSourceDoc`, `one_notebookSpoBaseUrl`, and `one_sectionWebUrl`. Refresh MAY (and MUST) dispatch `plugin/skills/pull-onenote/scripts/recapture-section-url.mjs` mid-run when these fields are absent. This is **not** re-discovery — `wdsectionfileid` is preserved if already present. It is a one-time backfill via user URL paste, cached forever after.
+
+The script's `--check` mode is the gate; the interactive mode is the heal. See `pull-onenote/SKILL.md` Pre-flight C for the contract.
+
+4. **Cite** the registry path in the per-user refresh report: `Resolved IDs sourced from m365-mutable.json#knownSections.<projectKey> (last_updated: <ts>)`.
+
+## Anti-patterns (HARD-rule violations)
+
+1. ❌ Refresh probes WorkIQ for `"List sections in OneNote notebook"` instead of reading `one_sectionFileId` from the registry.
+2. ❌ Bootstrap persists an ID without validating it via the source's Step A enumerate query.
+3. ❌ Pull-* skill uses the wrong WorkIQ phrasing for the source. For OneNote specifically: using `wdsectionfileid = <id>` as filter syntax routes WorkIQ to summary mode — the working WorkIQ pattern is natural-language naming `one_sectionName` and notebook display name. But per `pull-onenote/SKILL.md` v2.6.0, browser-scrape is the PRIMARY path; WorkIQ is fallback only.
+6. ❌ A pull-* skill silently drops pages/items that returned BODY-NOT-EXPOSED, auth-required, or workiq-degraded instead of registering them for retry. Per-page retry registries (e.g. `one_pages[]` for OneNote) are the durable state that survives across refreshes — without them, refresh runs cannot tell pending-retry from never-attempted.
+7. ❌ A pull-* skill stores only ONE form of an identifier when the registry doctrine requires multiple forms. For OneNote specifically: `one_pages[]` entries MUST persist BOTH `webPageId` (browser navigation) AND `wdpartid` (WorkIQ correlation) when both are observed. Storing only one creates a single-path lock-in that the empirical record (browser-vs-WorkIQ retrieval gap) explicitly forbids.
+4. ❌ Bootstrap writes a partial / speculative ID with a `_note` field instead of marking the source disabled.
+5. ❌ Refresh "rediscovers" because it didn't find the project key — must re-dispatch through bootstrap, not improvise.
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` D12 (v3.7.8 / retuned v3.7.9 / extended v3.8.0) verifies that each `pull-*/SKILL.md` cites `m365-id-registry.instructions.md` at least once and contains source-specific contract tokens. For `pull-onenote` v2.6.0 the required tokens are: `m365-id-registry`, `one_pages`, `webPageId`, `auth-required`, `playwright-profile` — these prove the skill carries the dual-ID retry registry + browser-primary contract.