kushi-agents 3.4.2 → 3.13.0

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

@@ -1,11 +1,21 @@
 ---
 name: "bootstrap-project"
-version: "2.1.0"
-description: "First-time setup for a project: machine preflight (WorkIQ check, optional az login), side-by-side config (templates -> live filled), engagement-root + project resolution, initial 30d snapshot+stream pull across all enabled sources. Builds State/ only on the `full` profile (skipped on `standard`). Idempotent — safe to re-run."
+version: "2.3.1"
+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
 
+> **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.
+>
+> **Cleanup on resolution**: when this run resolves an ID/folder/section, prune stale `no-match` / probe-trail notes per `cleanup-on-resolution.instructions.md`.
+>
+> **Capture learnings**: any quirk / fix discovered mid-run is appended to `<KUSHI_ROOT>/plugin/learnings/<source>.md` in the same turn per `capture-learnings.instructions.md`.
+>
+> **Canonical evidence layout** (HARD, kushi v3.12.1+): every per-source artifact lands under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` and **nowhere else** under `<project>/`. Sibling folders like `<project>/email-context/`, `<project>/notes/`, `<project>/_Weekly Summaries/` are FORBIDDEN. Bootstrap MUST (a) scaffold the canonical tree, and (b) before pulling, scan `<project>/` for non-canonical source-output folders and migrate each to `Evidence/<alias>/<source>/_legacy_<original-name>_pre-bootstrap/` (move, do not delete; log under `## Layout migrations` in the bootstrap report; add a `runs:` entry with `type: layout-migration`). See `evidence-layout-canonical.instructions.md`.
+
 Run this when the user says any of: "bootstrap a new project", "set up project evidence for `<X>`", "add me to project `<X>`", "I'm new to `<X>`", "do it all for `<X>`" (and the project has no Evidence/ folder yet).
 
 ## Profile-aware behavior
@@ -17,6 +27,10 @@ This skill is **profile-aware** as of Kushi v3.3.0:
 
 The active profile is read from `kushi-install.json#profile` next to this agent file. If absent, default to `standard`.
 
+## Bootstrap-status artifact
+
+After every run (success or coverage-gaps), write `<project>/bootstrap-status.md` per the format contract in `instructions/bootstrap-status-format.instructions.md`. This is the project's fast-orientation artifact — required tables, normalized status vocabulary (`resolved`, `populated`, `unsynced`, `degraded-list-only`, `throttled-tooManyRequests`, `ado-not-complete`, `completed-with-coverage-gaps`), one-line final status. Do NOT inline run history here; that goes in `update-status.md`.
+
 ## Inputs
 
 - `<project>` — engagement name (fuzzy-matched per `engagement-root-resolution.instructions.md`).
@@ -62,6 +76,8 @@ Optional (only if user enables CRM/ADO):
 | `<engagement-root>/.project-evidence/crm/config.yml` | `templates/init/crm-config.template.yml` |
 | `<engagement-root>/.project-evidence/ado/config.yml` | `templates/init/ado-config.template.yml` |
 
+**Boundaries upgrade for existing projects (v3.7.0+):** If `<engagement-root>/<project>/integrations.yml` already exists but has no top-level `boundaries:` key, append the scaffolded `boundaries:` block from `templates/init/project-integrations.template.yml` (preserving every existing key). Then proceed to Step 4 to populate it.
+
 ### Step 3 — Project folder scaffold
 
 Create the project folder structure (per `engagement-root-resolution.instructions.md`):
@@ -85,7 +101,66 @@ The `State/` subtree is created **only on `full` profile**. On `standard`, only
 
 ### Step 4 — Initial pull (last 30 days)
 
-Dispatch to each enabled per-source skill with `--window 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.
+
+For CRM and ADO additionally verify the global config files exist (`<engagement-root>/.project-evidence/{crm,ado}/config.yml`) with non-placeholder values; if missing, scaffold from `templates/init/{crm,ado}-config.template.yml` and park in Open Questions with the path and template reference. **Do NOT auto-improvise** by inferring a tenant/org or by narrating CRM evidence from email — both are explicit anti-patterns in v3.7.0.
+
+**CRM discovery is REQUIRED before declaring `disabled` (kushi v3.11.0+, per `crm-bootstrap-discovery.instructions.md`).** If `<engagement-root>/.project-evidence/crm/config.yml` exists and `az` auth succeeds, bootstrap MUST run the full 4-step Dataverse REST resolution sequence from `pull-crm/SKILL.md#resolution-order-when-crmrecordid-is-unset` (title-first → all matching accounts → wide-text → recent-slice → ask user) against the live endpoint before writing `boundaries.crm.disabled: true`. Any other path that sets `disabled: true` is a defect. If steps 1–4 all return 0, present the top 5 candidates from step 4 to the user before final disposition. Log the full attempt trail (queries + counts + outcome) to the bootstrap refresh-report under `## CRM resolution attempts`. If auth fails or Dataverse is unreachable, leave the boundary empty with `reason: 'crm-auth-unavailable-<date>'` — NOT `disabled: true` — so the next refresh retries.
+
+#### Step 4a — Discovery & registry persistence (REQUIRED, kushi v3.7.8+, per `m365-id-registry.instructions.md`)
+
+**Doctrine: bootstrap discovers, refresh consumes.** Bootstrap is the ONLY phase that probes WorkIQ to resolve canonical M365 identifiers. Refresh runs MUST read these from `m365-mutable.json#knownSections.<project>` and pass them into the index extractor verbatim. Refresh must NEVER re-discover — that is the source of "OneNote works for me sometimes" non-determinism.
+
+For each enabled source, resolve and persist the canonical lookup keys into `<engagement-root>/.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>`. The schema is fixed — populate every key the source supports:
+
+```jsonc
+"knownSections": {
+  "<projectKey>": {
+    // OneNote (pull-onenote uses these as Step A inputs)
+    "one_sectionName":         "<displayName>.one",
+    "one_sectionFileId":       "<wdsectionfileid GUID>",        // PRIMARY — verbatim into wdsectionfileid = <id>
+    "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
+    "one_notebookSourceDoc":   "<notebook sourceDoc GUID>",     // parentReferenceId fallback
+    // Email
+    "emailContext":            "Inbox/<folder-path>",
+    // Teams
+    "teamsChatContext": {
+      "chatHints":         ["..."],   // exact chat topics
+      "channelHints":      ["..."],   // exact channel display names
+      "participantHints":  ["..."]    // exact display names
+    },
+    // SharePoint (when boundary is a SP site/library/folder)
+    "sp_siteId":   "<siteId>",
+    "sp_webId":    "<webId>",
+    "sp_listId":   "<listId>",
+    "sp_path":     "/<site>/<library>/<folder>"
+  }
+}
+```
+
+**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."
+   ```
+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
+   ```
+   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.
+
+**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
+
+Then dispatch to each enabled per-source skill with `--window last 30 days` (each skill self-refuses if its boundary is still empty):
 
 1. `pull-email`
 2. `pull-teams`
@@ -94,9 +169,12 @@ Dispatch to each enabled per-source skill with `--window last 30 days`:
 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)
 
 Each produces snapshot/ + stream/ output per `snapshot-vs-stream.instructions.md`.
 
+**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).
+
 ### Step 5 — Consolidate (single contributor = no-op)
 
 If multiple contributors already exist, dispatch `consolidate-evidence`. For first-time bootstrap (one user), skip.

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

@@ -0,0 +1,108 @@
+---
+name: "propose-ado-update"
+version: "0.1.0-preview"
+status: "preview"
+description: "Read-only generator: reads the latest <project>/Evidence/_Consolidated/ and produces <project>/ado-updates/<YYYY-MM-DD>/proposed.md — a Markdown preview of the proposed ADO Initiative updates (FDE Status Summary field + Discussion comment). Performs NO writes to ADO. Safe to run unattended on the same Monday-9am schedule as refresh."
+---
+
+# Skill: propose-ado-update
+
+Run this when the user says any of: "propose ado update for `<X>`", "what would kushi write to ADO for `<X>`", "ado preview `<X>`", "draft ado update `<X>`".
+
+This skill is **read-only**. It reads the most recent consolidated evidence and produces a Markdown file the user can review. It does **not** call ADO. Apply happens in the separate `apply-ado-update` skill, which is gated.
+
+## Profile
+
+Belongs to the **`preview`** profile. Not present in `core` / `standard` / `full`. Opt in via `npx kushi-agents --clawpilot --profile preview`.
+
+## Deterministic config — do not invent paths
+
+This skill does **NOT** create a new top-level config file. It reads from the configs Kushi already maintains:
+
+| What | Where | Maintained by |
+|---|---|---|
+| ADO tenant + org + apiVersion + auth strategy | `<engagement-root>/.project-evidence/ado/config.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>` ← `~/.copilot/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`.
+5. `<project>/Evidence/_Consolidated/<latest>_consolidated.md` — REQUIRED input. Never re-aggregate.
+
+## Prerequisites (HARD — do not bypass)
+
+Refuse to produce `proposed.md` and tell the user exactly what's missing if any of these fail:
+
+| Prereq | Failure message |
+|---|---|
+| `<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`." |
+| 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`. |
+
+## Steps
+
+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):
+   ```
+   GET https://dev.azure.com/{org}/{project}/_apis/wit/workitems/{engagement_id}?api-version=7.1&fields={ado.writes.statusSummary.fieldRefName},System.Rev
+   ```
+   If field reference name not on the work item → record `field-not-found` in `proposed.md` and skip the field portion. Don't fail the run.
+5. **Distill the field update**:
+   - Format: `<MMM YYYY>: <one-liner ≤ 140 chars>`. Source: TL;DR / first-paragraph / explicit "summary" line in the consolidated file.
+   - Apply `strategy` (`append-month` default, `replace`, or `rolling-6`) to the value fetched in step 4.
+   - Compute the proposed new value locally; record `currentValue`, `proposedValue`, `revFetched` for the apply step's optimistic-lock guard.
+6. **Distill the Discussion comment**:
+   - Render `<KUSHI_ROOT>/plugin/templates/ado-update/discussion-comment.template.md` with sections: TL;DR, Decisions this week, Action items (owner + due), Risks/blockers, Asks, Evidence pack.
+   - Every bullet **must** carry a citation from the consolidated file (`[source: <path> · <date>]`). No bullet without a citation.
+   - End with the Kushi fingerprint line (used by `apply-ado-update` to detect duplicates):
+     ```
+     — Generated by Kushi v<version> · proposed <YYYY-MM-DD> · ledger:ado-updates/<YYYY-MM-DD>/ledger.jsonl
+     ```
+7. **Score confidence** per item (`high` / `medium` / `low`):
+   - `high` — explicit verbatim source quote, single source, recent (≤ this consolidated window).
+   - `medium` — paraphrased or aggregated from 2–3 sources.
+   - `low` — inferred, conflicting sources, or older than this window.
+8. **Write `proposed.md`** to `<engagement-root>/<project>/ado-updates/<YYYY-MM-DD>/proposed.md` from `<KUSHI_ROOT>/plugin/templates/ado-update/proposed.template.md`.
+9. **Echo summary** to user with path to `proposed.md` and one-line stats footer (`1 field, 1 comment, 7 cited bullets, 5 high / 2 medium / 0 low confidence`).
+
+## 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 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`).
+
+## Outputs
+
+- `<engagement-root>/<project>/ado-updates/<YYYY-MM-DD>/proposed.md` — the human-reviewable proposal.
+- (No state file changes, no ledger writes, no ADO writes.)
+
+## Failure modes
+
+| Symptom | Recovery |
+|---|---|
+| `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 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`. |
+| No `_Consolidated/` files at all | Refuse. Tell user to run `@Kushi refresh <project>` then `consolidate` first. |
+
+## 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.
+- `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.

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

@@ -1,23 +1,34 @@
 ---
 name: "pull-ado"
-version: "2.0.0"
-description: "Pull ADO evidence (snapshot: work-item fields; stream: comments + state changes + history). Conditional az login per az-auth-conditional rule."
+version: "2.3.1"
+description: "Pull ADO evidence as an engagement TREE (parent Engagement + every child WI). Per-item discussion comments + revision history (verbatim). Deterministic resolution; no parent-only summaries. Per ado-engagement-tree.instructions.md."
 ---
 
 # Skill: pull-ado
 
+
+> **v3.7.6 contracts** — This skill operates under four HARD-rule doctrines:
+> - `verbatim-by-default.instructions.md` — full bodies/notetext/fields by default; no preview-grade pulls accepted.
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md` immediately.
+> - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale `no-match` / `not yet` notes referencing the prior unresolved state must be rewritten in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/YYYY-MM-DD-HHMM_refresh.md`.
+
+> **Canonical evidence layout** (HARD, kushi v3.12.1+): all artifacts produced by this skill MUST be written under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` — sibling folders under `<project>/` (e.g. `<project>/<source>-context/`, `<project>/<source>/`, `<project>/_Weekly Summaries/`) are FORBIDDEN. See `evidence-layout-canonical.instructions.md`.
+
 Pulls **ado** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
-- **snapshot/** — work item with all fields (title, type, area, iteration, parent, state, assignee, custom fields)
-- **stream/** — comments verbatim + state changes (old → new) + field changes + attachments — per work item
+- **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`. 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-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`.
 
 ## Inputs
 
 - `<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) `<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) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
 
@@ -27,30 +38,162 @@ WorkIQ-first per `workiq-first.instructions.md`. Thoroughness per `evidence-thor
 - `ado.queryId` — saved query ID for the project
 - `ado.areaPath` / `ado.iterationPath` — for filtering
 
-## Snapshot pass
+## Hard prerequisites (REQUIRED — see `scope-boundaries.instructions.md` Rule 3)
+
+This skill is **HARD-fail** without both:
+
+1. Global config: `<engagement-root>/.project-evidence/ado/config.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
+to <project>/integrations.yml.
+```
+
+Discovery loops (`title_contains`, `tags_contains`, `custom_iscrm_id`) are still
+permitted — but ONLY inside `boundaries.ado.area_paths`. There is no
+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
+$tok = az account get-access-token `
+  --resource $cfg.azDevOpsResourceId `
+  --tenant $cfg.tenantId `
+  --query accessToken -o tsv
+$h = @{ Authorization = "Bearer $tok"; 'Content-Type' = 'application/json' }
+$org  = $cfg.organization               # e.g. https://dev.azure.com/IndustrySolutions
+$proj = $cfg.defaultProject             # e.g. "IS Engagements"
+$projUrl = "$org/$([uri]::EscapeDataString($proj))"
+```
+
+If `az account get-access-token` returns nothing → ask user to `az login --tenant <tenantId>` and stop. Do NOT silently proceed.
+
+## Step 1 — Resolve the Engagement WI ID (deterministic order)
+
+Per `ado-engagement-tree.instructions.md` § Resolution order:
+
+### 1a — Pinned ID
+
+If `<project>/integrations.yml#ado.engagement_id` is non-null, use it. Skip to Step 2.
+
+### 1b — Pinned query
+
+If `ado.queryId` is set:
+
+```powershell
+$q = Invoke-RestMethod -Headers $h -Uri "$projUrl/_apis/wit/wiql/$($cfg.ado.queryId)?api-version=7.1"
+```
+
+Take the single `Engagement`-typed row. If multiple → ask user, persist choice.
+
+### 1c — Bounded WIQL
+
+Build the WIQL ONLY inside `boundaries.ado.area_paths`:
+
+```sql
+SELECT [System.Id],[System.Title],[System.WorkItemType],[System.State],
+       [System.AreaPath],[System.IterationPath],[System.Tags],[System.AssignedTo],
+       [System.Parent],[System.CreatedDate],[System.ChangedDate]
+FROM workitems
+WHERE [System.TeamProject] = '<defaultProject>'
+  AND [System.WorkItemType] = 'Engagement'
+  AND [System.AreaPath] UNDER '<area_path>'
+  AND ([System.Title] CONTAINS '<project>' OR
+       [Custom.ISCRMRequestId] = '<crm.request_id>' OR
+       [System.Tags] CONTAINS '<project>')
+  AND [System.CreatedDate] > '<2-years-ago>'
+  AND [System.State] <> 'Removed'
+ORDER BY [System.ChangedDate] DESC
+```
+
+POST to `$projUrl/_apis/wit/wiql?api-version=7.1` with body `{ "query": "<wiql>" }`.
+
+- 0 rows → write `last_discovery_result: no-match` + the WIQL used + `next_step` and STOP.
+- 1 row → use it. Persist `engagement_id` to `integrations.yml#ado` AND to `m365Mutable.knownSections.<project>.ado.engagementId`.
+- N rows → render the candidates table to the user (id, title, state, areaPath, createdDate). Ask which one. **Never auto-pick.** Persist on confirmation.
+
+## Step 2 — Expand the engagement tree
+
+```powershell
+$wi = Invoke-RestMethod -Headers $h -Uri "$projUrl/_apis/wit/workitems/$engagementId?`$expand=relations&api-version=7.1"
+$childIds = $wi.relations |
+  Where-Object { $_.rel -eq 'System.LinkTypes.Hierarchy-Forward' } |
+  ForEach-Object { ($_.url -split '/')[-1] }
+```
+
+Recurse — expand each child's `relations` the same way until the tree closes. Persist the resulting tree (parent → children IDs) to `Evidence/<alias>/ado/snapshot/tree.md`.
+
+## Step 3 — Per-item fetch (parent + every child, no batching)
+
+For each WI id in the tree:
+
+### 3a — Core fields
+
+```powershell
+$item = Invoke-RestMethod -Headers $h `
+  -Uri "$projUrl/_apis/wit/workitems/$id?`$expand=all&api-version=7.1"
+```
+
+`$expand=all` returns every populated field including custom fields. Don't pre-filter.
+
+### 3b — Discussion comments (verbatim, paginated until exhausted)
+
+```powershell
+$cmts = @()
+$ct = $null
+do {
+  $url = "$projUrl/_apis/wit/workItems/$id/comments?api-version=7.1-preview.4&`$top=200"
+  if ($ct) { $url += "&continuationToken=$ct" }
+  $page = Invoke-RestMethod -Headers $h -Uri $url
+  $cmts += $page.comments
+  $ct = $page.continuationToken
+} while ($ct)
+```
+
+Capture EVERY comment: `id`, `text` (verbatim, no truncation), `createdBy.displayName`, `createdDate`, `modifiedDate`. Render newest-first under `## Discussion (verbatim)`.
+
+### 3c — Revision history (every state + assignee + field change)
+
+```powershell
+$updates = Invoke-RestMethod -Headers $h `
+  -Uri "$projUrl/_apis/wit/workItems/$id/updates?api-version=7.1&`$top=500"
+```
+
+For each update, render `revisedBy.displayName`, `revisedDate`, and the `fields.<name>.{oldValue → newValue}` deltas. Group by date.
 
-Write `snapshot/items/<id>.md` per work item with every field. Top header: id, title, type, state, parent, area, iteration, assignee, last fetched.
+### 3d — Attachments (metadata only)
 
-Write to: `<engagement-root>/<project>/Evidence/<alias>/ado/snapshot/<entity>.md`
+From `$item.relations` where `rel = 'AttachedFile'` — record `name`, `resourceSize`, `attributes`. Do not download binary unless user asks.
 
-Use template: `templates/snapshot/ado-<kind>.template.md`
+### 3e — Write per-item snapshot file
 
-## Stream pass
+`<engagement-root>/<project>/Evidence/<alias>/ado/snapshot/items/<id>.md` (parent gets `engagement-<id>.md` at the snapshot root):
 
-Per `evidence-thoroughness.instructions.md`: every comment verbatim with author + timestamp; every state change; every field change. Bucketed by ISO week into `stream/items/<id>/<YYYY-MM-DD>_ado-stream.md`.
+- Header: id, type, title, state, areaPath, parent, assignee, last fetched.
+- `## Source Basis` — tool used (rest), boundary applied, comments fetched, revisions fetched.
+- `## AI Narrative Summary` (3+ paragraphs — REQUIRED FIRST).
+- `## All fields` — 2-column table; empty as `_(empty)_`.
+- `## Discussion (verbatim)` — every comment as `### <author> · <date>` then verbatim blockquote.
+- `## Revision history` — every update row.
+- `## Attachments` — metadata table.
 
-Write to: `<engagement-root>/<project>/Evidence/<alias>/ado/stream/<YYYY-MM-DD>_ado-stream.md` (date = Monday of the ISO week the events fall in).
+## Step 4 — Stream pass
 
-Use template: `templates/weekly/ado-summary.template.md`
+After all snapshots written, build the weekly stream from comments + updates whose `createdDate` / `revisedDate` fall in `<window>`. Bucket by Monday-of-ISO-week into `stream/<YYYY-MM-DD>_ado-stream.md` with AI Narrative Summary first then the verbatim entries grouped by WI.
 
-If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+If a week file exists, MERGE (dedupe by `comment.id` and `update.rev`).
 
 ## Tools (in order)
 
-1. **WorkIQ** — ````$WorkIQQuery`````
-2. **Host fallback** — ADO REST API via `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798` (read connection/queries from `<engagement-root>/.project-evidence/ado/config.yml`)
-3. **Graph REST** — last resort, soft-fail per `az-auth-conditional.instructions.md`.
-4. **Ask user** — paste verbatim source content if all above fail.
+1. **WorkIQ** — discovery only (asking "is there an Engagement WI for HCA?" before doing the WIQL). Never used for discussion-comment fetch — it summarizes.
+2. **ADO REST** — REQUIRED for fields + comments + updates + tree expansion (preferred path). Auth block above.
+3. **Ask user** — paste verbatim source content if REST returns 401 / 404 / persistent 5xx after 2 retries (3s/6s).
 
 Document which path succeeded under `## Source Basis` in each output file.
 
@@ -61,17 +204,24 @@ If discovered, immediately write to `m365Mutable.knownSections.<project>.<source
 - `ado.engagementId` — pinned engagement work-item ID
 - `ado.queryId` — saved query ID for the project
 - `ado.areaPath` / `ado.iterationPath` — for filtering
+- `ado.tree.lastBuiltOn` + `ado.tree.itemCount` — so consolidate can detect drift between runs.
 
 ## Update run-log
 
 After successful pass:
 - `sources.ado.last_pulled = now`
-- `sources.ado.watermark = now` (stream only; snapshot has no watermark)
-- `sources.ado.item_count = <N>`
+- `sources.ado.engagement_id = <id>`
+- `sources.ado.tree_size = <N>` — total WIs in the tree
+- `sources.ado.comments_fetched = <N>` — across the tree
+- `sources.ado.updates_fetched = <N>` — across the tree
+- `sources.ado.items_failed = <N>`
+- `sources.ado.watermark = now` (stream only)
 - For each week touched, add to `weekly_files` index.
 
 ## Stop conditions
 
-- 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.
-- WorkIQ fails AND host fallback fails AND Graph fails → write evidence file with `❌ all paths failed` marker, log to run-log errors, continue with rest of run.
+- Hard-prereq missing → refuse (see Hard prerequisites above).
+- Step 1 returns multiple Engagement candidates → ask user, never auto-pick.
+- 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.