kushi-agents 5.0.2 → 5.0.4

package/plugin/skills/intro/references/walkthrough.md

@@ -0,0 +1,310 @@
+# Interactive Walkthrough
+
+Loaded by `intro` SKILL when the user accepts the guided tour.
+
+## Mode 2: Interactive Walkthrough
+
+### Pre-flight
+
+Before opening, check whether any project is already bootstrapped:
+
+1. Read `<workspace>/.kushi/config/user/project-evidence.yml` (personal config). If `active_projects` has entries, pick the most recent as the demo target — substitute that name into `{{active_project}}` placeholders below.
+2. If none, propose a fictional project named **Contoso Discovery** and tell the user that Try-it prompts will use that name; they can substitute their own at any time.
+
+### Navigation Keywords
+
+After every demo moment, list:
+
+- `next` (or `n`) — advance to the next moment.
+- `skip` (or `s`) — jump to the next moment without trying this one.
+- `done` (or `d`, `exit`, `quit`) — exit the walkthrough; show the cheat sheet.
+- `try` (or `t`) — actually run the Try-it prompt now (kushi will execute it for the active project).
+
+### Opening
+
+> Great — let's tour Kushi end-to-end. Each step:
+>
+> - Explains **one verb** in plain language.
+> - Gives you a **ready-to-send prompt** in a code block — copy-paste it, or just reply `try` and I'll run it for you.
+> - Waits for `next` / `skip` / `done` before advancing.
+>
+> Demo target for this tour: **{{active_project}}**. (Substitute any project name in the Try-it prompts.)
+>
+> Reply `next` (or just say "let's go") to begin.
+
+### Demo Moments
+
+Present in order. After each moment, append the navigation block.
+
+---
+
+**Moment 1 — Snapshot vs Stream (the foundation)**
+
+> **The single most important rule in Kushi.** Every per-source skill writes two kinds of evidence:
+>
+> - **Snapshot** = current state of one entity. One file per entity. Replaced on every refresh. No date in filename. Example: `Evidence/{{alias}}/Teams-Chats/snapshot/roster.md` always shows the *current* member list of the project chat — not who was in it three weeks ago.
+> - **Stream** = timestamped events. One file per ISO week. Append-only. Dated filename. Example: `Evidence/{{alias}}/Email/stream/2026-05-04_email-stream.md` shows every email received during the week of May 4.
+>
+> State files (e.g. `02_stakeholders.md`) cite snapshots for *current* facts and streams for *temporal* claims like "decision made on May 5".
+
+Reply `next` to see how to bootstrap a project, or `done` to exit.
+
+---
+
+**Moment 2 — Bootstrap a new project**
+
+> **`bootstrap-project`** — first-time setup for an engagement. Lays configs side-by-side, scaffolds `Evidence/` and `State/` folders, asks you to confirm sources, then runs the initial 30-day pull across every enabled source.
+
+**Try it** — copy and send (or reply `try`):
+
+```
+kushi bootstrap {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 3 — Refresh with a watermark**
+
+> **`refresh-project`** — incremental pull driven by `Evidence/run-log.yml` watermarks. If the last successful pull was Monday 9 AM, refresh picks up everything since then. No window arg = "since last watermark", with a 7-day fallback if no watermark exists.
+
+**Try it — default (since last watermark):**
+
+```
+kushi refresh {{active_project}}
+```
+
+**Try it — explicit window:**
+
+```
+kushi refresh {{active_project}} last 14 days
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 4 — Pull one source in isolation**
+
+> **`pull-<source>`** — run a single per-source skill without touching the others. Useful when you only care about new ADO items, or you want to backfill OneNote pages without re-pulling email. Each `pull-*` skill is **WorkIQ-first** and writes to your alias subfolder under `Evidence/<alias>/<source>/`.
+
+**Try it — pull just email:**
+
+```
+kushi pull email for {{active_project}} last 7 days
+```
+
+**Try it — pull just ADO work items:**
+
+```
+kushi pull ado for {{active_project}} last 30 days
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 5 — Render State from existing Evidence**
+
+> **`build-state`** — re-render every file under `State/` from existing `Evidence/`, **without any source pulls**. Use this when you want to see how the state view changes after manually editing evidence, or when you've consolidated streams from multiple contributors and want a fresh outcome view.
+>
+> State output is outcome-based — `00_overview.md`, `01_decisions.md`, `02_stakeholders.md`, `03_architecture.md`, `04_workshops.md`, `05_actions.md`, `06_risks.md`, `07_timeline.md`, `08_artifacts.md`, `09_open-questions.md`. Every assertion cites the evidence file + date it came from.
+
+**Try it:**
+
+```
+kushi state {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 6 — Consolidate multi-user evidence**
+
+> **`consolidate-evidence`** — merge per-user streams into `Evidence/_Consolidated/`. Only needed if multiple contributors are pulling for the same project. The consolidated file tags each entry with the contributor alias so provenance is preserved.
+
+**Try it:**
+
+```
+kushi consolidate {{active_project}} last 7 days
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 7 — Inspect the run-log**
+
+> **`project-status`** — read-only inspector for `Evidence/run-log.yml`. Shows per-source watermarks, last successful run, and any failures. Use it before kicking off a refresh to see what kushi will pull.
+
+**Try it:**
+
+```
+kushi status {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 8 — Ask the project (cited Q&A)**
+
+> **`ask-project`** — read-only natural-language Q&A over what's already been captured. Loads the cheapest set of files needed (Evidence/ first; State/ on `full`), cites every assertion `[source: <alias>/<folder>/<file> · YYYY-MM-DD]`, warns if the relevant source is older than 14 days, and ends with a Confidence verdict.
+>
+> **Auto-routes — no prefix needed.** Just name a project and ask a question. The slash form (`/ask`) and the explicit `kushi ask` are also accepted.
+>
+> **Never** triggers a `pull-*`. If evidence is stale or missing, it offers `kushi refresh <project>` and stops.
+
+**Try it — explicit form:**
+
+```
+kushi ask {{active_project}} what's the status?
+```
+
+**Try it — auto-routed (no prefix):**
+
+```
+what's the MACC for {{active_project}} and is it confirmed?
+```
+
+```
+who is the EM on {{active_project}}?
+```
+
+```
+summarize {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 9 — FDE Intake (first-artifact authoring)**
+
+> **`fde-intake`** — author or update the FDE Intake document at `Reports/00-FDE-Intake-<project>.md`. It is the first artifact in any FDE engagement and is consumed by FDE Triage to decide which team is best suited and whether the engagement is billable.
+>
+> Grounded in **two sources**: the project's Evidence/ + the FDE reference pack (`intake-questions.md`, `report-doctrine.md`, `core-fde-reference.md`). Embeds inline `> ⚠️ VALIDATION WARNING — Rule X.Y` blockquotes wherever Evidence is silent.
+>
+> **Standard + Full profiles only.**
+
+**Try it:**
+
+```
+kushi fde-intake {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 10 — FDE Report (5 shapes)**
+
+> **`fde-report`** — generate an FDE-shaped engagement report. One skill, five shapes:
+>
+> - `weekly` (default) — internal status, 1–2 pages.
+> - `short` — customer-facing, sanitized (no MACC / MS staffing / CRM IDs).
+> - `long` — incoming-crew handoff, 3–5 pages.
+> - `fitness` — 10-row FDE Fitness scorecard + verdict.
+> - `stage-readiness` — "should we advance to the next FDE stage?" check.
+>
+> Read-only against Evidence; no outbound. Apply all 9 doctrine rules.
+
+**Try it — weekly default:**
+
+```
+kushi fde-report {{active_project}}
+```
+
+**Try it — fitness scorecard:**
+
+```
+kushi fde-report {{active_project}} fitness
+```
+
+**Try it — stage-readiness check:**
+
+```
+kushi fde-report {{active_project}} stage-readiness
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 11 — FDE Triage (full 7-file bundle)**
+
+> **`fde-triage`** — produce the full FDE Triage bundle: 7 companion files at `Reports/triage/<YYYY-MM-DD>/`:
+>
+> 1. `00-fde-analysis.md` — concise FDE analysis (entry point)
+> 2. `01-fde-fitness.md` — 10-row fitness scorecard
+> 3. `02-risk-analysis.md` — risks bucketed into 8 reference-pack categories
+> 4. `03-6Q.md` — 6-question engagement framing
+> 5. `04-readiness-checklist.md` — **mobilization readiness** (distinct from stage readiness)
+> 6. `05-executive-consolidated-report.md` — leadership readout
+> 7. `06-global-opportunity-and-reuse.md` — repeatability lens
+> 8. `07-validation-warnings-checklist.md` — central tracker (open / resolved / NA)
+>
+> Re-runs preserve user-edited statuses in file 07.
+
+**Try it:**
+
+```
+kushi fde-triage {{active_project}}
+```
+
+Reply `next`, `skip`, or `done`.
+
+---
+
+**Moment 12 — Self-check before committing**
+
+> **`self-check`** — Kushi has its own consistency checker. Before you commit changes to the kushi repo (or after editing an instruction file), run self-check to verify every skill is in the agent inventory, every prompt routes to a real skill, every cross-link resolves, and the live `~/.copilot/m-skills/kushi/` install matches the repo. Run it as a markdown report (default), JSON for CI (`-Json`), or with deeper hash + schema checks (`-Deep`). Cross-OS: on macOS/Linux use `./run.sh` (requires `pwsh` 7+).
+
+**Try it — quick:**
+
+```
+kushi self-check
+```
+
+**Try it — deep + strict for CI (Windows):**
+
+```
+pwsh plugin/skills/self-check/run.ps1 -Deep -StrictExit
+```
+
+**Try it — deep + strict for CI (macOS / Linux):**
+
+```
+./plugin/skills/self-check/run.sh -Deep -StrictExit
+```
+
+Reply `next` to see the closing cheat sheet, or `done` to exit.
+
+---
+
+### Closing
+
+> That's the full tour. Cheat sheet:
+>
+> | What you want | What to say |
+> |---|---|
+> | First-time engagement setup | `kushi bootstrap <project>` |
+> | Catch up since last pull | `kushi refresh <project>` |
+> | Backfill a custom range | `kushi refresh <project> last N days` |
+> | One source only | `kushi pull <source> for <project>` |
+> | Re-render state files (full only) | `kushi state <project>` |
+> | Merge contributors | `kushi consolidate <project>` |
+> | Inspect run-log | `kushi status <project>` |
+> | **Ask a question (cited Q&A)** | `kushi ask <project> <question>` — or just say it naturally |
+> | First-artifact FDE Intake | `kushi fde-intake <project>` |
+> | FDE report (5 shapes) | `kushi fde-report <project> [shape]` |
+> | Full FDE Triage bundle (7 files) | `kushi fde-triage <project>` |
+> | Pre-commit validation | `kushi self-check` (or `-Deep`) |
+> | This tour again | `kushi intro` |
+>
+> You can also describe what you need in plain language — kushi will route to the right verb. Reply `restart` to retake the tour, or just ask me anything.
+
+---
+

package/plugin/skills/link-entities/evals/evals.json

@@ -0,0 +1,31 @@
+{
+  "skill": "link-entities",
+  "version": "1.0.0",
+  "description": "Deterministic entity-graph output — closed edge taxonomy + nodes/edges schema.",
+  "cases": [
+    {
+      "id": "le-graph-schema",
+      "name": "fixture project-graph.json has v1 schema + nodes + edges",
+      "input": "validate graph schema",
+      "fixture": "evals/fixtures/fixture-acme",
+      "canary": true,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "Evidence/_graph/project-graph.json" },
+        { "type": "json-path-equals", "path": "Evidence/_graph/project-graph.json", "json_path": "$.schema", "equals": "kushi.project-graph/v1" }
+      ]
+    },
+    {
+      "id": "le-closed-taxonomy",
+      "name": "every edge uses a kind from the closed taxonomy",
+      "input": "validate edges",
+      "fixture": "evals/fixtures/fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "args": { "read_fixture": "Evidence/_graph/project-graph.json" },
+      "expected_assertions": [
+        { "type": "regex-match", "pattern": "\"kind\":\\s*\"(references|decides|action-item-tracks|discusses|produced-by|follow-up-of|same-thread|participant-of)\"" }
+      ]
+    }
+  ]
+}

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

@@ -58,4 +58,13 @@ Scan run-log `history` for entries where `status != ok` in the last 5 runs. Disp
 - "status of `<X>`"
 - "@Kushi status `<X>`"
 - "what was the last refresh for `<X>`"
-- "show run-log for `<X>`"
+- "show run-log for `<X>`"
+
+## Validation loop
+
+<!-- TODO(retrofit): fill in — describe how to verify this skill ran correctly. Auto-added by skill-checker --retrofit --apply per skill-authoring.instructions.md. -->
+
+1. Run pwsh plugin/skills/self-check/run.ps1 -Targeted <area>.
+2. Fix any findings, then re-run the affected step.
+3. Repeat until self-check exits 0.
+4. Only then update 

package/plugin/skills/project-status/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill": "project-status",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for project-status. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "project-status-smoke-1",
+      "name": "project-status produces a non-empty response",
+      "input": "synthetic project-status probe — canary smoke",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": ".+"
+        }
+      ]
+    },
+    {
+      "id": "project-status-smoke-2",
+      "name": "project-status echoes case id",
+      "input": "case-id project-status-smoke-2",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "project-status-smoke-2"
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/propose-ado-update/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill": "propose-ado-update",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for propose-ado-update. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "propose-ado-update-smoke-1",
+      "name": "propose-ado-update produces a non-empty response",
+      "input": "synthetic propose-ado-update probe — canary smoke",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": ".+"
+        }
+      ]
+    },
+    {
+      "id": "propose-ado-update-smoke-2",
+      "name": "propose-ado-update echoes case id",
+      "input": "case-id propose-ado-update-smoke-2",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "propose-ado-update-smoke-2"
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-ado/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-ado",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-ado. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-ado-cached-1",
+      "name": "pull-ado cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-ado-rubric-1",
+      "name": "pull-ado output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-ado pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-ado response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-crm/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-crm",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-crm. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-crm-cached-1",
+      "name": "pull-crm cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-crm-rubric-1",
+      "name": "pull-crm output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-crm pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-crm response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-email/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-email",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-email. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-email-cached-1",
+      "name": "pull-email cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-email-rubric-1",
+      "name": "pull-email output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-email pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-email response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-loop/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-loop",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-loop. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-loop-cached-1",
+      "name": "pull-loop cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-loop-rubric-1",
+      "name": "pull-loop output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-loop pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-loop response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-meetings/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-meetings",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-meetings. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-meetings-cached-1",
+      "name": "pull-meetings cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-meetings-rubric-1",
+      "name": "pull-meetings output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-meetings pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-meetings response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-misc/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-misc",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-misc. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-misc-cached-1",
+      "name": "pull-misc cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-misc-rubric-1",
+      "name": "pull-misc output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-misc pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-misc response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-onenote/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-onenote",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-onenote. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-onenote-cached-1",
+      "name": "pull-onenote cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-onenote-rubric-1",
+      "name": "pull-onenote output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-onenote pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-onenote response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}