kushi-agents 5.0.0 → 5.0.2

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

@@ -1,180 +1,197 @@
----
-name: "pull-loop"
-version: "1.0.0"
-description: "Pull Microsoft Loop evidence (snapshot: full page bodies; stream: page-edit events). Workspaces + pages are registered during setup per loop-bootstrap-discovery.instructions.md. Browser-scrape (Playwright with persisted M365 profile) is the PRIMARY capture path because fluid-framework page bodies are not reliably returned by Graph/Search. WorkIQ remains the fallback when the profile is auth-expired AND is used for discovery + page-edit metadata. Reuses the OneNote-for-Web Playwright profile."
----
-
-# Skill: pull-loop
-
-> **Doctrine contracts** — This skill operates under the standard pull-* doctrine set:
-> - `verbatim-by-default.instructions.md` — full page bodies by default; no preview-grade pulls.
-> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (workspaceId + pageId schema).
-> - `loop-bootstrap-discovery.instructions.md` — workspace/page registration shape + flow.
-> - `capture-learnings.instructions.md` — every Loop-specific fix logs to `plugin/learnings/loop.md`.
-> - `cleanup-on-resolution.instructions.md` — when a page resolves, all stale `unresolved` / `page-body-unavailable` markers are upgraded in the same turn.
-> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/`.
-> - `evidence-thoroughness.instructions.md` — runtime detector + auto-retry; partial body = failure not "ok".
-> - `evidence-layout-canonical.instructions.md` — all artifacts under `<project>/Evidence/<alias>/loop/{snapshot,stream}/`.
-> - `per-source-verification-gate.instructions.md` — gate §2 loop row + §2a canonical kind.
-> - `issue-recovery.instructions.md` — apply when discovery or capture exposes a doctrine gap.
-
-Pulls **loop** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
-
-- **snapshot/** — full Loop page bodies — one file per registered page with `lastModified` + verbatim body
-- **stream/** — page-edit events (who edited what, when) since last watermark — one file per ISO week in the window
-
-Standalone Loop components embedded in Teams/OneNote/Email are NOT captured here — they are captured by their host source's pull skill to avoid double-counting. See `loop-bootstrap-discovery.instructions.md` §Surface model.
-
-## Tools (in order)
-
-1. **Playwright (browser-scrape, persisted M365 profile)** — PRIMARY. Drives Loop-for-Web to render each registered page and read the verbatim body. Profile at `~/.kushi/playwright-profile/m365/` (falls back to `~/.kushi/playwright-profile/onenote/` for older installs — both are valid M365-wide profiles). Implementation: `plugin/skills/pull-loop/runner.mjs`.
-2. **WorkIQ** — FALLBACK for body capture when Playwright profile is auth-expired (`auth-required`). PRIMARY for the **stream** shape (page-edit metadata) and for discovery during setup. Always cite `m365-id-registry` doctrine when invoking.
-3. **Host (m365_*)** — not used. Graph Loop API is preview-only and incomplete; do not call directly.
-
-## Canonical CLI invocations
-
-### Bootstrap (one-time per machine)
-
-Loop reuses the OneNote Playwright profile. Run the OneNote bootstrap if you haven't already:
-
-```pwsh
-cd <kushi-repo-root>
-node plugin/skills/pull-onenote/runner.mjs --bootstrap
-```
-
-The bootstrap signs you into OneNote-for-Web, then visits SharePoint surfaces. The same profile authenticates Loop-for-Web — no separate Loop bootstrap is needed.
-
-### Pre-flight (check profile + reachability)
-
-```pwsh
-cd <kushi-repo-root>
-node plugin/skills/pull-loop/runner.mjs --preflight
-```
-
-Exits `0` on success, `3` on `auth-required` (re-run the OneNote bootstrap).
-
-### Scrape a workspace (production)
-
-Use the wrapper, not the bare runner. The wrapper writes the snapshot in the canonical layout, upserts the per-user mutable registry, and emits a run report:
-
-```pwsh
-cd <kushi-repo-root>
-node plugin/skills/pull-loop/write-snapshot.mjs `
-  --project "<project>" `
-  --workspace-url "<workspace-url-from-m365-mutable.json>" `
-  --engagement-root "<engagement-root>" `
-  --alias <your-alias>
-```
-
-The wrapper:
-
-1. Loads `m365-mutable.json#knownSections.<project>.loop` for the workspace.
-2. Enumerates registered `loop_pages[]`.
-3. Invokes `runner.mjs` once per page (or once per workspace with `--titles` filter for partial runs).
-4. Writes snapshot files at canonical paths.
-5. Upserts each `loop_pages[].last_status` + `last_captured_at` + `captured_via`.
-6. Emits `refresh-reports/<timestamp>_loop.md`.
-
-## Output structure (per `evidence-layout-canonical.instructions.md`)
-
-```
-<engagement-root>/<project>/Evidence/<alias>/loop/
-├── snapshot/
-│   ├── <workspace-slug>/
-│   │   ├── _workspace.md                                <- workspace metadata (title, owner, page list)
-│   │   ├── <page-slug>.md                               <- one per page; verbatim body
-│   │   └── ...
-│   └── _index.md                                        <- workspaces enumerated this run
-└── stream/
-    └── YYYY-MM-DD_loop-stream.md                        <- per-ISO-week page-edit events
-```
-
-Every artifact carries the frontmatter required by `per-source-verification-gate.instructions.md` §2a:
-
-```yaml
----
-source: loop
-project: <project>
-workspace_id: <id>
-page_id: <id>
-captured_at: <ISO-8601>
-captured_via: playwright | workiq
-evidence_source_kind: page-body | page-body-unavailable | tree-only
----
-```
-
-`evidence_source_kind` values (canonical → fallbacks):
-
-- `page-body` — Playwright rendered the page and the full body was captured. **Canonical.**
-- `page-body-unavailable` — Playwright reached the page but body was empty / fluid container did not render (page is a stub or component-only). Coverage notes MUST explain.
-- `tree-only` — Only workspace metadata + page-list was captured (no page bodies). Used when WorkIQ-only path runs because Playwright auth is expired.
-
-## Pre-flight gates (run before EVERY scrape)
-
-Per `loop-bootstrap-discovery.instructions.md`:
-
-| Pre-flight | Failure action |
-|---|---|
-| **A. Workspaces registered** for the resolved project | Refuse to run. Instruct user to run `@Kushi setup --reconfigure`. |
-| **B. Pages registered** OR `loop_pages_status: to-be-enumerated` | Run page enumeration via WorkIQ first; on enumerate-fail, write FOLLOW-UPS.md per the gate. |
-| **C. Playwright profile exists** at `~/.kushi/playwright-profile/m365/` or `.../onenote/` | Refuse; instruct: `node plugin/skills/pull-onenote/runner.mjs --bootstrap`. |
-| **D. URLs are canonical** (matches Loop URL grammar; not synthesized) | Refuse + log to learnings/loop.md per `issue-recovery.instructions.md`. |
-
-## Verification gate (per `per-source-verification-gate.instructions.md`)
-
-After every `pull-loop` run, the gate verifies:
-
-- Snapshot shape: at least one `snapshot/<workspace-slug>/<page-slug>.md` ≥ 200 bytes per registered page, OR a documented `page-body-unavailable` annotation in coverage notes.
-- Stream shape: `stream/YYYY-MM-DD_loop-stream.md` covers every ISO week in the run window OR is `.empty` with reason.
-- Registry consistency: every `loop_pages[].last_status` was updated this run (no stale `unresolved` from previous runs unless the page truly remains unresolved).
-- `evidence_source_kind` annotation present on every written artifact.
-- Citation: spot-check 3 random assertions per `citation-ledger.instructions.md`.
-
-## Boundary contract
-
-Per `loop-bootstrap-discovery.instructions.md` §Boundary:
-
-```yaml
-# <project>/integrations.yml
-boundaries:
-  loop:
-    workspace_ids: []      # REQUIRED — empty = source disabled (never silently widens)
-    page_ids: []           # optional — pin specific pages
-    include_components: false
-```
-
-## How users invoke this
-
-Direct invocation is uncommon — this skill is normally dispatched by:
-
-- `@Kushi bootstrap <project>` (full per-source loop)
-- `@Kushi refresh <project>` (per-source loop)
-- `@Kushi aggregate <project>` (pull-only loop)
-
-Direct:
-
-```text
-@Kushi pull loop <project>
-@Kushi pull loop <project> last 14 days
-```
-
-## What this skill never does
-
-- Never captures standalone Loop components from Teams/OneNote/Email — those belong to their host source (avoids double-counting).
-- Never falls back to Graph (Loop Graph API is preview-only and incomplete) — see `deferred-retry-on-workiq-fail.instructions.md`.
-- Never synthesizes a `pageUrl` from `workspaceId + pageId` — only URLs observed in WorkIQ responses or registered during setup are valid. See `issue-recovery.instructions.md` for why (mirrors OneNote learnings).
-- Never sends outbound messages.
-- Never reads/writes outside the resolved project's folder.
-
-## References
+---
+name: "pull-loop"
+version: "1.0.0"
+description: "USE WHEN refresh-project / bootstrap-project dispatches Loop source OR the user says \"pull Loop for <X>\" AND the project has loop workspaces/pages registered. DO NOT USE for general Loop content discovery. Capability: pulls Microsoft Loop evidence in snapshot (full page bodies) + stream (page-edit events) shape per loop-source doctrine."
+---
+
+# Skill: pull-loop
+
+> **Doctrine contracts** — This skill operates under the standard pull-* doctrine set:
+> - `verbatim-by-default.instructions.md` — full page bodies by default; no preview-grade pulls.
+> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (workspaceId + pageId schema).
+> - `loop-bootstrap-discovery.instructions.md` — workspace/page registration shape + flow.
+> - `capture-learnings.instructions.md` — every Loop-specific fix logs to `plugin/learnings/loop.md`.
+> - `cleanup-on-resolution.instructions.md` — when a page resolves, all stale `unresolved` / `page-body-unavailable` markers are upgraded in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/`.
+> - `evidence-thoroughness.instructions.md` — runtime detector + auto-retry; partial body = failure not "ok".
+> - `evidence-layout-canonical.instructions.md` — all artifacts under `<project>/Evidence/<alias>/loop/{snapshot,stream}/`.
+> - `per-source-verification-gate.instructions.md` — gate §2 loop row + §2a canonical kind.
+> - `issue-recovery.instructions.md` — apply when discovery or capture exposes a doctrine gap.
+
+Pulls **loop** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — full Loop page bodies — one file per registered page with `lastModified` + verbatim body
+- **stream/** — page-edit events (who edited what, when) since last watermark — one file per ISO week in the window
+
+Standalone Loop components embedded in Teams/OneNote/Email are NOT captured here — they are captured by their host source's pull skill to avoid double-counting. See `loop-bootstrap-discovery.instructions.md` §Surface model.
+
+## Gotchas
+
+- **Loop workspaces are NOT discoverable via WorkIQ** — must be registered at setup time per `loop-bootstrap-discovery.instructions.md`. An empty workspaces list = the user needs to paste URLs, not a "Loop disabled" signal.
+- **Page bodies are HTML, not Markdown** — the snapshot writer converts via Readability; if a page renders as raw HTML in evidence, the converter regressed.
+- **Co-authoring writes can race** — Loop pages support real-time edit. The page-edit stream cites `editedAt + editor`; a single visible change can produce N stream events. De-dupe by `(editor, page, minute-bucket)`.
+- **Component links inside Loop pages** — embedded components (tables, tasks) live in sub-URLs. Capture the parent page; do NOT recursively scrape every embedded component (out of scope for v5).
+- **No `Loop.Read` Graph scope** — when the host backend lacks the new Loop API, pull-loop is a no-op. Surface `loop.unavailable-no-api` in `_index/entities.yml#status`.
+
+## Tools (in order)
+
+1. **Playwright (browser-scrape, persisted M365 profile)** — PRIMARY. Drives Loop-for-Web to render each registered page and read the verbatim body. Profile at `~/.kushi/playwright-profile/m365/` (falls back to `~/.kushi/playwright-profile/onenote/` for older installs — both are valid M365-wide profiles). Implementation: `plugin/skills/pull-loop/runner.mjs`.
+2. **WorkIQ** — FALLBACK for body capture when Playwright profile is auth-expired (`auth-required`). PRIMARY for the **stream** shape (page-edit metadata) and for discovery during setup. Always cite `m365-id-registry` doctrine when invoking.
+3. **Host (m365_*)** — not used. Graph Loop API is preview-only and incomplete; do not call directly.
+
+## Canonical CLI invocations
+
+### Bootstrap (one-time per machine)
+
+Loop reuses the OneNote Playwright profile. Run the OneNote bootstrap if you haven't already:
+
+```pwsh
+cd <kushi-repo-root>
+node plugin/skills/pull-onenote/runner.mjs --bootstrap
+```
+
+The bootstrap signs you into OneNote-for-Web, then visits SharePoint surfaces. The same profile authenticates Loop-for-Web — no separate Loop bootstrap is needed.
+
+### Pre-flight (check profile + reachability)
+
+```pwsh
+cd <kushi-repo-root>
+node plugin/skills/pull-loop/runner.mjs --preflight
+```
+
+Exits `0` on success, `3` on `auth-required` (re-run the OneNote bootstrap).
+
+### Scrape a workspace (production)
+
+Use the wrapper, not the bare runner. The wrapper writes the snapshot in the canonical layout, upserts the per-user mutable registry, and emits a run report:
+
+```pwsh
+cd <kushi-repo-root>
+node plugin/skills/pull-loop/write-snapshot.mjs `
+  --project "<project>" `
+  --workspace-url "<workspace-url-from-m365-mutable.json>" `
+  --engagement-root "<engagement-root>" `
+  --alias <your-alias>
+```
+
+The wrapper:
+
+1. Loads `m365-mutable.json#knownSections.<project>.loop` for the workspace.
+2. Enumerates registered `loop_pages[]`.
+3. Invokes `runner.mjs` once per page (or once per workspace with `--titles` filter for partial runs).
+4. Writes snapshot files at canonical paths.
+5. Upserts each `loop_pages[].last_status` + `last_captured_at` + `captured_via`.
+6. Emits `refresh-reports/<timestamp>_loop.md`.
+
+## Output structure (per `evidence-layout-canonical.instructions.md`)
+
+```
+<engagement-root>/<project>/Evidence/<alias>/loop/
+├── snapshot/
+│   ├── <workspace-slug>/
+│   │   ├── _workspace.md                                <- workspace metadata (title, owner, page list)
+│   │   ├── <page-slug>.md                               <- one per page; verbatim body
+│   │   └── ...
+│   └── _index.md                                        <- workspaces enumerated this run
+└── stream/
+    └── YYYY-MM-DD_loop-stream.md                        <- per-ISO-week page-edit events
+```
+
+Every artifact carries the frontmatter required by `per-source-verification-gate.instructions.md` §2a:
+
+```yaml
+---
+source: loop
+project: <project>
+workspace_id: <id>
+page_id: <id>
+captured_at: <ISO-8601>
+captured_via: playwright | workiq
+evidence_source_kind: page-body | page-body-unavailable | tree-only
+---
+```
+
+`evidence_source_kind` values (canonical → fallbacks):
+
+- `page-body` — Playwright rendered the page and the full body was captured. **Canonical.**
+- `page-body-unavailable` — Playwright reached the page but body was empty / fluid container did not render (page is a stub or component-only). Coverage notes MUST explain.
+- `tree-only` — Only workspace metadata + page-list was captured (no page bodies). Used when WorkIQ-only path runs because Playwright auth is expired.
+
+## Pre-flight gates (run before EVERY scrape)
+
+Per `loop-bootstrap-discovery.instructions.md`:
+
+| Pre-flight | Failure action |
+|---|---|
+| **A. Workspaces registered** for the resolved project | Refuse to run. Instruct user to run `@Kushi setup --reconfigure`. |
+| **B. Pages registered** OR `loop_pages_status: to-be-enumerated` | Run page enumeration via WorkIQ first; on enumerate-fail, write FOLLOW-UPS.md per the gate. |
+| **C. Playwright profile exists** at `~/.kushi/playwright-profile/m365/` or `.../onenote/` | Refuse; instruct: `node plugin/skills/pull-onenote/runner.mjs --bootstrap`. |
+| **D. URLs are canonical** (matches Loop URL grammar; not synthesized) | Refuse + log to learnings/loop.md per `issue-recovery.instructions.md`. |
+
+## Verification gate (per `per-source-verification-gate.instructions.md`)
+
+After every `pull-loop` run, the gate verifies:
+
+- Snapshot shape: at least one `snapshot/<workspace-slug>/<page-slug>.md` ≥ 200 bytes per registered page, OR a documented `page-body-unavailable` annotation in coverage notes.
+- Stream shape: `stream/YYYY-MM-DD_loop-stream.md` covers every ISO week in the run window OR is `.empty` with reason.
+- Registry consistency: every `loop_pages[].last_status` was updated this run (no stale `unresolved` from previous runs unless the page truly remains unresolved).
+- `evidence_source_kind` annotation present on every written artifact.
+- Citation: spot-check 3 random assertions per `citation-ledger.instructions.md`.
+
+## Boundary contract
+
+Per `loop-bootstrap-discovery.instructions.md` §Boundary:
+
+```yaml
+# <project>/integrations.yml
+boundaries:
+  loop:
+    workspace_ids: []      # REQUIRED — empty = source disabled (never silently widens)
+    page_ids: []           # optional — pin specific pages
+    include_components: false
+```
+
+## How users invoke this
+
+Direct invocation is uncommon — this skill is normally dispatched by:
+
+- `@Kushi bootstrap <project>` (full per-source loop)
+- `@Kushi refresh <project>` (per-source loop)
+- `@Kushi aggregate <project>` (pull-only loop)
+
+Direct:
+
+```text
+@Kushi pull loop <project>
+@Kushi pull loop <project> last 14 days
+```
+
+## What this skill never does
+
+- Never captures standalone Loop components from Teams/OneNote/Email — those belong to their host source (avoids double-counting).
+- Never falls back to Graph (Loop Graph API is preview-only and incomplete) — see `deferred-retry-on-workiq-fail.instructions.md`.
+- Never synthesizes a `pageUrl` from `workspaceId + pageId` — only URLs observed in WorkIQ responses or registered during setup are valid. See `issue-recovery.instructions.md` for why (mirrors OneNote learnings).
+- Never sends outbound messages.
+- Never reads/writes outside the resolved project's folder.
+
+## References
+
+- `../../instructions/loop-bootstrap-discovery.instructions.md` — workspace/page registration.
+- `../../instructions/per-source-verification-gate.instructions.md` — gate §2 + §2a.
+- `../../instructions/fuzzy-disambiguation.instructions.md` — workspace title → ID resolution.
+- `../../instructions/issue-recovery.instructions.md` — Issue Recovery Rule applies when discovery or capture exposes a doctrine gap; fix the smallest correct repo-owned artifact first; never use memory as a substitute.
+- `../../learnings/loop.md` — Loop-specific fixes accumulated across runs.
+- `docs/concepts/loop-source.md` — user-facing companion doc.
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
 
-- `../../instructions/loop-bootstrap-discovery.instructions.md` — workspace/page registration.
-- `../../instructions/per-source-verification-gate.instructions.md` — gate §2 + §2a.
-- `../../instructions/fuzzy-disambiguation.instructions.md` — workspace title → ID resolution.
-- `../../instructions/issue-recovery.instructions.md` — Issue Recovery Rule applies when discovery or capture exposes a doctrine gap; fix the smallest correct repo-owned artifact first; never use memory as a substitute.
-- `../../learnings/loop.md` — Loop-specific fixes accumulated across runs.
-- `docs/concepts/loop-source.md` — user-facing companion doc.
+## Validation loop
 
-## Issue Recovery
+After writing outputs:
 
-When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-loop`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

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

@@ -1,7 +1,7 @@
 ---
 name: "pull-meetings"
-version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull Meetings evidence as (A) raw immutable verbatim/<dir>/ audit folder per meeting (UNCHANGED from v2.x — meetings expire) + (B) Comprehensive Structured Capture (CSC) block per meeting in weekly/YYYY-MM-DD_meetings-csc.md, upserted in _index/entities.yml. WorkIQ-ONLY: CSC canonical prompts for Half B; v4.8 verbatim transcript prompts retained for Half A only. Bootstrap walks the FULL boundary window writing verbatim/ for every meeting (no one-per-source carve-out). Per-contributor _index/. See meetings-verbatim-required + weekly-csc + comprehensive-structured-capture doctrines."
+version: "3.0.1"
+description: "USE WHEN refresh-project / bootstrap-project dispatches Meetings source OR the user says \"pull meetings for <X>\" AND the project boundaries.meetings window is non-empty. DO NOT USE for tenant-wide calendar queries. Capability: pulls Meetings as (A) raw immutable verbatim/<dir>/ audit folder per meeting (transcript+chat+recording-url) AND (B) CSC blocks written to weekly/YYYY-MM-DD_meetings-csc.md. WorkIQ-only."
 ---
 
 # Skill: pull-meetings
@@ -22,6 +22,14 @@ description: "v3.0.0 (kushi v4.9.0): Pull Meetings evidence as (A) raw immutable
 > - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC for Half B; Half A still verbatim).
 > - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
 
+## Gotchas
+
+- **Meetings expire** — transcripts and chat are purged by tenant policy (~30-90 days). The verbatim/ folder is the only durable record. Always write verbatim/<YYYY-MM-DD-HHMM>_<slug>/ BEFORE writing the weekly CSC block; the CSC cites verbatim.
+- **Join URL is the canonical ID, not subject** — the same recurring meeting has the same `meetings://joinurl=...` id across occurrences. De-dupe in _index/entities.yml by joinUrl, not by subject string.
+- **WorkIQ returns "meeting summary" instead of transcript when scope is too wide** — ask for ONE meeting at a time by joinUrl. Bulk calendar enumeration phrasings punt to Graph; see `meetings-bootstrap-discovery.instructions.md` for the canonical forbidden list.
+- **Recording URLs rot when the meeting host leaves the tenant** — capture the SharePoint embed URL into verbatim/recording-url.txt; if the host later leaves, the URL 404s but the verbatim transcript + chat remain.
+- **Facilitator notes require Copilot license + organizer role** — `m365_get_facilitator_notes` returns 403 silently. If notes are missing for a meeting where you are not organizer, log `facilitator-notes: unavailable-not-organizer` in `_index/entities.yml#status`, don''t retry.
+
 ## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
 
 Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
@@ -67,8 +75,8 @@ Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructi
 
 - **Keep Half A entirely intact** (see "Half A — verbatim/ capture" section below). Half A is still mandatory and uses the v4.8 verbatim transcript WorkIQ prompts.
 - **Half B becomes the CSC weekly block** (one CSC block per meeting in `weekly/<Monday>_meetings-csc.md`). Every assertion cites the sibling `verbatim/<dir>/` file. `Artifacts/Links` MUST include the verbatim folder path and (when present) the recording URL.
-- Bootstrap walks the FULL boundary window — no one-meeting-per-bootstrap carve-out. Each meeting produces its own verbatim/ folder.
-
+- Bootstrap walks the FULL boundary window — no one-meeting-per-bootstrap carve-out. Each meeting produces its own verbatim/ folder.
+
 Pulls **meetings** evidence in three shapes per `snapshot-vs-stream.instructions.md` + `meetings-verbatim-required.instructions.md`:
 
 - **snapshot/** — `series-index.md` listing all recurring meeting series for this project (subject, recurrence, organizer, current attendees)
@@ -122,59 +130,9 @@ plugin/instructions/scope-boundaries.instructions.md.
 
 For EACH meeting in the window, the cascade has **two halves**: (A) write raw artifacts to `verbatim/<YYYY-MM-DD-HHMM>_<slug>/`, then (B) produce the curated stream block citing those verbatim files. Half A is mandatory before Half B per `meetings-verbatim-required.instructions.md`.
 
-### Half A — verbatim/ capture (REQUIRED, transcript-first, WorkIQ-only per workiq-only.instructions.md)
-
-For every meeting, BEFORE writing any curated text:
-
-0. Compute slug + timestamp, create `Evidence/<alias>/meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/`, write `captured-at.txt` (started_at, kushi_version).
-
-1. **Transcript cascade — WorkIQ-only, EXHAUSTIVE, in order. Do NOT stop at first weak result; record each path's result in `coverage.md`.** Per `meetings-verbatim-required.instructions.md` "Transcript capture cascade":
-   - **a. WorkIQ full-transcript pull (REQUIRED first attempt)** with the canonical prompt from `workiq-only.instructions.md`:
-     > `Find the Teams meeting titled "<subject>" that occurred on <YYYY-MM-DD>. Return the full transcript verbatim with speaker labels and timestamps. Do not summarize.`
-     - If WorkIQ returns full speaker-turn text (≥ ~10 distinct `Name:` lines) → strip `request-id:` prefix, save body as `transcript.txt` with header (source, query, request-id, fidelity).
-     - If WorkIQ returns a summary (paragraphs only, no speaker turns) → run the **doubled-strict retry** from `workiq-only.instructions.md` once. If still summary-only, save as `transcript-source.md` with the `WARNING: NOT a verbatim transcript` header.
-   - **b. WorkIQ Copilot recap (SUPPLEMENTARY, always attempt)**:
-     > `Get the Copilot meeting recap (decisions, action items, key points) for the Teams meeting "<subject>" on <YYYY-MM-DD>. Return the FULL recap card verbatim. Do not summarize.`
-     - Save as `facilitator-notes.md`. Supplementary; does NOT replace the transcript.
-   - **c. WorkIQ recording-URL discovery**:
-     > `For the meeting "<subject>" on <YYYY-MM-DD>, return the SharePoint Stream recording URL if it exists, and the calendar event body.`
-     - Save URL(s) to `recording-url.txt`. If a `.mp4` URL is present, downloading the recording binary is governed by the `pull-meetings` recording-download carve-out (size < 200MB) — this is the ONLY allowed `m365_download_file` call in any kushi pull-* skill, because the recording is binary media and WorkIQ does not download binaries.
-   - **d. User-paste fallback (first-class, NOT a degradation)** — when (a) returns empty/`body-unavailable` after doubled-strict retry AND (b) returns nothing usable: prompt the user to paste verbatim transcript or notes. Save to `transcript.txt` with header `User-pasted; WorkIQ returned no transcript on <ISO timestamp>`.
-
-   **FORBIDDEN** (do NOT attempt; do NOT log as cascade steps in coverage.md): `m365_get_transcript`, `m365_get_facilitator_notes`, `m365_list_meetings`, `m365_list_events`, Graph REST `/me/onlineMeetings/.../transcripts/.../content`. These have a near-100% failure rate in this workspace and pollute the coverage trail. Use WorkIQ steps (a)/(b)/(c).
-
-2. **Chat capture (ALWAYS, parallel with step 1 — allowed exception to workiq-only)**: `m365_list_chat_messages(chatId)` → `chat-messages.json` (raw structured-data dump) + `chat-messages.md` (rendered, one heading-block per message). Chat is **supporting evidence**; it is **NEVER** a transcript substitute. If `m365_list_chat_messages` fails, run the WorkIQ chat-thread prompt as fallback (per `workiq-only.instructions.md` Teams chat thread section).
-
-3. Walk chat for attachments → `m365_download_file` each → `attachments/<original-name>` (binary download carve-out, same as recording.mp4).
-
-4. Walk chat for Copilot recap card → `recap-card.md` verbatim.
-
-5. **Classify** the verbatim folder per the doctrine:
-   - `transcript-complete` — at least one of `transcript.vtt` / `transcript.txt` / `transcript-source.md` is non-empty.
-   - `transcript-missing` — only `chat-messages.*` present; all WorkIQ cascade paths (1a–1d) returned empty.
-
-6. Write `coverage.md` with classification + per-path attempt log (every WorkIQ path attempted, with request-id, even successful ones) + source-basis classification for stream/.
-
-7. Update `captured-at.txt` with `completed_at` + `final_status` (one of `transcript-complete-text` / `transcript-complete-summary-only` / `transcript-missing-chat-only` / `unrecoverable`).
-
-If 1a–1d ALL return empty AND step 2 chat is also empty AND user paste is declined → `unrecoverable`. Apply retry pattern per `auth-and-retry.instructions.md`.
+### Half A — verbatim/ capture (REQUIRED)
 
-### Half B — curated stream/ block (cites verbatim/)
-
-Build the per-meeting block in `stream/<week>_meetings-stream.md` using ONLY content already persisted in verbatim/. Every assertion cites a verbatim file. Preferred citation chain:
-- `[source: Evidence/<alias>/meetings/verbatim/<dir>/transcript.vtt · <date>]` when transcript-complete-vtt.
-- `[source: Evidence/<alias>/meetings/verbatim/<dir>/transcript.txt · <date>]` when transcript-complete-text.
-- `[source: Evidence/<alias>/meetings/verbatim/<dir>/transcript-source.md · <date>]` when only Copilot summary (always note the warning).
-- `[source: Evidence/<alias>/meetings/verbatim/<dir>/chat-messages.md · <date>]` only for assertions backed by chat (not transcript content).
-
-`Source basis` line in the curated block reflects verbatim classification:
-- `transcript (raw VTT)` — transcript.vtt present
-- `transcript (plain text)` — transcript.txt present, no VTT
-- `transcript (WorkIQ Copilot summary — NOT verbatim)` — only transcript-source.md
-- `❌ no-transcript-recovered-chat-only` — only chat-messages.*
-- `❌ unrecoverable` — only captured-at.txt + coverage.md
-
-A meeting with `transcript-missing-chat-only` is valid evidence in a degraded sense — actions/decisions citeable from chat are still useful — but the curated block MUST flag the gap prominently and the run-log MUST record `transcript-unrecoverable` for that meeting.
+> **Load `references/verbatim-capture.md`** for the full transcript cascade (WorkIQ steps a–d), chat capture procedure, verbatim-folder classification rules, coverage.md format, and the Half B citation chain. Load when executing per-meeting capture.
 
 ### Ask-user fallback
 
@@ -182,17 +140,9 @@ When the entire cascade (1a–1d + chat) produces nothing usable, ask the user t
 
 ## Stream pass
 
-> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer (Half B) above. The Half A `verbatim/<dir>/` capture remains mandatory and unchanged. Kept for historical reference; the per-meeting curated stream block is now a CSC block in `weekly/<Monday>_meetings-csc.md`.
-
-Per `evidence-thoroughness.instructions.md`: every meeting in the window gets a full per-meeting block whose **FIRST sub-section is an AI Narrative Summary (REQUIRED, 5+ paragraphs)** covering the whole meeting end-to-end — context, what was discussed in what order, who took which position, the reasoning, the back-and-forth, soft signals, sentiment, what landed and what stayed open (cited to transcript timestamps). Then attendees → agenda → Detailed Discussion Summary (topic-organized) → chronological transcript walk-through with verbatim quotes → Decisions → Open Questions → Next Steps → Action Items → Risks → Customer Asks → Coverage Notes. **A 30-line meetings file for a week with 2 meetings is a defect — expect 300+ lines (the AI Narrative Summary alone is typically 30-50 lines per meeting).** A per-meeting block missing the AI Narrative Summary as the first sub-section is a defect even if every other section is present.
-
-Write to: `<engagement-root>/<project>/Evidence/<alias>/Meetings/stream/<YYYY-MM-DD>_meetings-stream.md` (date = Monday of the ISO week).
-
-Use template: `templates/weekly/meetings-stream.template.md`
-
-If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer (Half B) above. The Half A `verbatim/<dir>/` capture remains mandatory and unchanged.
 
-**Verbatim sibling required.** Every per-meeting block written here MUST have a matching `Evidence/<alias>/meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` folder produced by Half A. The block's `Source basis` line and `Artifacts` section must cite the verbatim folder's relative path. Self-check D13 enforces this.
+> **Load `references/legacy-stream.md`** for the full legacy stream-file format (AI Narrative Summary, chronological transcript walk-through, attendees/agenda structure, merge rules). Load only when reading or maintaining pre-v4.9.0 stream/ files on disk.
 
 ## Mutable hints to upsert (during the run, not at the end)
 
@@ -217,11 +167,11 @@ After the pass:
 - A meeting has neither transcript NOR chat messages → write `verbatim/<dir>/coverage.md` documenting every failed path + write `❌ source-expired-or-unrecoverable` block in stream/, log error, continue.
 - All paths failed for ALL meetings in the window → mark source `failed`, write a single `❌ all paths failed` evidence file with actionable next step. Verbatim/ folders for each meeting still get created with captured-at.txt + coverage.md (the empty-folder audit trail is itself evidence).
 - A per-meeting block lacks a sibling `verbatim/<YYYY-MM-DD-HHMM>_<slug>/` directory → **defect** per `meetings-verbatim-required.instructions.md`. Re-run Half A immediately; do NOT ship the curated block alone.
-
-## References (v4.4.7)
-
-- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
-- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
 
 
 ## Issue Recovery
@@ -240,6 +190,10 @@ WorkIQ (`workiq ask`) is the only allowed path. Use **CSC canonical prompts** fr
 
 ## Changelog
 
+- **v3.0.1 (kushi v5.0.1, 2026-05-26)**: agentskills.io spec-compliance pass. Extracted Half A
+  transcript cascade (WorkIQ steps a–d, chat capture, classification, coverage.md) →
+  `references/verbatim-capture.md`; legacy stream-file format → `references/legacy-stream.md`.
+  SKILL.md trimmed from 267 to ~175 lines. Behaviour unchanged; load-on-trigger pointers added.
 - **v3.0.0 (kushi v4.9.0, 2026-05-26)**: BREAKING. Half B is now a single weekly CSC file per ISO week
   (`weekly/<YYYY-MM-DD>_meetings-csc.md`) + per-contributor `_index/entities.yml`. snapshot/ + stream/
   writes removed. WorkIQ prompts for Half B switched to CSC canonical prompts. AI Narrative Summary
@@ -247,4 +201,13 @@ WorkIQ (`workiq ask`) is the only allowed path. Use **CSC canonical prompts** fr
   still uses v4.8 verbatim transcript prompts. Bootstrap now walks the FULL boundary window writing
   verbatim/ for every meeting (v4.8 one-per-source carve-out DROPPED). Legacy snapshot/+stream/
   folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/+verbatim/ shape. See git history.
+- **v2.x.x**: prior snapshot/+stream/+verbatim/ shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-meetings`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/pull-meetings/references/legacy-stream.md

@@ -0,0 +1,15 @@
+# references/legacy-stream.md (pull-meetings)
+
+> **Load this file when** maintaining or reading pre-v4.9.0 `stream/` or `snapshot/` files — i.e., when legacy evidence exists on disk and you need to understand the prior output shape for reader fallback purposes.
+
+## Stream pass (LEGACY — pre-v4.9.0)
+
+Per `evidence-thoroughness.instructions.md`: every meeting in the window gets a full per-meeting block whose **FIRST sub-section is an AI Narrative Summary (REQUIRED, 5+ paragraphs)** covering the whole meeting end-to-end — context, what was discussed in what order, who took which position, the reasoning, the back-and-forth, soft signals, sentiment, what landed and what stayed open (cited to transcript timestamps). Then attendees → agenda → Detailed Discussion Summary (topic-organized) → chronological transcript walk-through with verbatim quotes → Decisions → Open Questions → Next Steps → Action Items → Risks → Customer Asks → Coverage Notes. **A 30-line meetings file for a week with 2 meetings is a defect — expect 300+ lines (the AI Narrative Summary alone is typically 30-50 lines per meeting).** A per-meeting block missing the AI Narrative Summary as the first sub-section is a defect even if every other section is present.
+
+Write to: `<engagement-root>/<project>/Evidence/<alias>/Meetings/stream/<YYYY-MM-DD>_meetings-stream.md` (date = Monday of the ISO week).
+
+Use template: `templates/weekly/meetings-stream.template.md`
+
+If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+
+**Verbatim sibling required.** Every per-meeting block written here MUST have a matching `Evidence/<alias>/meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` folder produced by Half A. The block's `Source basis` line and `Artifacts` section must cite the verbatim folder's relative path. Self-check D13 enforces this.