kushi-agents 3.4.2 → 3.12.1

package/plugin/reference-packs/fde/crm-field-manifest.md

@@ -0,0 +1,165 @@
+# FDE CRM (Dataverse) Field Manifest
+
+> Canonical mapping of FDE engagement-submission long-text fields + annotation pull pattern. Consumed by `pull-crm` whenever the configured entity set is an FDE engagement-submission table.
+
+Cite as: `[source: reference-packs/fde/crm-field-manifest.md · packaged]`.
+
+---
+
+## Why this manifest exists
+
+The FDE engagement-submission record in Dataverse holds the strategic answers an FDE crew needs (business scenario, why current offers don't fit, success criteria, technology workloads, work done so far). These live in **long-text fields** (`Memo` / multi-line text) that must be captured **verbatim** — paraphrasing or summarizing them at pull time strips the context Kushi is supposed to preserve.
+
+Pre-v3.7.2, `pull-crm` retrieved a CRM record with whatever fields the API returned by default, which often dropped or truncated the long-text answers. This manifest fixes that by giving `pull-crm` an explicit `$select` list and an explicit annotation fetch loop.
+
+---
+
+## Display-name → logical-name mapping
+
+The user-facing labels (left) map to Dataverse logical names (right). Logical names vary per tenant; treat the right column as the **probable** logical name and do the discovery probe described below if a `$select` returns null.
+
+| Display label (form question) | Probable logical name | Type |
+|---|---|---|
+| Engaged With | `msfre_engagedwith` | Memo (multi-line) |
+| What is the business scenario or technical blocker that FDE would solve? | `msfre_businessscenario` | Memo |
+| Why are the current offers or solutions not suitable for this customer's needs? | `msfre_currentofferinggap` | Memo |
+| What does success look like for the customer? | `msfre_successcriteria` | Memo |
+| Please list the relevant technology (1st party / 3rd party) workloads being used | `msfre_technologyworkloads` | Memo |
+| Give a description of the work completed so far (if any) | `msfre_workcompletedsofar` | Memo |
+| MSX Opportunity ID | `msfre_msxopportunityid` | Single line |
+| Customer name | `msfre_customername` (or via lookup `_msfre_account_value`) | Lookup |
+| Engagement title | `msfre_engagementtitle` (or `name`) | Single line |
+| FDE crew / division | `msfre_division`, `msfre_crew` | OptionSet / Single line |
+| Status / state | `statuscode`, `statecode` | OptionSet |
+| Created on / by | `createdon`, `_createdby_value` | Datetime / Lookup |
+| Modified on / by | `modifiedon`, `_modifiedby_value` | Datetime / Lookup |
+
+### Discovery probe (run once per project, persist to mutable)
+
+If the configured `entitySetName` is `msfre_*` and a `$select` for any of the probable logical names above returns `null`, run a **metadata probe** to confirm the actual logical names:
+
+```http
+GET /api/data/v9.2/EntityDefinitions(LogicalName='msfre_engagementsubmission')/Attributes?$select=LogicalName,DisplayName,AttributeType&$filter=AttributeType eq 'Memo'
+```
+
+Persist the resolved mapping to `m365Mutable.knownSections.<project>.crm.fieldMap` so subsequent pulls skip the probe.
+
+---
+
+## REQUIRED $select for FDE engagement-submission records
+
+Every snapshot pull MUST request these fields explicitly (no relying on default projection):
+
+```
+$select=
+  msfre_engagementsubmissionid,
+  name,
+  msfre_engagedwith,
+  msfre_businessscenario,
+  msfre_currentofferinggap,
+  msfre_successcriteria,
+  msfre_technologyworkloads,
+  msfre_workcompletedsofar,
+  msfre_msxopportunityid,
+  statuscode,
+  statecode,
+  createdon,
+  createdby,
+  modifiedon,
+  modifiedby,
+  _ownerid_value,
+  _msfre_account_value
+```
+
+Then `$expand=Annotations($select=annotationid,subject,notetext,createdon,_createdby_value,filename,mimetype)` to pull every note attached to the record.
+
+If the discovery probe returned a different logical name, substitute it before issuing the request.
+
+---
+
+## Annotation (notes) pull pattern
+
+CRM Notes are stored as `Annotation` records related to the parent record via `objectid`. They are NOT included by default — they must be expanded.
+
+For each annotation returned:
+
+1. Capture **verbatim** the full `notetext` (do not summarize, do not truncate, do not strip newlines).
+2. Capture metadata: `subject`, `createdon`, `createdby` (resolved name, not GUID), `filename` + `mimetype` if attached.
+3. Write each annotation as a `### Note — <subject> (<createdon> by <createdby>)` block under a `## Notes (verbatim)` H2 section in the snapshot file.
+4. If the annotation has an attached file (`filename` non-null), record its filename + mimetype + size; do NOT download the binary unless the user explicitly asks.
+
+---
+
+## Snapshot file shape (FDE CRM record)
+
+When the entity is FDE engagement-submission, the snapshot file MUST follow this shape:
+
+```markdown
+# CRM — <customer-name> · <engagement-title>
+
+**Record ID:** `<id>` · **MSX Opportunity:** `<msx-id>` · **Last fetched:** `<iso-ts>`
+**Status:** `<statuscode label>` · **Owner:** `<owner display name>`
+
+## Source Basis
+
+- Tool: <workiq | dataverse-rest | graph>
+- Boundary: `boundaries.crm.record_ids = [<id>]`
+- Field map: `m365Mutable.knownSections.<project>.crm.fieldMap` (probed <date>) | packaged (default)
+- Annotations fetched: <N>
+
+## AI Narrative Summary
+
+(3+ paragraphs — engagement story so far, current stage, what's at stake, latest direction. No paraphrase of the long-text answers below; summarize what they say collectively.)
+
+## Engagement context
+
+### Engaged With
+> (verbatim msfre_engagedwith)
+
+### Business scenario / technical blocker
+> (verbatim msfre_businessscenario)
+
+### Why current offers / solutions not suitable
+> (verbatim msfre_currentofferinggap)
+
+### What success looks like
+> (verbatim msfre_successcriteria)
+
+### Technology workloads (1st / 3rd party)
+> (verbatim msfre_technologyworkloads)
+
+### Work completed so far
+> (verbatim msfre_workcompletedsofar)
+
+## All other fields
+
+(Every other field returned by the $select, in a 2-column table: field | value. Empty fields shown as `_(empty)_` so absence is visible.)
+
+## Notes (verbatim)
+
+### Note — <subject> (<createdon> by <createdby>)
+> (verbatim notetext, no truncation)
+
+### Note — <subject> (<createdon> by <createdby>)
+> (verbatim notetext)
+
+(... one block per annotation, oldest first ...)
+```
+
+---
+
+## Anti-patterns (defects)
+
+- ❌ Paraphrasing the long-text fields — they MUST be verbatim.
+- ❌ Omitting empty fields — write `_(empty)_` so the reader can see we asked.
+- ❌ Skipping annotations because they look like noise — every annotation goes in.
+- ❌ Truncating long annotations with `...` — record the full text even if it's pages.
+- ❌ Falling back to "narrate from email" when CRM is unreachable — see `pull-crm/SKILL.md` Hard prerequisites; refuse instead.
+
+---
+
+## See also
+
+- `intake-questions.md` — the FDE Intake question set this manifest backs.
+- `pull-crm/SKILL.md` — the skill that must apply this manifest.
+- `core-fde-reference.md` — broader FDE operating model.

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

@@ -0,0 +1,125 @@
+---
+name: "apply-ado-update"
+version: "0.1.0-preview"
+status: "preview-stub"
+description: "Gated write skill: reads <engagement-root>/<project>/ado-updates/<date>/proposed.md, presents the diff for approval, applies approved items to ADO (PATCH field + POST comment), and appends to the per-project update ledger. v0.1.0-preview is a STUB — runs in dry-mode only and writes a planned-writes log; no real ADO PATCH/POST yet."
+---
+
+# Skill: apply-ado-update
+
+Run this when the user says any of: "apply ado update for `<X>`", "@Kushi apply ado `<X>`", "write to ado for `<X>`".
+
+This skill is the **only** code path in Kushi authorized to write to ADO. It implements the doctrine in `update-ledger.instructions.md`.
+
+## Status: preview-stub (v0.1.0-preview)
+
+In v0.1.0-preview this skill **runs in dry-mode only**. It:
+
+- Reads `proposed.md`.
+- Validates the proposal shape and citations.
+- Re-fetches the current ADO Initiative state and re-computes the diff (in case it drifted since `propose-ado-update` ran).
+- Asks the user to approve all / select / none.
+- Writes a **planned-writes log** to `<project>/ado-updates/<YYYY-MM-DD>/planned.jsonl` recording what *would* have been written.
+- Does **not** call any ADO `PATCH` or `POST` endpoint yet.
+
+The real write path (PATCH field + POST comment + ledger append) lands in v0.1.x once the proposed.md format, the apply UX, and the ledger schema have been validated against real projects for at least one full week. See `docs/concepts/roadmap.md`.
+
+## Profile
+
+Belongs to the **`preview`** profile. Opt in via `npx kushi-agents --clawpilot --profile preview`.
+
+## Deterministic config — do not invent paths
+
+Same as `propose-ado-update`. Reads ADO connection from `<engagement-root>/.project-evidence/ado/config.yml`, per-project `engagement_id` and `writes:` block from `<engagement-root>/<project>/integrations.yml ado:`. Never asks for paths the bootstrap layer already resolved.
+
+## Pre-flight (HARD — do not bypass)
+
+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 `<engagement-root>/.project-evidence/ado/config.yml`) **must** complete green before any further step.
+
+## Steps (current preview-stub behavior)
+
+1. **Load proposed.md** and parse the field-update + comment-update sections (Markdown headings + fenced blocks).
+2. **Re-fetch current ADO state** (read-only GET) and compare against the `current` value embedded in `proposed.md`. If they differ → warn `proposal-drift`, show the live current value, and require explicit re-approval.
+3. **Duplicate detection** — list the latest 5 Discussion comments via ADO API; if any contain the Kushi fingerprint line for this same week → mark `duplicate-detected`, skip the comment write, still proceed with field update if not duplicate.
+4. **Allowlist gate** — every item in `proposed.md` whose `fieldRefName` is NOT in `integrations.yml ado.writes.allowlist.fields` is rejected before approval is even offered. This is the last-line guard against a malformed proposal.
+5. **Approval gate**:
+   - Default: prompt user with the diff and `[a]ll · [s]elect · [n]one`.
+   - Auto-apply: if `ado.writes.statusSummary.autoApply: true` AND the field-update item has `confidence: high` AND the new line matches the configured `<MMM YYYY>: ...` pattern → mark approver `auto:append-month-high-conf`. Same for `discussionComment.autoApply` (rare; off by default).
+   - All other items → require interactive approval.
+6. **(Stub)** Instead of calling ADO writes, append to `<project>/ado-updates/<YYYY-MM-DD>/planned.jsonl` one record per approved item:
+   ```json
+   {
+     "timestamp": "2026-05-18T16:30:00Z",
+     "engagementId": 12345,
+     "kind": "field|comment",
+     "fieldRefName": "Custom.FDEStatusSummary",
+     "currentValue": "...",
+     "proposedValue": "...",
+     "approver": "ushak | auto:append-month-high-conf",
+     "confidence": "high",
+     "evidenceCitations": ["ushak/onenote/snapshot/architecture-decisions.md · 2026-05-12"],
+     "fingerprint": "kushi-weekly-2026-05-18-12345-field",
+     "executed": false,
+     "stubReason": "v0.1.0-preview: write path not yet enabled"
+   }
+   ```
+7. **Echo summary** to user: how many items would be written, path to `planned.jsonl`, and the line "No ADO calls were made (preview-stub)."
+
+## Steps (planned for v0.1.x — when write path lands)
+
+After step 5 (approval), instead of step 6:
+
+6. **Apply field update** (one PATCH per approved field):
+   ```http
+   PATCH https://dev.azure.com/{org}/{project}/_apis/wit/workitems/{engagement_id}?api-version=7.1
+   Content-Type: application/json-patch+json
+
+   [
+     { "op": "test", "path": "/rev", "value": <currentRev> },
+     { "op": "add", "path": "/fields/Custom.FDEStatusSummary", "value": "<new value>" }
+   ]
+   ```
+   The `test` on `/rev` is the optimistic-lock guard. If it fails → ledger entry `error: rev-mismatch`, do NOT retry silently; surface to user.
+
+7. **Apply Discussion comment** (one POST per approved comment):
+   ```http
+   POST https://dev.azure.com/{org}/{project}/_apis/wit/workItems/{engagement_id}/comments?api-version=7.1-preview.4
+   Content-Type: application/json
+   { "text": "<rendered HTML>" }
+   ```
+
+8. **Append to ledger** at `<project>/ado-updates/<YYYY-MM-DD>/ledger.jsonl` per `update-ledger.instructions.md` §Schema, including the **reverse op** (so a later `revert` skill can roll back).
+
+9. **Optional notify** — if `ado.writes.approvals.notifyOnApply: teams`, post a one-line summary via `m_send_teams_message` to the user (never to others).
+
+## Failure modes (preview-stub)
+
+| Symptom | Recovery |
+|---|---|
+| `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. |
+| `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`. |
+
+## What this skill does NOT do (ever — not even in v0.1.x)
+
+- Does NOT auto-apply any item with `confidence < high`.
+- Does NOT auto-apply any item not on the per-project allowlist (`ado.writes.<x>.autoApply: true`).
+- Does NOT write to fields not listed in `ado.writes.allowlist.fields` of `<project>/integrations.yml`.
+- Does NOT post comments other than the single rendered Discussion comment from `proposed.md`.
+- Does NOT bulk-apply across projects in a single call (one project per invocation).
+- Does NOT delete or close work items, change parent links, change area path, or touch any field outside the configured allowlist.
+
+## 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.
+- `propose-ado-update` SKILL.md — produces the `proposed.md` consumed by this skill.
+- `engagement-root-resolution.instructions.md` — resolving `<engagement-root>` and `<project>`.

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

@@ -20,6 +20,8 @@ The user does NOT need to type `/ask-project` or `@Kushi ask`. If the message:
 - **Read-only.** No `pull-*`, no Graph writes, no WorkIQ calls during answering. Source pulls are a separate user-initiated step.
 - **No cross-project bleed.** Answer only from the resolved project's own folders. If the question requires comparing two projects, ask the user to confirm and run `ask-project` per project, then merge in the answer.
 - **Citation Ledger applies.** Every fact, decision, person, date, $ figure carries inline `[source: <alias>/<folder>/<file> · YYYY-MM-DD]` per `instructions/citation-ledger.instructions.md` and `instructions/answer-from-evidence.instructions.md`. If the corpus does not support an answer, say so explicitly — never invent.
+- **Full-view gate applies.** Walk the standard 7-source set per `instructions/full-view-gate.instructions.md` before answering and render the Source Basis disposition table. Do not call the answer a "full view" if any applicable source is `cached-stale`, `attempted-but-blocked`, or `unknown`.
+- **Confidence ladder applies.** Tag every claim about decisions/status/funding/scope/owner/commitment with `internal-only` / `communicated` / `confirmed` per `instructions/evidence-confidence-ladder.instructions.md`. Never paraphrase a CRM/ADO field flip as a settled fact without a customer-facing confirmation dated AFTER the flip.
 - **Privacy posture.** Same as Kushi global: no outbound messages, no leaking attendee emails into anything visible to others. Answer goes to chat only.
 - **Freshness gate, not freshness auto-fix.** If the freshest source relevant to the question is older than `chat.freshness_warn_days` (default 14), warn the user and offer `@Kushi refresh <project>` — but NEVER auto-refresh.
 - **Reference packs may be consulted for domain doctrine.** When the question maps to a known reference-pack domain (currently only `fde/` — FDE stages, fitness, CRM status meanings, intake gates, risk categories, "MACC", "is this FDE-fit"), ALSO load the matching reference pack as additional grounding using the 3-layer override order (project → user → packaged). Cite reference-pack assertions with `[source: reference-packs/<pack>/<file>.md · <layer>]` where layer is `packaged` / `user-override` / `project-override`. Reference-pack content NEVER overrides project Evidence/ for facts about *this* project; it only provides definitions, gates, and rubrics.

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.