kushi-agents 4.4.3 → 4.7.4

package/plugin/instructions/onedrive-pin-policy.instructions.md

@@ -0,0 +1,132 @@
+---
+applyTo: "**"
+description: "After a SharePoint library is synced to a local OneDrive mirror, kushi must pin (always-keep-on-device) the folders this contributor reads+writes constantly while leaving other contributors' evidence cloud-only. This avoids 8× disk duplication on shared engagements without losing visibility of shared state. Cross-platform: Windows uses `attrib +P` / `attrib -P +U`; macOS uses `xattr` + `brctl`."
+---
+
+# OneDrive pin policy (v4.5.0)
+
+## Why
+
+A kushi engagement root, once synced, contains:
+
+```
+<engagement-root>/
+  <project>/
+    integrations.yml                  ← shared, tiny, read every run
+    bootstrap-status.md               ← shared, read every run
+    Evidence/
+      run-log.yml                     ← shared
+      contributors.yml                ← shared
+      ushak/        ← YOUR slice — read+write heavy
+      bob/          ← other contributor — read only during consolidate
+      maria/        ← other contributor — read only during consolidate
+      _Consolidated/ ← shared output of consolidate
+    State/                            ← shared, rewritten by state/consolidate
+```
+
+If every contributor's OneDrive holds every byte of every other contributor's evidence, an 8-person engagement multiplies disk usage by 8× for no benefit.
+
+But scoping the sync per-contributor breaks `consolidate` and `state` (they need to read everyone's evidence). The right answer is: **one sync root, Files-On-Demand pinning per folder**.
+
+Files-On-Demand makes non-pinned folders **cloud-only stubs** on disk:
+
+- Folder + file metadata visible (so kushi can walk the tree).
+- Bytes downloaded only when a file is opened.
+- Pinned folders are kept locally always.
+
+## What to pin (per contributor)
+
+The pin policy on each contributor's machine:
+
+| Folder/file | Action | Reason |
+|---|---|---|
+| `<project>/integrations.yml` | **Pin** | Read every kushi run; tiny |
+| `<project>/bootstrap-status.md` | **Pin** | Read every kushi run; tiny |
+| `<project>/FOLLOW-UPS.md` | **Pin** | Written by gate; read by next run |
+| `<project>/Evidence/run-log.yml` | **Pin** | Watermark, every run |
+| `<project>/Evidence/contributors.yml` | **Pin** | Every run |
+| `<project>/Evidence/<my-alias>/` | **Pin (recursive)** | Read+write heavy; can't be cloud-only |
+| `<project>/Evidence/_Consolidated/` | **Pin (recursive)** | Read+write by consolidate/state |
+| `<project>/State/` | **Pin (recursive)** | Read+write by build-state |
+| `<project>/Evidence/<other-alias>/` | **Leave cloud-only** (default) | Only touched during consolidate; OneDrive auto-downloads on demand |
+
+## Cross-platform pin commands
+
+### Windows
+
+```powershell
+# Pin (always keep on device) — recursive on folders
+attrib +P "<absolute-path>" /S /D
+
+# Cloud-only (free up space) — recursive on folders
+attrib -P +U "<absolute-path>" /S /D
+```
+
+`attrib` ships with Windows; no admin required for files the user owns. Note: `+P` and `+U` are mutually exclusive — when pinning, OneDrive auto-clears `+U` and vice versa.
+
+### macOS
+
+```bash
+# Pin a folder
+xattr -w com.microsoft.OneDrive.PinnedToDevice 1 "<absolute-path>"
+
+# Force download (materialize) a cloud-only path
+brctl download "<absolute-path>"
+
+# Free up local space (set cloud-only)
+brctl evict "<absolute-path>"
+```
+
+For recursive operations, walk the tree and apply per-folder. macOS does NOT support a single recursive pin command equivalent to Windows' `attrib /S /D` — kushi MUST iterate sub-folders.
+
+### Linux
+
+Not supported. No OneDrive client → no Files-On-Demand → no pin semantics. Skip pin policy on Linux; surface a one-line info note.
+
+## When kushi applies the policy
+
+### Setup Step 4h — initial pin policy
+
+After `projects_root` is resolved AND points at a real directory AND OneDrive is detected (Windows: OneDrive.exe process; macOS: `pgrep OneDrive`), apply pin policy to **every project listed in `active_projects`** that has an `Evidence/<my-alias>/` folder. Skip projects with no own-alias folder yet (they'll be picked up by bootstrap).
+
+Output:
+
+```
+🔧 Optimizing OneDrive cache for your engagement…
+   ✅ Pinned (kept on device): HCA/Evidence/ushak/, HCA/State/, HCA/_Consolidated/,
+                               + project-level run-log.yml + integrations.yml
+   ➖ Left cloud-only (downloaded on demand): HCA/Evidence/bob/, HCA/Evidence/maria/
+   Disk impact: ~180 MB local · ~6.2 GB available cloud-only.
+   Change later: right-click any folder → 'Always keep on device' / 'Free up space',
+                 or run @Kushi setup --reconfigure.
+```
+
+### Bootstrap pin hook
+
+When `bootstrap-project` creates a new project's `Evidence/<my-alias>/` + `State/` + `_Consolidated/`, it MUST extend the pin set to those new folders. Idempotent — repeated calls are no-ops.
+
+### Refresh — no policy action
+
+`refresh-project` does NOT re-apply pin policy. Trust the user's manual overrides between runs. (Self-check D24 surfaces if the policy got demoted, e.g. user clicked "Free up space" on their own evidence folder.)
+
+## Detection of unsupported environments
+
+Pin commands MUST be a no-op (with info log) when:
+
+- OS = Linux.
+- OneDrive process not running.
+- Path is NOT inside a OneDrive-synced root (Windows: not under `%USERPROFILE%`; macOS: not under `~/Library/CloudStorage/` or `~/<Tenant>/`).
+- Path is on a network share or mapped drive that bypasses OneDrive entirely.
+
+In all those cases: log `Pin policy skipped (OneDrive Files-On-Demand not applicable on this path).` and continue.
+
+## Override mechanics
+
+Users can manually pin/unpin via right-click Explorer/Finder at any time. Kushi MUST NOT overwrite user choices on subsequent runs. The pin operations above are **additive**: kushi adds folders to the pin set, never removes them. (Demotion is solely the user's action.)
+
+## References
+
+- `sharepoint-to-onedrive-sync.instructions.md` — the auto-sync doctrine that precedes this.
+- `engagement-root-resolution.instructions.md` — where `projects_root` is canonically resolved.
+- `docs/concepts/sync-and-pinning.md` — user-facing doc explaining the disk-footprint model.
+- `docs/concepts/storage-backends.md` — supported backend matrix.

package/plugin/instructions/per-source-verification-gate.instructions.md

@@ -0,0 +1,193 @@
+---
+applyTo: "**/SKILL.md,**/bootstrap-project/**,**/refresh-project/**,**/aggregate-project/**"
+description: "HARD rule v4.4.7+ — after each pull-<source> completes inside bootstrap/refresh/aggregate, run a verification gate that confirms snapshot/stream/verbatim shapes are healthy. On gate failure, retry the pull ONCE. If still failing, write a follow-on entry to <project>/FOLLOW-UPS.md + tracking + run-log and continue to the next source. Never silently move on."
+---
+
+# Per-Source Verification Gate (HARD RULE, v4.4.7+)
+
+Every `pull-<source>` invocation inside `bootstrap-project` / `refresh-project` / `aggregate-project` MUST be followed by a verification gate before the next source starts. Sources are independent — one source's gate failure does NOT cascade to others, but it MUST be captured in three places (run-log, tracking, FOLLOW-UPS.md) so the user can review later.
+
+## Why this exists
+
+Before v4.4.7, a `pull-*` could "complete" with `status: ok` but leave an empty `snapshot/` folder, no `stream/<week>.md` file, or a meetings `verbatim/` folder with only `captured-at.txt`. The orchestrator moved on. The user only discovered the gap days later when querying.
+
+The gate detects the gap **in the same run** and retries once. If retry still fails, the gap is queued for review instead of buried.
+
+## Gate contract (per source)
+
+Run this check **after** `pull-<source>` returns, **before** the next source starts:
+
+### 1. Shape checks (universal)
+
+| Check | Pass criteria |
+|---|---|
+| `Evidence/<alias>/<source>/` exists | directory exists, not empty |
+| Snapshot shape (if source has snapshots) | at least one `snapshot/<artifact>.md` file ≥ 200 bytes, OR `snapshot/.empty` marker with documented reason |
+| Stream shape (if source has streams) | at least one `stream/<YYYY-MM-DD>_<source>-stream.md` per ISO week in the run window, OR `stream/.empty` marker with documented reason |
+| Run-log entry written | `Evidence/run-log.yml#sources.<source>.last_run` matches THIS run's timestamp + has `last_status` from `status-taxonomy.instructions.md` |
+| Status taxonomy compliance | `last_status` ∈ closed set from `status-taxonomy.instructions.md` (no ad-hoc strings) |
+| Citation compliance | spot-check 3 random assertions in newly written files — each MUST have inline `[source: ...]` citation per `citation-ledger.instructions.md` |
+
+### 2. Per-source extra checks
+
+| Source | Additional gate |
+|---|---|
+| `meetings` | every per-meeting block in `stream/<week>.md` HAS a sibling `verbatim/<YYYY-MM-DD-HHMM>_<slug>/` containing at least `captured-at.txt` + `coverage.md` + ONE transcript-class file (`transcript.vtt` / `transcript.txt` / `transcript-source.md`) OR `coverage.md` documents `transcript-unrecoverable` |
+| `onenote` | every section listed in `m365-mutable.json#knownSections.<project>.onenote` resolved to a `sectionId` (no `<auto>` left); per-page-body or per-section-summary written |
+| `loop` | every workspace listed in `m365-mutable.json#knownSections.<project>.loop.workspaces[]` resolved to a `workspaceId`; per `loop-bootstrap-discovery.instructions.md` Pre-flight A–D; per-page-body file written for each registered `loop_pages[]` OR a documented `page-body-unavailable` / `tree-only` annotation |
+| `sharepoint` | resolved `siteId` persisted to `<project>/integrations.yml`; tree file in `snapshot/sharepoint-tree.md` exists |
+| `teams` | resolved `chatId[]` persisted to `<alias>/.settings.yml`; chat-stream files cover the window |
+| `email` | mailbox-folder filter persisted in `m365-auth.json#emailContext.folders`; email-stream files cover the window |
+| `crm` | resolved `engagementRecordId` persisted to `<project>/integrations.yml`; 4-step Dataverse resolution per `crm-bootstrap-discovery.instructions.md` is complete (not stuck at step 1 or 2) |
+
+### 2a. Evidence-source-kind annotation (v4.5.1+ — HARD)
+
+When a `pull-<source>` cannot read the canonical surface and falls back to a secondary surface, the per-source coverage notes (`coverage.md` for meetings; `<week>-stream.md` header for streamed sources; `snapshot/<artifact>.md` header for snapshotted sources) MUST emit an explicit annotation:
+
+```yaml
+# At top of the written artifact, immediately after the source/window header:
+evidence_source_kind: comments        # canonical — preferred
+# OR
+evidence_source_kind: history         # secondary — record/board history when comments are empty
+# OR
+evidence_source_kind: attachment-fallback   # tertiary — discussion lives in a .docx/.pdf attachment
+# OR
+evidence_source_kind: page-body-unavailable # OneNote stub section (pages moved/pulled out)
+# OR
+evidence_source_kind: transcript-unrecoverable  # meetings only — recording exists but transcript inaccessible
+```
+
+The gate MUST verify this annotation:
+- ✅ **Pass** when `evidence_source_kind: comments` (or a source's canonical equivalent) is present.
+- ✅ **Pass** when a non-canonical `evidence_source_kind` is present AND the coverage notes explain why the canonical surface was not used.
+- ❌ **Fail** when the artifact carries discussion content but NO `evidence_source_kind` annotation (caller can't tell whether comments were empty or the canonical surface was simply not checked).
+
+Canonical surface by source (the value that means "the preferred surface was used"):
+
+| Source | Canonical kind | Fallback kinds |
+|---|---|---|
+| `ado` | `comments` | `history`, `attachment-fallback`, `description-only` |
+| `crm` | `notes` | `timeline`, `attachment-fallback`, `summary-only` |
+| `onenote` | `page-body` | `page-body-unavailable`, `section-summary-only` |
+| `loop` | `page-body` | `page-body-unavailable`, `tree-only` |
+| `sharepoint` | `tree+modified` | `tree-only`, `permission-denied` |
+| `meetings` | `transcript` | `transcript-unrecoverable`, `attachment-fallback`, `chat-only` |
+| `teams` | `messages` | `messages-truncated`, `attachment-fallback` |
+| `email` | `messages` | `messages-truncated`, `attachment-fallback` |
+
+Downstream consumers (`aggregate-project`, `ask-project`, `fde-report`) MUST read this annotation and surface it in any answer/report that cites the artifact, so the user knows whether they are reading canonical discussion or a fallback (which is rarely as complete).
+| `ado` | resolved `areaPath` persisted to `<project>/integrations.yml`; ADO-update-snapshot rendered |
+| `misc` | OPEN-QUESTIONS-DRAFT.md, external-links.txt processed (`read` markers updated) |
+
+### 3. Process-compliance checks (the "did we actually follow the process" audit)
+
+These verify the skill **followed its own doctrine**, not just produced output:
+
+| Process check | Doctrine | What we verify |
+|---|---|---|
+| WorkIQ-first | `workiq-only.instructions.md` | run-log entry's `tools_used:` lists `workiq` as tool #1 (when applicable for the source) |
+| Verbatim-by-default | `verbatim-by-default.instructions.md` | source was dispatched (not silently skipped) IF boundary was satisfied |
+| Capture learnings | `capture-learnings.instructions.md` | if `run-log#sources.<source>.errors[]` has entries this run, `<KUSHI_ROOT>/plugin/learnings/<source>.md` was updated in the same turn |
+| Run-report mention | `run-reports.instructions.md` | this source appears in today's `refresh-reports/<timestamp>_<mode>.md` per-source table |
+| Fuzzy disambiguation | `fuzzy-disambiguation.instructions.md` | if any name → id resolution happened, the resolution was persisted to the right registry (id-registry / integrations.yml / .settings.yml) |
+| Cleanup on resolution | `cleanup-on-resolution.instructions.md` | if a previous `unresolved-<x>` was resolved this run, the stale marker was pruned |
+| Citation ledger | `citation-ledger.instructions.md` | newly written files carry inline `[source: …]` citations |
+
+## Retry-once contract
+
+If ANY gate check fails on first pass:
+
+1. **Diagnose** — record which checks failed and why.
+2. **Re-dispatch** the same `pull-<source>` skill with the same boundary, same window, plus a `--gate-retry` flag (skill MAY use this to widen its cascade, e.g. relax a strict-match in step 2).
+3. **Re-run** the gate.
+4. **If second pass also fails** → record + continue (see "Failure handling").
+
+NEVER retry more than once per source per run. NEVER block other sources.
+
+## Failure handling (write to all three surfaces)
+
+When the gate fails after retry, write to ALL of:
+
+### A. `Evidence/run-log.yml#sources.<source>`
+
+```yaml
+sources:
+  <source>:
+    last_status: completed-with-coverage-gaps   # or partial / failed per status-taxonomy
+    retry_signal: user-action                   # or retry / watch per status-taxonomy
+    last_run: <ISO-8601>
+    gate_failures:
+      - check: <gate-check-id>
+        reason: <short>
+        retried: true
+        retry_outcome: <status>
+    process_audit:
+      workiq_first: pass | fail | n/a
+      verbatim_by_default: pass | fail | n/a
+      capture_learnings: pass | fail | n/a
+      run_report_mention: pass | fail | n/a
+      fuzzy_disambiguation: pass | fail | n/a
+      cleanup_on_resolution: pass | fail | n/a
+      citation_ledger: pass | fail | n/a
+```
+
+### B. `<project>/FOLLOW-UPS.md` (new file — shared across contributors per `multi-user-shared-files.instructions.md`)
+
+Append an entry under `## Open follow-ups`:
+
+```markdown
+### <source> · <YYYY-MM-DD> · <alias>
+
+**Gate failures (after 1 retry):**
+- ❌ <check-name>: <reason>
+- ❌ <check-name>: <reason>
+
+**Process audit failures:**
+- ❌ <doctrine>: <what was skipped>
+
+**Next-time-do:**
+1. <specific actionable step>
+2. <specific actionable step>
+
+**Tracking:** `.kushi/tracking/runs/<YYYY-MM-DD>-<project>-<verb>.md`
+**Run-log entry:** `Evidence/run-log.yml#sources.<source>.last_run = <ISO-8601>`
+**Status:** open
+```
+
+The "Next-time-do" steps are the same actionable hints the agent would have surfaced in chat — but written somewhere the user (or a future kushi run) can pick them up.
+
+### C. `<workspace>/.kushi/tracking/runs/<YYYY-MM-DD>-<project>-<verb>.md`
+
+In the tracking file's `## Decisions & open questions` section:
+
+```markdown
+- ⚠ <source> gate failed after 1 retry. See `<project>/FOLLOW-UPS.md` entry dated <YYYY-MM-DD>.
+  - Failed checks: <check-name>, <check-name>
+  - Process audit: <doctrine>=<pass|fail>, ...
+  - Continued to next source per per-source-verification-gate.instructions.md.
+```
+
+## Resolution / closeout
+
+When a follow-up is resolved (next refresh fixes the gap, or user fixes manually):
+
+1. The next gate run detects the source is now healthy → marks the FOLLOW-UPS.md entry `**Status:** resolved-<YYYY-MM-DD>` and moves it under `## Resolved follow-ups`.
+2. The `cleanup-on-resolution.instructions.md` rules apply: stale `gate_failures` rows older than 60 days with status `resolved` get pruned from run-log.
+
+## Self-check enforcement
+
+**D18 — Per-source verification gate cite.** Every `pull-*` SKILL.md MUST reference `per-source-verification-gate.instructions.md` in its body. `bootstrap-project` + `refresh-project` + `aggregate-project` SKILL.md MUST describe gate invocation between sources.
+
+**D19 — FOLLOW-UPS.md format compliance.** When a `<project>/FOLLOW-UPS.md` exists, every "Open follow-ups" entry MUST have the 5 required fields (Gate failures / Process audit / Next-time-do / Tracking / Run-log entry / Status). Same shape per multi-user merge rules.
+
+## References
+
+- `status-taxonomy.instructions.md` — closed-set vocabulary for `last_status` and `retry_signal`.
+- `verbatim-by-default.instructions.md` — sources may be silently skipped only when boundary is missing.
+- `meetings-verbatim-required.instructions.md` — meetings-source extra gate (transcript-class file required).
+- `citation-ledger.instructions.md` — citation spot-check rule.
+- `multi-user-shared-files.instructions.md` — `FOLLOW-UPS.md` is shared across contributors via OneDrive; absorb conflict copies on every write.
+- `run-reports.instructions.md` — the per-user refresh report references gate outcomes.
+- `tracking.instructions.md` — tracking file is the per-run audit surface.
+- `fuzzy-disambiguation.instructions.md` — universal name → id resolution flow.
+- `cleanup-on-resolution.instructions.md` — closeout flow for resolved gate failures.

package/plugin/instructions/sharepoint-to-onedrive-sync.instructions.md

@@ -0,0 +1,116 @@
+---
+applyTo: "**"
+description: "When a user provides a SharePoint URL where a local path is required (e.g. projects_root), trigger the OneDrive client to sync the library via the sanctioned odopen:// URI scheme with user consent, then poll for the local mirror and persist that path. Cross-platform: Windows + macOS supported; Linux falls through to manual. Never silent — user always sees + confirms OneDrive's native sync dialog."
+---
+
+# SharePoint → OneDrive auto-sync (v4.5.0)
+
+## Why
+
+`projects_root` and any other "local engagement folder" config field MUST resolve to a real filesystem path. Kushi reads + writes with normal filesystem APIs and cannot dereference `https://*.sharepoint.com/*` URLs.
+
+But users typically know their engagement library as a SharePoint URL (the link they got in a Teams message), not as a local path. This doctrine bridges the two with **one user consent**.
+
+## Detection
+
+A value supplied for `projects_root`, `engagement_root`, or any `*_root` config field is a SharePoint URL when ALL of:
+
+- Scheme is `https://`
+- Hostname matches `*.sharepoint.com`
+- Path contains `/sites/` or `/teams/` followed by additional segments
+
+Examples:
+
+- ✅ `https://contoso.sharepoint.com/sites/ISE-FDE/Shared%20Documents/Engagement%20Assets`
+- ✅ `https://contoso.sharepoint.com/teams/CTO-Eng/Documents/Engagements`
+- ❌ `https://contoso.sharepoint.com` (root only — ambiguous, ask)
+- ❌ `C:\Users\…` / `/Users/…` (already local — proceed as today)
+
+## The `odopen://` handshake
+
+OneDrive Personal + OneDrive for Business both register the `odopen://` URI scheme. This is the same handler triggered by the SharePoint "Sync" button. Using it is **not** intrusive — OneDrive itself presents a native confirmation dialog ("Start syncing this library?") and the user must consent.
+
+### URI shape
+
+```
+odopen://sync/?url={encoded-sp-folder-url}&userEmail={encoded-upn}
+```
+
+Where:
+
+- `url` — full SharePoint URL the user provided, percent-encoded.
+- `userEmail` — current contributor UPN (resolved by `setup` Step 3). Helps OneDrive pick the right tenant identity when the user has multiple.
+
+This simple form works in all recent OneDrive client builds. If it ever fails on a particular machine, the recovery path is the documented manual flow (click Sync in browser).
+
+### Launching the URI
+
+Cross-platform launch (always non-blocking; OneDrive runs in its own process):
+
+- **Windows (PowerShell)** — `Start-Process "odopen://sync/?url=...&userEmail=..."`
+- **macOS (zsh / bash)** — `open "odopen://sync/?url=...&userEmail=..."`
+- **Linux** — not supported (no OneDrive client). Fall through to manual recipe in `docs/concepts/sync-and-pinning.md`.
+
+## Expected local mirror path
+
+After sync starts, OneDrive creates a folder under the user's home directory. Path conventions:
+
+### Windows
+
+- `%USERPROFILE%\<Tenant Display Name>\<Site Display Name> - <Library Display Name>\<sub-folder>`
+- Common form: `C:\Users\<you>\Contoso\ISE-FDE - Documents\Engagement Assets`
+- Personal OneDrive (rare for engagements): `C:\Users\<you>\OneDrive - Contoso\<sub-folder>`
+
+### macOS (12.3+ uses CloudStorage)
+
+- `~/Library/CloudStorage/OneDrive-SharedLibraries-<Tenant>/<Site> - <Library>/<sub-folder>`
+- Example: `~/Library/CloudStorage/OneDrive-SharedLibraries-Contoso/ISE-FDE - Documents/Engagement Assets`
+- Legacy (pre-CloudStorage): `~/<Tenant>/<Site> - <Library>/<sub-folder>` (still detected as fallback).
+
+### Linux
+
+- Not supported. Skill MUST not poll on Linux — surface the manual recipe immediately.
+
+## Polling contract
+
+After launching the `odopen://` URI:
+
+1. Compute the **candidate local paths** (Windows: 2 candidates including personal OneDrive; macOS: 2 candidates including legacy). Best-guess the tenant/site/library segments from the URL path.
+2. Poll every 5 seconds for up to **5 minutes** (cold libraries can take a while to materialize the top-level folder structure). Each poll: `Test-Path` / `[ -d ]` on every candidate.
+3. On first hit, **also wait for at least one expected sub-folder to appear** (any folder, not just empty mirror) — confirms the directory tree has started populating, not just the empty stub.
+4. Print a progress line every 15 seconds: `Waiting for OneDrive to materialize <path-being-watched>… (elapsed: 45s)`.
+5. On hit → persist + green ✅.
+6. On 5-min timeout → write `projects_root_status: "syncing"` + `projects_root_candidate: "<best-guess-path>"` to `project-evidence.yml` and surface: `Sync started but the local mirror hasn't appeared yet. Run @Kushi setup --resume-sync once OneDrive finishes (status bar icon shows ✅).`
+
+## ask_user contract (Setup Step 4c)
+
+When user pastes a SharePoint URL where a path was expected:
+
+> ⚠ That's a SharePoint URL, not a local path. Kushi needs a local folder (the OneDrive client mirrors SharePoint to disk).
+>
+> • **Sync this library now** (recommended) — opens OneDrive's native sync dialog; you click "Sync" once.
+> • **I'll sync it myself** — show me the manual steps + docs link.
+> • **Cancel** — let me paste a local path instead.
+
+| Choice | Action |
+|---|---|
+| Sync this library now | Launch `odopen://`, then poll. |
+| I'll sync it myself | Print 3-step manual recipe (open URL in browser → click Sync → wait → run `setup --resume-sync`). Persist `projects_root_status: "manual-sync-pending"`. |
+| Cancel | Go back to "type a local path" prompt. |
+
+## Bootstrap blocking behavior
+
+If `projects_root_status` is `syncing` or `manual-sync-pending`, `bootstrap`/`refresh` MUST refuse to start with: `Engagement root sync still pending. Run @Kushi setup --resume-sync to complete.`
+
+`ask`, `status`, and Q&A verbs remain available (they read existing files only).
+
+## Linux + fallback
+
+On Linux OR if OneDrive client process is not detected (`Get-Process onedrive` on Windows; `pgrep -f OneDrive` on macOS returns nothing), skip the `odopen://` path entirely and show the manual recipe with a link to `docs/concepts/sync-and-pinning.md`.
+
+## References
+
+- `engagement-root-resolution.instructions.md` — where `projects_root` is canonically read/written.
+- `onedrive-pin-policy.instructions.md` — what to pin AFTER the local mirror exists (this doctrine's natural follow-on).
+- `docs/concepts/sync-and-pinning.md` — user-facing companion doc.
+- `docs/concepts/storage-backends.md` — supported backend matrix.

package/plugin/instructions/status-color-rule.instructions.md

@@ -0,0 +1,62 @@
+---
+applyTo: "plugin/skills/project-status/**, plugin/skills/emit-vertex/**, plugin/skills/build-state/**"
+description: "Deterministic status-color rule (🟢/🟡/🔴) with auditable Reason: line. Borrowed from vertex weekly-status agent Phase 3."
+---
+
+# Status-color rule (first-match-wins)
+
+When emitting a project status (kushi `project-status`, `emit-vertex` weekly status, `build-state` health summary), the color MUST be computed from inputs by the rule below — never from LLM inference. The triggering rule MUST be recorded verbatim in the `Reason:` line of any emitted status email or in the `status_reason` field of any structured artifact.
+
+## Rule order — first match wins
+
+### 🔴 Red — any of:
+
+| # | Trigger | Evidence source |
+|---|---|---|
+| R1 | ≥1 active risk with `Severity: High` AND `Mitigation:` empty | `State/06_risks-and-issues.md` (or `Evidence/_Consolidated/risks-ledger.md`) |
+| R2 | Previous status was 🔴 AND no closing note exists in this period | last `status-updates/*.md` + `Evidence/*/<period>` |
+| R3 | Explicit escalation in this period — `"blocked"`, `"stop work"`, `"executive escalation"`, `"go/no-go"` in emails or meetings | `Evidence/*/email/snapshot/`, `meetings/snapshot/` |
+| R4 | ADO work item with `Severity: 1` opened in period | `Evidence/*/ado/snapshot/` |
+
+### 🟡 Yellow — any of:
+
+| # | Trigger | Evidence source |
+|---|---|---|
+| Y1 | ≥1 active risk with `Severity: High` (mitigation present) | risks ledger |
+| Y2 | ≥3 active risks with `Severity: Medium` | risks ledger |
+| Y3 | Milestone slipped past due date in this period | `State/07_timeline-and-milestones.md` (or game-plan equivalents) |
+| Y4 | Open action items overdue by > 7 days | `State/05_action-items.md` |
+
+### 🟢 Green
+
+None of the above triggered.
+
+## Reason line shape
+
+Format: `<RULE-ID>: <brief human reason>`
+
+Examples:
+
+```text
+Reason: R1: 1 High-severity risk has no mitigation (FK schema mismatch, Bob Jones, opened 2026-05-12)
+Reason: Y2: 3 Medium risks active (data migration, AKS skill gap, CI/CD timeline)
+Reason: Y3: Milestone "Production deployment readiness" slipped from 2026-05-15 to 2026-05-22
+Reason: GREEN: 0 reds; 0 yellows; 1 milestone on track
+```
+
+The rule-id MUST be present so the choice is reproducible from inputs alone.
+
+## Implementation contract
+
+A skill computing status color SHOULD:
+
+1. Load risks ledger, action items ledger, timeline ledger, and the current reporting-period evidence index.
+2. Evaluate R1→R4, then Y1→Y4 in order.
+3. Stop at first match. Record `rule_id`, `triggers` (list of matching items with citations), and `color`.
+4. Emit `status_color`, `status_reason`, and `status_evidence` (list of `[source: ...]` citations) into the output artifact.
+
+If the inputs are insufficient to evaluate any rule (missing ledgers), the color MUST be `🟡` with `Reason: INSUFFICIENT-EVIDENCE: <list of missing inputs>` — never default-green.
+
+## Why this exists
+
+Status color is the single most consequential field in a weekly status email — it drives the ADO field via the Studio automation. Letting an LLM infer it from prose is non-reproducible and creates audit gaps. The rule borrowed from vertex's weekly-status agent (where it was a single block of doctrine) is promoted to a kushi instruction file so it applies to `project-status`, `emit-vertex`, and `build-state` uniformly.

package/plugin/instructions/studio-registry.instructions.md

@@ -0,0 +1,48 @@
+---
+applyTo: "plugin/skills/setup/**, plugin/skills/bootstrap-project/**, plugin/skills/refresh-project/**, plugin/skills/emit-vertex/**, plugin/skills/fde-report/**"
+description: "Studio registry — single source of truth for studio-scoped distribution lists, report recipients, and org-default behavior. Loaded via plugin/lib/studio-registry.mjs."
+---
+
+# Studio registry
+
+A **studio** in kushi is an organizational unit that owns:
+
+- The Studio engagement automation address for status emails (`status_email.automation_to`)
+- The Studio leadership BCC list (`status_email.bcc_recipients`)
+- FDE report distribution defaults (`report_recipients.fde_report_to`, `_cc`)
+- Brand metadata for emitted reports (`brand.name`, `brand.color_hex`)
+
+Borrowed from vertex's `.vertex/scripts/studios.json` (status_email namespace only there); extended in kushi with `report_recipients` and `brand`.
+
+## Files
+
+- **Packaged registry**: `plugin/config/studios.json` (ships with kushi)
+- **User override**: `~/.copilot/m-skills/kushi/config/studios.json` (optional)
+- **Per-project override**: `<project>/.kushi/studios.json` (optional, highest precedence)
+
+Schema: `plugin/config/studios.schema.json`. Self-check D29 validates packaged registry against schema.
+
+## Lookup
+
+```js
+import { loadStudioRegistry, getStudio } from '../../lib/studio-registry.mjs';
+const reg = loadStudioRegistry({ projectRoot, userOverrideDir });
+const studio = getStudio(reg, studioId); // null if unknown
+```
+
+## How skills SHOULD use this
+
+1. Read `project.studio` from `<project>/kushi.yaml` (added in v4.7.0).
+2. `getStudio(reg, project.studio)`.
+3. If `null` (unknown studio): treat distribution lists as user-managed; warn once per run with a link to GOVERNANCE.md (when published).
+4. If `studio._default` was returned (no project.studio set): ask user once, save into `kushi.yaml`.
+
+## Adding a new studio
+
+Editing the registry is data-only. Until a Decision Process is published, contributors:
+
+1. Open a PR against `plugin/config/studios.json` adding their studio block.
+2. CI validates against `studios.schema.json`.
+3. Once merged + published, the new studio is selectable across every kushi install.
+
+For local-only use, drop the block into `~/.copilot/m-skills/kushi/config/studios.json` (user override).

package/plugin/instructions/update-ledger.instructions.md

@@ -128,5 +128,5 @@ C13 is not yet implemented in `self-check/run.ps1` — added when `apply-ado-upd
 
 - `propose-ado-update` SKILL.md — produces the `proposed.md` this doctrine governs.
 - `apply-ado-update` SKILL.md — the only code path authorized to write to ADO; consumes `proposed.md`, appends to `ledger.jsonl`.
-- `azure-auth-patterns.instructions.md` — pre-flight + token + tenant guards that protect every write.
+- `auth-and-retry.instructions.md` — pre-flight + token + tenant guards that protect every write.
 - `side-by-side-config.instructions.md` — `integrations.yml ado.writes:` follows the same template-vs-live pattern.

package/plugin/instructions/verbatim-by-default.instructions.md

@@ -23,7 +23,7 @@ This restates and hardens the existing thoroughness contract in `evidence-thorou
 
 ## Anti-patterns (defects to refuse, not negotiate)
 
-The following are defects in any `pull-*` output. If the runtime detects one, it MUST auto-retry with stricter prompting per `thoroughness-detector.instructions.md` rather than ship the thin output.
+The following are defects in any `pull-*` output. If the runtime detects one, it MUST auto-retry with stricter prompting per `evidence-thoroughness.instructions.md` rather than ship the thin output.
 
 1. **Email preview-only** — capturing only `bodyPreview` (200 chars) instead of `body`. Defect.
 2. **"And N more"** — any phrase like "...and 12 more emails", "10 of 47 shown", "see source for rest". Defect.