kushi-agents 5.6.4 → 5.7.0

package/plugin/instructions/deferred-retry-on-workiq-fail.instructions.md

@@ -1,155 +1,155 @@
----
-applyTo: "**"
-description: "When WorkIQ fails (and the doubled-strict retry also fails), Kushi MUST NOT fall back to Graph / m365_get_* / Dataverse REST as a workaround. Instead, write a deferred-retry marker, surface it in the run report, and continue. The next refresh drains the queue. This is the v4.4.1 hard rule that closes the last Graph-fallback escape hatch."
----
-
-# Deferred-Retry on WorkIQ Failure (HARD RULE, kushi v4.4.1+)
-
-## Why this exists
-
-`workiq-only.instructions.md` (v3.11.0+) forbade Graph / `m365_get_*` as a **first-class fallback**. But the doctrine's step 3 still said *"ask the user to paste"* — which in practice agents interpreted as:
-
-1. *"WorkIQ failed → block the entire run and wait for the human."*  (bootstrap stops mid-flight, evidence for OTHER sources is lost)
-2. *"WorkIQ failed → silently try `m365_get_*` since it's right there in the tool list."*  (the very anti-pattern workiq-only was meant to kill)
-3. *"WorkIQ failed → skip the source, no record."*  (next refresh never retries; the gap is permanent)
-
-All three are defects. This rule replaces them with a deterministic, auditable, **non-blocking** flow.
-
-## The rule (HARD)
-
-When a WorkIQ call fails (auth error, empty after doubled-strict retry, throttled, CLI error, or any non-success), Kushi MUST:
-
-1. **NOT call Graph, `m365_get_*`, or any other M365 host tool as a fallback.** No exceptions. Even if the tool is right there and looks like it would work. The doctrine in `workiq-only.instructions.md` is absolute.
-2. **Write a deferred-retry marker** (see schema below).
-3. **Surface a one-liner** in coverage.md, the per-user run report, and the project's `bootstrap-status.md` `## Deferred Retries` section.
-4. **Continue the run** for all other sources. Never block the orchestrator on a single source's failure.
-5. **Inform the user** at end-of-run with the count of deferred items and the path to the queue directory.
-
-The next `refresh-project` run drains the queue first (Step 2a). On success, the marker is deleted. On repeated failure, the marker's `attempts` counter increments and the user is re-informed.
-
-## Marker file location
-
-```
-<engagement-root>/<project>/Evidence/<alias>/_deferred-retries/<YYYY-MM-DD-HHmm>_<source>_<short-reason>.yml
-```
-
-- Per-contributor (`<alias>`) — never shared, so multi-user safety is moot.
-- Sortable by filename (chronological).
-- One marker per failed call. Do NOT batch — granular markers make retry deterministic.
-
-## Marker schema
-
-```yaml
-# Deferred-retry marker — auto-generated. Do NOT hand-edit.
-# Drained by refresh-project Step 2a. Deleted on retry success.
-schema_version: 1
-source: meetings          # one of: email, teams, meetings, onenote, sharepoint, crm, ado, misc, identity
-project: Northwind
-alias: ushak
-created_at: 2026-05-20T12:30:00Z
-attempts: 1
-last_attempt_at: 2026-05-20T12:30:00Z
-window: { from: '2026-04-20', to: '2026-05-20' }
-target:
-  # source-specific identifying fields — exactly what the retry needs to re-issue the call
-  subject: "JD FDE Intake"
-  date: "2026-05-13"
-workiq:
-  command: 'workiq ask -q "Find the Teams meeting titled \"JD FDE Intake\" that occurred on 2026-05-13..."'
-  request_id: '54d9c6bc-6e56-43b6-9eb7-ac23e86e2cc0'    # if WorkIQ returned one before failing
-  error_class: 'empty-after-doubled-strict'             # auth-error | empty | empty-after-doubled-strict | throttled | cli-error | timeout
-  error_message: 'WorkIQ returned a summary only after both prompts.'
-user_message: |
-  Could not retrieve the full verbatim transcript of "JD FDE Intake" (2026-05-13) via WorkIQ.
-  The next refresh will retry automatically. To populate now, paste the transcript into
-  Evidence/ushak/meetings/snapshot/2026-05-13_jd-fde-intake_transcript.md and mark this marker
-  resolved by deleting the file.
-```
-
-## Producer contract (every pull-* skill + identity-resolution)
-
-Before considering a source "failed and skipped", the skill MUST:
-
-1. Call WorkIQ once with the canonical prompt from `workiq-only.instructions.md`.
-2. On weak result, call the doubled-strict retry prompt from the same table.
-3. If both fail:
-   - Write the marker per the schema above.
-   - Add a row to coverage.md: `Source: WorkIQ → DEFERRED (marker: <relative-path>)`.
-   - Continue the run. Do NOT throw. Do NOT call any other M365 tool.
-
-Pseudocode (PowerShell shape):
-
-```powershell
-$result = Invoke-WorkIQ -Query $canonical
-if (-not (Test-Sufficient $result)) {
-  $result = Invoke-WorkIQ -Query $doubledStrict
-}
-if (-not (Test-Sufficient $result)) {
-  Write-DeferredRetryMarker -Source $src -Target $target -Window $win -Workiq $workiqMeta
-  Add-CoverageRow -Source 'WorkIQ' -Status 'DEFERRED' -MarkerPath $markerPath
-  return  # CONTINUE the orchestrator with the next source. NEVER call m365_get_*.
-}
-```
-
-## Consumer contract (refresh-project)
-
-`refresh-project` SKILL Step 2a (NEW, REQUIRED) runs **before** the per-source dispatch loop:
-
-```
-For each <alias>/_deferred-retries/*.yml in chronological order:
-  - Load marker
-  - Re-issue the canonical WorkIQ query with original window + target
-  - If success → write artifact to its canonical Evidence/ path, delete marker, log "drained" in refresh report
-  - If failure → increment attempts, update last_attempt_at, leave marker in place, log "still-deferred"
-After drain → run normal Step 2 per-source dispatch
-After Step 2 → report drain results in the run report's `## Deferred-retry drain` section
-```
-
-If `attempts` reaches 5, do NOT keep silently retrying. Promote to a project-level Open Question:
-
-```
-- [ ] DEFERRED-RETRY (5 attempts): <source> for <target>. See <marker-path>. Manual intervention required (paste verbatim, or remove the marker if no longer needed).
-```
-
-## bootstrap-status.md integration
-
-`bootstrap-status-format.instructions.md` mandates a `## Deferred Retries` section. Format:
-
-```
-## Deferred Retries
-
-| Source | Target | Attempts | Marker | First seen |
-|---|---|---|---|---|
-| meetings | JD FDE Intake 2026-05-13 | 1 | Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml | 2026-05-20 |
-```
-
-Section is omitted entirely when no markers exist.
-
-## What "informing the user" looks like
-
-At end-of-run summary (every `pull-*`, `bootstrap-project`, `refresh-project`):
-
-```
-⚠ Deferred retries this run: 2 (will retry on next `refresh <project>`)
-   - meetings/JD FDE Intake 2026-05-13 → Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml
-   - onenote/Architecture overview → Evidence/ushak/_deferred-retries/2026-05-20-1231_onenote_throttled.yml
-```
-
-Never silent. Never collapsed. The user sees exactly which calls deferred and where to find the markers.
-
-## Anti-patterns (defects)
-
-1. **Calling `m365_get_*` / Graph REST after a WorkIQ failure.** FORBIDDEN. Even "just to check if it works." Even "as a last resort." Write the marker; move on.
-2. **Throwing / blocking the orchestrator on a single source's WorkIQ failure.** FORBIDDEN. Bootstrap and refresh dispatch every enabled source; a single failure must not stop the others.
-3. **Silently skipping a source with no marker.** FORBIDDEN. If WorkIQ failed and you did NOT write a marker, the user has no signal and `refresh` will never retry. Always mark.
-4. **Asking the user to paste mid-run as the primary recovery.** Pasting is a manual override the user MAY do later (by populating the artifact directly and deleting the marker). It is NOT the agent's recovery flow. The agent's recovery flow is: mark + continue + inform.
-5. **Promoting markers to OPEN-QUESTIONS-DRAFT.md before 5 attempts.** Too noisy. Let refresh drain naturally.
-6. **Storing markers outside `Evidence/<alias>/_deferred-retries/`.** Wrong location = the drainer can't find them. Wrong scope = breaks multi-user (markers are per-contributor by design).
-
-## Cross-references
-
-- `workiq-only.instructions.md` — WorkIQ is the only path. This file defines what happens when that path fails.
-- `identity-resolution.instructions.md` — "Failure modes" table now cites this rule.
-- `bootstrap-status-format.instructions.md` — `## Deferred Retries` section contract.
-- `multi-user-shared-files.instructions.md` — `_deferred-retries/` is per-contributor (under `Evidence/<alias>/`) so multi-user collision doctrine does not apply.
-- `verbatim-by-default.instructions.md` — deferring is NOT a silent skip. A marker IS the audit trail.
+---
+applyTo: "**"
+description: "When WorkIQ fails (and the doubled-strict retry also fails), Kushi MUST NOT fall back to Graph / m365_get_* / Dataverse REST as a workaround. Instead, write a deferred-retry marker, surface it in the run report, and continue. The next refresh drains the queue. This is the v4.4.1 hard rule that closes the last Graph-fallback escape hatch."
+---
+
+# Deferred-Retry on WorkIQ Failure (HARD RULE, kushi v4.4.1+)
+
+## Why this exists
+
+`workiq-only.instructions.md` (v3.11.0+) forbade Graph / `m365_get_*` as a **first-class fallback**. But the doctrine's step 3 still said *"ask the user to paste"* — which in practice agents interpreted as:
+
+1. *"WorkIQ failed → block the entire run and wait for the human."*  (bootstrap stops mid-flight, evidence for OTHER sources is lost)
+2. *"WorkIQ failed → silently try `m365_get_*` since it's right there in the tool list."*  (the very anti-pattern workiq-only was meant to kill)
+3. *"WorkIQ failed → skip the source, no record."*  (next refresh never retries; the gap is permanent)
+
+All three are defects. This rule replaces them with a deterministic, auditable, **non-blocking** flow.
+
+## The rule (HARD)
+
+When a WorkIQ call fails (auth error, empty after doubled-strict retry, throttled, CLI error, or any non-success), Kushi MUST:
+
+1. **NOT call Graph, `m365_get_*`, or any other M365 host tool as a fallback.** No exceptions. Even if the tool is right there and looks like it would work. The doctrine in `workiq-only.instructions.md` is absolute.
+2. **Write a deferred-retry marker** (see schema below).
+3. **Surface a one-liner** in coverage.md, the per-user run report, and the project's `bootstrap-status.md` `## Deferred Retries` section.
+4. **Continue the run** for all other sources. Never block the orchestrator on a single source's failure.
+5. **Inform the user** at end-of-run with the count of deferred items and the path to the queue directory.
+
+The next `refresh-project` run drains the queue first (Step 2a). On success, the marker is deleted. On repeated failure, the marker's `attempts` counter increments and the user is re-informed.
+
+## Marker file location
+
+```
+<engagement-root>/<project>/Evidence/<alias>/_deferred-retries/<YYYY-MM-DD-HHmm>_<source>_<short-reason>.yml
+```
+
+- Per-contributor (`<alias>`) — never shared, so multi-user safety is moot.
+- Sortable by filename (chronological).
+- One marker per failed call. Do NOT batch — granular markers make retry deterministic.
+
+## Marker schema
+
+```yaml
+# Deferred-retry marker — auto-generated. Do NOT hand-edit.
+# Drained by refresh-project Step 2a. Deleted on retry success.
+schema_version: 1
+source: meetings          # one of: email, teams, meetings, onenote, sharepoint, crm, ado, misc, identity
+project: Northwind
+alias: ushak
+created_at: 2026-05-20T12:30:00Z
+attempts: 1
+last_attempt_at: 2026-05-20T12:30:00Z
+window: { from: '2026-04-20', to: '2026-05-20' }
+target:
+  # source-specific identifying fields — exactly what the retry needs to re-issue the call
+  subject: "JD FDE Intake"
+  date: "2026-05-13"
+workiq:
+  command: 'workiq ask -q "Find the Teams meeting titled \"JD FDE Intake\" that occurred on 2026-05-13..."'
+  request_id: '54d9c6bc-6e56-43b6-9eb7-ac23e86e2cc0'    # if WorkIQ returned one before failing
+  error_class: 'empty-after-doubled-strict'             # auth-error | empty | empty-after-doubled-strict | throttled | cli-error | timeout
+  error_message: 'WorkIQ returned a summary only after both prompts.'
+user_message: |
+  Could not retrieve the full verbatim transcript of "JD FDE Intake" (2026-05-13) via WorkIQ.
+  The next refresh will retry automatically. To populate now, paste the transcript into
+  Evidence/ushak/meetings/snapshot/2026-05-13_jd-fde-intake_transcript.md and mark this marker
+  resolved by deleting the file.
+```
+
+## Producer contract (every pull-* skill + identity-resolution)
+
+Before considering a source "failed and skipped", the skill MUST:
+
+1. Call WorkIQ once with the canonical prompt from `workiq-only.instructions.md`.
+2. On weak result, call the doubled-strict retry prompt from the same table.
+3. If both fail:
+   - Write the marker per the schema above.
+   - Add a row to coverage.md: `Source: WorkIQ → DEFERRED (marker: <relative-path>)`.
+   - Continue the run. Do NOT throw. Do NOT call any other M365 tool.
+
+Pseudocode (PowerShell shape):
+
+```powershell
+$result = Invoke-WorkIQ -Query $canonical
+if (-not (Test-Sufficient $result)) {
+  $result = Invoke-WorkIQ -Query $doubledStrict
+}
+if (-not (Test-Sufficient $result)) {
+  Write-DeferredRetryMarker -Source $src -Target $target -Window $win -Workiq $workiqMeta
+  Add-CoverageRow -Source 'WorkIQ' -Status 'DEFERRED' -MarkerPath $markerPath
+  return  # CONTINUE the orchestrator with the next source. NEVER call m365_get_*.
+}
+```
+
+## Consumer contract (refresh-project)
+
+`refresh-project` SKILL Step 2a (NEW, REQUIRED) runs **before** the per-source dispatch loop:
+
+```
+For each <alias>/_deferred-retries/*.yml in chronological order:
+  - Load marker
+  - Re-issue the canonical WorkIQ query with original window + target
+  - If success → write artifact to its canonical Evidence/ path, delete marker, log "drained" in refresh report
+  - If failure → increment attempts, update last_attempt_at, leave marker in place, log "still-deferred"
+After drain → run normal Step 2 per-source dispatch
+After Step 2 → report drain results in the run report's `## Deferred-retry drain` section
+```
+
+If `attempts` reaches 5, do NOT keep silently retrying. Promote to a project-level Open Question:
+
+```
+- [ ] DEFERRED-RETRY (5 attempts): <source> for <target>. See <marker-path>. Manual intervention required (paste verbatim, or remove the marker if no longer needed).
+```
+
+## bootstrap-status.md integration
+
+`bootstrap-status-format.instructions.md` mandates a `## Deferred Retries` section. Format:
+
+```
+## Deferred Retries
+
+| Source | Target | Attempts | Marker | First seen |
+|---|---|---|---|---|
+| meetings | JD FDE Intake 2026-05-13 | 1 | Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml | 2026-05-20 |
+```
+
+Section is omitted entirely when no markers exist.
+
+## What "informing the user" looks like
+
+At end-of-run summary (every `pull-*`, `bootstrap-project`, `refresh-project`):
+
+```
+⚠ Deferred retries this run: 2 (will retry on next `refresh <project>`)
+   - meetings/JD FDE Intake 2026-05-13 → Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml
+   - onenote/Architecture overview → Evidence/ushak/_deferred-retries/2026-05-20-1231_onenote_throttled.yml
+```
+
+Never silent. Never collapsed. The user sees exactly which calls deferred and where to find the markers.
+
+## Anti-patterns (defects)
+
+1. **Calling `m365_get_*` / Graph REST after a WorkIQ failure.** FORBIDDEN. Even "just to check if it works." Even "as a last resort." Write the marker; move on.
+2. **Throwing / blocking the orchestrator on a single source's WorkIQ failure.** FORBIDDEN. Bootstrap and refresh dispatch every enabled source; a single failure must not stop the others.
+3. **Silently skipping a source with no marker.** FORBIDDEN. If WorkIQ failed and you did NOT write a marker, the user has no signal and `refresh` will never retry. Always mark.
+4. **Asking the user to paste mid-run as the primary recovery.** Pasting is a manual override the user MAY do later (by populating the artifact directly and deleting the marker). It is NOT the agent's recovery flow. The agent's recovery flow is: mark + continue + inform.
+5. **Promoting markers to OPEN-QUESTIONS-DRAFT.md before 5 attempts.** Too noisy. Let refresh drain naturally.
+6. **Storing markers outside `Evidence/<alias>/_deferred-retries/`.** Wrong location = the drainer can't find them. Wrong scope = breaks multi-user (markers are per-contributor by design).
+
+## Cross-references
+
+- `workiq-only.instructions.md` — WorkIQ is the only path. This file defines what happens when that path fails.
+- `identity-resolution.instructions.md` — "Failure modes" table now cites this rule.
+- `bootstrap-status-format.instructions.md` — `## Deferred Retries` section contract.
+- `multi-user-shared-files.instructions.md` — `_deferred-retries/` is per-contributor (under `Evidence/<alias>/`) so multi-user collision doctrine does not apply.
+- `verbatim-by-default.instructions.md` — deferring is NOT a silent skip. A marker IS the audit trail.

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

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