kushi-agents 4.3.0 → 4.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -10,8 +10,6 @@
     "bin/",
     "src/",
     "plugin/",
-    ".github/config/m365-auth.json.example",
-    ".github/config/m365-mutable.json.example",
     ".github/copilot-instructions.kushi.md"
   ],
   "engines": {
@@ -43,7 +41,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test src/check-workiq.test.mjs",
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm test && npm run smoke"
   },

package/plugin/agents/kushi.agent.md

@@ -98,9 +98,9 @@ When a user message arrives:
 ## Configuration layout
 
 ```
-<workspace>/.kushi/config/project-evidence.yml     ← personal: alias, engagement_root, active_projects (seeded by installer; never overwritten)
-<workspace>/.kushi/config/integrations.yml         ← optional global CRM/ADO defaults (seeded by installer; never overwritten)
-<engagement-root>/.project-evidence/                ← per-machine, per-user M365 + CRM + ADO config (OneDrive-synced)
+<workspace>/.kushi/config/user/project-evidence.yml     ← personal: alias, engagement_root, active_projects (seeded by installer; never overwritten)
+<workspace>/.kushi/config/shared/integrations.yml         ← optional global CRM/ADO defaults (seeded by installer; never overwritten)
+<workspace>/.kushi/config/                  ← per-machine, per-user M365 config + per-project shared ADO/CRM connection (v4.4.0+, replaces legacy `<engagement-root>/.project-evidence/`)
    m365/m365-auth.json
    m365/m365-mutable.json
    crm/config.yml

package/plugin/instructions/ado-engagement-tree.instructions.md

@@ -49,7 +49,7 @@ After the Engagement WI ID is resolved:
 
 ## Source files
 
-- `<engagement-root>/.project-evidence/ado/config.yml` — connection: `tenantId`, `organization`, `defaultProject`, `apiVersion`, `azDevOpsResourceId`.
+- `<workspace>/.kushi/config/shared/integrations.yml` — connection: `tenantId`, `organization`, `defaultProject`, `apiVersion`, `azDevOpsResourceId`.
 - `<engagement-root>/<project>/integrations.yml#ado` — per-project: `engagement_id`, `queryId`, `area_paths`, `iteration_paths`.
 - `<engagement-root>/<project>/integrations.yml#boundaries.ado` — required scope (`area_paths` + optional `work_item_ids`).
 

package/plugin/instructions/az-auth-conditional.instructions.md

@@ -10,8 +10,8 @@ The skill calls `az account get-access-token` only when CRM (Dataverse) or ADO a
 ## Decision logic
 
 ```
-crm_enabled = Test-Path <engagement-root>/.project-evidence/crm/config.yml
-ado_enabled = Test-Path <engagement-root>/.project-evidence/ado/config.yml
+crm_enabled = Test-Path <workspace>/.kushi/config/shared/integrations.yml
+ado_enabled = Test-Path <workspace>/.kushi/config/shared/integrations.yml
 
 if (NOT crm_enabled AND NOT ado_enabled):
     Skip az check entirely. Display "az sign-in skipped (no CRM/ADO configured)".

package/plugin/instructions/azure-auth-patterns.instructions.md

@@ -39,7 +39,7 @@ Acquire each token **once per run** (per `auth-and-retry.instructions.md §2`).
 ### 2.1 CRM / Dataverse
 
 ```powershell
-$crmConfig   = Get-Content "$engagementRoot\.project-evidence\crm\config.yml" -Raw | ConvertFrom-Yaml  # or JSON variant
+$crmConfig   = (Get-Content "$workspace\.kushi\config\shared\integrations.yml" -Raw | ConvertFrom-Yaml).crm  # v4.4.0+ — was <engagement-root>\.project-evidence\crm\config.yml
 $tenant      = $crmConfig.tenantId
 $crmBaseUrl  = $crmConfig.baseUrl
 $crmToken    = (az account get-access-token --tenant $tenant --resource $crmBaseUrl --query accessToken -o tsv --only-show-errors 2>&1).Trim()
@@ -60,7 +60,7 @@ $crmHeaders = @{
 ADO's resource is the constant `499b84ac-1321-427f-aa17-267ca6975798` (Visual Studio Team Services). Read it from config — never hardcode:
 
 ```powershell
-$adoConfig = Get-Content "$engagementRoot\.project-evidence\ado\config.yml" -Raw | ConvertFrom-Yaml
+$adoConfig = (Get-Content "$workspace\.kushi\config\shared\integrations.yml" -Raw | ConvertFrom-Yaml).ado  # v4.4.0+ — was <engagement-root>\.project-evidence\ado\config.yml
 $tenant    = $adoConfig.tenantId
 $adoRes    = $adoConfig.resource   # 499b84ac-1321-427f-aa17-267ca6975798
 $adoToken  = (az account get-access-token --tenant $tenant --resource $adoRes --query accessToken -o tsv --only-show-errors 2>&1).Trim()
@@ -127,7 +127,7 @@ Allowed tenants are config-driven, not hardcoded. Validate before the first ADO
 
 ```powershell
 # $account from Section 1
-$adoConfig      = Get-Content "$engagementRoot\.project-evidence\ado\config.yml" -Raw | ConvertFrom-Yaml
+$adoConfig      = (Get-Content "$workspace\.kushi\config\shared\integrations.yml" -Raw | ConvertFrom-Yaml).ado  # v4.4.0+
 $allowedTenants = @($adoConfig.allowedTenantIds)
 $currentTenant  = $account.tenantId
 if ($allowedTenants.Count -gt 0 -and $allowedTenants -notcontains $currentTenant) {
@@ -224,10 +224,10 @@ Maintained alongside `auth-and-retry §3` (canonical) — quick lookup:
 
 | Service | Config file (engagement-scoped) |
 |---------|---------------------------------|
-| Dynamics 365 / CRM | `<engagement-root>/.project-evidence/crm/config.yml` |
-| Azure DevOps | `<engagement-root>/.project-evidence/ado/config.yml` |
-| Microsoft Graph / M365 / OneNote | `<engagement-root>/.project-evidence/m365/m365-mutable.json` + `<engagement-root>/.project-evidence/m365/m365-auth.json` |
-| WorkIQ CLI path | `<workspace>/.kushi/config/project-evidence.yml` (workspace-scoped) |
-| Global integrations (optional) | `<workspace>/.kushi/config/integrations.yml` |
+| Dynamics 365 / CRM | `<workspace>/.kushi/config/shared/integrations.yml` |
+| Azure DevOps | `<workspace>/.kushi/config/shared/integrations.yml` |
+| Microsoft Graph / M365 / OneNote | `<workspace>/.kushi/config/user/m365-mutable.json` + `<workspace>/.kushi/config/user/m365-auth.json` |
+| WorkIQ CLI path | `<workspace>/.kushi/config/user/project-evidence.yml` (workspace-scoped) |
+| Global integrations (optional) | `<workspace>/.kushi/config/shared/integrations.yml` |
 
 Always read tenant IDs, resource URLs, org URLs, and allowed-tenant lists from these files at the start of each run. **Never hardcode them in skills or prompts.** The only acceptable literal in instructions/prompts is the public Microsoft tenant ID `72f988bf-86f1-41af-91ab-2d7cd011db47` in the user-facing `az login --tenant ...` suggestion text.

package/plugin/instructions/bootstrap-status-format.instructions.md

@@ -22,8 +22,8 @@ When `bootstrap-project` (or any full refresh / retry workflow) finishes a proje
 
 | Check | Status | Notes |
 |---|---|---|
-| `.project-evidence/ado/config.yml` filled | resolved \| blocked-auth \| missing | ... |
-| `.project-evidence/crm/config.yml` filled | ... | ... |
+| `.kushi/config/shared/integrations.yml` filled | resolved \| blocked-auth \| missing | ... |
+| `.kushi/config/shared/integrations.yml` filled | ... | ... |
 | `<project>/integrations.yml` boundaries present | ... | ... |
 | `az` CLI tenant matches | cli-available \| blocked-auth | ... |
 
@@ -54,6 +54,17 @@ When `bootstrap-project` (or any full refresh / retry workflow) finishes a proje
 | CRM | blocked-auth | tenant mismatch | `az login --tenant <id>` |
 | Email | throttled-tooManyRequests | WorkIQ rate-limited | retry next refresh |
 
+## Deferred Retries (kushi v4.4.1+, per `deferred-retry-on-workiq-fail.instructions.md`)
+
+Omit this section entirely if `<project>/Evidence/<alias>/_deferred-retries/` is empty across all contributors.
+
+| Source | Target | Attempts | Marker | First seen | Discovered by |
+|---|---|---|---|---|---|
+| meetings | "JD FDE Intake" 2026-05-13 | 1 | `Evidence/ushak/_deferred-retries/2026-05-20-1230_meetings_empty.yml` | 2026-05-20 | ushak |
+| onenote | "Architecture overview" | 2 | `Evidence/ushak/_deferred-retries/2026-05-19-0810_onenote_throttled.yml` | 2026-05-19 | ushak |
+
+Markers older than 5 attempts auto-promote to `OPEN-QUESTIONS-DRAFT.md`. The next `refresh` drains the queue (Step 2a in `refresh-project/SKILL.md`) — do NOT manually retry by calling `m365_get_*` / Graph; those are forbidden per `workiq-only.instructions.md`.
+
 ## Bootstrap Status
 
 ONE final line, normalized:
@@ -79,6 +90,30 @@ Use these exact strings everywhere (table cells, run-log, narrative):
 - `ado-not-complete` — engagement record not found yet OR ADO linkage missing
 - `completed-with-coverage-gaps` — final outcome with explicit gaps recorded
 
+## Multi-contributor safety (kushi v4.4.0+)
+
+`<project>/bootstrap-status.md` is shared across all contributors via OneDrive. Per `multi-user-shared-files.instructions.md`:
+
+1. **Before writing**, scan `<project>/` for sibling conflict copies (e.g. `bootstrap-status-conflict-<alias>-<host>.md` or OneDrive's `bootstrap-status (Stan's conflicted copy *)`). If any exist, merge their content into the canonical file (taking the most recent per-source row) and delete the conflict copies. Log this in the per-user bootstrap report under `## Conflict copies merged`.
+2. **Preserve other contributors' attribution.** Read the existing file; the `## Contributors who have bootstrapped this project` section MUST keep one row per alias that has ever written it. Update only the row matching the current alias.
+3. **Per-source rows** in `## Context Artifact Status` reflect the most recent discovery across all contributors. Add a trailing `Discovered by` column showing which alias performed the latest discovery (cross-referenced from each alias's `m365-mutable.json` via `Get-KushiConfig`).
+4. **The final one-line status** is for the most recent run only and may be overwritten by any contributor.
+
+### Required `## Contributors who have bootstrapped this project` section
+
+Append this section immediately after `## Bootstrap Status`:
+
+```
+## Contributors who have bootstrapped this project
+
+| Alias | Display Name | Last Run | Mode | Outcome |
+|---|---|---|---|---|
+| ushak | Usha Kandregula | 2026-05-20 07:42 EDT | bootstrap | bootstrap-complete-with-coverage-gaps |
+| stand | Stan Doe       | 2026-05-18 16:01 EDT | refresh   | refresh-complete |
+```
+
+Preserve every existing row except the one matching your alias.
+
 ## Sections to AVOID in bootstrap-status
 
 Do NOT keep these in `bootstrap-status.md` (they belong elsewhere or become stale):

package/plugin/instructions/cleanup-on-resolution.instructions.md

@@ -28,7 +28,7 @@ When a resolution succeeds, in the same turn, prune:
 - Remove inline comments like `# TODO: find this`, `# could not resolve as of YYYY-MM-DD`.
 - Keep `pinned_on` + `pinned_by` (those are durable provenance).
 
-### `<engagement-root>/.project-evidence/m365/m365-mutable.json`
+### `<workspace>/.kushi/config/user/m365-mutable.json`
 - Remove entries under `m365Mutable.unresolved.<project>.<source>` if the same key was just resolved into `m365Mutable.knownSections.<project>.<source>`.
 - Replace any `confidence: 'low'` entry with the new `confidence: 'high'` entry on resolution; do not keep both.
 

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

@@ -21,7 +21,7 @@ Any other path that writes `disabled: true` is a defect. The correct fallback fo
 
 ```powershell
 # 1. Acquire Dataverse token (per pull-crm Step Auth)
-$config = Get-Content "<engagement-root>/.project-evidence/crm/config.yml" | ConvertFrom-Yaml
+$config = Get-Content "<workspace>/.kushi/config/shared/integrations.yml" | ConvertFrom-Yaml
 $token = (az account get-access-token --tenant $config.tenant_id --resource $config.base_url --query accessToken -o tsv --only-show-errors).Trim()
 $headers = @{
   Authorization = "Bearer $token"

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

@@ -0,0 +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: HCA
+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/engagement-root-resolution.instructions.md

@@ -11,24 +11,27 @@ The **engagement-root** is the parent folder that contains all of the user's eng
 
 Resolve `<engagement-root>` in this order — first match wins:
 
-1. **`<workspace>/.kushi/config/project-evidence.yml`** — read `engagement_root:` field (preferred).
+1. **`<workspace>/.kushi/config/user/project-evidence.yml`** — read `engagement_root:` field (preferred).
 2. **`customer_workspace/FDEDocs/`** — if the user's workspace has this symlink, follow it. Common in FDE-style installs.
-3. **Ask the user** once and persist the answer to `<workspace>/.kushi/config/project-evidence.yml engagement_root`.
+3. **Ask the user** once and persist the answer to `<workspace>/.kushi/config/user/project-evidence.yml engagement_root`.
 
-## Live config location
+## Live config location (v4.4.0+)
 
-Once `<engagement-root>` is known, live filled configs live at:
+Live filled configs live under the workspace (where `.kushi/` is), NOT under the engagement root:
 
 ```
-<engagement-root>/.project-evidence/
-   m365/m365-auth.json
-   m365/m365-mutable.json
-   crm/config.yml
-   ado/config.yml
-   project-evidence.yml         ← optional per-engagement override
+<workspace>/.kushi/config/
+   user/                            ← per-contributor (gitignored)
+      project-evidence.yml          identity, engagement_root, workiq cli path
+      m365-auth.json                tenant + default notebook + mailbox folders + SP root
+      m365-mutable.json             discovered IDs (knownSections.<projectKey>)
+   shared/                          ← team-owned (safe to commit)
+      integrations.yml              ADO + CRM connection blocks (per project)
 ```
 
-This folder is OneDrive-synced (typically) and follows the user across machines.
+The legacy location `<engagement-root>/.project-evidence/` is no longer used as of kushi v4.4.0. Existing installs are migrated on first run of v4.4.0+. The new layout is host-agnostic: workspace is always where `.kushi/` lives (vscode target: project root; clawpilot target: any `cwd` where the user invokes Kushi).
+
+`<engagement-root>` is still where per-project Evidence/, State/, and `<project>/integrations.yml` (per-project boundaries) live.
 
 ## Project resolution
 
@@ -42,8 +45,8 @@ Once `<engagement-root>` is known, individual projects are subfolders:
 
 Project name resolution (always fuzzy):
 
-1. Match against keys in `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections`.
-2. Match against `active_projects:` in `<workspace>/.kushi/config/project-evidence.yml`.
+1. Match against keys in `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections`.
+2. Match against `active_projects:` in `<workspace>/.kushi/config/user/project-evidence.yml`.
 3. Match against actual subfolder names under `<engagement-root>`.
 
 Case-insensitive; ranking `exact > prefix > contains`. Multiple plausible candidates → ask user to pick. Zero candidates AND verb is `bootstrap` → create the folder. Zero candidates AND verb is anything else → ask user.

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

@@ -85,7 +85,7 @@ Anything outside these paths is invisible to them — by design. The path IS the
 
 `plugin/skills/self-check/run.ps1` -Deep MUST detect any `<project>/<sibling>/` folder under engagement roots where:
 
-- `<sibling>` is not in the allow-list `@('Evidence','State','Reports','.kushi','.kushi-reference','.project-evidence','.vscode')`, AND
+- `<sibling>` 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.
@@ -105,7 +105,7 @@ Together they guarantee that two contributors running the same verb on the same
 
 - `snapshot-vs-stream.instructions.md` — the two shapes inside each `<source>/` folder.
 - `scope-boundaries.instructions.md` — what each source is allowed to query (orthogonal: scope vs path).
-- `side-by-side-config.instructions.md` — config files (mutable hints, integrations.yml) — also outside `<project>/`, but under `<engagement-root>/.project-evidence/`.
+- `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.

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

@@ -1,6 +1,6 @@
 ---
 applyTo: "**"
-description: "Identity auto-resolution — Kushi never asks the user for alias / email / display_name. On the first bootstrap (or whenever those fields are <auto> / placeholder in .kushi/config/project-evidence.yml), Kushi resolves them from WorkIQ in a single call, persists them, and continues. Skipped entirely if the user has set explicit values."
+description: "Identity auto-resolution — Kushi never asks the user for alias / email / display_name. On the first bootstrap (or whenever those fields are <auto> / placeholder in .kushi/config/user/project-evidence.yml), Kushi resolves them from WorkIQ in a single call, persists them, and continues. Skipped entirely if the user has set explicit values."
 ---
 
 # Identity Resolution — Don't Ask, Probe
@@ -9,7 +9,7 @@ Kushi must not prompt the user for `alias`, `email`, or `display_name`. These ar
 
 ## When to resolve
 
-On the **first step of every prompt** that reads contributor identity (bootstrap, refresh, aggregate, ask, fde-*, propose-ado, apply-ado), check `<workspace>/.kushi/config/project-evidence.yml`:
+On the **first step of every prompt** that reads contributor identity (bootstrap, refresh, aggregate, ask, fde-*, propose-ado, apply-ado), check `<workspace>/.kushi/config/user/project-evidence.yml`:
 
 * If `alias`, `email`, or `display_name` is **missing**, set to `<auto>`, or matches a placeholder pattern (`<your-alias>`, `<Your Full Name>`, `your.email@example.com`) → **resolve from WorkIQ**.
 * If all three are explicit non-placeholder values → **skip**. Respect the user's override.
@@ -32,35 +32,42 @@ Map the response:
 
 ## After resolution
 
-1. **Persist back** to `<workspace>/.kushi/config/project-evidence.yml` (preserving comments + indentation). The user sees the resolved values on next open; no surprise.
+1. **Persist back** to `<workspace>/.kushi/config/user/project-evidence.yml` (preserving comments + indentation). The user sees the resolved values on next open; no surprise.
 2. **Echo back** to the user, one line:
-   > ✓ Identity: `Alex Smith <alex@microsoft.com>` (alias=`alex`). Edit `.kushi/config/project-evidence.yml` to override.
+   > ✓ Identity: `Alex Smith <alex@microsoft.com>` (alias=`alex`). Edit `.kushi/config/user/project-evidence.yml` to override.
 3. **Continue** the prompt.
 
-## Failure modes
+## Failure modes (kushi v4.4.1+: never block, never fallback to Graph)
+
+Per `deferred-retry-on-workiq-fail.instructions.md`, identity resolution NEVER blocks the orchestrator and NEVER calls `m365_get_*` / Graph as a fallback. On WorkIQ failure, the agent writes a deferred-retry marker and continues with a derived alias so evidence still lands somewhere it can later be re-keyed.
 
 | Scenario                                      | Behavior                                                                                                                     |
 |-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
-| WorkIQ returns auth error                     | Block: "Sign in to WorkIQ first: `workiq accept-eula && workiq ask -q ping`". Do not proceed.                                |
-| WorkIQ returns empty / NO_RESULTS             | Block: "WorkIQ could not resolve your identity. Try `workiq ask -q 'who am I'` and retry."                                   |
-| WorkIQ binary missing                         | This should already have been caught by the installer's pre-flight. If reached, block with the same install hint.            |
-| User has explicit non-placeholder values      | Skip resolution entirely. Never overwrite user-set values.                                                                   |
+| WorkIQ returns auth error                     | Write deferred-retry marker (`source: identity`, `error_class: auth-error`). Echo: *"⚠ Identity unresolved (WorkIQ auth). Using alias=`<from-config-or-env>`; will retry on next refresh. Sign in with `workiq accept-eula && workiq ask -q ping` and re-run."* Continue. **Do NOT call `m365_get_my_profile` or Graph `/me`.** |
+| WorkIQ returns empty / NO_RESULTS             | Write marker (`error_class: empty`). Echo: *"⚠ Identity unresolved (WorkIQ empty). Using alias=`<env-user>`; will retry on next refresh."* Continue. |
+| WorkIQ binary missing                         | Installer pre-flight should catch this. If reached at skill-time, write marker (`error_class: cli-missing`), echo the install hint, continue with alias=`<env-user>`. |
+| User has explicit non-placeholder values      | Skip resolution entirely. Never overwrite user-set values. No marker needed.                                                 |
 | Alias collision with another contributor      | Bootstrap detects existing `Evidence/<alias>/` whose `contributors.yml` records a different email → ask the user to disambiguate (suggest `<alias>-<tenant-prefix>` e.g. `alex-ms`). |
 
+**Derived alias fallback (when WorkIQ unavailable):** use `$env:USERNAME` (Windows) or `$env:USER` (POSIX) lowercased. Persist provisionally with `alias_resolved_from: env-fallback-pending-workiq`. The next refresh's deferred-retry drain will re-issue the WorkIQ probe and rename `Evidence/<env-alias>/` → `Evidence/<workiq-alias>/` if they differ.
+
 ## What NOT to do
 
 * Do NOT ask the user `What alias should Kushi use?`. The legacy onboarding prompt is gone.
-* Do NOT call `m365_*` / Graph as a fallback. WorkIQ is the single source of identity truth (`workiq-first.instructions.md`).
+* Do NOT call `m365_get_my_profile`, `m365_*`, or Graph `/me` as a fallback. WorkIQ is the single source of identity truth. On failure, write a marker and use the env-fallback. See `workiq-only.instructions.md` and `deferred-retry-on-workiq-fail.instructions.md`.
+* Do NOT block the bootstrap orchestrator on identity failure. Continue with the env-fallback alias; the marker drives the eventual reconciliation.
 * Do NOT resolve on every run. Once persisted, the config values are authoritative.
 
 ## Integration with other doctrine
 
-* `workiq-first.instructions.md` — identity resolution is the canonical example of WorkIQ-first. Add to the inventory.
+* `workiq-only.instructions.md` — identity resolution is the canonical example of WorkIQ-only. M365 fallbacks are forbidden.
+* `deferred-retry-on-workiq-fail.instructions.md` — on WorkIQ failure, mark + continue + inform; never block.
 * `bootstrap-project` SKILL — Step 0 is identity resolution. Step 1 is project context.
 * `tracking.instructions.md` — the resolved identity goes into the tracking artifact's frontmatter under `actor:`.
 
 ## References
 
-* `workiq-first.instructions.md` — the parent doctrine.
+* `workiq-only.instructions.md` — the parent doctrine (supersedes legacy `workiq-first`).
+* `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.

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

@@ -12,7 +12,7 @@ priority: HARD
 
 ## The registry
 
-`<engagement-root>/.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>` is the **single source of truth** for canonical M365 identifiers per project.
+`<workspace>/.kushi/config/user/m365-mutable.json#knownSections.<projectKey>` is the **single source of truth** for canonical M365 identifiers per project.
 
 Schema (populate every key the source supports):
 

package/plugin/instructions/multi-user-shared-files.instructions.md

@@ -0,0 +1,87 @@
+---
+applyTo: "**/SKILL.md,**/*.prompt.md,**/Evidence/run-log.yml,**/integrations.yml,**/bootstrap-status.md,**/OPEN-QUESTIONS-DRAFT.md,**/State/09_open-questions.md,**/Evidence/contributors.yml"
+---
+
+# Multi-user shared-file safety
+
+## Why this exists
+
+A Kushi engagement folder (`<engagement-root>/<project>/`) is shared across all contributors via OneDrive. Several artifacts inside it are **logically shared** — every contributor reads and writes the same path:
+
+| Shared artifact | Path | Writers |
+|---|---|---|
+| Per-project integrations | `<project>/integrations.yml` | `bootstrap-project`, `propose-ado-update`, `apply-ado-update`, every `pull-*` that discovers an ID |
+| Bootstrap status snapshot | `<project>/bootstrap-status.md` | `bootstrap-project` (every run, any contributor) |
+| Open questions draft | `<project>/OPEN-QUESTIONS-DRAFT.md` (or `State/09_open-questions.md` on full profile) | `bootstrap-project`, `consolidate-evidence`, `build-state`, `propose-ado-update` |
+| Run log | `<project>/Evidence/run-log.yml` | every `pull-*`, `bootstrap-project`, `refresh-project`, `fde-*` |
+| Contributors list | `<project>/Evidence/contributors.yml` | every `pull-*` (first time an alias touches the project) |
+
+Without rules, two contributors running concurrently produce one of:
+- OneDrive conflict-copy (`*-conflict-<alias>-<host>.yml`) — silent loss until manually merged.
+- Last-writer-wins overwrite — silent loss of the other contributor's data.
+
+This doctrine codifies the contract every writer must honor. It is **not** a substitute for proper locking, but it makes concurrent runs eventually consistent and recoverable.
+
+## Universal rules (apply to every shared artifact)
+
+1. **Read-modify-write, never blind-write.** Before writing any shared artifact, the skill MUST read the current file, merge its new contribution, and write the merged result. Blind overwrite is forbidden.
+2. **Detect and absorb conflict-copies.** Before reading the canonical file, glob for sibling files matching `<basename>-conflict-*` or `<basename> (<host>'s conflicted copy *)`. If any exist, merge their contents into the canonical file, then delete the conflict copies. Log the merge in the run report.
+3. **Stamp every contribution.** Every line / block / list-entry that a skill adds must carry its alias (from `project-evidence.yml`) and an ISO timestamp so future readers (and the merge logic above) can deterministically reconcile.
+4. **Idempotent appends.** Re-running the same skill in the same window MUST NOT duplicate prior entries. Use a `(alias, source, window_key)` tuple as the dedupe key.
+5. **Never delete another contributor's contribution.** A skill may only modify or remove entries it created (matched by alias). Cleanup of other aliases' entries is reserved for `consolidate-evidence`.
+
+## Per-artifact contracts
+
+### `<project>/integrations.yml`
+
+- **Pattern**: read-modify-write with alias stamp on changed fields.
+- Whenever a skill discovers a new ID (CRM `record_id`, ADO `engagement_id`, OneNote `section_file_id`, etc.), it MUST:
+  1. Read the current file.
+  2. If the target field is non-empty AND differs from the discovered value, write the discovered value into a sibling key `<field>_proposed_<alias>` and add a Q-row to `OPEN-QUESTIONS-DRAFT.md` for human reconciliation. Do not overwrite.
+  3. If the target field is empty (or matches), write the value and append a comment line: `# resolved by <alias> on <YYYY-MM-DD>` immediately above the changed key.
+- The `last_discovery_attempt` / `last_discovery_result` keys MAY be overwritten by any alias (they are intentionally last-writer-wins; the value is "the most recent attempt by anyone").
+
+### `<project>/bootstrap-status.md`
+
+- **Pattern**: full rewrite is permitted, but the file MUST carry a `## Contributors who have bootstrapped this project` section listing every alias that has ever written it, with their last-run timestamp.
+- Before rewriting, the skill MUST read the existing Contributors section and preserve every entry whose alias differs from the current alias. Update only its own alias row.
+- The per-source status tables (`OneNote`, `Email`, `Teams`, etc.) reflect the **most recent** discovery across all contributors. Skills MUST cross-reference `m365-mutable.json` (which is per-user) — when a row shows discovered IDs, also note which alias performed the discovery in a trailing `(by <alias>)` cell.
+
+### `<project>/OPEN-QUESTIONS-DRAFT.md` and `<project>/State/09_open-questions.md`
+
+- **Pattern**: append-only with dedup.
+- Every question row carries `[asked by <alias> on <YYYY-MM-DD>]` as the trailing column.
+- Before appending a new question, the skill MUST scan existing rows for a question whose normalized text (lowercased, whitespace-collapsed) matches. If a match exists, do not append a duplicate; instead, append `, <alias> on <date>` to the existing row's attribution.
+- Rows are removed only by an explicit `resolve-open-question` action (out of scope here) — never by another `bootstrap` / `refresh` run.
+
+### `<project>/Evidence/run-log.yml`
+
+- **Pattern**: structured append + max() merge.
+- Run history (`runs:` list) is append-only. Every entry carries `alias:` and `run_at:`.
+- Per-source watermarks (`sources.<source>.watermark`) use **max()** merge: when writing, the skill reads the current value and writes `max(current, new)`. Never overwrite with an older watermark.
+- Per-source errors (`sources.<source>.errors[]`) are append-only with `alias` + `at` on every entry; dedup on `(alias, code, at)`.
+
+### `<project>/Evidence/contributors.yml`
+
+- **Pattern**: append-only, alias-keyed.
+- The first time an alias runs against the project, append `{ alias, display_name, email, first_seen: <YYYY-MM-DD> }`. Subsequent runs MUST NOT modify the entry.
+- `last_seen` MAY be updated by any run, max()-merged.
+
+## Implementation guidance for skill authors
+
+- Read `<workspace>/.kushi/config/user/project-evidence.yml` to get your alias via `Get-KushiConfig -Name 'project-evidence'`. Never hardcode aliases.
+- For YAML merges, use `Get-Content -Raw | ConvertFrom-Yaml`, mutate, then `ConvertTo-Yaml`. Preserve comments where possible by line-based merging when structure permits.
+- For Markdown table merges in `OPEN-QUESTIONS-DRAFT.md`, parse the body to a list of rows, dedup by normalized question text, re-emit.
+- On any merge conflict the skill cannot resolve deterministically, write the alternative as a sibling-key `<field>_proposed_<alias>` (for YAML) or a `> Disagreement: <alias-A> says ..., <alias-B> says ...` callout (for Markdown) and add a Q-row to `OPEN-QUESTIONS-DRAFT.md`.
+
+## Out of scope
+
+- True file locking (filesystem advisory locks, OneDrive's checkout API) — relies on platform support Kushi can't assume.
+- Server-side merge service — Kushi is local-only by design.
+
+## Related doctrine
+
+- `evidence-layout-canonical.instructions.md` — what lives where under `Evidence/`.
+- `run-reports.instructions.md` — per-user run narrative (always under `Evidence/<alias>/`, no concurrency risk).
+- `bootstrap-status-format.instructions.md` — format contract for the shared status artifact.
+- `citation-ledger.instructions.md` — every assertion in shared artifacts must carry a citation; alias attribution is the citation for shared-file entries.

package/plugin/instructions/run-reports.instructions.md

@@ -24,7 +24,7 @@ Critical for multi-user projects: each contributor's runs are independent, and e
   YYYY-MM-DD-HHmm_<mode>.md
 ```
 
-- `<alias>` — the contributor running the skill (from `<workspace>/.kushi/config/project-evidence.yml#alias`).
+- `<alias>` — the contributor running the skill (from `<workspace>/.kushi/config/user/project-evidence.yml#alias`).
 - `<mode>` — one of `bootstrap`, `refresh`, `force-refresh`, `consolidate`.
 - Timestamp uses the **start time** of the run, in local time, format `YYYY-MM-DD-HHmm` (no seconds, no timezone — local-time prefix is enough for chronological sort).