kushi-agents 4.4.3 → 4.7.4

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

@@ -129,4 +129,106 @@ Before writing any per-entity block (meeting / thread / email / page / file / re
 - [ ] **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
+- [ ] Empty sections explicitly say `_None surfaced._`, never omitted
+
+<!-- merged from evidence-thoroughness.instructions.md (v4.4.9) -->
+## Detection algorithm
+
+Every `pull-*` skill MUST run this check after writing each evidence file. A file that fails the detector is a **defect** — it MUST be re-extracted with a richer query or replaced with pasted source content. The skill MUST NOT silently accept a thin file.
+
+This detector enforces `evidence-thoroughness.instructions.md` at runtime. The thoroughness doctrine defines what "full" means; this file defines how to **detect** and **fix** violations.
+
+## Per-source minimum thresholds
+
+Apply the threshold for the source the file belongs to. A file fails if **any** check triggers.
+
+### Email stream (`email/stream/*.md`)
+
+- Per thread block: body text ≥ **400 characters** (not counting headers / metadata / "see original" stubs).
+- Per thread block contains at least one of: `Body:`, `Reply chain`, or a quoted block.
+- File-level: ≥ 1 thread block per substantive subject mentioned in the windowed search results.
+
+### Teams stream (`teams/stream/*.md`)
+
+- Per thread block: reproduces ≥ **5 messages** (or, if thread is shorter, ALL messages — collapse only routine acks 👍 / "thanks").
+- Each reproduced message has `<sender> · <timestamp>` line + verbatim or close-paraphrase text.
+- File-level: rejects "summary-only" files with no message-by-message reproduction.
+
+### OneNote snapshot (`onenote/snapshot/pages/*.md`)
+
+- Page body text ≥ **600 characters** OR contains a `## Page Body` section followed by content (not just a link).
+- Page metadata block (last-modified, author) present.
+
+### OneNote stream (`onenote/stream/*.md`)
+
+- Each page-edit event includes diff summary (what changed) — not just "page updated".
+
+### SharePoint snapshot tree (`sharepoint/snapshot/tree.md`)
+
+- Tree is not truncated (no "…" or "N more" placeholders).
+- Each entry has a status tag: `[key]` / `[recent]` / `[pin]` / `[skip]` / `[tree-only]`.
+
+### SharePoint snapshot file (`sharepoint/snapshot/files/*.md`)
+
+- Body summary ≥ **400 characters** OR explicit `[tree-only]` justification.
+- Has changed-by + change-type + last-modified.
+
+### Meetings stream (`meetings/stream/*.md`)
+
+- Per meeting block contains ALL of the following named sections:
+  - `## Detailed Discussion Summary`
+  - `## Transcript Walk-Through` (or `## Chronological Walk-Through`)
+  - `## Key Decisions`
+  - `## Open Questions` (or `## Open Questions / Non-Decisions`)
+  - `## Next Steps` ← **dedicated section, distinct from Action Items**
+  - `## Action Items`
+- `## Next Steps` MUST be present even if empty (`_None this meeting._`) — missing the section is a defect.
+- Per meeting block: total length ≥ **800 characters**.
+- Action items: every bullet has owner + due (date OR "TBD" with reason) + `[source: …]` citation.
+
+### CRM/ADO snapshot (`crm/snapshot/*.md`, `ado/snapshot/*.md`)
+
+- Snapshot lists ≥ **8 fields** with values (not just an ID + a link).
+
+### CRM/ADO stream (`crm/stream/*.md`, `ado/stream/*.md`)
+
+- Each change event has old-value → new-value + actor + timestamp.
+
+## Red-flag patterns (auto-fail)
+
+Any file containing these strings outside a `## Coverage Notes` block fails:
+
+- `(see original in …)` / `see original email` / `see Teams thread` / `see page` — link-only stubs.
+- `Full body unavailable` / `body not captured` without an accompanying `## Coverage Notes` explaining why.
+- `Summary: …` as the entire body (no detail beneath it).
+- `[redacted]` without justification.
+- `TODO` / `FIXME` left in production evidence.
+
+## Retry policy
+
+When a file fails the detector:
+
+1. **Auto-retry once** with a deeper WorkIQ query. Append `"give me full bodies and full reply chain — not just metadata"` (or source-appropriate equivalent) to the query. Re-write the file.
+2. If the second attempt still fails the detector, emit the **paste-prompt** (see `plugin/templates/paste-prompt.md`) to the user with the specific file path, the failing checks, and ready-to-paste section headers.
+3. Mark the file with `⚠ thoroughness: pending-paste` at the top under `## Source Basis` and log `thoroughness-pending` in `run-log.yml` for that source. Continue the rest of the run — do NOT block.
+
+## Validation block in every evidence file
+
+Every evidence file MUST end with:
+
+```
+## Validation
+
+- [ ] bodies-present
+- [ ] attendees-or-participants-captured       <!-- meetings/teams only -->
+- [ ] next-steps-section-present               <!-- meetings only -->
+- [ ] action-items-have-owner-and-due          <!-- meetings only -->
+- [ ] no-link-only-stubs
+- [ ] coverage-notes-explain-any-gaps
+```
+
+The skill ticks the boxes it can verify automatically; the rest are left for `self-check` and human review.
+
+## Out of scope
+
+This detector does NOT enforce citation density (that's `citation-ledger.instructions.md`) or snapshot-vs-stream placement (that's `snapshot-vs-stream.instructions.md`). It enforces depth-of-capture only.

package/plugin/instructions/fuzzy-disambiguation.instructions.md

@@ -0,0 +1,97 @@
+---
+applyTo: "**"
+description: "Universal fuzzy-match contract — whenever a kushi skill needs to map a user-given name (project, OneNote section, SharePoint site, Teams chat, ADO area, CRM record, mailbox folder, meeting topic) to a concrete identifier, it MUST use the same ranked-candidate flow with ask_user disambiguation on ambiguity. Eliminates inconsistent matching across sources."
+---
+
+# Fuzzy Disambiguation (HARD RULE, v4.4.7+)
+
+Every kushi skill that maps a **string the user typed** (or pulled from config) to a **concrete ID/path/record** in an external system goes through this exact flow. No per-source improvisation.
+
+## Why this exists
+
+Different sources used different matching heuristics: `engagement-root-resolution` did `exact > prefix > contains` and prompted on ambiguity; `pull-onenote` Step A did its own section-name fuzz; `pull-teams` matched chat topics manually; `pull-crm` accepted whichever Dataverse row came back first. Result: same project name resolved to different things across sources, and users were silently sent to the wrong artifact.
+
+## The flow (applies to ALL sources)
+
+1. **Candidate list.** Pull every plausible target from the source (notebooks under the user's account, chats in the last 60d, project folders under engagement-root, etc.). Cap at 50 candidates.
+
+2. **Score and rank** with this fixed lexicographic order:
+   - **exact** (case-insensitive equality) — score 1000
+   - **prefix** (target startsWith query) — score 800 − (target.length − query.length)
+   - **contains** (target.includes query) — score 500 − distance-from-start
+   - **token-overlap** (query and target share ≥ 1 whitespace-split token, case-insensitive) — score 300 + matchedTokens × 10
+   - **levenshtein** (within 2 edits) — score 100 + (3 − distance) × 10
+   - else — score 0 (drop)
+
+3. **Decision rule** (uses top 5 scored candidates):
+   | Situation | Action |
+   |---|---|
+   | Top candidate score ≥ 800 AND #2 score ≤ top × 0.7 | **Auto-pick top**. Echo: `✓ Resolved '<query>' → '<picked>' (<source-id>) [score=<n>, confidence=high]`. Continue. |
+   | Top candidate score ≥ 300 AND #2 score ≤ top × 0.7 AND in `--non-interactive` mode | **Auto-pick top with warning**. Echo: `⚠ Auto-picked '<query>' → '<picked>' (<source-id>) [score=<n>, confidence=medium]. Re-run interactively to confirm.` |
+   | Top ≥ 1 candidate AND interactive | **`ask_user` with options**. See "Disambiguation prompt shape" below. |
+   | Zero candidates above score 100 | **`ask_user` with type-in-an-id option**. After 1 failed retry → write `unresolved-<source>` to run-log + tracking; continue with the source-level coverage gap. |
+
+4. **Persist the resolution** to the appropriate registry so the next run is direct:
+   - Project name → `m365-mutable.json#m365Mutable.knownSections.<project>` (per `m365-id-registry.instructions.md`)
+   - OneNote section/notebook → `m365-mutable.json#m365Mutable.knownSections.<project>.onenote.<section>`
+   - SharePoint site → `<project>/integrations.yml#sharepoint.siteId` + `siteName`
+   - Teams chat → `<alias>/.settings.yml#teams.chatIds[]`
+   - ADO area → `<project>/integrations.yml#ado.areaPath`
+   - CRM record → `<project>/integrations.yml#crm.recordId`
+   - Mailbox folder name → `<workspace>/.kushi/config/user/m365-auth.json#emailContext.folders[]` (already canonical names)
+
+   Persistence happens INSIDE the pull skill that resolved it, in the same run.
+
+## Disambiguation prompt shape (ALWAYS the same)
+
+```
+🤔 Multiple matches for '<query>' in <source>:
+
+  1) <candidate-1-display-name> · <secondary-context>   [score=<n>]
+  2) <candidate-2-display-name> · <secondary-context>   [score=<n>]
+  3) <candidate-3-display-name> · <secondary-context>   [score=<n>]
+  4) Type a different name / ID
+  5) Skip this source for now (write unresolved-<source> to run-log)
+
+Which one matches '<query>'?
+```
+
+Render via `ask_user` (preferred) when the host supports it. Fallback: chat-message prompt with the same shape.
+
+- "Secondary context" is whatever disambiguates **the same display name appearing twice**: notebook owner, site URL host, ADO project, CRM account name, meeting organizer + date, etc.
+- The chosen option is **persisted immediately** (see step 4). No re-prompt for the same query in the same project.
+
+## Retry-once contract
+
+If `ask_user` returns option 4 (type-in) and the typed value still doesn't resolve in step 1, retry ONCE with the new query, then fall through to option 5 (skip + write `unresolved-<source>`). Never loop forever.
+
+## Where this rule applies (HARD inventory)
+
+| Surface | Query | Resolves to |
+|---|---|---|
+| `engagement-root-resolution` Step "project name" | user's project arg | `<engagement-root>/<project>/` folder |
+| `pull-onenote` Step A | section name from `m365-mutable.json` or new ask | OneNote `sectionId` + `notebookId` (write to id-registry) |
+| `pull-sharepoint` Step "resolve site" | site name / URL hint | `siteId` + `webUrl` (write to project `integrations.yml`) |
+| `pull-teams` Step "scope chats" | chat topic / member name | `chatId[]` (write to alias `.settings.yml`) |
+| `pull-meetings` Step "scope meetings" | meeting subject pattern | meeting candidates by joinUrl (no persistence — meeting-scoped) |
+| `pull-crm` Step "resolve record" | account / project name | Dataverse `engagementRecordId` (write to project `integrations.yml`) |
+| `pull-ado` Step "resolve area" | area name | ADO `areaPath` (write to project `integrations.yml`) |
+| `pull-email` Step "resolve mailbox folders" | folder name | canonical folder display-name (write to `m365-auth.json`) |
+| `ask-project` Step "resolve project" | user's project arg in question | same as engagement-root-resolution |
+
+## What NOT to do
+
+- Do NOT silently pick the first candidate when score-gap is `< 0.7`. Always disambiguate.
+- Do NOT prompt with the legacy "Enter the exact name:" free-text — always present a ranked list first.
+- Do NOT re-prompt for the same query in the same run after the user picked an answer. Cache it for this run AND persist for next-run direct lookup.
+- Do NOT use per-source thresholds. The above scoring is universal.
+
+## Self-check enforcement
+
+**D17 — Fuzzy disambiguation cite.** Every `pull-*` SKILL.md whose source has fuzzy name → ID resolution (`pull-onenote`, `pull-sharepoint`, `pull-teams`, `pull-crm`, `pull-ado`, `pull-email`) MUST reference `fuzzy-disambiguation.instructions.md` in its body. Plus `engagement-root-resolution.instructions.md` and `ask-project` SKILL.md.
+
+## References
+
+- `engagement-root-resolution.instructions.md` — the originating "ask user on ambiguity" pattern (project-name resolution). v4.4.7+ this rule is the universal generalization.
+- `m365-id-registry.instructions.md` — destination registries for persisted resolutions.
+- `multi-user-shared-files.instructions.md` — `m365-mutable.json` writes go through the SharePoint conflict-absorb pattern.

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

@@ -71,3 +71,79 @@ Per `deferred-retry-on-workiq-fail.instructions.md`, identity resolution NEVER b
 * `deferred-retry-on-workiq-fail.instructions.md` — failure-mode contract.
 * `engagement-root-resolution.instructions.md` — `projects_root` resolution (separate from identity).
 * `templates/init/project-evidence.template.yml` — defaults to `<auto>` for these three fields.
+
+---
+
+## v4.4.5 extension — `setup` skill is the single source of truth for ALL onboarding questions
+
+The `setup` skill (added v4.4.4) extends this doctrine beyond identity to cover the full onboarding question set. `bootstrap-project` MUST NOT re-ask any question that `setup` already answered.
+
+### Fields managed by `setup`
+
+| File | Field | Required? | Auto-resolved from |
+|---|---|---|---|
+| `project-evidence.yml` | `identity.alias` / `display_name` / `email` | YES | WorkIQ "Who am I?" |
+| `project-evidence.yml` | `identity_status`, `identity_verified_at` | YES | written by setup |
+| `project-evidence.yml` | `projects_root` | YES | cwd-ancestor detection; otherwise prompt |
+| `project-evidence.yml` | `default_onenote_notebook` | **OPTIONAL** | user prompt; value `<skip>` = OneNote disabled |
+| `project-evidence.yml` | `active_projects[]` | YES (list, may be empty) | the project arg if dispatched from `bootstrap <project>`; otherwise leave existing |
+| `project-evidence.yml` | `workiq.cli_path` | OPTIONAL | only written when discovered via PATH/fallback, not already pinned |
+| `m365-auth.json` | `_meta.owner` | YES | `<identity.email>` |
+| `m365-auth.json` | `oneNote.defaultLinkOwner` | YES (when OneNote enabled) | `<identity.email>` — the user's own UPN, since OneNote queries default to the user's personal notebook |
+| `m365-auth.json` | `oneNote.defaultNotebookId` | **NOT WRITTEN (kushi v4.7.3+)** | Per `workiq-onenote-query-shape.instructions.md`, WorkIQ has no notebook-ID lookup surface — any such probe punts to Graph Explorer. Setup persists `defaultNotebookName` only; section IDs are discovered per-section at bootstrap/refresh time using the natural-language WorkIQ pattern. |
+| `m365-auth.json` | `oneNote.enabled` | YES | `false` when user chose `<skip>` for the notebook name |
+| `m365-auth.json` | `emailContext.folders[]` | OPTIONAL | user prompt: comma-sep list / `all` / blank. `all` or blank → `[]` (full mailbox) |
+| `m365-auth.json` | `sharePointContext.localProjectsRoot` | YES | mirrors `<projects_root>` |
+
+### Auto-EULA + sign-in detection
+
+`pingWorkIQ()` in `src/check-workiq.mjs` auto-runs `workiq accept-eula` (idempotent) when the first `workiq ask -q "ping"` returns empty OR mentions EULA/license, then retries the ping. Only if BOTH attempts return empty does the installer surface a "Sign in by running `workiq ask -q \"Who am I?\"` in a new terminal" hint.
+
+The `setup` skill does the deeper recovery (3-retry loop with `ask_user` choices).
+
+### OneNote — optional + auto-resolve
+
+- User chose `<skip>` → set `oneNote.enabled: false`, leave all other OneNote fields blank, OneNote source becomes a no-op (reported as `not-applicable` in run logs).
+- User gave a notebook name → query WorkIQ for `{notebookId, notebookSourceDoc, notebookSpoBaseUrl}`. Persist all three. If WorkIQ returns empty, leave `defaultNotebookId: ""` with a `_defaultNotebookId_note` and let `pull-onenote` Step A do per-section discovery.
+- `defaultLinkOwner` is ALWAYS the user's own UPN unless the user explicitly overrides (shared/team-owned notebook case).
+
+### Mailbox folders — multi-value with "all" sentinel
+
+Question text (only asked once, only by `setup`, only when `emailContext.folders` is empty or `["__FILL_ME_IN__"]`):
+
+> Which mailbox folders should kushi search for email evidence?
+> • Enter a comma-separated list (e.g. `Inbox, Archive, Projects/HCA`)
+> • Type `all` to search the FULL mailbox (slower — every refresh scans everything)
+> • Press Enter to leave blank (equivalent to `all`)
+
+Both `all` and blank persist as `[]`. ALWAYS print after persisting:
+
+> Note: empty list = scan the full mailbox on every refresh (slower). Add specific folders later via `.kushi/config/user/m365-auth.json#emailContext.folders` to speed runs up.
+
+### Active projects — don't ask, use what was asked
+
+- **Dispatched from `bootstrap <project>`** → append `<project>` to `active_projects` (don't replace).
+- **Standalone `setup`** → leave `active_projects` untouched; just print the file pointer.
+- **`setup --reconfigure`** → ask the user explicitly, default = current list.
+
+### "Where to edit this later" footer (REQUIRED on every setup run)
+
+```
+Edit these files later if anything changes:
+  • <workspace>/.kushi/config/user/project-evidence.yml
+      identity, projects_root, default_onenote_notebook, active_projects, workiq.cli_path
+  • <workspace>/.kushi/config/user/m365-auth.json
+      OneNote defaults, email folder list, SharePoint root
+  • <workspace>/.kushi/config/shared/integrations.yml   (team-wide; commit changes)
+      CRM environmentUrl + tenantId, ADO organization + project
+
+To re-walk every question (overwrites all answers):
+  @Kushi setup --reconfigure
+```
+
+Render the file paths as clickable `file:///` URIs when the host (VS Code, Clawpilot) supports them.
+
+### `bootstrap-project` Step 0 contract
+
+`bootstrap-project` Step 0 dispatches to `setup` only when `identity_status` is missing or `skipped-*`. It NEVER directly asks for identity, OneNote name/ID, mailbox folders, or `projects_root`. If `identity_status: verified` is set, Step 0 is a no-op and bootstrap proceeds directly to Step 1.
+

package/plugin/instructions/issue-recovery.instructions.md

@@ -0,0 +1,58 @@
+---
+applyTo: "**"
+description: "Universal Issue Recovery Rule. When a workflow exposes a reusable problem in the repo-owned surface (skill text, instruction, prompt, config, supporting code), fix the smallest correct artifact first — don't just report and continue. Prefer durable fixes over one-off workarounds. After the fix, re-run the narrowest failed check before continuing. Never use memory as a substitute for correcting the workflow surface."
+---
+
+# Issue Recovery Rule (v4.5.1)
+
+A universal rule for every kushi skill that hits an external service (M365 via WorkIQ, Dataverse via az CLI, ADO via az boards, OneNote via Playwright, etc.) AND for every workflow that consumes evidence (aggregate-project, ask-project, fde-report).
+
+## The rule
+
+When a run exposes a reusable problem in the repo-owned ADO/CRM/M365/OneNote/SharePoint/Meetings/Email surface:
+
+1. **Fix the smallest correct repo-owned artifact first** when feasible.
+   - Skill text (`plugin/skills/<name>/SKILL.md`)
+   - Instruction file (`plugin/instructions/*.instructions.md`)
+   - Prompt (`plugin/prompts/*.prompt.md`)
+   - Config template (`plugin/templates/init/*.template.*`)
+   - Supporting code (`plugin/skills/<name>/*.mjs`, `plugin/lib/*.ps1`, `src/*.mjs`)
+   - Reference pack (`plugin/reference-packs/<pack>/*.md`)
+2. **Prefer a durable fix over a one-off workaround** when the issue will affect the next run too. Per-run workarounds (chat-only retries, ad-hoc filter changes that aren't persisted) are escalation paths, not solutions.
+3. **After the fix, rerun the narrowest failed check** before continuing the broader workflow steps. E.g. if pull-onenote failed Pre-flight C URL completeness, fix the canonical URL doctrine + re-run Pre-flight C only; don't re-run the whole bootstrap.
+4. **Record the minimum useful guardrail in the run report + learnings** AFTER the fix is confirmed. Per `capture-learnings.instructions.md` for the source-specific learnings file; per `run-reports.instructions.md` for the per-run narrative.
+5. **Do NOT use memory as a substitute** for correcting the workflow surface. If an issue happened once, the fix lives in the repo. Memory captures user preferences and decisions, not workflow defects.
+
+## Examples (correct application)
+
+| Symptom | Wrong response | Right response |
+|---|---|---|
+| pull-onenote returns auth-required on every project after a URL-formula change | Add retry loop to runner.mjs | Fix `pull-onenote/SKILL.md` Pre-flight C to ban synthesized URLs (per learnings/onenote.md) — durable across every project |
+| pull-ado finds zero comments because comments/history is empty; attachment has the discussion | Skip this run / mark as no-coverage | Emit `evidence_source_kind: attachment-fallback` in coverage notes; `aggregate-project` reads it; user knows the discussion lives in an attachment, not comments. Update `pull-ado/SKILL.md` if the fallback path itself is missing |
+| pull-crm finds the engagement record but the bootstrap discovery skipped it because of a 401 | Add a per-run retry in the orchestrator | Fix the auth-and-retry pattern in `auth-and-retry.instructions.md` if the retry shape is broken; or fix the `crm-bootstrap-discovery.instructions.md` if the 401 means the user has a different tenant than the config says |
+| Workspace template missing a field that user keeps having to add by hand | Document the workaround in CHANGELOG | Update the template at `plugin/templates/init/*.template.*` so the next user gets the right shape from `setup` Step 2 |
+
+## Examples (wrong application — don't do these)
+
+- ❌ **"Just store this in memory so I don't forget next time."** Memory is for user preferences and engagement-specific decisions, not workflow defects. If the same issue happens again, the fix must already be in the repo.
+- ❌ **"Hot-patch the live install but skip the repo edit."** Live install fixes are temporary; repo is the source of truth. Self-check D4 will surface the drift.
+- ❌ **"Add a one-off filter for this project to avoid the bad data."** Per-project filters belong in the project's `integrations.yml#boundaries.*`. Doctrine fixes belong in the repo.
+
+## Scope (which skills MUST cite this rule)
+
+The Issue Recovery Rule applies to every skill that runs against an external service AND to every consumer of their evidence:
+
+| Skill | Cite required | Why |
+|---|---|---|
+| `pull-email`, `pull-teams`, `pull-meetings`, `pull-onenote`, `pull-sharepoint`, `pull-crm`, `pull-ado`, `pull-misc` | ✅ | External service failures expose doctrine gaps |
+| `aggregate-project`, `consolidate-evidence` | ✅ | Consumers — they discover when capture quality is poor |
+| `bootstrap-project`, `refresh-project` | ✅ | Orchestrators — they observe per-source gate outcomes |
+| `setup`, `self-check`, `intro` | ➖ | Internal-state skills; no external service surface |
+| `ask-project`, `project-status`, `fde-*` | ➖ | Read-only over local evidence; defects surface via gate, not directly |
+
+## References
+
+- `per-source-verification-gate.instructions.md` — the per-source gate exposes the symptoms this rule responds to.
+- `capture-learnings.instructions.md` — where the post-fix learning gets appended.
+- `run-reports.instructions.md` — where the run-specific narrative records the fix.
+- `fallback-status-reporting.instructions.md` — when an attachment-fallback or comments-empty path was used, how to surface it in status.

package/plugin/instructions/kushi-config-root.instructions.md

@@ -0,0 +1,66 @@
+---
+applyTo: "**/*"
+---
+
+# Kushi config root — never hardcode `.kushi/config/` paths
+
+**Truth (v4.7.2+):** the `.kushi/config/` tree lives in different places
+depending on how Kushi was installed:
+
+| Install command                              | Config root                                  |
+|----------------------------------------------|----------------------------------------------|
+| `npx kushi-agents@latest` (default = vscode) | `<workspace>/.kushi/config/`                 |
+| `npx kushi-agents@latest --clawpilot`        | `~/.copilot/m-skills/kushi/config/`          |
+
+Some users install BOTH (per-repo vscode + global clawpilot). Both layouts are
+first-class and supported indefinitely.
+
+## Rule
+
+Every skill, prompt, and instructions file that needs to **read or write** a
+Kushi config file MUST resolve the path via the official helpers — never by
+joining `<workspace>` + `.kushi/config/...` directly.
+
+| Caller                | Helper                                                         |
+|-----------------------|----------------------------------------------------------------|
+| PowerShell (`.ps1`)   | `& "$PSScriptRoot/Get-KushiConfig.ps1" -Name '<name>'`         |
+| Node (`.mjs`)         | `import { loadKushiConfig } from '../../../src/config-loader.mjs'` |
+| Agent / prompt text   | Refer to `<kushi-config-root>/user/<name>.<ext>` (placeholder) |
+
+The helpers walk a fixed candidate order:
+
+1. `<workspace>/.kushi/config/` — if it exists with `user/` or `shared/`.
+2. `~/.copilot/m-skills/kushi/config/` — clawpilot fallback.
+
+The first match wins. The helpers throw a clear actionable error
+("Run `npx kushi-agents@latest [--clawpilot]`") when neither exists.
+
+## What this fixes (v4.7.2)
+
+Before v4.7.2, every skill (setup, bootstrap-project, pull-*) hardcoded
+`<workspace>/.kushi/config/...`. On a Clawpilot-only host (where the config
+lives at `~/.copilot/m-skills/kushi/config/`), Step 0 of `bootstrap` saw the
+workspace path missing, concluded "no install", and asked the user to
+install/overwrite `.kushi/`. That prompt was a bug — the config was present at
+the clawpilot location and bootstrap should have proceeded normally.
+
+## Prompts and user-facing text
+
+When telling the user where their config file lives (for hand-editing), call
+the resolver first:
+
+```ps1
+$pePath = & "$PSScriptRoot/Get-KushiConfig.ps1" -Name 'project-evidence' -Path
+"Edit: file:///$($pePath -replace '\\','/')"
+```
+
+Do NOT emit `file:///<workspace>/.kushi/config/user/...` as a literal — it
+points at a non-existent file on Clawpilot-only hosts.
+
+## Migration of legacy doctrine text
+
+In prose, the canonical placeholder is `<kushi-config-root>/user/<name>.yml`
+(or `.../shared/<name>.yml`). Old text using `<workspace>/.kushi/config/...`
+is equivalent ONLY for vscode installs and should be migrated when touched.
+The helpers continue to support both layouts, so the bug is in the doctrine
+text, not the runtime.

package/plugin/instructions/loop-bootstrap-discovery.instructions.md

@@ -0,0 +1,105 @@
+---
+applyTo: "**/pull-loop/**,**/setup/**,**/bootstrap-project/**,**/refresh-project/**"
+description: "How Loop workspaces and pages are registered, resolved, and persisted. WorkIQ-first for discovery + metadata; Playwright for body capture. Mirrors the OneNote bootstrap pattern."
+---
+
+# Loop bootstrap discovery (v4.6.0+)
+
+Loop is a first-class evidence source in kushi v4.6.0+. This doctrine governs how a project's Loop workspaces and pages are discovered, resolved to durable IDs, and persisted to the per-user registry.
+
+## Surface model
+
+Microsoft Loop has three relevant surface levels:
+
+| Level | URL pattern | What it is |
+|---|---|---|
+| **Workspace** | `https://*.loop.microsoft.com/loop/p/<workspaceId>/_workspace` | Top-level container; holds pages |
+| **Page** | `https://*.loop.microsoft.com/loop/p/<workspaceId>/<pageId>` | A document inside a workspace; can hold components, tables, lists |
+| **Standalone component** | `https://*.fluidpreview.office.net/...`, `https://loop-api.cloud.microsoft/...` | A Loop component embedded in another surface (Teams chat, OneNote page, Outlook email, etc.) |
+
+Kushi captures workspace + page bodies. Standalone components embedded in Teams/OneNote/Email are captured by their host source's `pull-*` skill, NOT by `pull-loop` (which would double-count).
+
+## Registry shape
+
+Persisted to `<workspace>/.kushi/config/user/m365-mutable.json` under `knownSections.<projectKey>.loop`:
+
+```json
+{
+  "knownSections": {
+    "<projectKey>": {
+      "loop": {
+        "workspaces": [
+          {
+            "workspaceId": "<base64-workspace-id>",
+            "workspaceUrl": "https://<tenant>.loop.microsoft.com/loop/p/<workspaceId>/_workspace",
+            "workspaceTitle": "<display title>",
+            "owner": "<upn>",
+            "discovered_at": "<ISO-8601>",
+            "loop_pages": [
+              {
+                "pageId": "<page-id>",
+                "pageUrl": "https://<tenant>.loop.microsoft.com/loop/p/<workspaceId>/<pageId>",
+                "pageTitle": "<display title>",
+                "last_status": "ok | auth-required | page-body-unavailable | unresolved",
+                "last_captured_at": "<ISO-8601>",
+                "captured_via": "playwright | workiq | host"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+This shape mirrors `knownSections.<projectKey>.onenote.{sections, one_pages}` — same discover-once / consume-deterministically contract per `m365-id-registry.instructions.md`.
+
+## Discovery flow (during `setup` Step 4d-loop)
+
+When the user enables Loop for a project, run this flow:
+
+1. **Ask for the workspace URL(s).** `ask_user` with the user's recent Loop activity (if WorkIQ can surface it via `workiq ask -q "List my recent Loop workspaces. Return strictly JSON: [{workspaceId, workspaceUrl, workspaceTitle}]. No prose."`). Else ask for a URL paste.
+2. **Resolve via WorkIQ** — `workiq ask -q "What is the Loop workspace ID for workspace at URL '<URL>'? Return strictly JSON: {workspaceId, workspaceTitle, owner}. No prose."`. WorkIQ returns metadata via the M365 search/Graph index.
+3. **Enumerate pages via WorkIQ** — `workiq ask -q "List pages in Loop workspace '<workspaceTitle>' (id=<workspaceId>) modified in the last 90 days. Return strictly JSON array: [{pageId, pageUrl, pageTitle, lastModified}]. No prose."`. Persist each as `loop_pages[]` with `last_status: "unresolved"`.
+4. **Persist** — write to `knownSections.<projectKey>.loop.workspaces[]` per `m365-id-registry.instructions.md` (discover-once); never re-discover unless `--reconfigure`.
+5. **Skip-friendly** — Loop is OPTIONAL. If WorkIQ returns no Loop coverage in this tenant (Conditional Access / new feature / no workspaces), persist `loop_status: "skipped-no-coverage"` and continue. `pull-loop` will refuse to run when Loop isn't registered for a project — never silently widens to "all loop workspaces."
+
+## Pre-flight gates (every `pull-loop` invocation)
+
+| Pre-flight | Pass criteria |
+|---|---|
+| **A. Workspaces registered** | `knownSections.<projectKey>.loop.workspaces[]` non-empty for the resolved project. |
+| **B. Pages registered** | At least one workspace has `loop_pages[]` non-empty OR `loop_pages_status: "to-be-enumerated"`. |
+| **C. Playwright profile bootstrapped** | `~/.kushi/playwright-profile/m365/` exists OR `~/.kushi/playwright-profile/onenote/` exists (reused; see Profile sharing below). |
+| **D. URLs are canonical** | Every `pageUrl` matches `https://*.loop.microsoft.com/loop/p/<workspaceId>/<pageId>` (or a documented redirect target). Synthesized URLs (constructed from workspaceId + pageId templates) are FORBIDDEN unless they were observed in a WorkIQ response — same rule as OneNote per the learnings/onenote.md doctrine. |
+
+On Pre-flight failure: refuse to run, write a `FOLLOW-UPS.md` entry per `per-source-verification-gate.instructions.md`, and instruct the user to run `@Kushi setup --reconfigure` (or `setup --resync-loop`).
+
+## Profile sharing with OneNote
+
+The Playwright profile at `~/.kushi/playwright-profile/onenote/` is M365-wide — it holds the user's signed-in browser context for OneNote-for-Web, SharePoint-Online, Loop, and Office.com. `pull-loop` reuses this profile (no separate bootstrap). If the profile is missing or auth-expired, the OneNote bootstrap recipe re-mints it: `node plugin/skills/pull-onenote/runner.mjs --bootstrap` (the bootstrap visits SharePoint surfaces, which also seeds Loop auth).
+
+In v4.6.0+ the profile path is canonically `~/.kushi/playwright-profile/m365/` with `~/.kushi/playwright-profile/onenote/` retained as a fallback for older installs. Both readers check both paths; new bootstraps write to `m365/`.
+
+## Boundary in `<project>/integrations.yml`
+
+```yaml
+boundaries:
+  loop:
+    workspace_ids: []                # required: durable IDs from knownSections.<project>.loop.workspaces[]
+    page_ids: []                     # optional: pin specific pages; else enumerate all in workspace
+    include_components: false        # v4.6.0: standalone components captured by their host source (teams/onenote/email)
+```
+
+`workspace_ids` MUST be non-empty for Loop to be enabled per `scope-boundaries.instructions.md`. Empty = source disabled.
+
+## References
+
+- `m365-id-registry.instructions.md` — discover-once contract.
+- `evidence-thoroughness.instructions.md` — verbatim body capture.
+- `per-source-verification-gate.instructions.md` — gate §2 loop row + §2a canonical kind.
+- `workiq-only.instructions.md` — discovery via WorkIQ first.
+- `issue-recovery.instructions.md` — apply when Loop discovery or capture fails.
+- `cleanup-on-resolution.instructions.md` — when a page resolves from `unresolved` → `ok`, prune the stale marker.
+- `docs/concepts/loop-source.md` — user-facing companion doc.

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

@@ -123,7 +123,7 @@ The script's `--check` mode is the gate; the interactive mode is the heal. See `
 
 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.
+3. ❌ Pull-* skill uses the wrong WorkIQ phrasing for the source. For OneNote specifically (per `workiq-onenote-query-shape.instructions.md`, kushi v4.7.3+): WorkIQ is the **PRIMARY** path; Playwright is opt-in recovery-only fallback. The only working WorkIQ shape is **natural-language naming by display name** (one section in one notebook). Forbidden: `"List my OneNote notebooks"`, `"What is the OneNote notebook ID for..."`, `"List sections in OneNote notebook..."`, anything with `wdsectionfileid = <id>` filter syntax, anything asking for ID-shaped JSON output. These all empirically fail (WorkIQ punts to Graph or routes to summary mode).
 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.