kushi-agents 5.0.0 → 5.0.1

package/README.md

@@ -5,6 +5,11 @@
 [![license](https://img.shields.io/npm/l/kushi-agents.svg)](LICENSE)
 [![host: Clawpilot](https://img.shields.io/badge/host-Clawpilot-7c9cff)](https://gim-home.github.io/kushi/)
 [![host: VS Code](https://img.shields.io/badge/host-VS%20Code-007acc)](https://gim-home.github.io/kushi/)
+[![spec: agentskills.io](https://img.shields.io/badge/spec-agentskills.io-22c55e)](https://agentskills.io/skill-creation/best-practices)
+
+> **v5.0.1 spec-compliance pass.** Every `plugin/skills/<name>/SKILL.md` follows the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices) and [optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) guides: ≤ 500 lines & ≤ 5000 tokens, load-on-trigger references, top-5 gotchas, checklist orchestrators, validation loops, plan-validate-execute for graph + State writers, and "USE WHEN …" descriptions. Enforced by `self-check -Deep` D30.*.
+
+> **Project lineage:** for the *why* behind each release — what built on what, what trade-offs were accepted, what external work inspired which design — see [`docs/genealogy.md`](docs/genealogy.md). Every release MUST add an entry there before tagging (enforced by `self-check` D31.genealogy).
 
 > A multi-skill GitHub Copilot agent for grounded engagement evidence — across Email, Teams, Meetings, OneNote, SharePoint, Dataverse (CRM), and Azure DevOps.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/instructions/agentskills-compliance.instructions.md

@@ -0,0 +1,144 @@
+---
+name: "agentskills-compliance"
+description: "Spec-compliance doctrine. Aligns every plugin/skills/<name>/SKILL.md with the conventions from https://agentskills.io/skill-creation/best-practices and /optimizing-descriptions. Defines size caps, load-on-trigger layout, gotchas, checklists, validation loops, plan-validate-execute, defaults-not-menus, and description-optimization rules. Enforced by self-check D30."
+applies_to: "every plugin/skills/<name>/SKILL.md"
+since: "kushi v5.0.1"
+---
+
+# agentskills-compliance — doctrine
+
+A SKILL.md is loaded **fully** into the agent's context window the moment it triggers. Every token competes with the conversation, system prompt, and other active skills. Compliance with the agentskills.io best-practices is therefore not stylistic — it is a context-budget contract.
+
+Authoritative external references:
+
+- <https://agentskills.io/skill-creation/best-practices>
+- <https://agentskills.io/skill-creation/optimizing-descriptions>
+
+## Rules (HARD)
+
+### 1. Size cap
+
+Every `plugin/skills/<name>/SKILL.md` MUST be:
+
+- ≤ **500 lines**, AND
+- ≤ **5000 tokens** (approximated by `char_count / 4`).
+
+Oversize SKILLs MUST be split per rule 2 below. Enforced by `self-check D30.skill-size`.
+
+### 2. Load-on-trigger layout
+
+`plugin/skills/<name>/SKILL.md` contains:
+
+- front-matter (`name`, `version`, `description`)
+- one-paragraph purpose
+- `## Gotchas` (top 5) — pull-* skills MUST have this
+- numbered or checklist procedure
+- `## Validation loop` (writer skills)
+- output contract
+
+Bulk content (full canonical WorkIQ prompts, full error-mode taxonomies, deep schema details, worked examples) moves to `plugin/skills/<name>/references/<topic>.md`. Standard reference filenames:
+
+| File | Contents |
+|------|----------|
+| `references/canonical-prompts.md` | Full WorkIQ prompt text (tier A/B/C, CSC, recovery) |
+| `references/error-modes.md` | Error taxonomy with retry semantics |
+| `references/taxonomy.md` | CSC schema deep details (where source-specific) |
+| `references/examples.md` | Full worked examples |
+| `references/playwright-fallback.md` | Opt-in fallback procedures |
+
+Every reference cited from SKILL.md MUST be cited with an **explicit trigger**, not a passive link. Trigger templates:
+
+```
+> Load references/canonical-prompts.md when constructing the WorkIQ query for this source.
+> Load references/error-modes.md if the API returns non-200, or WorkIQ returns "throttled".
+> Load references/playwright-fallback.md only when WorkIQ body-retrieval rate stays poor across ≥2 refreshes.
+```
+
+Enforced by `self-check D30.references-layout`.
+
+### 3. Gotchas (top 5)
+
+Every `pull-*` SKILL.md MUST surface its top 5 gotchas in a `## Gotchas` section near the top (immediately after the H1 / opening paragraph; before `## Steps` or `## Procedure`).
+
+Format: bullet list. Each bullet starts with the **concrete failure mode**, then the correction.
+
+```markdown
+## Gotchas
+
+- **Moved pages keep original wdsectionfileid** → if a section returns `page-body-unavailable` or zero `wdpartid` entries, the pages were authored elsewhere and moved. Open OneNote desktop, drag pages back into target section, retry.
+- **WorkIQ tier C requires ONE page per call** — batching multiple pages into a single ask returns empty results. Loop over pageIds, one call each.
+```
+
+Pull from `plugin/learnings/<source>.md` if present; else extract from the SKILL body itself. Enforced by `self-check D30.gotchas-section`.
+
+### 4. Checklists for orchestrators
+
+Orchestrator SKILLs (`bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour`) MUST use GitHub checkbox syntax `- [ ]` for their step lists so progress is trackable in tooling and in conversation.
+
+```markdown
+- [ ] Step 1 — Resolve engagement root.
+- [ ] Step 2 — Resolve project alias.
+- [ ] Step 3 — Preflight per source.
+```
+
+Enforced by `self-check D30.checklist-orchestrators`.
+
+### 5. Validation loops (writer skills)
+
+Every skill that writes files to `Evidence/`, `State/`, `_graph/`, `dashboards/`, or `tours/` MUST end with a `## Validation loop` section:
+
+```markdown
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted <area>`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.
+```
+
+Enforced by `self-check D30.validation-loop`.
+
+### 6. Plan-validate-execute (link-entities + build-state)
+
+See `plan-validate-execute.instructions.md`. The skill writes a plan JSON, validates against a source of truth, then executes.
+
+### 7. Defaults not menus
+
+Pick ONE tool for each procedure step. Alternatives are escape hatches and MUST live in `references/` (e.g. `references/playwright-fallback.md`), not in the main SKILL body. The SKILL.md procedure does not enumerate alternatives.
+
+### 8. Procedures over declarations
+
+Write what the agent must DO, not what the skill IS. Imperative voice, concrete steps.
+
+### 9. Description optimization
+
+Per <https://agentskills.io/skill-creation/optimizing-descriptions> the `description:` front-matter is the sole trigger signal. It MUST describe **WHEN to use** the skill (trigger conditions), not just what it does. Convention for kushi skills:
+
+```yaml
+description: "USE WHEN <situational trigger> AND <precondition>. DO NOT USE for <near-miss>. <one-line capability summary>."
+```
+
+- BAD: `"Pulls OneNote pages and saves them as markdown."`
+- GOOD: `"USE WHEN refreshing project evidence for a known kushi project AND the project boundaries.onenote.section_ids list is non-empty. DO NOT USE for global OneNote search or non-kushi note capture."`
+
+Hard limit: 1024 characters. Enforced loosely by `self-check D30.description-optimized` (checks for the literal substring `USE WHEN` or `WHEN ` near the start of `description:`).
+
+## Migration checklist (per oversized SKILL)
+
+- [ ] Move full WorkIQ prompts → `references/canonical-prompts.md`
+- [ ] Move full error taxonomy → `references/error-modes.md`
+- [ ] Move source-specific schema details → `references/taxonomy.md`
+- [ ] Move opt-in fallbacks (Playwright, Edge profile bootstrap) → `references/playwright-fallback.md`
+- [ ] Add `## Gotchas` (top 5)
+- [ ] Add `## Validation loop` (if writer)
+- [ ] Replace inline blocks with "Load references/&lt;file&gt; when …" pointers
+- [ ] Bump skill version (minor) since structure changed
+- [ ] Re-run `self-check D30` and `npm test`
+
+## References
+
+- `instructions/plan-validate-execute.instructions.md`
+- `instructions/capture-learnings.instructions.md`
+- `instructions/issue-recovery.instructions.md`

package/plugin/instructions/plan-validate-execute.instructions.md

@@ -0,0 +1,75 @@
+---
+name: "plan-validate-execute"
+description: "Three-phase write doctrine for cross-source synthesisers. A skill writes a plan JSON to <project>/Evidence/_plan/<skill>-plan.json, validates it against a source of truth (entities.yml / project-graph.json), and only then executes by writing the real artifact. Applies to link-entities (graph) and build-state (State/). Prevents silent corruption from bad inputs."
+applies_to: "link-entities, build-state"
+since: "kushi v5.0.1"
+---
+
+# plan-validate-execute — doctrine
+
+Cross-source synthesisers can silently corrupt the project tree if a malformed input survives a single run (e.g. an orphan reference in the graph propagates into State/ pages). The fix is a three-phase write:
+
+1. **Plan** — emit a structured JSON proposal.
+2. **Validate** — check it against a source of truth.
+3. **Execute** — write the real artifact only if validation passes.
+
+This separates failures from corruption: a bad plan is a recoverable artifact; a bad execute is a stale tree.
+
+## File convention
+
+```
+<engagement-root>/<project>/Evidence/_plan/
+   link-entities-plan.json
+   state-plan.json
+```
+
+The `_plan/` folder is per-project, single-writer-per-skill, overwritten each run. Self-check does not gate on its presence; it is an intermediate artifact, not a contract.
+
+## Schema (common envelope)
+
+```json
+{
+  "schema": "kushi.plan/v1",
+  "skill": "link-entities | build-state",
+  "project": "<project-name>",
+  "generated_at": "<ISO-8601>",
+  "kushi_version": "<x.y.z>",
+  "summary": { "<counter>": <int>, ... },
+  "items": [ { ... } ],
+  "validation": {
+    "checks_run": [ "<check-id>", ... ],
+    "passed": true | false,
+    "failures": [ { "code": "...", "item_ref": "...", "fix": "..." } ]
+  }
+}
+```
+
+## Per-skill contracts
+
+### link-entities
+
+- **Plan**: `Evidence/_plan/link-entities-plan.json` lists proposed nodes (one per resolved entity id) and edges (one per `(from, to, kind)` triple) with their source citations.
+- **Validate against**: every per-source `Evidence/<alias>/<source>/_index/entities.yml`. Every plan node MUST resolve to a row in some contributor's entities.yml. Every edge endpoint MUST appear in `nodes[]`.
+- **Execute**: write `Evidence/_graph/project-graph.json`.
+
+If validation fails, the skill MUST NOT touch `project-graph.json`. It surfaces the failures to the orchestrator and exits non-zero (or returns `{ ok: false }` in `-Json` mode).
+
+### build-state
+
+- **Plan**: `Evidence/_plan/state-plan.json` lists proposed State pages (one per category × entity) and `log.md` entries with their CSC citations.
+- **Validate against**: `Evidence/_graph/project-graph.json` (every page MUST cite a node id; no orphan references) AND `_index/entities.yml` for every cited weekly file.
+- **Execute**: write `State/index.md`, `State/log.md`, and per-category pages.
+
+If validation fails, the skill MUST NOT touch `State/`. Same failure semantics as link-entities.
+
+## Self-check coupling
+
+- `D20.graph` validates the executed `project-graph.json` (post-execute).
+- `D21.state` validates the executed Karpathy State layout (post-execute).
+- `D30.validation-loop` ensures the SKILL.md documents the plan/validate/execute loop with a `## Validation loop` section.
+
+## References
+
+- `instructions/agentskills-compliance.instructions.md`
+- `instructions/entity-graph.instructions.md`
+- `instructions/karpathy-state-layout.instructions.md`

package/plugin/instructions/release-genealogy.instructions.md

@@ -0,0 +1,52 @@
+---
+title: Release genealogy
+applies_to: every kushi release before tagging
+status: stable
+since: v5.0.1
+---
+
+# Release genealogy doctrine
+
+Every shipped tag MUST have a corresponding entry in `docs/genealogy.md`. The genealogy file is the canonical *why* for the project — `CHANGELOG.md` records *what changed*; genealogy records *what each release built on, what it enabled, and what trade-offs were accepted*.
+
+## When to write the entry
+
+Before `git tag`. The entry is part of the ship checklist, not a follow-up.
+
+## Required fields
+
+Every entry MUST contain:
+
+1. **Built on** — which prior release (or external work) this depends on. State the *causal* dependency, not just the version number ("Built on v4.9.0 CSC. Without per-contributor `_index/entities.yml` and stable entity IDs, cross-source linking would be guesswork.").
+2. **Why this release** — the problem this release solves, in 2–4 sentences.
+3. **What it enabled** — concrete capabilities now available that weren't before. Bullets OK.
+4. **Next ancestor** — name the next release in the lineage (forward link). Update the prior release's "Next ancestor" line when shipping.
+
+## Recommended fields
+
+5. **Inspired by** — external work, papers, gists, repos. Link them. This is the project's reading list.
+6. **Trade-offs accepted** — what was knowingly sacrificed. Includes locked decisions from design time (e.g. "Q1 LLM edges opt-in").
+7. **Patch lineage** — if patch releases under this entry fix bugs introduced here, list them inline rather than as separate sections.
+
+## Grouping rule
+
+One section per release that **materially advanced** the lineage. Patch releases that only fix bugs in the parent (e.g. v4.2.1–v4.2.3 fixing v4.2.0's WorkIQ probe on Windows) MUST be named under the parent's "Patch lineage" line, not given their own section. This keeps the file readable while ensuring every tag is discoverable.
+
+## Self-check enforcement
+
+`D31.genealogy` (in `plugin/skills/self-check/run.ps1`):
+
+- Every `git tag` matching `v\d+\.\d+\.\d+` MUST appear in `docs/genealogy.md` either as a `## v<x.y.z>` heading or as an explicit named patch under a parent's "Patch lineage" line.
+- Missing tags fail the check with the actionable fix: "Add an entry to docs/genealogy.md before re-tagging, or list this tag under a parent's Patch lineage line."
+
+## Cross-references
+
+- README links to `docs/genealogy.md` under "Project lineage"
+- CHANGELOG.md header notes: "For the *why* behind each release, see [docs/genealogy.md](docs/genealogy.md)"
+- Major GitHub tag descriptions link to the genealogy entry for that release
+
+## Style
+
+- Genealogy entries are short — 6–15 lines per release. If a release needs more, split the entry into "summary" + "deep-dive references" rather than letting the genealogy bloat.
+- Write in present tense for what the release *does*; past tense for what it *replaced*.
+- Don't list every file changed (that's CHANGELOG's job). Name only the structural shifts that matter to future readers.

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

@@ -1,7 +1,7 @@
 ---
 name: "aggregate-project"
 version: "1.0.0"
-description: "Pull-only multi-source aggregation for a project. Runs every enabled pull-* skill + consolidate-evidence, but DOES NOT run build-state. Produces a complete Evidence/ folder (the public contract) without Kushi's State/ overlay — intended for standalone use and for integration with external rollup systems."
+description: "USE WHEN the user asks to \"pull everything for <project>\" or \"refresh evidence without rebuilding State\" for an already-bootstrapped kushi project. DO NOT USE for first-time setup (use bootstrap-project) or to answer questions (use ask-project). Capability: runs every enabled pull-* skill + consolidate-evidence; SKIPS build-state. Profile-aware. Verbatim-by-default — every enabled source dispatched. Writes per-user refresh report."
 ---
 
 # Skill: aggregate-project
@@ -91,4 +91,13 @@ See `docs/reference/evidence-contract.md` for the full schema (filename rules, f
 
 ## 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.
+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.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted aggregate-project`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

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

@@ -2,7 +2,7 @@
 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."
+description: "USE WHEN the user has reviewed <project>/ado-updates/<date>/proposed.md and says \"apply the ADO updates\" / \"approve and push to ADO\" / \"commit the proposed work-item edits\". DO NOT USE without an existing proposed.md (run propose-ado-update first). Capability: gated write skill — presents diff for approval, applies approved items to Azure DevOps via WorkIQ, writes applied.md ledger with success/failure per work item."
 ---
 
 # Skill: apply-ado-update
@@ -127,4 +127,13 @@ After step 5 (approval), instead of step 6:
 
 ## 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.
+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.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted apply-ado-update`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

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

@@ -1,7 +1,7 @@
 ---
 name: "ask-project"
 version: "4.0.0"
-description: "Read-only Q&A over an already-bootstrapped project (v5.0.0). Answers natural-language questions using State/, Evidence/, and weekly CSC files. v5 cross-source questions go GRAPH-FIRST: consult Evidence/_graph/project-graph.json before walking weekly files. 3-step reader fallback (_index/entities.yml → weekly/*.md → legacy snapshot/ + stream/). Cited; no source pulls; no outbound."
+description: "USE WHEN the user asks a natural-language question about a known kushi project (\"what was decided about MACC?\", \"who is the EM on Acme?\", \"list open follow-ups for <project>\"). Read-only; auto-routes when a message names a known project. DO NOT USE for cross-project search or for questions about unbootstrapped projects. Capability: graph-first for cross-source questions (v5.0.0), walks _index/entities.yml → weekly CSC → legacy snapshot/+stream/ fallback chain. Every assertion cited."
 ---
 
 # Skill: ask-project

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

@@ -1,7 +1,7 @@
 ---
 name: "bootstrap-project"
-version: "4.0.0"
-description: "First-time setup for a project (kushi v4.9.0+): machine preflight, side-by-side config, engagement-root + project resolution, customer-hint discovery sweep across all WorkIQ-driven sources, initial full-window CSC pull across all enabled sources writing weekly/ + _index/ per source. All pull-* skills write CSC blocks per comprehensive-structured-capture.instructions.md. Verbatim-by-default — every enabled source dispatched, no silent skips. Discovery sweep MANDATORY before declaring blocked-config. CRM bootstrap discovery REQUIRED per `crm-bootstrap-discovery.instructions.md`. 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."
+version: "4.0.1"
+description: "USE WHEN the user says \"bootstrap <X>\", \"set up project evidence for <X>\", \"add me to project <X>\", \"I'm new to <X>\", or \"do it all for <X>\" AND the project has no Evidence/ folder yet. DO NOT USE for incremental refresh of an existing project (use refresh-project) or for tenant-wide M365 setup (use setup). Capability: machine preflight, side-by-side config, engagement-root + project resolution, customer-hint discovery sweep, initial full-window CSC pull across all enabled sources writing weekly/ + _index/. Builds State/ only on `full` profile."
 ---
 
 # Skill: bootstrap-project
@@ -49,6 +49,22 @@ After every run (success or coverage-gaps), write `<project>/bootstrap-status.md
 
 ## Steps
 
+
+## Step checklist
+
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+
+- [ ] Step 0 — Delegate ALL onboarding questions to the `setup` skill (REQUIRED, never asks here)
+- [ ] Step 1 — Machine preflight (SETUP)
+- [ ] Step 2 — Side-by-side config bootstrap
+- [ ] Step 3 — Project folder scaffold
+- [ ] Step 3.5 — Customer-hint discovery sweep (REQUIRED, kushi v4.8.0+)
+- [ ] Step 4 — Initial pull (last 30 days)
+- [ ] Step 5 — Consolidate (single contributor = no-op)
+- [ ] Step 6 — Build state (FULL PROFILE ONLY)
+- [ ] Step 6b — Cross-source graph + dashboard + tour (kushi v5.0.0)
+- [ ] Step 7 — Verify + summary
+
 ### Step 0 — Delegate ALL onboarding questions to the `setup` skill (REQUIRED, never asks here)
 
 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.
@@ -122,137 +138,19 @@ The `State/` subtree is created **only on `full` profile**. On `standard`, only
 
 ### Step 3.5 — Customer-hint discovery sweep (REQUIRED, kushi v4.8.0+)
 
-Per `customer-hint-discovery.instructions.md` — **before the boundaries gate runs in Step 4**, bootstrap MUST attempt a WorkIQ-driven discovery sweep for every source whose boundary is currently empty AND whose WorkIQ-driven discovery doctrine exists. This prevents the silent-skip defect where bootstrap scaffolds empty boundaries and immediately writes every source as `blocked-config` without ever asking WorkIQ what mentions the customer.
-
-For each source in the table below, if `<engagement-root>/<project>/integrations.yml#boundaries.<source>.<required-key>` is empty (or contains only `needs_review: true` rows from a prior incomplete sweep), dispatch the sweep using the customer hint from Step 1 + `<discoveryLookbackDays>` (default 90, configurable via `m365-mutable.json#bootstrap.discoveryLookbackDays`):
-
-| Source | Sweep doctrine | Populates | Required-key gate |
-|---|---|---|---|
-| email | `email-bootstrap-discovery.instructions.md` | `boundaries.email.mailboxes[]` | `mailboxes` empty |
-| teams | `teams-bootstrap-discovery.instructions.md` | `boundaries.teams.chat_ids[]` + `channel_ids[]` | BOTH empty |
-| meetings | `meetings-bootstrap-discovery.instructions.md` | `boundaries.meetings.series_join_urls[]` | `series_join_urls` empty |
-| sharepoint | `sharepoint-bootstrap-discovery.instructions.md` | `boundaries.sharepoint.site_urls[]` | `site_urls` empty AND `local_folders` empty |
-| onenote | existing Step 4a (display-name driven, v4.7.x) | `boundaries.onenote.section_file_ids[]` + `section_group_ids[]` | both empty |
-| loop | `loop-bootstrap-discovery.instructions.md` (v4.6.0) | `boundaries.loop.workspace_ids[]` | empty |
-| crm | `crm-bootstrap-discovery.instructions.md` (v3.11.0) | `boundaries.crm.record_ids[]` + `request_ids[]` | both empty AND `crm:` shared block populated |
-| ado | `ado-bootstrap-discovery.instructions.md` | `boundaries.ado.area_paths[]` | empty AND `ado:` shared block populated |
-
-For each sweep:
+Per `customer-hint-discovery.instructions.md` — before the boundaries gate runs in Step 4, bootstrap MUST attempt a WorkIQ-driven discovery sweep for every source whose boundary is currently empty.
 
-1. Read the per-source doctrine for the exact approved WorkIQ query shape.
-2. Issue ONE WorkIQ ask per source per project (chats + channels are TWO asks under the same teams doctrine).
-3. Parse the response per the doctrine's parsing rules.
-4. Cap at 10 candidates by recency (or per-doctrine ordering).
-5. Append discovered values to `<project>/integrations.yml#boundaries.<source>.<key>` as plain strings (deduplicate by exact-string equality).
-6. Write sidecar `<project>/Evidence/<alias>/_discovery/<YYYY-MM-DD>_<source>_discovery.yml` with per-row metadata (`discovered_by`, `discovered_at`, `needs_review: true`, `confidence`, `query`, `workiq_request_id`). The sidecar lives INSIDE the contributor's alias folder (discovery results are per-identity); filename is NOT suffixed with `-<alias>` since the folder already namespaces the owner.
-7. If `> 10` candidates: append the remainder to `<project>/OPEN-QUESTIONS-DRAFT.md` under `## Discovery sweep — candidates over cap`.
-8. If `0` candidates: write `last_status: unresolved` (NOT `blocked-config`) and append a one-line widen-hint suggestion to Open Questions.
-9. If WorkIQ errors: write a `deferred-retry` marker per `deferred-retry-on-workiq-fail.instructions.md` and set `last_status: deferred`. Do NOT skip ahead to `blocked-config`.
-
-Run sweeps **in parallel** where possible (they're independent WorkIQ asks). Total wall time should be ≤ 5× single-ask latency.
-
-**Rerun rule** — if the boundary already has at least one row that is NOT `needs_review: true` in the sidecar (user manually confirmed), the sweep is **skipped** for that source. Boundary is gospel. Pass `--force-rediscover` to override.
-
-**Forbidden:** declaring `last_status: blocked-config` for email/teams/meetings/sharepoint without first running this sweep. That is a defect per `customer-hint-discovery.instructions.md` § The rule. `blocked-config` is only legitimate when a prerequisite is genuinely missing (CRM/ADO shared config, SharePoint when both `site_urls` AND `local_folders` are empty AND the sweep returned 0).
-
-After all sweeps complete, write the `## Discovery Sweep Results` table to `<project>/bootstrap-status.md` per `customer-hint-discovery.instructions.md` § Required outputs (4).
+> **Load `references/discovery-sweep.md`** for the full per-source sweep table, sidecar format, parallelism rules, rerun doctrine, and cap-at-10 behavior. Load when any source boundary is empty before Step 4.
 
 ### 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. After Step 3.5, many of these should now contain discovered rows (annotated `needs_review: true` in their sidecars). For sources where the sweep ran but returned 0 candidates, the status is `unresolved` (not `blocked-config`) — add a one-liner to `<project>/OPEN-QUESTIONS-DRAFT.md` asking the user to widen the hint or manually seed the boundary. For sources where the sweep COULD NOT run because a prerequisite is genuinely missing (CRM/ADO shared connection block empty; SharePoint local-folder discovery), `blocked-config` is correct and the `next_step` MUST cite the specific missing field.
-
-For CRM and ADO additionally verify the shared connection block exists in `<workspace>/.kushi/config/shared/integrations.yml` (`crm:` block with `environment_url` + `tenant_id`, OR `ado:` block with `organization` + `project`) with non-placeholder values. **As of kushi v4.8.4, these blocks ship PRE-FILLED with the canonical Microsoft Industry Solutions defaults** (iscrm.crm.dynamics.com / Microsoft tenant / IndustrySolutions ADO org / IS Engagements project), so on a fresh install this preflight passes by default. Only if a contributor has hand-edited the file to empty values or works in a non-Microsoft tenant will this preflight fail — in that case, prompt the user to fix the affected field directly and park in Open Questions with the path. **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 `<workspace>/.kushi/config/shared/integrations.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 `<workspace>/.kushi/config/user/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 — 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
-    "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).**
+#### Step 4a — Discovery & registry persistence (REQUIRED, kushi v3.7.8+)
 
-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:
-   ```
-   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."
-   ```
-   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.
+> **Load `references/registry-persistence.md`** for the `knownSections` JSON schema, OneNote deterministic discovery procedure (GUID extraction from URL fragments), and per-source ID-persistence rules — all per `m365-id-registry.instructions.md`. Load when resolving canonical M365 identifiers for any source.
 
 #### 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). **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-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)
-
-> **v4.9.0 SUPERSEDED.** Bootstrap walks the full window now; pull-* write `weekly/<YYYY-MM-DD>_<source>-csc.md` + `_index/entities.yml` per source (not snapshot/ + stream/). See `weekly-csc.instructions.md` and `comprehensive-structured-capture.instructions.md`.
-
-Each produces CSC weekly output per `weekly-csc.instructions.md` + `comprehensive-structured-capture.instructions.md`. The gate enforces: shape (weekly/ + _index/ + verbatim/ for meetings) → 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).
+> **Load `references/pull-dispatch.md`** for the boundaries gate logic, CRM discovery requirement, verification-gate pseudocode, per-source dispatch order, and pull-misc scaffolding rules. Load when dispatching per-source pulls after discovery is complete.
 
 ### Step 5 — Consolidate (single contributor = no-op)
 
@@ -311,6 +209,20 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
 
 ## Changelog
 
+
+- **v4.0.1 (kushi v5.0.1, 2026-05-26)**: agentskills.io spec-compliance pass. Extracted customer-hint
+  discovery sweep → `references/discovery-sweep.md`; registry persistence (knownSections schema +
+  OneNote discovery procedure) → `references/registry-persistence.md`; pull-dispatch loop (boundaries
+  gate + CRM discovery + verification-gate pseudocode) → `references/pull-dispatch.md`. SKILL.md
+  trimmed from 341 to ~190 lines. Behaviour unchanged; load-on-trigger pointers added.
+- **v4.0.0 (kushi v5.0.0, 2026-05-26)**: After build-state, dispatch the v5 enrichment chain — `link-entities` → `dashboard` → `tour`. Each step's success/failure is recorded in the run summary; a failure of one step does not block the next.
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: Drops "1 verbatim per source per bootstrap" carve-out. Walks the full boundary window per source. Preflight ensures `weekly/` + `_index/` exist per source. All pull-* invoked write CSC blocks per comprehensive-structured-capture.instructions.md.
+
+## Validation loop
+
+After writing outputs:
 
-- **v4.0.0 (kushi v5.0.0, 2026-05-26)**: After build-state, dispatch the v5 enrichment chain — `link-entities` → `dashboard` → `tour`. Each step's success/failure is recorded in the run summary; a failure of one step does not block the next.
-- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: Drops "1 verbatim per source per bootstrap" carve-out. Walks the full boundary window per source. Preflight ensures `weekly/` + `_index/` exist per source. All pull-* invoked write CSC blocks per comprehensive-structured-capture.instructions.md.
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted bootstrap`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/bootstrap-project/references/discovery-sweep.md

@@ -0,0 +1,40 @@
+# references/discovery-sweep.md (bootstrap-project)
+
+> **Load this file when** executing Step 3.5 (customer-hint discovery sweep) — i.e., when at least one source boundary is empty and you need the per-source WorkIQ discovery procedure, table of sweep targets, sidecar format, and rerun/cap rules.
+
+## Customer-hint discovery sweep (REQUIRED, kushi v4.8.0+)
+
+Per `customer-hint-discovery.instructions.md` — **before the boundaries gate runs in Step 4**, bootstrap MUST attempt a WorkIQ-driven discovery sweep for every source whose boundary is currently empty AND whose WorkIQ-driven discovery doctrine exists. This prevents the silent-skip defect where bootstrap scaffolds empty boundaries and immediately writes every source as `blocked-config` without ever asking WorkIQ what mentions the customer.
+
+For each source in the table below, if `<engagement-root>/<project>/integrations.yml#boundaries.<source>.<required-key>` is empty (or contains only `needs_review: true` rows from a prior incomplete sweep), dispatch the sweep using the customer hint from Step 1 + `<discoveryLookbackDays>` (default 90, configurable via `m365-mutable.json#bootstrap.discoveryLookbackDays`):
+
+| Source | Sweep doctrine | Populates | Required-key gate |
+|---|---|---|---|
+| email | `email-bootstrap-discovery.instructions.md` | `boundaries.email.mailboxes[]` | `mailboxes` empty |
+| teams | `teams-bootstrap-discovery.instructions.md` | `boundaries.teams.chat_ids[]` + `channel_ids[]` | BOTH empty |
+| meetings | `meetings-bootstrap-discovery.instructions.md` | `boundaries.meetings.series_join_urls[]` | `series_join_urls` empty |
+| sharepoint | `sharepoint-bootstrap-discovery.instructions.md` | `boundaries.sharepoint.site_urls[]` | `site_urls` empty AND `local_folders` empty |
+| onenote | existing Step 4a (display-name driven, v4.7.x) | `boundaries.onenote.section_file_ids[]` + `section_group_ids[]` | both empty |
+| loop | `loop-bootstrap-discovery.instructions.md` (v4.6.0) | `boundaries.loop.workspace_ids[]` | empty |
+| crm | `crm-bootstrap-discovery.instructions.md` (v3.11.0) | `boundaries.crm.record_ids[]` + `request_ids[]` | both empty AND `crm:` shared block populated |
+| ado | `ado-bootstrap-discovery.instructions.md` | `boundaries.ado.area_paths[]` | empty AND `ado:` shared block populated |
+
+For each sweep:
+
+1. Read the per-source doctrine for the exact approved WorkIQ query shape.
+2. Issue ONE WorkIQ ask per source per project (chats + channels are TWO asks under the same teams doctrine).
+3. Parse the response per the doctrine's parsing rules.
+4. Cap at 10 candidates by recency (or per-doctrine ordering).
+5. Append discovered values to `<project>/integrations.yml#boundaries.<source>.<key>` as plain strings (deduplicate by exact-string equality).
+6. Write sidecar `<project>/Evidence/<alias>/_discovery/<YYYY-MM-DD>_<source>_discovery.yml` with per-row metadata (`discovered_by`, `discovered_at`, `needs_review: true`, `confidence`, `query`, `workiq_request_id`). The sidecar lives INSIDE the contributor's alias folder (discovery results are per-identity); filename is NOT suffixed with `-<alias>` since the folder already namespaces the owner.
+7. If `> 10` candidates: append the remainder to `<project>/OPEN-QUESTIONS-DRAFT.md` under `## Discovery sweep — candidates over cap`.
+8. If `0` candidates: write `last_status: unresolved` (NOT `blocked-config`) and append a one-line widen-hint suggestion to Open Questions.
+9. If WorkIQ errors: write a `deferred-retry` marker per `deferred-retry-on-workiq-fail.instructions.md` and set `last_status: deferred`. Do NOT skip ahead to `blocked-config`.
+
+Run sweeps **in parallel** where possible (they're independent WorkIQ asks). Total wall time should be ≤ 5× single-ask latency.
+
+**Rerun rule** — if the boundary already has at least one row that is NOT `needs_review: true` in the sidecar (user manually confirmed), the sweep is **skipped** for that source. Boundary is gospel. Pass `--force-rediscover` to override.
+
+**Forbidden:** declaring `last_status: blocked-config` for email/teams/meetings/sharepoint without first running this sweep. That is a defect per `customer-hint-discovery.instructions.md` § The rule. `blocked-config` is only legitimate when a prerequisite is genuinely missing (CRM/ADO shared config, SharePoint when both `site_urls` AND `local_folders` are empty AND the sweep returned 0).
+
+After all sweeps complete, write the `## Discovery Sweep Results` table to `<project>/bootstrap-status.md` per `customer-hint-discovery.instructions.md` § Required outputs (4).