kushi-agents 4.3.0 → 4.4.1

package/plugin/skills/propose-ado-update/SKILL.md

@@ -21,13 +21,13 @@ This skill does **NOT** create a new top-level config file. It reads from the co
 
 | What | Where | Maintained by |
 |---|---|---|
-| ADO tenant + org + apiVersion + auth strategy | `<engagement-root>/.project-evidence/ado/config.yml` | `bootstrap-project` (global, one-time) |
+| ADO tenant + org + apiVersion + auth strategy | `<workspace>/.kushi/config/shared/integrations.yml` | `bootstrap-project` (global, one-time) |
 | Per-project Initiative ID (`engagement_id`), area, title filter, discovery hints | `<engagement-root>/<project>/integrations.yml` under `ado:` | `bootstrap-project` + `pull-ado` (auto-discovers and persists) |
 | Per-project **writes block** (allowlist, autoApply per field, strategy, fieldRefName) | `<engagement-root>/<project>/integrations.yml` under `ado.writes:` | First run of this skill scaffolds the block from the template, then user edits |
 
 **Resolution is fully deterministic** — never ask the user for paths the bootstrap layer already resolved:
 
-1. `<engagement-root>` ← `<workspace>/.kushi/config/project-evidence.yml engagement_root` (per `engagement-root-resolution.instructions.md`).
+1. `<engagement-root>` ← `<workspace>/.kushi/config/user/project-evidence.yml engagement_root` (per `engagement-root-resolution.instructions.md`).
 2. `<project>` folder ← fuzzy-match per `engagement-root-resolution.instructions.md` (knownSections → active_projects → subfolders).
 3. `<project>/integrations.yml ado.engagement_id` — REQUIRED. If `0` or missing → see "Prerequisites" below; never invent an ID.
 4. `<project>/integrations.yml ado.writes` — if missing, append the block from `<KUSHI_ROOT>/plugin/templates/ado-update/integrations-ado-writes.example.yml` and stop for user confirmation of `fieldRefName`.
@@ -41,7 +41,7 @@ Refuse to produce `proposed.md` and tell the user exactly what's missing if any
 |---|---|
 | `<project>/integrations.yml` exists | "Project not bootstrapped. Run `@Kushi bootstrap <project>` first." |
 | `ado.engagement_id` > 0 | "ADO Initiative not yet linked for `<project>` (engagement_id is 0). pull-ado will auto-discover on next refresh; once `engagement_id` is set in `integrations.yml`, retry." |
-| `<engagement-root>/.project-evidence/ado/config.yml` exists with non-placeholder `organization` | "Global ADO config missing or has placeholder org. Run `@Kushi bootstrap <project>` to scaffold, then fill `.project-evidence/ado/config.yml`." |
+| `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `organization` | "Global ADO config missing or has placeholder org. Run `@Kushi bootstrap <project>` to scaffold, then fill `.kushi/config/shared/integrations.yml`." |
 | At least one `Evidence/_Consolidated/<date>_consolidated.md` exists | "No consolidated evidence yet for `<project>`. Run `@Kushi refresh <project>` then `consolidate` first." |
 | Latest consolidated file ≤ 8 days old | Continue but flag `stale-evidence` at top of `proposed.md`. |
 
@@ -76,7 +76,7 @@ Refuse to produce `proposed.md` and tell the user exactly what's missing if any
 ## What this skill does NOT do
 
 - Does NOT call any ADO `PATCH` or `POST` endpoint.
-- Does NOT create or modify the global `.project-evidence/ado/config.yml`.
+- Does NOT create or modify the global `.kushi/config/shared/integrations.yml`.
 - Does NOT touch `<project>/integrations.yml` other than appending the `ado.writes:` sub-block on first run (preserving every existing key).
 - Does NOT re-pull evidence (uses the most recent `_Consolidated/` file as-is).
 - Does NOT write to the ledger (the ledger is written only by `apply-ado-update`).

package/plugin/skills/pull-ado/SKILL.md

@@ -27,9 +27,9 @@ WorkIQ-first per `workiq-first.instructions.md` — but **for ADO, REST is prefe
 - `<project>` — already-resolved project name.
 - `<alias>` — current contributor.
 - `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/ado/config.yml` — connection.
+- (read) `<workspace>/.kushi/config/shared/integrations.yml` — connection.
 - (read) `<engagement-root>/<project>/integrations.yml#ado` — per-project pinned IDs.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
 - (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
 
 ## Resolution hints (pinned in mutable)
@@ -42,15 +42,15 @@ WorkIQ-first per `workiq-first.instructions.md` — but **for ADO, REST is prefe
 
 This skill is **HARD-fail** without both:
 
-1. Global config: `<engagement-root>/.project-evidence/ado/config.yml` exists with non-placeholder `organization` AND `defaultProject`.
+1. Global config: `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `organization` AND `defaultProject`.
 2. Per-project boundary: `<engagement-root>/<project>/integrations.yml#boundaries.ado.area_paths` is non-empty (OR `boundaries.ado.work_item_ids` is pinned).
 
 If either is missing, refuse with the exact message:
 
 ```
 ado-config-missing — drop a filled config.yml at
-<engagement-root>/.project-evidence/ado/config.yml. See template at
-plugin/templates/init/ado-config.template.yml. Then add boundaries.ado.area_paths
+<workspace>/.kushi/config/shared/integrations.yml. See template at
+plugin/templates/init/integrations.template.yml (ado: block). Then add boundaries.ado.area_paths
 to <project>/integrations.yml.
 ```
 
@@ -61,7 +61,7 @@ tenant-wide title-fuzzy scan in v3.7.0+.
 ## Auth (deterministic, no improvisation)
 
 ```powershell
-$cfg = Get-Content "<engagement-root>/.project-evidence/ado/config.yml" | ConvertFrom-Yaml
+$cfg = Get-Content "<workspace>/.kushi/config/shared/integrations.yml" | ConvertFrom-Yaml
 $tok = az account get-access-token `
   --resource $cfg.azDevOpsResourceId `
   --tenant $cfg.tenantId `

package/plugin/skills/pull-crm/SKILL.md

@@ -27,7 +27,7 @@ WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thor
 - `<project>` — already-resolved project name.
 - `<alias>` — current contributor.
 - `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
 - (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
 
 ## Resolution hints (pinned in mutable)
@@ -40,15 +40,15 @@ WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thor
 
 This skill is **HARD-fail** without both:
 
-1. Global config: `<engagement-root>/.project-evidence/crm/config.yml` exists with non-placeholder `environmentUrl`.
+1. Global config: `<workspace>/.kushi/config/shared/integrations.yml` exists with non-placeholder `environmentUrl`.
 2. Per-project boundary: `<engagement-root>/<project>/integrations.yml#boundaries.crm.record_ids` OR `boundaries.crm.request_ids` is non-empty.
 
 If either is missing, refuse with the exact message:
 
 ```
 crm-config-missing — drop a filled config.yml at
-<engagement-root>/.project-evidence/crm/config.yml. See template at
-plugin/templates/init/crm-config.template.yml. Then add boundaries.crm.record_ids
+<workspace>/.kushi/config/shared/integrations.yml. See template at
+plugin/templates/init/integrations.template.yml (crm: block). Then add boundaries.crm.record_ids
 (or request_ids) to <project>/integrations.yml.
 ```
 
@@ -195,7 +195,7 @@ If a week file already exists, MERGE (dedupe by event ID, append new events, kee
 
 ## Tools (in order)
 
-1. **Dataverse REST Web API** (preferred for snapshot — gives explicit `$select` + `$expand` control) via `az account get-access-token` against the configured tenant. Read connection from `<engagement-root>/.project-evidence/crm/config.yml`.
+1. **Dataverse REST Web API** (preferred for snapshot — gives explicit `$select` + `$expand` control) via `az account get-access-token` against the configured tenant. Read connection from `<workspace>/.kushi/config/shared/integrations.yml`.
 2. **WorkIQ** — only when REST is unavailable; phrase queries to demand verbatim long-text + every annotation (see Step B template above). WorkIQ summarizes by default, so use this path only as fallback.
 3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
 4. **Ask user** — paste verbatim source content if all above fail.

package/plugin/skills/pull-email/SKILL.md

@@ -26,7 +26,7 @@ Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + aut
 - `<project>` — already-resolved project name.
 - `<alias>` — current contributor.
 - `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
 - (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
 
 ## Resolution hints (pinned in mutable)
@@ -43,7 +43,7 @@ This skill REFUSES to query unless `<engagement-root>/<project>/integrations.yml
 - `boundaries.email.subject_keywords` — optional narrowing.
 - `boundaries.date_window_days` — defaults to 30 if absent.
 
-Every WorkIQ ask, every `m365_search_emails` / `m365_list_emails` call, every Graph fallback MUST be scoped to those mailboxes + (if set) sender_domains + subject_keywords. Empty hits inside the boundary → write Coverage Notes citing the limiting key; do NOT widen the scope.
+Every WorkIQ ask MUST be scoped to those mailboxes + (if set) sender_domains + subject_keywords. Empty hits inside the boundary → write Coverage Notes citing the limiting key; do NOT widen the scope. (`m365_search_emails` / `m365_list_emails` / any Graph call is FORBIDDEN per `workiq-only.instructions.md`; on WorkIQ failure, write a deferred-retry marker per `deferred-retry-on-workiq-fail.instructions.md` and continue.)
 
 Refusal message when boundary is missing:
 

package/plugin/skills/pull-meetings/SKILL.md

@@ -30,7 +30,7 @@ Auth + retry + error logging per `auth-and-retry.instructions.md`. WorkIQ-only p
 - `<project>` — already-resolved project name.
 - `<alias>` — current contributor.
 - `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints (`calendarContext.subjectKeywords`, `calendarContext.knownSeries`).
+- (read) `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints (`calendarContext.subjectKeywords`, `calendarContext.knownSeries`).
 
 ## Discovery (snapshot pass — WorkIQ ONLY per `workiq-only.instructions.md`)
 

package/plugin/skills/pull-onenote/scripts/recapture-section-url.mjs

@@ -49,7 +49,8 @@ if (!PROJECT || !ENGAGEMENT_ROOT) {
   process.exit(2);
 }
 
-const REG_PATH = path.join(ENGAGEMENT_ROOT, '.project-evidence', 'm365', 'm365-mutable.json');
+const WORKSPACE = args.workspace || process.cwd();
+const REG_PATH = path.join(WORKSPACE, '.kushi', 'config', 'user', 'm365-mutable.json');
 if (!fs.existsSync(REG_PATH)) {
   console.error(`[recapture-section-url] Registry not found: ${REG_PATH}`);
   process.exit(3);

package/plugin/skills/pull-onenote/write-snapshot.mjs

@@ -54,7 +54,8 @@ const TIMEOUT_MS = args.timeout || '120000';
 const PROJECT = args.project;
 const ROOT = args['engagement-root'];
 const ALIAS = args.alias || 'ushak';
-const MUTABLE_PATH = args.mutable || path.join(ROOT || '.', '.project-evidence', 'm365', 'm365-mutable.json');
+const WORKSPACE = args.workspace || process.cwd();
+const MUTABLE_PATH = args.mutable || path.join(WORKSPACE, '.kushi', 'config', 'user', 'm365-mutable.json');
 
 if ((!JSON_PATH && !SECTION_URL) || !PROJECT || !ROOT) {
   console.error('Usage: (--json <runner-output> | --section-url <url>) --project <name> --engagement-root <root> [--alias ushak] [--mutable <path>] [--timeout 120000]');

package/plugin/skills/pull-sharepoint/SKILL.md

@@ -28,7 +28,7 @@ Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + aut
 - `<project>` — already-resolved project name.
 - `<alias>` — current contributor.
 - `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
 - (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
 
 ## Resolution hints (pinned in mutable)

package/plugin/skills/pull-teams/SKILL.md

@@ -28,7 +28,7 @@ Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + aut
 - `<project>` — already-resolved project name.
 - `<alias>` — current contributor.
 - `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
+- (read) `<workspace>/.kushi/config/user/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
 - (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
 
 ## Resolution hints (pinned in mutable)

package/plugin/skills/refresh-project/SKILL.md

@@ -8,7 +8,7 @@ description: "Incremental refresh for an already-bootstrapped project. Reads run
 
 > **Verbatim-by-default**: This orchestrator MUST dispatch every enabled `pull-<source>` skill whose boundary in `integrations.yml#boundaries.<source>` is satisfied. Skipping a source silently is a defect. See `verbatim-by-default.instructions.md`.
 >
-> **Discover once, consume deterministically**: Refresh MUST read canonical M365 IDs from `<engagement-root>/.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>` and pass them verbatim into each `pull-*`'s index-extractor query. **Refresh never re-discovers.** If the project entry is missing or a per-source key is empty, re-dispatch through `bootstrap-project` for that source's discovery only, then resume. See `m365-id-registry.instructions.md`.
+> **Discover once, consume deterministically**: Refresh MUST read canonical M365 IDs from `<workspace>/.kushi/config/user/m365-mutable.json#knownSections.<projectKey>` and pass them verbatim into each `pull-*`'s index-extractor query. **Refresh never re-discovers.** If the project entry is missing or a per-source key is empty, re-dispatch through `bootstrap-project` for that source's discovery only, then resume. See `m365-id-registry.instructions.md`.
 >
 > **Per-user refresh report REQUIRED**: At end of run, write `<project>/Evidence/<alias>/refresh-reports/<YYYY-MM-DD-HHmm>_refresh.md` per `run-reports.instructions.md`. Even on a no-op run. Cite the registry: `Resolved IDs sourced from m365-mutable.json#knownSections.<projectKey>`.
 >
@@ -50,6 +50,26 @@ Profile is read from `kushi-install.json#profile` next to the agent file. Defaul
   - Else if `sources.<src>.watermark` exists → use `(watermark, today)`.
   - Else (first refresh after bootstrap, or new source) → fallback to `last 7 days`.
 
+### Step 2a — Drain deferred-retry queue (REQUIRED, kushi v4.4.1+, per `deferred-retry-on-workiq-fail.instructions.md`)
+
+**Before per-source dispatch**, drain any markers that previous runs deferred. The queue lives at:
+
+```
+<engagement-root>/<project>/Evidence/<alias>/_deferred-retries/*.yml
+```
+
+For each marker (chronological order):
+
+1. Load the YAML marker. Parse `source`, `target`, `window`, `workiq.command`.
+2. Re-issue the canonical WorkIQ query (NOT the doubled-strict — give the first prompt another chance first; if it fails, then doubled-strict).
+3. If success → write the artifact to its canonical `Evidence/<alias>/<source>/{snapshot,stream}/` path per the source's normal write rules. Delete the marker. Append a `drained:` entry to the refresh report's `## Deferred-retry drain` section.
+4. If failure → increment `attempts`, update `last_attempt_at`, leave marker in place. Append a `still-deferred:` entry to the report.
+5. If `attempts >= 5` after this run → also promote to a row in `<project>/OPEN-QUESTIONS-DRAFT.md` (or `State/09_open-questions.md` on `full` profile) per the doctrine's escalation rule.
+
+**NEVER call `m365_get_*` / Graph as a fallback during drain.** A drain failure is just another deferral.
+
+After drain, proceed to Step 2 even if some markers remain — the orchestrator never blocks on deferred-retry failures.
+
 ### Step 2 — Per-source dispatch
 
 For each enabled source (or just the requested one), call its `pull-<source>` skill with the effective window.

package/plugin/skills/self-check/run.ps1

@@ -616,7 +616,7 @@ if ($Deep) {
     if (-not (Test-Path $layoutInst)) {
         Add-Finding D14 'Evidence layout' 'warning' "plugin/instructions/evidence-layout-canonical.instructions.md is missing" "Restore the canonical-layout doctrine from kushi v3.12.1." $layoutInst 0
     }
-    $allowedSiblings = @('Evidence','State','Reports','.kushi','.kushi-reference','.project-evidence','.vscode','.git')
+    $allowedSiblings = @('Evidence','State','Reports','.kushi','.kushi-reference','.vscode','.git')
     $sourceTokens = @(
         'email-context','email-summary','email-summaries',
         'teams-context','teams-summary','teams-summaries',
@@ -655,6 +655,29 @@ if ($Deep) {
             }
         }
     }
+
+    # D15: legacy path regression guard — no `.project-evidence/{m365,crm,ado}` refs outside CHANGELOG/learnings.
+    # v4.4.0+ moved per-user config to `<workspace>/.kushi/config/{user,shared}/`. Any plugin/docs file
+    # still referencing the legacy `<engagement-root>/.project-evidence/(m365|crm|ado)` path will mislead
+    # skills and authors. CHANGELOG and learnings/ legitimately mention the legacy path for history.
+    $legacyPattern = '\.project-evidence[\\/](?:m365|crm|ado)'
+    $legacyTargets = @(
+        (Join-Path $Root 'plugin'),
+        (Join-Path $Root 'docs')
+    )
+    foreach ($target in $legacyTargets) {
+        if (-not (Test-Path $target)) { continue }
+        $legacyHits = Get-ChildItem -Path $target -Recurse -File -Include '*.md','*.ps1','*.mjs','*.json','*.yml','*.yaml' -ErrorAction SilentlyContinue |
+            Where-Object { $_.FullName -notmatch '[\\/]learnings[\\/]' -and $_.Name -ne 'CHANGELOG.md' } |
+            Select-String -Pattern $legacyPattern -ErrorAction SilentlyContinue
+        foreach ($m in $legacyHits) {
+            # Allow lines that explicitly mark as historical breadcrumb (contain "legacy" or "v4.4.0+" or "was")
+            if ($m.Line -match '(?i)\blegacy\b|v4\.4\.0\+|\bwas\b|\breplaces?\b|\bdeprecated\b|\bhistorical\b') { continue }
+            $msg  = 'Legacy .project-evidence/{m365|crm|ado} reference — v4.4.0+ moved per-user config to <workspace>/.kushi/config/{user,shared}/'
+            $fix  = "Replace with the new path; if intentionally documenting history, add the word 'legacy' or 'v4.4.0+ replaces' on the same line."
+            Add-Finding D15 'Legacy paths' 'warning' $msg $fix $m.Path $m.LineNumber
+        }
+    }
 }
 
 # === Output ===

package/plugin/templates/ado-update/integrations-ado-writes.example.yml

@@ -4,7 +4,7 @@
 # read from the SAME integrations.yml that pull-ado already uses — no separate config file.
 #
 # Global ADO connection (tenantId, organization, apiVersion, auth) lives at:
-#   <engagement-root>/.project-evidence/ado/config.yml
+#   <workspace>/.kushi/config/shared/integrations.yml
 # Do NOT duplicate those keys here.
 
 ado:

package/plugin/templates/init/azuredevops.template.json

@@ -0,0 +1,159 @@
+{
+  "azureDevOps": {
+    "organizationUrl": "https://dev.azure.com/IndustrySolutions",
+    "project": "IS Engagements",
+    "apiVersion": "7.1",
+    "resource": "499b84ac-1321-427f-aa17-267ca6975798",
+    "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
+    "allowedTenantIds": [
+      "72f988bf-86f1-41af-91ab-2d7cd011db47"
+    ],
+    "workItemTypes": {
+      "engagement": "Engagement",
+      "activity": "Activity"
+    },
+    "queryTemplates": {
+      "engagementByExactTitle": "SELECT [System.Id], [System.Title], [System.State], [System.ChangedDate] FROM WorkItems WHERE [System.TeamProject] = '@project' AND [System.WorkItemType] = '@engagementType' AND [System.Title] = '@title' ORDER BY [System.ChangedDate] DESC",
+      "engagementByPartialTitle": "SELECT [System.Id], [System.Title], [System.State], [System.ChangedDate] FROM WorkItems WHERE [System.TeamProject] = '@project' AND [System.WorkItemType] = '@engagementType' AND [System.Title] CONTAINS '@titlePart' ORDER BY [System.ChangedDate] DESC",
+      "activityByParentEngagementId": "SELECT [System.Id], [System.Title], [System.State], [System.ChangedDate] FROM WorkItems WHERE [System.TeamProject] = '@project' AND [System.WorkItemType] = '@activityType' AND [System.Parent] = @engagementId ORDER BY [System.ChangedDate] DESC"
+    },
+    "fieldMappings": {
+      "common": {
+        "id": "System.Id",
+        "title": "System.Title",
+        "state": "System.State",
+        "assignedTo": "System.AssignedTo",
+        "tags": "System.Tags",
+        "changedDate": "System.ChangedDate",
+        "parent": "System.Parent",
+        "historyWrite": "System.History"
+      },
+      "activity": {
+        "activityType": "Custom.activity_type",
+        "goal": "Custom.activity_goal",
+        "successCriteria": "Custom.activity_successcriteria",
+        "startDate": "Custom.activity_startdate",
+        "endDate": "Custom.activity_enddate",
+        "rrStatus": "Custom.activity_rr_status",
+        "rr1Type": "Custom.activity_rr1_type",
+        "assignedResource1": "Custom.AssignedResource1",
+        "rrStartDate1": "Custom.RRStartDate1",
+        "rrEndDate1": "Custom.RREndDate1",
+        "rr2Type": "Custom.activity_rr2_type",
+        "assignedResource2": "Custom.AssignedResource2",
+        "rrStartDate2": "Custom.RRStartDate2",
+        "rrEndDate2": "Custom.RREndDate2",
+        "country": "Custom.Country"
+      },
+      "engagement": {
+        "_comment_status": "Confirm exact engagement status field reference name",
+        "status": "System.State",
+        "_comment_customer": "Confirm exact customer/account field reference name",
+        "customer": "",
+        "_comment_primaryLead": "Confirm exact engagement owner/lead field reference name",
+        "primaryLead": "System.AssignedTo",
+        "_comment_joinKeyIsCrmOpportunityGuid": "Confirm this field exists in this process template",
+        "isCrmId": "Custom.ISCRMID",
+        "_comment_msxOpportunityId": "Optional if available in your process template",
+        "msxOpportunityId": "Custom.MSXOpportunityID"
+      },
+      "discussion": {
+        "_comment_historyRead": "History is available as revisions; confirm whether dedicated comments API should be the primary read path",
+        "historyWrite": "System.History",
+        "useCommentsApiRead": true,
+        "useCommentsApiWrite": false
+      }
+    },
+    "joinMapping": {
+      "crmToAdo": {
+        "primary": "Custom.ISCRMID",
+        "secondary": "System.Title"
+      }
+    },
+    "activity": {
+      "activityTypeField": "Custom.activity_type",
+      "advisoryValue": "Advisory",
+      "defaultState": "02 Active",
+      "defaultTags": "#FDE; #recon"
+    },
+    "queries": {
+      "maxSearchResults": 10,
+      "partialMatchEnabled": true,
+      "partialMatchMinScore": 0.6,
+      "searchFields": [
+        "System.Title",
+        "System.Tags"
+      ],
+      "defaultOrderBy": "[System.ChangedDate] DESC"
+    },
+    "linking": {
+      "preferredModel": "System.Parent",
+      "fallbackAllowed": false,
+      "allowPartialMatchSelection": true,
+      "candidateLimit": 5
+    },
+    "discussion": {
+      "mode": "history",
+      "sourceOfTruthForTranscriptUpdates": true,
+      "writeTarget": "pending-decision",
+      "contextReadSources": [
+        "engagement",
+        "activity",
+        "allChildren"
+      ],
+      "includeTranscriptSource": true,
+      "maxEntryChars": 8000,
+      "dedupe": {
+        "enabled": true,
+        "keyPattern": "meetingDate|transcriptId",
+        "includeWorkItemId": true
+      },
+      "template": {
+        "header": "Meeting Update",
+        "sections": [
+          "MeetingDate",
+          "Participants",
+          "Summary",
+          "Decisions",
+          "Actions",
+          "Risks",
+          "TranscriptSource"
+        ]
+      }
+    },
+    "contextRead": {
+      "dualSource": true,
+      "preferAdoDiscussion": true,
+      "includeCrmDuringMigration": true,
+      "childWorkItemDiscovery": {
+        "enabled": true,
+        "includeAllChildren": true,
+        "includeChildDiscussions": true,
+        "preferredChildTypeForExecution": "Activity",
+        "preferredActivityTypeValue": "Advisory"
+      },
+      "precedence": [
+        "ado.engagement.discussion",
+        "ado.children.discussion",
+        "ado.activity.discussion",
+        "ado.engagement",
+        "ado.children",
+        "ado.activities",
+        "crm.profile",
+        "crm.notes",
+        "transcript.unposted",
+        "external.docs"
+      ]
+    },
+    "validation": {
+      "requireExplicitSelectionOnAmbiguousMatch": true,
+      "requiredFieldsOnCreate": [
+        "System.Title",
+        "Custom.activity_type"
+      ],
+      "requiredFieldsOnLink": [
+        "System.Parent"
+      ]
+    }
+  }
+}