kushi-agents 4.4.0 → 4.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.4.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": {

package/plugin/agents/kushi.agent.md

@@ -100,7 +100,7 @@ When a user message arrives:
 ```
 <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)
-<engagement-root>/.project-evidence/                ← per-machine, per-user M365 + CRM + ADO config (OneDrive-synced)
+<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,9 +224,9 @@ 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` |
+| 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` |
 

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:

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

@@ -15,20 +15,23 @@ Resolve `<engagement-root>` in this order — first match wins:
 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/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,7 +45,7 @@ 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`.
+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>`.
 

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

@@ -37,30 +37,37 @@ Map the response:
    > ✓ 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/scope-boundaries.instructions.md

@@ -21,7 +21,7 @@ host-fallback Graph call, and every CRM/ADO probe MUST honor.
 Before issuing **any** WorkIQ query, `m365_*` host call, Graph REST call, or CRM/ADO
 REST call, the skill MUST resolve the boundary it is operating inside from
 `<engagement-root>/<project>/integrations.yml boundaries:` (per-source) or the
-global `<engagement-root>/.project-evidence/{crm,ado}/config.yml` (auth +
+global `<workspace>/.kushi/config/shared/integrations.yml` (auth +
 tenant + org). The resolved boundary MUST be recorded in the evidence file's
 `## Source Basis` block, e.g.:
 
@@ -57,8 +57,8 @@ returns evidence over the same surface — no run-to-run drift.
 
 | Skill | Hard prerequisite | Failure message (verbatim) |
 |---|---|---|
-| `pull-crm` | `<engagement-root>/.project-evidence/crm/config.yml` exists with non-placeholder `environmentUrl` | `crm-config-missing — drop a filled config.yml at <engagement-root>/.project-evidence/crm/config.yml. See plugin/templates/init/crm-config.template.yml.` |
-| `pull-ado` | `<engagement-root>/.project-evidence/ado/config.yml` exists with non-placeholder `organization` AND `defaultProject` | `ado-config-missing — drop a filled config.yml at <engagement-root>/.project-evidence/ado/config.yml. See plugin/templates/init/ado-config.template.yml.` |
+| `pull-crm` | `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `crm.environmentUrl` | `crm-config-missing — fill the crm: block in <workspace>/.kushi/config/shared/integrations.yml. See plugin/templates/init/integrations.template.yml.` |
+| `pull-ado` | `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `ado.organization` AND `ado.defaultProject` | `ado-config-missing — fill the ado: block in <workspace>/.kushi/config/shared/integrations.yml. See plugin/templates/init/integrations.template.yml.` |
 | `propose-ado-update` | both above + `integrations.yml ado.engagement_id > 0` | per `propose-ado-update/SKILL.md` Prerequisites table |
 
 Pre-v3.7.0 behavior allowed `pull-crm` to "narrate from email" when the live
@@ -172,7 +172,7 @@ On first run for a new project, bootstrap MUST:
 3. For sources where bootstrap cannot auto-populate, write the source as
    **disabled** (`enabled: false`) with a one-liner in `OPEN-QUESTIONS-DRAFT.md`
    asking the user to fill the boundary and re-enable.
-4. For CRM and ADO, ALSO check that the global `<engagement-root>/.project-evidence/{crm,ado}/config.yml`
+4. For CRM and ADO, ALSO check that the global `<workspace>/.kushi/config/shared/integrations.yml`
    exists and has non-placeholder values; if not, scaffold from
    `plugin/templates/init/{crm,ado}-config.template.yml` and park in
    `OPEN-QUESTIONS-DRAFT.md` with the path the user needs to fill.

package/plugin/instructions/workiq-only.instructions.md

@@ -42,8 +42,8 @@ For every M365 source in scope:
 
 1. **WorkIQ FIRST and ONLY.** Issue the canonical query from the table below.
 2. **If WorkIQ returns insufficient content** (empty, truncated, or only a summary when the query asked for verbatim): retry ONCE with the doubled-strict prompt from the same row.
-3. **If WorkIQ still fails or is unavailable**: ask the user to paste the data verbatim. This is a first-class evidence path, not a degradation.
-4. **DO NOT attempt** `m365_get_transcript`, `m365_get_facilitator_notes`, `m365_list_meetings`, `m365_list_events`, `m365_search_files` (for content), `m365_download_file` (for transcript/notes), or any Graph REST URL for the in-scope sources above. These are FORBIDDEN. Calling them is a defect; coverage.md must NOT show them in the attempt trail.
+3. **If WorkIQ still fails or is unavailable**: follow `deferred-retry-on-workiq-fail.instructions.md` — write a deferred-retry marker under `<project>/Evidence/<alias>/_deferred-retries/`, surface a one-liner in coverage.md and the run report, and **continue the run** for the remaining sources. The next `refresh-project` drains the queue. User-paste remains available as a manual recovery the user MAY do later by populating the artifact directly and deleting the marker — it is NOT the agent's recovery flow.
+4. **DO NOT attempt** `m365_get_transcript`, `m365_get_facilitator_notes`, `m365_list_meetings`, `m365_list_events`, `m365_search_files` (for content), `m365_download_file` (for transcript/notes), or any Graph REST URL for the in-scope sources above. These are FORBIDDEN — **including as a "last-resort" fallback after WorkIQ fails** (kushi v4.4.1+). Calling them is a defect; coverage.md must NOT show them in the attempt trail. The deferred-retry marker IS the audit trail for WorkIQ failures.
 5. **Allowed alongside WorkIQ** (structured-data dumps only): `m365_list_chat_messages` for chat-id'd threads → `chat-messages.json`. These run in parallel with the WorkIQ pull, not as a substitute.
 
 ## Canonical WorkIQ commands (CODIFIED — do not re-discover)
@@ -174,6 +174,7 @@ If `Result: SUMMARY-ONLY` after doubled-strict retry: the artifact is acceptable
 
 ## Anti-patterns (defects)
 
+0. **Falling back to `m365_get_*` / Graph after a WorkIQ failure (kushi v4.4.1+).** FORBIDDEN. Even framed as "a last-resort partial," "just to try," or "we already have a WorkIQ marker so this is harmless." The doctrine is: WorkIQ fail → deferred-retry marker → continue → next refresh retries. Never a Graph escape hatch. See `deferred-retry-on-workiq-fail.instructions.md`.
 1. **Calling `m365_get_transcript`, `m365_get_facilitator_notes`, `m365_list_meetings`, `m365_list_events` from a kushi pull-* skill.** FORBIDDEN. These tools have a near-100% failure rate in this workspace. Use WorkIQ.
 2. **Using Graph REST URLs directly** (e.g. `https://graph.microsoft.com/v1.0/me/onlineMeetings/...`) from a kushi pull-* skill. FORBIDDEN for the in-scope M365 sources. Use WorkIQ.
 3. **Re-discovering the right WorkIQ prompt every run.** FORBIDDEN. Use the codified prompts from the table above. If a new source variant is needed, add a row to the table, do not improvise.
@@ -192,3 +193,4 @@ If `Result: SUMMARY-ONLY` after doubled-strict retry: the artifact is acceptable
 - `plugin/instructions/ado-bootstrap-discovery.instructions.md` — ADO is OUT of WorkIQ scope; it uses ADO REST.
 - `plugin/instructions/scope-boundaries.instructions.md` — every pull-* still respects integrations.yml#boundaries.
 - `plugin/instructions/evidence-thoroughness.instructions.md` — verbatim is the bar; this rule operationalizes how to hit it.
+- `plugin/instructions/deferred-retry-on-workiq-fail.instructions.md` (kushi v4.4.1+) — defines exactly what happens when WorkIQ fails. NO Graph fallback. Marker + continue + inform.

package/plugin/lib/Get-KushiConfig.ps1

@@ -53,6 +53,92 @@ param(
 
 $ErrorActionPreference = 'Stop'
 
+# Schema-aware required-field map (kushi v4.4.1+).
+# For each logical config name, list the dot-paths that MUST be populated
+# (non-empty, non-sentinel) before the config is considered usable. The check
+# runs IN ADDITION to the substring sentinel check.
+$script:RequiredFields = @{
+  'm365-auth' = @(
+    'm365Auth.defaultTenantId',
+    'm365Auth.oneNote.defaultNotebookName',
+    'm365Auth.oneNote.defaultNotebookId',
+    'm365Auth.oneNote.defaultLinkOwner',
+    'm365Auth.emailContext.folders',
+    'm365Auth.sharePointContext.localProjectsRoot'
+  )
+  'project-evidence' = @(
+    'identity.alias',
+    'identity.email',
+    'engagement_root'
+  )
+  # integrations.yml is shared and per-project — required-field check is
+  # the consumer skill's job (it knows which sources are enabled).
+  'integrations' = @()
+}
+
+# Sentinel substrings that indicate "still a placeholder."
+$script:Sentinels = @(
+  '__FILL_ME_IN__',
+  '<auto>',
+  '<TENANT_ID>',
+  '<NOTEBOOK_ID>',
+  '<NOTEBOOK_NAME>',
+  '<LINK_OWNER>',
+  '<SP_LOCAL_ROOT>',
+  '<your-alias>',
+  '<Your Full Name>',
+  'your.email@example.com'
+)
+
+function Test-Sentinel {
+  param([string] $Value)
+  if ([string]::IsNullOrWhiteSpace($Value)) { return $true }
+  foreach ($s in $script:Sentinels) {
+    if ($Value -like "*$s*") { return $true }
+  }
+  return $false
+}
+
+function Get-DotPath {
+  param([object] $Obj, [string] $DotPath)
+  $cur = $Obj
+  foreach ($seg in $DotPath -split '\.') {
+    if ($null -eq $cur) { return $null }
+    if ($cur -is [System.Collections.IDictionary]) {
+      $cur = $cur[$seg]
+    } else {
+      $cur = $cur.$seg
+    }
+  }
+  return $cur
+}
+
+function Test-RequiredFields {
+  param([string] $Name, [object] $Parsed)
+  $required = $script:RequiredFields[$Name]
+  if (-not $required) { return @() }
+  $missing = @()
+  foreach ($field in $required) {
+    $val = Get-DotPath -Obj $Parsed -DotPath $field
+    if ($null -eq $val) { $missing += $field; continue }
+    # Arrays: must have at least one non-sentinel element.
+    if ($val -is [System.Collections.IEnumerable] -and -not ($val -is [string])) {
+      $arr = @($val)
+      if ($arr.Count -eq 0) { $missing += $field; continue }
+      $allBlank = $true
+      foreach ($item in $arr) {
+        if ($item -is [string]) {
+          if (-not (Test-Sentinel $item)) { $allBlank = $false; break }
+        } else { $allBlank = $false; break }
+      }
+      if ($allBlank) { $missing += $field }
+      continue
+    }
+    if ($val -is [string] -and (Test-Sentinel $val)) { $missing += $field }
+  }
+  return ,$missing
+}
+
 function Get-DefaultExtension([string] $name) {
   if ($name -match '^(project-evidence|integrations)$') { return 'yml' }
   return 'json'
@@ -84,9 +170,13 @@ if ($Path) { return $resolved }
 $raw = Get-Content -LiteralPath $resolved -Raw
 
 if (-not $AllowPlaceholders) {
-  if ($raw -match '__FILL_ME_IN__' -or $raw -match '<auto>') {
+  $sentinelHit = $false
+  foreach ($s in $script:Sentinels) {
+    if ($raw -like "*$s*") { $sentinelHit = $true; break }
+  }
+  if ($sentinelHit) {
     throw @"
-Kushi config '$resolved' still has template placeholders (__FILL_ME_IN__ or <auto>).
+Kushi config '$resolved' still has template placeholders (e.g. __FILL_ME_IN__, <auto>, <TENANT_ID>).
 Edit the file with your actual values, or pass -AllowPlaceholders to bypass this check.
 "@
   }
@@ -94,16 +184,31 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
 
 if ($Raw) { return $raw }
 
-switch ($ext) {
+$parsed = switch ($ext) {
   'json' {
-    return ($raw | ConvertFrom-Json -Depth 100)
+    $raw | ConvertFrom-Json -Depth 100
   }
   { $_ -in 'yml','yaml' } {
     if (Get-Module -ListAvailable -Name 'powershell-yaml') {
       Import-Module powershell-yaml -ErrorAction Stop
-      return ConvertFrom-Yaml -Yaml $raw
+      ConvertFrom-Yaml -Yaml $raw
+    } else {
+      Write-Warning "powershell-yaml not installed; required-field validation skipped. Install with: Install-Module powershell-yaml -Scope CurrentUser"
+      $null
     }
-    Write-Warning "powershell-yaml not installed; returning raw YAML text. Install with: Install-Module powershell-yaml -Scope CurrentUser"
-    return $raw
   }
 }
+
+if (-not $AllowPlaceholders -and $null -ne $parsed) {
+  $missing = Test-RequiredFields -Name $Name -Parsed $parsed
+  if ($missing.Count -gt 0) {
+    throw @"
+Kushi config '$resolved' is missing required fields:
+$(($missing | ForEach-Object { "  - $_" }) -join "`n")
+Edit the file with your actual values, or pass -AllowPlaceholders to bypass this check.
+"@
+  }
+}
+
+if ($null -eq $parsed) { return $raw }
+return $parsed