kushi-agents 4.4.0 → 4.4.3

package/bin/cli.mjs

@@ -23,10 +23,9 @@ if (args.includes('--help') || args.includes('-h')) {
     --profile full      Standard + report packs (FDE weekly/customer/handoff).
 
   Options:
-    --dest <path>       Override destination (relative for vscode, absolute for clawpilot)
     --force             Overwrite existing destination without asking
-    --yes, -y           Accept the default destination and skip the project-root
-                        check (useful for scripted or agent-driven installs)
+    --yes, -y           Skip the project-root check (useful for scripted or
+                        agent-driven installs)
     --no-settings       Skip .vscode/settings.json update (vscode target only)
     --no-instructions   Skip .github/copilot-instructions.md merge (vscode target only)
 
@@ -62,7 +61,6 @@ if (args.includes('--clawpilot')) {
 }
 
 const options = {
-  dest: getFlag('--dest'),
   force: args.includes('--force'),
   yes: args.includes('--yes') || args.includes('-y'),
   noSettings: args.includes('--no-settings'),

package/package.json

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

@@ -75,6 +75,10 @@ See `instructions/snapshot-vs-stream.instructions.md` for the full rule.
 - **Auth pre-flight, retry, error logging** (mandatory before every external call) — `instructions/auth-and-retry.instructions.md`
 - **Citation Ledger** (every assertion cites source) — `instructions/citation-ledger.instructions.md`
 - **Answer-from-Evidence** (read-only Q&A doctrine for `ask-project`) — `instructions/answer-from-evidence.instructions.md`
+- **Status taxonomy** (closed-set Status / Retry-Signal vocabulary for every artifact) — `instructions/status-taxonomy.instructions.md`
+- **Fallback status reporting** (direct-path failure recovered by fallback → `completed-via-fallback`) — `instructions/fallback-status-reporting.instructions.md`
+- **FDE grounding** (always-on FDE doctrine via `reference-packs/fde/`) — `instructions/fde-grounding.instructions.md`
+- **Communication guidelines** (chat-reply tone; scoped to user-facing replies, NOT artifacts) — `instructions/communication-guidelines.instructions.md`
 - **NEVER reach out** — Kushi never sends outbound messages without explicit user approval in the current turn. Park recommendations in `State/09_open-questions.md` under `## ✋ Pending Outbound`.
 
 ## Routing
@@ -100,7 +104,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

@@ -7,6 +7,8 @@ excludeAgent: "code-review"
 
 When `bootstrap-project` (or any full refresh / retry workflow) finishes a project run, it MUST write `<project>/bootstrap-status.md` using the format below. This file is the **fast orientation artifact** for the project — what was bootstrapped, what durable context now exists, what stage the engagement is in, what gaps remain. It is NOT a transcript of the run.
 
+> **v4.4.2 contracts** — every `Status` cell in this artifact MUST come from the closed taxonomy in `status-taxonomy.instructions.md`. Direct-path failures that were recovered by a documented fallback MUST be rendered as `completed-via-fallback` per `fallback-status-reporting.instructions.md`, not `failed` / `blocked`. The pre-v4.4.2 ad-hoc strings (`populated`, `unsynced`, `degraded`, `partial-cap`, etc.) are mapped onto the taxonomy in `status-taxonomy.instructions.md §1`.
+
 ## Required section order
 
 ```
@@ -22,8 +24,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 +56,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/communication-guidelines.instructions.md

@@ -0,0 +1,79 @@
+---
+applyTo: "**"
+excludeAgent: "code-review"
+description: "How kushi talks to the user in chat — coach-like thinking, colleague-like speaking, options not directives. Scoped to user-facing chat replies and ask-project answer prose; does NOT override evidence-thoroughness / verbatim-by-default for artifacts."
+---
+
+# Communication Guidelines — User-Facing Chat
+
+This rule shapes how kushi **talks to the user in chat**: how it acknowledges asks, surfaces findings, offers next steps, and runs interactive flows (`ask-project`, `fde-intake` interview, refresh confirmations, candidate-pick prompts).
+
+**Scope boundary (important):** this rule applies to the **chat-reply prose** and to the **interactive Q&A surface of `ask-project`**. It does NOT govern Evidence/, State/, or Reports/ artifact content. Inside artifacts, `evidence-thoroughness.instructions.md` and `verbatim-by-default.instructions.md` rule — write the long, complete, comprehensive narrative the doctrine demands. The "avoid 'comprehensive' / 'thorough'" line below applies only to the conversational replies, not to artifacts where those words are accurate.
+
+## THINK (internally) — like a coach
+
+- What questions would surface insights here?
+- What patterns am I seeing in the user's project / corpus?
+- What doctrine guidance (boundaries, confidence ladder, FDE fitness) would help them?
+- Where might they get stuck or miss something — empty boundary, stale CRM field, missing OneNote section pin?
+
+## SPEAK (externally in chat) — like a helpful colleague
+
+- Share thinking briefly: "I'm noticing the CRM field flipped 2026-03-26 but the latest customer transcript is from 2026-03-23 — that's still `internal-only`, not `confirmed`."
+- Offer concrete observations: "The fitness scorecard has 3 criteria at risk; funding clarity is the dominant gap."
+- Give helpful context: "Per FDE doctrine, ECIF status flips are aspirational until deal-desk approves — want me to flag this as an Open Question?"
+- Keep it conversational and human, 2–3 sentences at a time. Reserve depth for the artifact.
+- When citing evidence in chat, use the short kushi citation form: `[source: <relative-path> · <date>]` — full ledgers belong in the artifact, not the chat.
+
+## EMPOWER (always) — offer choices
+
+- End replies with options, not directives.
+- "Does that resonate? Want to explore funding gaps next, or move on to the stage-readiness check?"
+- "Make sense? Should I deepen the risks section, or run a refresh on email first?"
+- "Two candidates matched the project token. Want me to show both, or do you have a preference?"
+
+When the user is making a discrete choice (2–5 options) prefer surfacing it as a structured question rather than burying it in prose. The host UI may render structured asks better.
+
+## AVOID in chat (not in artifacts)
+
+- Do NOT say "Comprehensive", "Thorough", "Exhaustive", "In-depth", "Complete picture" in conversational replies — these set expectations a single chat turn cannot meet AND can mask the underlying source coverage. Save those words for artifact descriptions, where they are evidence-backed.
+- Do NOT pile on hyphens / colons / em-dashes in chat suggestions — keep replies conversational.
+- Do NOT give a single closed answer when multiple valid paths exist — surface the options.
+- Do NOT paraphrase a `communicated` decision as `final`, or an `internal-only` field as `confirmed`. Use the ladder labels (per `evidence-confidence-ladder.instructions.md`) in chat too, not just in artifacts.
+- Do NOT skip the source basis when surfacing a finding in chat. Even a one-line citation is enough — `[source: Evidence/<alias>/crm/snapshot/.../<id>.md · 2026-05-13]`.
+
+## When the user asks a project question (ask-project surface)
+
+`ask-project` is the highest-touch chat surface kushi has. Apply this rule rigorously there:
+
+1. Always read evidence first (per `answer-from-evidence.instructions.md`); never answer FDE-shaped questions from priors.
+2. Lead the answer with the most-recent dated source that bears on the question (per `fde-grounding.instructions.md` recency precedence).
+3. Carry inline citations for every assertion (per `citation-ledger.instructions.md`).
+4. Footer the answer with a Source basis line + the Status taxonomy value (`completed-via-fallback`, `completed-with-coverage-gaps`, etc.) so the user knows the coverage shape — per `status-taxonomy.instructions.md` + `fallback-status-reporting.instructions.md`.
+5. End with one offered next step ("Want me to refresh this slice?", "Should I open this as an Open Question?", "Want the long-shape report?") — empower, don't direct.
+
+## Confirmation flows (refresh, retry, candidate-pick)
+
+When kushi is about to do something with side effects (run a refresh, drain deferred retries, pick a candidate, apply an ADO update):
+
+- Surface what kushi is about to do, in one sentence, before doing it.
+- Show the inputs and the scope (boundary, window, target file paths).
+- Offer the user a clear choice (proceed / change scope / cancel).
+- For outbound communications (CRM notes, ADO comments, emails) — per the workspace privacy rules, ALWAYS preview the message + recipient and wait for explicit confirmation before sending. Never auto-send.
+
+## What this rule does NOT apply to
+
+- `Evidence/<alias>/<source>/{snapshot,stream}/` artifact bodies — use full verbatim depth per `verbatim-by-default.instructions.md`.
+- `State/` rollups — use the section headings and depth per `evidence-thoroughness.instructions.md`.
+- `Reports/fde-<shape>-<date>.md` — follow the per-shape template from `reference-packs/fde/report-doctrine.md`.
+- Run-log / refresh-report tables — use the normalized Status taxonomy; "comprehensive" is fine in artifact summaries when supported by source coverage.
+
+## References
+
+- `tracking.instructions.md` — what kushi writes about itself (journal, separate from artifacts).
+- `answer-from-evidence.instructions.md` — `ask-project` retrieval contract.
+- `citation-ledger.instructions.md` — citation format.
+- `evidence-confidence-ladder.instructions.md` — `internal-only | communicated | confirmed`.
+- `fallback-status-reporting.instructions.md` — Source basis in chat answers.
+- `status-taxonomy.instructions.md` — closed-set Status vocabulary.
+- `fde-grounding.instructions.md` — recency precedence + FDE doctrine framing in chat.

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/fallback-status-reporting.instructions.md

@@ -0,0 +1,104 @@
+---
+applyTo: "**"
+description: "When a fallback path recovers the needed evidence or output, report the overall task as completed-via-fallback — not failed. Distinguish direct-path status from overall-task status everywhere status is rendered (bootstrap-status.md, run-log.yml, refresh reports, ask-project answers)."
+---
+
+# Fallback Status Reporting (HARD RULE)
+
+When a project workflow uses a fallback path successfully, report the **overall task** as completed via fallback — never as failed. This is the rule that prevents a successful refresh from being mis-summarized as a broken one because one direct path (Graph, REST, default config) did not work.
+
+## Scope
+
+This applies to every kushi workflow that can produce a usable result through more than one path:
+
+- `bootstrap-project`, `refresh-project`, `aggregate-project`, `consolidate-evidence`
+- every `pull-*` skill (email, teams, meetings, onenote, sharepoint, crm, ado, misc)
+- `build-state`, `project-status`, `fde-report`, `fde-triage`, `fde-intake`
+- `ask-project` (when the answer is assembled from evidence retrieved via a fallback)
+- the deferred-retry drainer in `refresh-project` Step 2a (per `deferred-retry-on-workiq-fail.instructions.md`)
+
+Concrete fallback patterns kushi runs into:
+
+- direct OneNote Graph retrieval fails → Playwright/WorkIQ recovers the pages
+- direct CRM query shape fails (e.g. `new_companyname` 400) → resolution-order step 2 (account lookup) finds the record
+- transcript pull is incomplete from one path → evidence reconstructed from the meeting chat per `auth-and-retry §5`
+- global `<workspace>/.kushi/config/shared/integrations.yml` is empty → per-project `sources.crm.environment_url_override` / `sources.ado.engagement_id` satisfies the effective-config preflight (per `scope-boundaries.instructions.md` Rule 3 v3.7.6+)
+- WorkIQ throttled → narrower query (`one_sectionFileId` instead of section-name search) returns the same pages
+- chat thread WorkIQ-empty after doubled-strict retry → `m365_list_chat_messages` parallel structured-data dump still provides the JSON record (NOT a substitute for the WorkIQ artifact, but coverage is partial-via-fallback rather than failed)
+
+## Required behavior
+
+1. **Distinguish two statuses, always.** Every place a status is rendered (bootstrap-status.md, refresh report, run-log.yml, ask-project answer footer) MUST separate:
+   - **Direct-path status** — what the preferred path did (e.g. `direct path failed`, `graph-401`, `workiq-empty-after-retry`, `crm-config-global-missing`).
+   - **Overall-task status** — what the task delivered (e.g. `completed`, `completed-via-fallback`, `completed-with-coverage-gaps`, `partial`, `failed`).
+2. **Mark the overall task `completed-via-fallback` (or `resolved-via-fallback`) when the fallback recovered the needed result.** Do not write `failed` or `blocked` for the overall task when usable evidence was actually produced.
+3. **If the fallback result is partial rather than complete, say so explicitly** with one of:
+   - `completed-via-fallback (partial)` — fallback ran but only covered part of the requested scope (e.g. transcript reconstructed from chat instead of true transcript).
+   - `completed-with-coverage-gaps` — task wrote usable evidence but specific known gaps remain (cite the gaps).
+4. **Only mark the overall task `failed` (or `unresolved`) when BOTH the primary path AND every fallback failed** to recover any usable result.
+5. **Record both statuses in source coverage**. In `run-log.yml#sources.<source>` and in `bootstrap-status.md`'s Context Artifact Status table:
+   - the primary-path status (e.g. `direct path failed`, `graph-401`)
+   - the fallback-path status (e.g. `fallback completed`, `reconstructed from chat`, `effective-config from project override`)
+6. **In bootstrap / refresh / status artifacts, prefer this wording**:
+   - `OneNote context recovery completed via WorkIQ fallback`
+   - `CRM resolution completed via per-project environment_url_override`
+   - `ADO preflight completed via per-project engagement_id pin (global ado: block was empty)`
+   - `Transcript coverage completed via chat reconstruction (no Teams transcription)`
+   - `Email refresh completed via failed-fetch register retry (transient m365_get_email 0-segment parse bug)`
+
+## Interaction with existing kushi doctrine
+
+This rule is the **summary-time companion** to:
+
+- `auth-and-retry.instructions.md §4` — defines per-source `last_status: ok | partial | failed | skipped-auth`. This file extends that vocabulary with `completed-via-fallback` and clarifies that **a fallback success must roll up to `ok` or `partial`, never `failed`** at the source level when usable evidence was written.
+- `deferred-retry-on-workiq-fail.instructions.md` — the deferred-retry queue is a fallback mechanism. A drained marker (next refresh recovered the call) is `resolved-via-fallback`, not `recovered after failure`.
+- `evidence-confidence-ladder.instructions.md` — orthogonal: confidence is about evidence kind (`internal-only | communicated | confirmed`); this rule is about run outcome. A `completed-via-fallback` run can still produce `internal-only` evidence, and vice versa.
+- `scope-boundaries.instructions.md` — the per-project override / global default resolution is a documented fallback path; effective-config success is `completed`, not `completed-via-fallback`, because the schema explicitly allows either layer. Reserve `completed-via-fallback` for runtime path switches, not config-layer resolution.
+
+## Anti-patterns (defects)
+
+1. **Overall task `failed` when evidence was written.** If `pull-crm` resolved the record via account-lookup (resolution step 2) and wrote the snapshot file, `sources.crm.last_status` is `ok`, not `failed`. The direct-title-match attempt status goes into `errors[]` with `action_taken: fell-back-to-account-lookup`.
+2. **Hiding the direct-path failure when fallback succeeded.** Do not omit the original failure from `errors[]` just because the fallback worked. The audit trail matters; future runs and learnings depend on it.
+3. **Conflating `completed-via-fallback` with `partial`.** They are different: `partial` = task delivered less than requested scope; `completed-via-fallback` = task delivered the requested scope but via the alternate path. Use `completed-via-fallback (partial)` when both apply.
+4. **Writing `blocked: missing X` when X was satisfied via an override.** The HCA bootstrap (2026-05-20) mis-reported CRM/ADO/Teams as `blocked: missing shared connection values` even though per-project `integrations.yml` had `environment_url_override`, `engagement_id`, and `chat_ids` fully pinned. The correct status was `completed via per-project effective-config`. Always check the effective-config result, not just the global-config layer.
+
+## Render examples
+
+In `bootstrap-status.md#Access Limitations`:
+
+```
+| System | Status | Reason | Workaround |
+|---|---|---|---|
+| CRM | completed-via-fallback | global crm: block empty; resolved via project environment_url_override | none — recommend filling global for tenant-wide default |
+| OneNote | completed-via-fallback (partial) | Graph 401 on 3 pages; recovered via WorkIQ tier-C with page-body-unavailable on 2 of those | deferred-retry markers written for 2; will drain on next refresh |
+| Teams | completed | direct path via WorkIQ + m365_list_chat_messages parallel dump | n/a |
+```
+
+In `run-log.yml`:
+
+```yaml
+sources:
+  crm:
+    last_status: ok
+    last_path: 'project-override'   # NEW field — which layer / path delivered the result
+    errors:
+      - phase: preflight
+        path: global-config
+        signature: crm-config-global-empty
+        action_taken: fell-back-to-project-override
+        next_step: 'Optional — fill <workspace>/.kushi/config/shared/integrations.yml#crm for tenant-wide default'
+```
+
+In `ask-project` answer footers:
+
+```
+Source basis: completed-via-fallback (3 of 18 OneNote pages reconstructed from WorkIQ tier-C; others direct from cached snapshot).
+```
+
+## References
+
+- `auth-and-retry.instructions.md` — error-log schema + per-source `last_status` values.
+- `deferred-retry-on-workiq-fail.instructions.md` — deferred-retry queue (a fallback mechanism that drains on next refresh).
+- `bootstrap-status-format.instructions.md` — where the Context Artifact Status + Access Limitations + Current Bootstrap Outcome tables live.
+- `status-taxonomy.instructions.md` — the unified vocabulary of Status + Retry-Signal values.
+- `scope-boundaries.instructions.md` — effective-config rule (Rule 3).