kushi-agents 4.4.3 → 4.7.4

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

@@ -20,7 +20,7 @@ This skill **never** writes to `State/`. It only writes to `Evidence/`.
 
 1. **Resolve project** — fuzzy-match against `m365-mutable.json knownSections` -> `active_projects` -> `<engagement-root>` subfolders.
 2. **Resolve window** — default = since last `aggregate`/`refresh`/`bootstrap` watermark in `Evidence/run-log.yml`; fallback 7 days if no watermark.
-3. **Pull each enabled source in turn** (`pull-email`, `pull-teams`, `pull-meetings`, `pull-onenote`, `pull-sharepoint`, `pull-crm`, `pull-ado`) — each writes its own snapshot/ + stream/ files under `Evidence/<alias>/<source>/`.
+3. **Pull each enabled source in turn** (`pull-email`, `pull-teams`, `pull-meetings`, `pull-onenote`, `pull-loop`, `pull-sharepoint`, `pull-crm`, `pull-ado`) — each writes its own snapshot/ + stream/ files under `Evidence/<alias>/<source>/`. **After each pull, run the verification gate** per `..\..\instructions\per-source-verification-gate.instructions.md`: on first failure retry once with the same window; on second failure append a 5-field entry to `<project>/FOLLOW-UPS.md`, log `status: failed-gate` to `Evidence/run-log.yml`, and continue to the next source (never abort the whole aggregate).
 4. **Run `consolidate-evidence`** — merges all aliases' streams into `Evidence/_Consolidated/<YYYY-MM-DD>_consolidated.md`. Skip silently if only one alias exists.
 5. **Update `Evidence/run-log.yml`** — record this aggregate run, its watermark, the sources pulled, the alias that produced it.
 6. **DO NOT run `build-state`.** State/ is not the concern of this skill.
@@ -37,13 +37,25 @@ Evidence/
 │   ├── teams/{snapshot,stream}/...                          <- snapshot + stream
 │   ├── meetings/{snapshot,stream}/...
 │   ├── onenote/{snapshot,stream}/...
+│   ├── loop/{snapshot,stream}/...                            <- if enabled (v4.6.0+)
 │   ├── sharepoint/{snapshot,stream}/...
 │   ├── crm/{snapshot,stream}/...                            <- if enabled
 │   └── ado/{snapshot,stream}/...                            <- if enabled
 └── _Consolidated/
-    └── YYYY-MM-DD_consolidated.md                            <- if multi-user
+    ├── YYYY-MM-DD_consolidated.md                            <- if multi-user
+    └── ado/current-state.md                                  <- v4.5.1+ if ADO enabled
 ```
 
+### ADO consolidated current-state (v4.5.1+)
+
+When ADO is enabled for the project, after the per-user ADO snapshots/streams are written, `aggregate-project` writes a single canonical roll-up at `Evidence/_Consolidated/ado/current-state.md` containing:
+
+- **Current best discussion source per work item** — for each ADO item touched in the window, the path to the artifact whose `evidence_source_kind` (per `per-source-verification-gate.instructions.md` §2a) ranks highest in the canonical order (`comments` > `history` > `attachment-fallback` > `description-only`).
+- **Supersession log** — when a newer artifact supersedes an earlier one (e.g. comments became available after an initial attachment-fallback snapshot), the prior path is logged with a `superseded-by:` pointer.
+- **Attachment-fallback annotation** — items whose best source is `attachment-fallback` are listed in a dedicated section with the attachment path so consumers (`ask-project`, `fde-report`) can warn that discussion lives in a doc, not in comments.
+
+This roll-up lives under `_Consolidated/` per `evidence-layout-canonical.instructions.md` (HARD: no source siblings under `<project>/`). It is regenerated on every aggregate/refresh run; prior versions are not preserved.
+
 `State/` is **NOT** touched. Existing `State/*.md` files (from earlier `refresh`/`state` runs) remain unchanged.
 
 See `docs/reference/evidence-contract.md` for the full schema (filename rules, frontmatter, citation format).
@@ -70,3 +82,13 @@ See `docs/reference/evidence-contract.md` for the full schema (filename rules, f
 | Rebuild State/ only, no new pulls | `state` |
 | Capture from one source only | `pull <source>` |
 | Merge per-user streams without pulling | `consolidate` |
+
+## References (v4.4.7)
+
+- Name → ID resolution (any source) follows `..\..\instructions\fuzzy-disambiguation.instructions.md`.
+- After each per-source pull, run the gate per `..\..\instructions\per-source-verification-gate.instructions.md` (retry once → FOLLOW-UPS.md on failure).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

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

@@ -37,7 +37,7 @@ Same as `propose-ado-update`. Reads ADO connection from `<workspace>/.kushi/conf
 1. **Resolve engagement root + project** per `engagement-root-resolution.instructions.md`.
 2. Confirm `<project>/integrations.yml ado.engagement_id > 0`. If 0 → abort with the same message `propose-ado-update` uses ("ADO Initiative not yet linked").
 3. Confirm `<project>/ado-updates/<YYYY-MM-DD>/proposed.md` exists. If not → tell user to run `@Kushi propose ado <project>` first. Never fabricate a proposal.
-4. Per `azure-auth-patterns.instructions.md` — Section 1 (session pre-check) + Section 3 (ADO tenant validation, using `<workspace>/.kushi/config/shared/integrations.yml`) **must** complete green before any further step.
+4. Per `auth-and-retry.instructions.md` — Section 1 (session pre-check) + Section 3 (ADO tenant validation, using `<workspace>/.kushi/config/shared/integrations.yml`) **must** complete green before any further step.
 
 ## Steps (current preview-stub behavior)
 
@@ -102,8 +102,8 @@ After step 5 (approval), instead of step 6:
 | `proposed.md` missing | Stop. Tell user to run `@Kushi propose ado <project>` first. |
 | `integrations.yml` missing or `ado.engagement_id == 0` | Stop with same message `propose-ado-update` uses; do not prompt for an ID. |
 | `ado.writes:` block missing | Stop. Tell user to run `@Kushi propose ado <project>` first (it scaffolds the block). |
-| ADO 401 on the read-only re-fetch in step 2 | Re-acquire token once per `azure-auth-patterns.instructions.md` §4; if still 401, abort `auth-failed`. |
-| Tenant mismatch | Per `azure-auth-patterns.instructions.md` §3 — abort with the exact `az login --tenant <id>` command. |
+| ADO 401 on the read-only re-fetch in step 2 | Re-acquire token once per `auth-and-retry.instructions.md` §4; if still 401, abort `auth-failed`. |
+| Tenant mismatch | Per `auth-and-retry.instructions.md` §3 — abort with the exact `az login --tenant <id>` command. |
 | `proposal-drift` (current ADO value differs from `proposed.md` snapshot) | Show diff between live and proposed; require user to re-confirm or re-run `propose-ado-update`. |
 | `duplicate-detected` (comment fingerprint already on the work item) | Skip comment portion; continue with field if not also duplicate. |
 | Allowlist rejection | Refuse the item before approval. Tell user the field reference name is not in `integrations.yml ado.writes.allowlist.fields`. |
@@ -120,6 +120,11 @@ After step 5 (approval), instead of step 6:
 ## References
 
 - `update-ledger.instructions.md` — ledger schema, reverse-op format, write-path safety doctrine.
-- `azure-auth-patterns.instructions.md` — pre-flight, tenant validation, token reuse, 401 recovery.
+- `auth-and-retry.instructions.md` — pre-flight, tenant validation, token reuse, 401 recovery.
 - `propose-ado-update` SKILL.md — produces the `proposed.md` consumed by this skill.
 - `engagement-root-resolution.instructions.md` — resolving `<engagement-root>` and `<project>`.
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

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

@@ -162,3 +162,7 @@ Explicit triggers also accepted:
 ### Example 6 — Missing evidence
 > User: "what did Mark say in last week's call about pricing?"
 > → If no Meetings file for that week: "I don't have a meetings transcript for week of YYYY-MM-DD. Want me to pull meetings for AGCO since YYYY-MM-DD?"
+
+## References (v4.4.7)
+
+- Name → ID resolution (any source) follows `..\..\instructions\fuzzy-disambiguation.instructions.md`.

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

@@ -1,11 +1,13 @@
 ---
 name: "bootstrap-project"
-version: "2.3.1"
+version: "2.3.3"
 description: "First-time setup for a project: machine preflight, side-by-side config, engagement-root + project resolution, initial 30d snapshot+stream pull across all enabled sources. Verbatim-by-default per `verbatim-by-default.instructions.md` — every enabled source dispatched, no silent skips. CRM bootstrap discovery REQUIRED to run live Dataverse 4-step resolution before declaring disabled per `crm-bootstrap-discovery.instructions.md` (v2.3.0). Writes per-user refresh report per `run-reports.instructions.md`. Cleans stale no-match notes on resolution per `cleanup-on-resolution.instructions.md`. Builds State/ only on `full` profile. Idempotent."
 ---
 
 # Skill: bootstrap-project
 
+> **Config-root resolution (v4.7.2+)**: NEVER conclude "Kushi isn't installed" from a missing `<workspace>/.kushi/` directory. Configs may live at `<workspace>/.kushi/config/` (vscode install) OR `~/.copilot/m-skills/kushi/config/` (Clawpilot install). Always probe via `Get-KushiConfig` / `loadKushiConfig`, which walks both. See `instructions/kushi-config-root.instructions.md`. If `Get-KushiConfig -Name 'project-evidence' -Path` returns a real path, the install is fine — proceed. Do NOT prompt the user to install/overwrite `.kushi/`.
+>
 > **Verbatim-by-default**: every `pull-<source>` whose boundary is satisfied MUST be dispatched. Silent skips are defects. See `verbatim-by-default.instructions.md`.
 >
 > **Per-user bootstrap report REQUIRED**: at end of run, write `<project>/Evidence/<alias>/refresh-reports/<YYYY-MM-DD-HHmm>_bootstrap.md` per `run-reports.instructions.md`. Distinct from `<project>/bootstrap-status.md` (durable state) — this is per-user run narrative.
@@ -41,33 +43,26 @@ After every run (success or coverage-gaps), write `<project>/bootstrap-status.md
 
 ## Steps
 
-### Step 0 — Identity resolution (REQUIRED, never asks the user)
+### Step 0 — Delegate ALL onboarding questions to the `setup` skill (REQUIRED, never asks here)
 
-Per `identity-resolution.instructions.md`. Read `<workspace>/.kushi/config/user/project-evidence.yml`:
+Per `identity-resolution.instructions.md` (v4.4.5 extension). The bootstrap orchestrator **MUST NOT** itself prompt for identity, OneNote, mailbox folders, or `projects_root`. The `setup` skill owns those questions.
 
-* If `alias`, `email`, or `display_name` is missing / `<auto>` / matches a placeholder → call WorkIQ once:
-  ```
-  workiq ask -q "Who am I? Return UPN, displayName, mailNickname as JSON."
-  ```
-  Map `upn → email`, `displayName → display_name`, `mailNickname → alias` (fallback `email.split('@')[0]`).
-* Persist resolved values back to the YAML (preserve comments).
-* Echo one line: `✓ Identity: <displayName> <<UPN>> (alias=<alias>). Edit .kushi/config/user/project-evidence.yml to override.`
-* If all three are already explicit non-placeholder values → skip silently.
+1. Read `<workspace>/.kushi/config/user/project-evidence.yml#identity_status`.
+2. If it is missing, empty, `<auto>`, or any `skipped-*` value → **dispatch the `setup` skill with `--from-bootstrap <project>`** and WAIT for completion.
+   - `setup` will auto-accept the EULA, functionally verify WorkIQ via `workiq ask -q "Who am I?"`, capture identity, ask the optional OneNote / mailbox questions, mirror `projects_root`, append `<project>` to `active_projects`, and print the file-pointer footer.
+   - On `setup` completion, re-read `identity_status`. If still `skipped-*` → STOP. Print: *"Bootstrap blocked — WorkIQ unreachable. Run `@Kushi setup` once WorkIQ is up. Or manually set `identity_status: verified` in `.kushi/config/user/project-evidence.yml` to override."* Exit cleanly.
+3. If `identity_status: verified` → no-op. Bootstrap proceeds to Step 1.
 
-Hard stop if WorkIQ returns auth error or empty — print the WorkIQ sign-in hint and exit. Never fall back to asking the user.
+Bootstrap NEVER calls `workiq ask -q "Who am I?"` itself. It NEVER asks the user about OneNote, mailbox folders, or `projects_root`. Those questions live in `setup` so the user is asked at most once.
 
 ### Step 1 — Machine preflight (SETUP)
 
 Verify in order. Stop on hard failures.
 
 1. **OS + host runtime** — display OS + Node/PowerShell version. Informational.
-2. **WorkIQ install (REQUIRED, hard stop)** — read `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path`. If missing, probe known paths:
-   - `$HOME\.kushi\bin\workiq.cmd`
-   - `$env:LOCALAPPDATA\Programs\WorkIQ\workiq.cmd`
-   - `$env:ProgramFiles\WorkIQ\workiq.cmd`
-   If found, persist path. If not found, ask user for path (or to install). Test with `<workiq.cli_path> --help`. Without WorkIQ, M365 sources will all fail — STOP.
-3. **Conditional az login** — only if `<workspace>/.kushi/config/shared/integrations.yml` OR `<workspace>/.kushi/config/shared/integrations.yml` exists. Per `az-auth-conditional.instructions.md`. Soft warning on failure, never blocking.
-4. **Engagement-root resolution** — per `engagement-root-resolution.instructions.md`. Persist to `<workspace>/.kushi/config/user/project-evidence.yml engagement_root` if newly resolved.
+2. **WorkIQ install (REQUIRED, hard stop)** — already verified in Step 0 via the `setup` dispatch. Re-confirm only that `workiq.cli_path` resolves; do NOT re-prompt or re-probe the filesystem. **Do NOT probe `$HOME\.kushi\bin\` — removed in v4.4.4** because it triggered VS Code's "Allow reading external directory?" prompt even on machines where workiq was already on PATH.
+3. **Conditional az login** — only if `<workspace>/.kushi/config/shared/integrations.yml` exists with CRM/ADO blocks populated. Per `auth-and-retry.instructions.md`. Soft warning on failure, never blocking.
+4. **Engagement-root resolution** — per `engagement-root-resolution.instructions.md`. `projects_root` was already captured by `setup` in Step 0; this step only validates it points at a real directory. **Sync-pending gate (v4.5.0):** if `<workspace>/.kushi/config/user/project-evidence.yml#projects_root_status` is `syncing` or `manual-sync-pending`, refuse to continue with: *"Engagement root sync still pending. Run `@Kushi setup --resume-sync` once OneDrive finishes syncing the library."* Exit cleanly.
 
 Display SETUP summary table with ✅ / ⚙️ / ❌ / ⚠️ / ➖ markers.
 
@@ -117,6 +112,8 @@ Create the project folder structure (per `engagement-root-resolution.instruction
 
 The `State/` subtree is created **only on `full` profile**. On `standard`, only `Evidence/` is scaffolded. State files (when scaffolded) come from `templates/state/*.template.md`.
 
+**Pin hook (v4.5.0):** immediately after scaffold, per `onedrive-pin-policy.instructions.md`, extend the OneDrive pin set to cover the new folders — `<project>/integrations.yml`, `<project>/bootstrap-status.md` (after Step 7 writes it), `<project>/Evidence/<alias>/`, `<project>/Evidence/_Consolidated/` (when created), and `<project>/State/` (when scaffolded). Idempotent + additive — never unpins. Skips silently on Linux or when OneDrive isn't running. This keeps every contributor's own slice always-on-device while leaving other contributors' evidence cloud-only.
+
 ### Step 4 — Initial pull (last 30 days)
 
 **Boundaries gate** (kushi v3.7.0+, per `scope-boundaries.instructions.md`): before dispatching any `pull-*`, read `<engagement-root>/<project>/integrations.yml#boundaries` and verify each enabled source has its required boundary key populated. For sources where bootstrap can auto-populate from existing `m365-mutable.json` discovery hints (e.g. a previously-discovered `section_file_id` lands in `boundaries.onenote.section_file_ids`), do so and continue. For sources where the boundary cannot be auto-populated, write the source as **disabled** in `integrations.yml` and add a one-liner to `<project>/OPEN-QUESTIONS-DRAFT.md` (or `State/09_open-questions.md` on `full` profile) asking the user to fill the boundary and re-enable.
@@ -136,7 +133,7 @@ For each enabled source, resolve and persist the canonical lookup keys into `<wo
   "<projectKey>": {
     // OneNote (pull-onenote uses these as Step A inputs)
     "one_sectionName":         "<displayName>.one",
-    "one_sectionFileId":       "<wdsectionfileid GUID>",        // PRIMARY — verbatim into wdsectionfileid = <id>
+    "one_sectionFileId":       "<wdsectionfileid GUID>",        // PRIMARY — consumed verbatim by pull-onenote
     "one_sectionGroupId":      "<wdsectiongroupid GUID>",       // when boundary is a section group
     "one_sectionOneNoteGuid":  "<wdsectiononenoteguid GUID>",   // alternate identifier (older notebooks)
     "one_sectionPath":         "/<group>/<section>.one",        // human-readable path for run-reports
@@ -158,38 +155,57 @@ For each enabled source, resolve and persist the canonical lookup keys into `<wo
 }
 ```
 
-**OneNote discovery procedure (deterministic, follow exactly):**
+**OneNote discovery procedure (deterministic, follow exactly).**
 
-1. From `boundaries.onenote.section_names[]` or user-provided section name (e.g. `HCA.one`), run:
-   ```
-   workiq ask -q "Search Microsoft 365 OneNote for sections matching the name <name>. For each match return: section display name, wdsectionfileid, wdsectiongroupid (parent group), wdsectiononenoteguid, parentReferenceId (notebook), sourceDoc URL. Flat table, no commentary, no truncation."
+Per `workiq-onenote-query-shape.instructions.md` — the **only** WorkIQ query shape that returns OneNote data is **natural-language naming by display name**, scoped to one section in one notebook. The doctrine file lists every empirically-broken phrasing (enumeration verbs, structured-field requests, filter-syntax expressions, ID-lookup questions) in its "Forbidden phrasings" table — see that file for the canonical anti-pattern list. Drivers MUST NOT emit any of those phrasings; they fail empirically (WorkIQ punts to Graph or routes to summary mode).
+
+1. For each entry in `boundaries.onenote.section_names[]` (or the user-provided section name, e.g. `HCA`), run **one** narrow WorkIQ query per section using display names only:
    ```
-2. Extract the GUIDs from the table (the `wdsectionfileid={GUID}` and `wdsectionfileid={GUID}` markers appear inline in the cell text — parse them out; do NOT use prose summaries).
-3. Validate by re-issuing the Step A.1 enumerate query from `pull-onenote/SKILL.md` against the discovered `wdsectionfileid`. If the table has ≥ 1 page row, persist the IDs. If empty, try `wdsectiongroupid`, then `wdsectiononenoteguid`. If all three fail, write the section as `disabled` with `next_step: ask user for sourceDoc URL` and continue.
-4. Persist to `m365-mutable.json#knownSections.<projectKey>` and mirror the resolved IDs into `boundaries.onenote.section_file_ids[]` / `section_group_ids[]` in `integrations.yml`.
-5. Record one line in `bootstrap-status.md`: `OneNote: resolved wdsectionfileid=<id> via name "<name>" (N pages enumerated)`.
-6. **Browser-URL completeness gate (kushi v3.10.0+).** After persisting `one_sectionFileId`, the browser-required fields (`one_notebookSourceDoc`, `one_notebookSpoBaseUrl`, `one_sectionWebUrl`, `one_sectionName`) MUST also be present and valid. Run:
-   ```pwsh
-   node plugin/skills/pull-onenote/scripts/recapture-section-url.mjs --project <name> --engagement-root <engagement-root> --check
+   workiq ask -q "In the OneNote notebook '<NOTEBOOK DISPLAY NAME>', show me the pages in the section named '<SECTION DISPLAY NAME>'. Return a flat table with: page title, last modified, web URL. No commentary. Do not truncate."
    ```
-   If exit code = 1, dispatch the same script WITHOUT `--check` so it prompts the user to paste the section's address-bar URL from OneNote-for-Web. The script parses + persists all five fields. Re-run `--check` to confirm exit 0 before continuing to Step 4b. If the user declines to paste, mark `boundaries.onenote.disabled = true, reason = "section-url-not-captured"` in `integrations.yml`, park in Open Questions, and skip pull-onenote dispatch.
+   The notebook display name comes from `m365Auth.oneNote.defaultNotebookName` in `m365-auth.json` (persisted during `setup`). The section display name comes from `boundaries.onenote.section_names[]` in `integrations.yml`.
+2. **Parse GUIDs out of the URL fragments** in the response — the `web URL` column contains `Doc.aspx` URLs of the form `...?...&wd=target(<section>|<wdsectionfileid>/...)&...&wdpartid={GUID}{1}&wdsectionfileid={GUID}`. Extract `wdsectionfileid`, `wdpartid`, and `sourcedoc` GUIDs. Do NOT interpret prose summaries.
+3. If the table is empty or the query returns a Graph-Explorer-style punt (classified per `fallback-status-reporting.instructions.md`), mark the section `disabled = true, reason = "workiq-discovery-failed"` in `integrations.yml`, write a one-line entry in `bootstrap-status.md`, and continue. Do NOT escalate to Playwright at bootstrap time — escalation is per `workiq-onenote-query-shape.instructions.md` "When (and only when) to use Playwright" (refresh-time, opted-in, threshold-driven).
+4. Persist resolved IDs to `m365-mutable.json#knownSections.<projectKey>` per `m365-id-registry.instructions.md` and mirror into `boundaries.onenote.section_file_ids[]` / `section_group_ids[]` in `integrations.yml`.
+5. Record one line in `bootstrap-status.md`: `OneNote: resolved wdsectionfileid=<id> via natural-language query for section "<name>" in notebook "<notebook>" (N pages enumerated)`.
+6. **Browser-URL fields are OPTIONAL at bootstrap (kushi v4.7.3+).** The Playwright-required fields (`one_notebookSourceDoc`, `one_notebookSpoBaseUrl`, `one_sectionWebUrl`, `one_sectionName`) are only needed if the user has opted into the Playwright recovery fallback (`m365Auth.oneNote.playwrightFallback: true`). When opted in, run `recapture-section-url.mjs --check`; if exit 1, prompt for the address-bar URL paste. When NOT opted in, skip this gate entirely — WorkIQ-only operation does not need these fields.
 
 **SharePoint, Teams, Email, CRM, ADO** follow the same shape: bootstrap discovers and persists; refresh consumes. Per-source discovery procedures live in each `pull-*/SKILL.md`'s "Bootstrap discovery" section. Bootstrap MUST invoke each pull-*'s discovery probe with the user-supplied seed (folder name, channel name, request id, work item id), persist the resolved IDs, and only then dispatch the pull.
 
-#### Step 4b — Dispatch
+#### Step 4b — Dispatch (with verification gate after each pull)
 
-Then dispatch to each enabled per-source skill with `--window last 30 days` (each skill self-refuses if its boundary is still empty):
+Then dispatch to each enabled per-source skill with `--window last 30 days` (each skill self-refuses if its boundary is still empty). **After every dispatch**, run the per-source verification gate per `..\..\instructions\per-source-verification-gate.instructions.md`:
+
+```
+for source in [pull-email, pull-teams, pull-meetings, pull-onenote, pull-loop,
+               pull-sharepoint, pull-crm, pull-ado, pull-misc]:
+    if not enabled(source): continue
+    result = dispatch(source, --window "last 30 days")
+    gate   = run_verification_gate(source, result)
+    if gate.status == "fail":
+        retry = dispatch(source, --window "last 30 days", --retry)
+        gate2 = run_verification_gate(source, retry)
+        if gate2.status == "fail":
+            append_to_followups(<project>/FOLLOW-UPS.md, gate2)
+            append_to_runlog(<project>/Evidence/run-log.yml, source, "failed-gate")
+            append_to_tracking(gate2.process_audit_failures)
+            # do NOT abort the whole bootstrap — continue to next source
+    # next source
+```
+
+Source order (deterministic, do not reshuffle):
 
 1. `pull-email`
 2. `pull-teams`
 3. `pull-meetings`
 4. `pull-onenote`
-5. `pull-sharepoint`
-6. `pull-crm` (if enabled)
-7. `pull-ado` (if enabled)
-8. `pull-misc` (if `<project>/external-links.txt` exists with ≥ 1 non-placeholder, non-delegated link)
+5. `pull-loop` (if enabled — boundary `boundaries.loop.workspace_ids[]` populated)
+6. `pull-sharepoint`
+7. `pull-crm` (if enabled)
+8. `pull-ado` (if enabled)
+9. `pull-misc` (if `<project>/external-links.txt` exists with ≥ 1 non-placeholder, non-delegated link)
 
-Each produces snapshot/ + stream/ output per `snapshot-vs-stream.instructions.md`.
+Each produces snapshot/ + stream/ output per `snapshot-vs-stream.instructions.md`. The gate enforces: shape (snapshot/ + stream/ + verbatim/ where applicable) → per-source extras (transcript-class file for meetings, sectionId for onenote, siteId for sharepoint, chatId for teams, folders for email, engagementRecordId for crm, areaPath for ado) → process-compliance (workiq-first / verbatim-by-default / capture-learnings / run-report mention / fuzzy-disambiguation cited / cleanup-on-resolution / citation-ledger).
 
 **pull-misc bootstrap note:** if `<project>/external-links.txt` does NOT exist, scaffold it from `templates/init/external-links.template.txt` so the user has a place to paste links. Mark the source as `enabled: true, links: 0` in `integrations.yml#boundaries.misc` and skip the dispatch (nothing to fetch yet).
 
@@ -208,8 +224,9 @@ If `standard` (or `core`) → **skip this step**. Note in the run summary: *"Sta
 Per `side-by-side-config.instructions.md` "Verification" rule, list all live config files (path + size + last-write time). Show:
 - SETUP summary table
 - Side-by-side config table (templates ↔ live files)
-- Per-source pull table (snapshot count + stream weeks covered)
+- Per-source pull table (snapshot count + stream weeks covered + **gate status** [pass / retried-pass / failed-followups-written])
 - New Open Questions count
+- **Open follow-ups count** — if `<project>/FOLLOW-UPS.md` was appended to, surface the count and link to the file
 
 End with a one-liner pointing at Q&A:
 
@@ -222,4 +239,13 @@ End with a one-liner pointing at Q&A:
 - "add me to project `<name>`"
 - "I'm new to `<name>`, set me up"
 - "do it all for `<name>`" (when project has no Evidence/ folder yet)
-- "redo onboarding for `<name>`" (forces re-prompt of all config questions)
+- "redo onboarding for `<name>`" (forces re-prompt of all config questions)
+## References (v4.4.7)
+
+- Name → ID resolution (any source) follows `..\..\instructions\fuzzy-disambiguation.instructions.md`.
+- After each per-source pull, run the gate per `..\..\instructions\per-source-verification-gate.instructions.md` (retry once → FOLLOW-UPS.md on failure).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/consolidate-evidence/SKILL.md

@@ -44,4 +44,8 @@ Append a `consolidation_runs:` entry: `{ window, contributors, files_written }`.
 
 - "consolidate `<X>` last `<N>` days"
 - "merge contributors for `<X>` week of `<date>`"
-- (auto) called by refresh-project when contributors.yml lists >1 alias
+- (auto) called by refresh-project when contributors.yml lists >1 alias
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/emit-vertex/README.md

@@ -0,0 +1,37 @@
+# emit-vertex / vertex-link
+
+Two sister skills that integrate kushi with the [vertex](https://github.com/commercial-software-engineering/vertex) shared note-taking platform.
+
+| Skill | What |
+|---|---|
+| `vertex-link` | One-time mapping: kushi project → vertex repo + customer + initiative. Populates `kushi.yaml#vertex`. |
+| `emit-vertex` | Render vertex-shaped artifacts (weekly status, decisions, workshops, comms, living-doc PR proposals) from kushi Evidence/+State/. |
+
+See:
+
+- [`SKILL.md`](./SKILL.md) for the full emit contract
+- [`../vertex-link/SKILL.md`](../vertex-link/SKILL.md) for the link contract
+- [`../../instructions/vertex-emit.instructions.md`](../../instructions/vertex-emit.instructions.md) for hard doctrine
+- [`../../../docs/concepts/kushi-with-vertex.md`](../../../docs/concepts/kushi-with-vertex.md) for the user-facing concept guide
+
+## CLI quick reference
+
+```text
+# One-time
+kushi vertex-link --project <p> --vertex-repo <path>
+
+# Then any time
+kushi emit-vertex --project <p> --weekly                       # this week's status
+kushi emit-vertex --project <p> --decisions                    # ADRs from State/01_decisions.md
+kushi emit-vertex --project <p> --workshops                    # workshop write-ups
+kushi emit-vertex --project <p> --comms                        # call transcripts + chats + significant emails
+kushi emit-vertex --project <p> --living                       # PR-style diffs against living docs
+kushi emit-vertex --project <p> --all                          # everything
+
+# Add --apply to copy staged files into the vertex repo
+# Add --dry-run to skip validation + apply
+```
+
+## No vertex schema vendoring
+
+Schemas live in the vertex repo at `.vertex/scripts/validation/schemas/`. The validator is `.vertex/scripts/validation/validate_frontmatter.py`. emit-vertex detects the vertex repo via `vertex.json` and uses both in place. Kushi ships no copies.

package/plugin/skills/emit-vertex/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: "emit-vertex"
+description: "Render vertex-shaped artifacts from kushi Evidence/+State/ — weekly status, decisions, workshops, comms, living-doc PR proposals. Stages first, validates against vertex's own schemas, applies on demand."
+applyTo: ["emit-vertex"]
+version: "1.1.0"
+maturity: "preview"
+---
+
+# emit-vertex
+
+Render the artifacts that the [vertex](https://github.com/commercial-software-engineering/vertex) shared note-taking platform publishes (`<customer-slug>/<initiative-slug>/…`) from kushi's captured Evidence/ + State/ for a single kushi project.
+
+## Implementation status (as of v4.7.1)
+
+End-to-end verified against the real vertex validator + schemas (43 tests passing):
+
+- ✅ **Detect** — `plugin/lib/detect-vertex-repo.mjs` reads `vertex.json`, locates `validate_frontmatter.py`, returns repo info or named errors (`vertex-repo-not-found`, `vertex-json-missing`, `vertex-json-malformed`, `vertex-validator-missing`)
+- ✅ **Validate** — `plugin/lib/vertex-validate.mjs` invokes the real Python validator with `--base-dir` so staged files OUTSIDE the vertex repo still match the schema-mapping globs. Probes for a Python with `pyyaml` (some Windows shims advertise `python3 --version` ok but lack the module).
+- ✅ **Render** — `plugin/lib/render-vertex.mjs` produces schema-clean markdown for:
+  - `status-updates/YYYY-MM-DD.md` (type=status-update; green/yellow/red enum; required fields)
+  - `decisions/NNN-<slug>.md` (zero-padded ADR number; type=decision)
+  - `comms/call-transcripts/YYYY-MM-DD-<slug>.md` (type=call-transcript; participants list)
+  - `comms/chats/YYYY-MM-DD-<slug>.md` (type=chat)
+  - `comms/emails/YYYY-MM-DD-<slug>.md` (type=email)
+- ✅ **Multi-binding mapping** — `kushi.yaml#vertex.bindings[]` with vertex-parity targeting precedence (CLI flag > path inference > default > single > prompt)
+
+Still doctrine-only (agent follows SKILL.md, no JS helper yet):
+- Workshops, living-doc diff proposals, indicator rollups from State/ ledgers
+
+## Doctrine
+
+This skill is governed by:
+
+1. **HARD** [`vertex-emit.instructions.md`](../../instructions/vertex-emit.instructions.md) — full doctrine: hard rules, source→artifact mapping, CLI surface, failure modes
+2. **HARD** [`citation-ledger.instructions.md`](../../instructions/citation-ledger.instructions.md) — every bullet/row carries `[source: …]`
+3. **HARD** [`workiq-input-sanitization.instructions.md`](../../instructions/workiq-input-sanitization.instructions.md) — any WorkIQ touch is sanitized
+4. **HARD** [`status-color-rule.instructions.md`](../../instructions/status-color-rule.instructions.md) — 🟢🟡🔴 first-match-wins
+5. **HARD** [`studio-registry.instructions.md`](../../instructions/studio-registry.instructions.md) — distros from `plugin/config/studios.json`
+6. **HARD** [`tracking.instructions.md`](../../instructions/tracking.instructions.md) — emit writes a tracking entry
+7. **HARD** [`run-reports.instructions.md`](../../instructions/run-reports.instructions.md) — per-run report under `Evidence/<alias>/refresh-reports/`
+
+## Tools
+
+- **Vertex repo** (PRIMARY, detected via `vertex.json`) — schemas + validator used in place; no vendoring
+- **kushi Evidence/+State/** (PRIMARY) — input
+- **kushi.yaml#vertex** (PRIMARY) — mapping (`repo_path`, `customer_slug`, `initiative_slug`, `studio`)
+- **WorkIQ** (FALLBACK, only if evidence is stale and user opts in via `--refresh-first`)
+- **Playwright / Host / Graph** (NOT USED)
+
+## Pre-flight gates (must all pass before staging)
+
+| Gate | Check |
+|---|---|
+| A | `kushi.yaml#vertex.repo_path` resolves to a directory containing `vertex.json` |
+| B | `<repo>/.vertex/scripts/validation/validate_frontmatter.py` exists |
+| C | `<repo>/<customer-slug>/<initiative-slug>/` either exists OR vertex bootstrap is needed (skill surfaces with vertex's own `/bootstrap` recommendation) |
+| D | `kushi.yaml#vertex.{customer_slug, initiative_slug}` are non-empty and pass `sanitize-workiq-input` |
+| E | At least one mode flag (`--weekly`, `--decisions`, `--workshops`, `--comms`, `--living`, `--all`) |
+| F | Python 3 is on PATH (required to invoke `validate_frontmatter.py`) |
+
+Failures: see "Failure modes" table in `vertex-emit.instructions.md`. Each failure is a named, actionable code — never silent.
+
+## Phases
+
+### Phase 1 — Resolve
+
+1. Read `kushi.yaml#vertex`. If missing, exit with `vertex-mapping-incomplete` and recommend `kushi vertex-link`.
+2. Resolve `repo_path`, verify `vertex.json` exists. Read `vertex.json#version` and log it.
+3. Resolve `<repo>/<customer-slug>/<initiative-slug>/` — confirm or recommend vertex bootstrap.
+4. Determine reporting window:
+   - `--weekly` without `--week-ending` → candidate week per vertex's rule (Mon-Fri; Fri after 17:00 = current; Sat/Sun = current; else = prior). Always confirm with user.
+   - Other modes → no window (operate on all evidence).
+
+### Phase 2 — Collect
+
+1. Load `Evidence/<all-aliases>/` for the project, filtered by window if applicable.
+2. Load `State/*.md` for living docs and decisions.
+3. Load `Evidence/_Consolidated/<week>_consolidated.md` for cross-contributor view (`consolidate-evidence` is a prerequisite for `--weekly`; if missing, run it first).
+4. Run `status-color-rule` evaluator on the evidence; record `rule_id`, `triggers` with citations, `color`, `reason`.
+5. For each requested artifact mode, build the in-memory render plan.
+
+### Phase 3 — Stage
+
+For each artifact in the render plan, write to:
+
+```text
+<engagement-root>/<project>/.kushi-staging/vertex/<run-ts>/<customer-slug>/<initiative-slug>/<vertex-relative-path>
+```
+
+Living-doc proposals are written as:
+
+```text
+<staging-root>/proposals/<vertex-relative-path>.diff
+<staging-root>/proposals/<vertex-relative-path>.proposal.md
+```
+
+Every emitted file has:
+- Schema-valid frontmatter (per vertex schema for that path)
+- Body content from kushi evidence, with inline citations on every claim
+- A `Sources` section at the end (point-in-time artifacts) listing the evidence files consulted
+
+### Phase 4 — Validate
+
+For each staged file (not for `.diff`/`.proposal.md` companions):
+
+```bash
+python3 <vertex-repo>/.vertex/scripts/validation/validate_frontmatter.py <staged-file>
+```
+
+If any file fails, surface the validator output, attempt one automatic fix-up pass (re-render with stricter frontmatter from the schema), revalidate. If still failing, exit with `vertex-schema-fail` and the path + error.
+
+### Phase 5 — Apply (only with `--apply`)
+
+1. For each staged point-in-time file:
+   - If target doesn't exist → copy in.
+   - If target exists → present diff, prompt overwrite / abort / sibling-suffix. Default abort.
+2. For each staged living-doc proposal:
+   - Do NOT copy into vertex repo.
+   - Print path to the staged `.diff` + `.proposal.md` and a one-line summary.
+3. GitDoc inside the vertex repo will auto-commit any actually-copied files when the user next saves the editor (or immediately if GitDoc debounce has fired).
+
+### Phase 6 — Report
+
+Write `<engagement-root>/<project>/Evidence/<alias>/refresh-reports/<ts>_emit-vertex.md` per `run-reports.instructions.md`. Write a tracking entry per `tracking.instructions.md`. Append per-source learnings (if any) per `capture-learnings.instructions.md`.
+
+## Boundary contract
+
+- emit-vertex MUST NOT `git commit` / `git push` — GitDoc inside the vertex repo handles all version control.
+- emit-vertex MUST NOT edit living docs in place — only PR-style proposals.
+- emit-vertex MUST NOT vendor or modify vertex schemas — read them in place from the vertex repo.
+- emit-vertex MUST run `validate_frontmatter.py` before any `--apply`.
+- emit-vertex MUST NOT call WorkIQ unless the user passes `--refresh-first` (and even then, only via `pull-*` skills with full sanitization).
+
+## Outputs (canonical paths)
+
+### Point-in-time (copied to vertex repo on `--apply`)
+
+```text
+<vertex-repo>/<customer-slug>/<initiative-slug>/status-updates/<week-ending>.md
+<vertex-repo>/<customer-slug>/<initiative-slug>/comms/emails/status/<week-ending>-weekly-status.md
+<vertex-repo>/<customer-slug>/<initiative-slug>/decisions/<NNN>-<slug>.md
+<vertex-repo>/<customer-slug>/<initiative-slug>/workshops/<topic>.md
+<vertex-repo>/<customer-slug>/<initiative-slug>/comms/call-transcripts/<YYYY-MM-DD>-<slug>.md
+<vertex-repo>/<customer-slug>/<initiative-slug>/comms/chats/<YYYY-MM-DD>-<topic>.md
+<vertex-repo>/<customer-slug>/<initiative-slug>/comms/emails/<YYYY-MM-DD>-<subject>.md
+```
+
+### Living-doc proposals (NEVER copied; staged only)
+
+```text
+<staging-root>/proposals/customer-details.md.diff
+<staging-root>/proposals/customer-details.md.proposal.md
+<staging-root>/proposals/msft-stakeholders.md.diff
+<staging-root>/proposals/risk-register.md.diff
+<staging-root>/proposals/architecture-overview.md.diff
+<staging-root>/proposals/tech-stack.md.diff
+<staging-root>/proposals/initiative-overview.md.diff
+```
+
+## Tracking + reporting
+
+Per `tracking.instructions.md`, every run writes one row to `<project>/Evidence/<alias>/tracking.md` with run-ts, mode flags, files staged, files validated, files applied, files skipped, and the validator exit summary. Per-run report at `refresh-reports/<ts>_emit-vertex.md` carries the human-readable detail.
+
+## Issue recovery
+
+Per `issue-recovery.instructions.md`. emit-vertex's pre-flight failures, schema failures, and overwrite-blocked events are all named codes — recovery is mechanical.
+
+## See also
+
+- [`vertex-emit.instructions.md`](../../instructions/vertex-emit.instructions.md) — full doctrine
+- [`vertex-link/SKILL.md`](../vertex-link/SKILL.md) — sister skill that populates `kushi.yaml#vertex` mapping
+- [`docs/concepts/kushi-with-vertex.md`](../../../docs/concepts/kushi-with-vertex.md) — outcome-based user-facing guide
+- [vertex repo](https://github.com/commercial-software-engineering/vertex)

package/plugin/skills/intro/SKILL.md

@@ -110,6 +110,8 @@ Present this verbatim:
 > | | `pull-crm` | core+ | ✅ | ✅ |
 > | | `pull-ado` | core+ | ✅ | ✅ |
 > | **Consumer (Q&A)** | `ask-project` | core+ | reads both | — |
+> | **Vertex integration** | `vertex-link` | core+ | — | — |
+> | | `emit-vertex` | core+ | reads both | — |
 > | **FDE authoring** | `fde-intake` | standard+ | reads both | — |
 > | | `fde-report` | standard+ | reads both | — |
 > | | `fde-triage` | standard+ | reads both | — |

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

@@ -50,7 +50,7 @@ Refuse to produce `proposed.md` and tell the user exactly what's missing if any
 1. **Resolve config (deterministic)** — load global ADO config (tenant/org/apiVersion) + per-project `integrations.yml` (engagement_id + writes block). All from known paths above. No prompts unless `writes:` is missing.
 2. **First-run scaffold of `ado.writes:`** — if missing, append the template block to `integrations.yml ado:` (preserving every existing key). Stop. Tell user to confirm `fieldRefName` matches their tenant's process template. (Honors `side-by-side-config.instructions.md`: template stays generic, live filled file holds the real value.)
 3. **Pick the consolidated file** — most recent `<project>/Evidence/_Consolidated/<YYYY-MM-DD>_consolidated.md`. Optionally chase referenced per-source files for citations.
-4. **Read current ADO field value** (read-only GET, per `azure-auth-patterns.instructions.md` — pre-flight + tenant validation + token reuse + 401 retry):
+4. **Read current ADO field value** (read-only GET, per `auth-and-retry.instructions.md` — pre-flight + tenant validation + token reuse + 401 retry):
    ```
    GET https://dev.azure.com/{org}/{project}/_apis/wit/workitems/{engagement_id}?api-version=7.1&fields={ado.writes.statusSummary.fieldRefName},System.Rev
    ```
@@ -93,7 +93,7 @@ Refuse to produce `proposed.md` and tell the user exactly what's missing if any
 | `integrations.yml` missing | Refuse. Tell user to run `@Kushi bootstrap <project>` first. |
 | `ado.engagement_id == 0` (Initiative not linked yet) | Refuse with the message in Prerequisites table. Do NOT prompt for an ID. |
 | `ado.writes:` block missing | Scaffold from template, stop, ask user to confirm `fieldRefName`. |
-| ADO 401 on fetch | Per `azure-auth-patterns.instructions.md` §4 — re-acquire token once, retry. If still 401, abort and report `auth-failed`. |
+| ADO 401 on fetch | Per `auth-and-retry.instructions.md` §4 — re-acquire token once, retry. If still 401, abort and report `auth-failed`. |
 | ADO 404 on Initiative ID | Abort, report `initiative-not-found`. The `engagement_id` in integrations.yml is wrong; tell user to re-run pull-ado discovery or fix manually. |
 | Field reference name not present on work item type | Skip the field portion of `proposed.md`; still produce the comment portion. |
 | Latest consolidated > 8 days old | Continue but flag `stale-evidence` at top of `proposed.md`. |
@@ -102,7 +102,12 @@ Refuse to produce `proposed.md` and tell the user exactly what's missing if any
 ## References
 
 - `update-ledger.instructions.md` — write-path doctrine and ledger schema (used by `apply-ado-update`; this skill produces the `proposed.md` shape `apply-ado-update` consumes).
-- `azure-auth-patterns.instructions.md` — token acquisition, tenant validation, retry-on-401.
+- `auth-and-retry.instructions.md` — token acquisition, tenant validation, retry-on-401.
 - `side-by-side-config.instructions.md` — config template vs live filled file (here: `integrations.yml ado.writes:` block).
 - `engagement-root-resolution.instructions.md` — resolving `<engagement-root>` and `<project>`.
 - `evidence-thoroughness.instructions.md` — what counts as a citable bullet.
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

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

@@ -20,7 +20,7 @@ Pulls **ado** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 - **snapshot/** — engagement TREE: parent Engagement + every child WI; each item gets full fields + every discussion comment verbatim + full revision history
 - **stream/** — new comments + state changes + field changes + attachments across the entire tree, weekly bucket
 
-WorkIQ-first per `workiq-first.instructions.md` — but **for ADO, REST is preferred for snapshot** because WorkIQ summarizes discussion threads. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`. Tree expansion + per-item discussion + revision pulls per `ado-engagement-tree.instructions.md`.
+WorkIQ-first per `workiq-only.instructions.md` — but **for ADO, REST is preferred for snapshot** because WorkIQ summarizes discussion threads. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `evidence-thoroughness.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`. Tree expansion + per-item discussion + revision pulls per `ado-engagement-tree.instructions.md`.
 
 ## Inputs
 
@@ -239,3 +239,13 @@ After successful pass:
 - Step 1 returns zero candidates → record `no-match` + WIQL + `next_step`, stop.
 - A child WI fetch fails → mark `❌ item-fetch-failed` in `tree.md`, continue tree.
 - Discussion paging fails mid-stream → record `❌ comments-partial — N/M fetched` and continue.
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

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

@@ -20,7 +20,7 @@ Pulls **crm** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 - **snapshot/** — engagement record with EVERY field the API returns (owner, status, account, dates, custom fields), all long-text fields VERBATIM, plus every related annotation (note) verbatim
 - **stream/** — notes added, activities logged, field-level changes (old → new + actor + timestamp)
 
-WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
+WorkIQ-first per `workiq-only.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `evidence-thoroughness.instructions.md`. Citations per `citation-ledger.instructions.md`. Side-by-side mutable hints written immediately on discovery per `side-by-side-config.instructions.md`.
 
 ## Inputs
 
@@ -208,7 +208,7 @@ If a week file already exists, MERGE (dedupe by event ID, append new events, kee
 
 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`.
+3. **Graph REST** — last resort, soft-fail per `auth-and-retry.instructions.md`.
 4. **Ask user** — paste verbatim source content if all above fail.
 
 Document which path succeeded under `## Source Basis` in each output file.
@@ -237,3 +237,13 @@ After successful pass:
 - Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
 - Multiple plausible candidates → ask user to pick, persist answer.
 - All paths failed for a given record → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.