kushi-agents 5.4.1 → 5.4.3

package/README.md

@@ -218,6 +218,14 @@ The Evidence/ folder produced by every profile is a **stable public contract**
 | `apply-ado` | **preview** | n/a | Gated apply skill. v0.1.0-preview is dry-mode only (writes `planned.jsonl`); real ADO PATCH/POST lands in v0.1.x. |
 | `vertex-link` | **preview** | n/a | One-time link of a kushi project to a vertex repo `<customer>/<initiative>` (multi-binding supported). Populates `kushi.yaml#vertex`. Re-run with `--reconfigure` to change. |
 | `emit-vertex` | **preview** | n/a | Render vertex-shaped artifacts from kushi Evidence/+State/ — weekly status, decisions, workshops, comms, living-doc diff proposals. Stages first, validates against vertex's own schemas, applies on demand. |
+| `doctor` | core+ | n/a | v5.4.0 — Aggregated health check (env, self-check, evals, skill-checker, live-install drift, global wiki). `--json` for CI; `--strict` to fail on yellow. |
+| `lint` | standard+ | n/a | v5.1.0 — Run wiki-lint checks against `State/` (contradictions, stale claims, orphans, missing cross-refs, data gaps). Writes `State/reports/lint-YYYY-MM-DD.md`. |
+| `teach` | standard+ | n/a | v5.2.0 — Persist a reusable fact/preference/pattern under `.kushi/learnings/`. |
+| `explain` | standard+ | n/a | v5.2.0 — Retrieve a previously taught fact/preference/pattern from `.kushi/learnings/`. |
+| `promote` | standard+ | n/a | v5.3.0 — Copy a project State page into the global wiki at `~/.kushi-global/` with identifier redaction + back-link + dual log. Refuses without `--force` when identifiers detected. |
+| `global` (init/status/ask/lint) | standard+ | n/a | v5.3.0 — Manage the per-user cross-engagement wiki at `~/.kushi-global/State/`. |
+| `schema-evolve` | standard+ | n/a | v5.2.0 — Migrate `kushi.yaml` and Evidence/ layouts across schema versions; idempotent + dry-run by default. |
+| `create-skill` / `check-skill` | full | n/a | v5.0.4 — Skill-authoring harness (scaffold a new skill; lint/retrofit every SKILL.md against `skill-authoring.instructions.md`). |
 
 See [Quickstart](https://gim-home.github.io/kushi/getting-started/quickstart/) for the full workflow.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.4.1",
+  "version": "5.4.3",
   "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/plugin.json

@@ -11,6 +11,8 @@
       "skills": [
         "intro",
         "self-check",
+        "doctor",
+        "eval",
         "setup",
         "pull-email",
         "pull-teams",
@@ -18,6 +20,7 @@
         "pull-onenote",
         "pull-loop",
         "pull-sharepoint",
+        "pull-misc",
         "pull-crm",
         "pull-ado",
         "aggregate-project",
@@ -34,7 +37,8 @@
         "status",
         "ask",
         "vertex-link",
-        "emit-vertex"
+        "emit-vertex",
+        "doctor"
       ],
       "instructions": "*",
       "templates": [
@@ -50,7 +54,8 @@
         "pull",
         "ask",
         "vertex-link",
-        "emit-vertex"
+        "emit-vertex",
+        "doctor"
       ]
     },
     "standard": {
@@ -64,7 +69,11 @@
         "fde-triage",
         "link-entities",
         "dashboard",
-        "tour"
+        "tour",
+        "lint-state",
+        "teach",
+        "promote",
+        "schema-evolve"
       ],
       "prompts": [
         "bootstrap",
@@ -92,15 +101,23 @@
         "fde-triage",
         "link-entities",
         "dashboard",
-        "tour"
+        "tour",
+        "lint",
+        "teach",
+        "explain",
+        "promote",
+        "schema-evolve"
       ],
       "_": null
     },
     "full": {
       "extends": "standard",
-      "description": "Standard + State/ rollup. Adds the opinionated outcome-based State/ files (decisions, stakeholders, architecture, action items, risks, timeline, artifacts, open questions) built on top of Evidence/. On this profile, bootstrap/refresh call build-state at the end.",
+      "description": "Standard + State/ rollup + global cross-engagement wiki + skill-authoring harness. Adds the opinionated outcome-based State/ files (decisions, stakeholders, architecture, action items, risks, timeline, artifacts, open questions) built on top of Evidence/, plus ~/.kushi-global/ wiki tooling and skill-creator/skill-checker for contributors. On this profile, bootstrap/refresh call build-state at the end.",
       "skills": [
-        "build-state"
+        "build-state",
+        "global-wiki",
+        "skill-creator",
+        "skill-checker"
       ],
       "prompts": [
         "state"
@@ -110,7 +127,10 @@
       ],
       "reference_packs": [],
       "verbs": [
-        "state"
+        "state",
+        "global",
+        "create-skill",
+        "check-skill"
       ]
     },
     "preview": {

package/plugin/prompts/create-skill.prompt.md

@@ -0,0 +1,26 @@
+---
+name: create-skill
+description: "Scaffold a new kushi skill from the skill-creator harness."
+argument-hint: "Skill name + optional --description '...'. Example: 'create-skill pull-confluence'."
+agent: kushi
+tools: [search, read/readFile, edit, 'execute/runInTerminal', agent]
+---
+
+## User Input
+
+```text
+${input:name_and_flags:Skill name + optional flags, e.g. 'pull-confluence --description "Pull from Confluence"'}
+```
+
+# /create-skill
+
+Route to `@Kushi create-skill <name>`.
+
+Scaffolds a new skill under `plugin/skills/<name>/` with SKILL.md frontmatter,
+description placeholder, references/ folder, and example test stub. Output
+conforms to `skill-authoring.instructions.md` so `check-skill` passes on first
+run.
+
+Companion verb: `/check-skill <name>` lints + retrofits an existing skill.
+
+Delegates to `skill-creator` skill.

package/plugin/prompts/doctor.prompt.md

@@ -0,0 +1,31 @@
+---
+name: doctor
+description: "Aggregated health check — env, self-check, evals, skill-checker, install drift, global wiki."
+argument-hint: "No project needed; runs system-wide diagnostics. Flags: --json (CI), --strict (fail on yellow)."
+agent: kushi
+tools: [search, read/readFile, 'execute/runInTerminal', agent]
+---
+
+## User Input
+
+```text
+${input:flags:Optional flags (--json, --strict). Empty for human-readable run.}
+```
+
+# /doctor
+
+Route to `@Kushi doctor` — aggregated health check covering:
+
+- **env** — node, pwsh, kushi version, install layout
+- **self-check** `-Deep` — D1..D41 doctrine checks
+- **evals** `:canary` — golden-set regression check
+- **skill-checker** `-All` — every SKILL.md against `skill-authoring.instructions.md`
+- **live-install drift** — repo source vs installed `~/.copilot/m-skills/kushi/` and `~/.vscode/chat/skills/kushi/`
+- **global wiki** — `~/.kushi-global/State/` shape + run-log
+
+Output: colored ribbon (GREEN / YELLOW / RED) + per-finding fix.
+
+Read-only by default. No pulls, no writes.
+
+Delegates to the `doctor` skill (`skills/doctor/doctor.ps1`). For CI:
+`pwsh -File skills/doctor/doctor.ps1 --json --strict`.

package/plugin/prompts/explain.prompt.md

@@ -0,0 +1,22 @@
+---
+name: explain
+description: "Retrieve a previously taught fact / preference / pattern from .kushi/learnings/."
+argument-hint: "Topic. Example: 'explain HCA naming-convention'."
+agent: kushi
+tools: [search, read/readFile, agent]
+---
+
+## User Input
+
+```text
+${input:topic:Topic, e.g. 'HCA naming-convention'}
+```
+
+# /explain
+
+Route to `@Kushi explain <topic>`.
+
+Looks up `.kushi/learnings/<slug>.md` (or fuzzy-match by topic substring) and renders
+the body + history. Read-only — never mutates the learning. Companion to `/teach`.
+
+Delegates to `teach` skill (explain mode).

package/plugin/prompts/global.prompt.md

@@ -0,0 +1,28 @@
+---
+name: global
+description: "Manage the per-user cross-engagement wiki at ~/.kushi-global/State/."
+argument-hint: "Sub-verb: init | status | ask <question> | lint. Example: 'global ask what's our default pull window?'"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:subverb_and_args:Sub-verb + args, e.g. 'init', 'status', 'ask what's our default pull window?', 'lint'}
+```
+
+# /global
+
+Route to `@Kushi global <sub-verb>`.
+
+Manages the cross-engagement wiki at `~/.kushi-global/State/` (override with
+`KUSHI_GLOBAL_ROOT` for tests). Sub-verbs:
+
+- `init` — scaffold the global wiki layout (decisions/, patterns/, glossary/, run-log).
+- `status` — show last-promoted pages + recent activity from the dual log.
+- `ask <q>` — citation-only Q&A over the global wiki (mirrors `kushi ask <project>` shape).
+- `lint` — wiki-lint over the global wiki (same checks as project lint).
+
+Delegates to `global-wiki` skill. Companion verb: `/promote` copies a project
+page up into the global wiki with identifier redaction.

package/plugin/prompts/lint.prompt.md

@@ -0,0 +1,28 @@
+---
+name: lint
+description: "Run wiki-lint checks against State/ — contradictions, stale claims, orphans, gaps."
+argument-hint: "Project name; runs against <project>/State/ and writes State/reports/lint-YYYY-MM-DD.md"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+```
+
+# /lint
+
+Route to `@Kushi lint <project>`.
+
+Runs the v5.1.0 `lint-state` skill against `<engagement-root>/<project>/State/`:
+- contradiction detection (claim A vs claim B with same subject)
+- stale claims (>14d without source-evidence freshness)
+- orphan pages (no inbound cross-refs)
+- missing required cross-refs per page type
+- data gaps (entities referenced but not pulled)
+
+Writes `<project>/State/reports/lint-YYYY-MM-DD.md`. Read-only against Evidence/.
+
+Delegates to `lint-state` skill.

package/plugin/prompts/promote.prompt.md

@@ -0,0 +1,26 @@
+---
+name: promote
+description: "Copy a project State page into the global wiki with identifier redaction + back-link + dual log."
+argument-hint: "Project + page. Example: 'promote HCA decisions/macc-terms'."
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:project_and_page:Project + relative State page, e.g. 'HCA decisions/macc-terms'}
+```
+
+# /promote
+
+Route to `@Kushi promote <project> <page>`.
+
+Copies `<engagement-root>/<project>/State/<page>.md` into `~/.kushi-global/State/<page>.md`:
+- runs the customer-identifier redactor (refuses without `--force` when hits detected)
+- inserts a back-link to the source project page
+- appends entries to both the project run-log and the global wiki dual log
+
+Companion verb: `/global ask <q>` retrieves promoted content.
+
+Delegates to `promote` skill.

package/plugin/prompts/schema-evolve.prompt.md

@@ -0,0 +1,27 @@
+---
+name: schema-evolve
+description: "Migrate kushi.yaml + Evidence/ across schema versions. Idempotent + dry-run by default."
+argument-hint: "Project. Flags: --apply (real run), --to <version>. Example: 'schema-evolve HCA --apply'."
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:project_and_flags:Project + flags, e.g. 'HCA' (dry-run), 'HCA --apply', 'HCA --to 5.2.0 --apply'}
+```
+
+# /schema-evolve
+
+Route to `@Kushi schema-evolve <project>`.
+
+Walks `<engagement-root>/<project>/` and applies schema migrations declared under
+`plugin/schemas/migrations/` to bring `kushi.yaml`, run-log, and Evidence/ layout
+to the current (or `--to`-pinned) schema version.
+
+- Default: dry-run — prints planned changes, writes nothing.
+- `--apply` — performs the migration; idempotent (safe to re-run).
+- `--to <ver>` — pin a target version (default = current).
+
+Delegates to `schema-evolve` skill.

package/plugin/prompts/teach.prompt.md

@@ -0,0 +1,25 @@
+---
+name: teach
+description: "Persist a reusable fact / preference / pattern under .kushi/learnings/."
+argument-hint: "Topic + body. Example: 'teach HCA naming-convention: services are kebab-case'."
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:topic_and_body:Topic + body, e.g. 'HCA naming-convention: services are kebab-case'}
+```
+
+# /teach
+
+Route to `@Kushi teach <topic>`.
+
+Writes a single self-contained learning file under `.kushi/learnings/<slug>.md`
+with frontmatter `topic`, `created`, `last_updated`. Idempotent — re-teach updates
+the existing file in place and appends a `history` entry.
+
+Companion verb: `/explain <topic>` retrieves the learning without modifying it.
+
+Delegates to `teach` skill.

package/src/setup-wizard.mjs

@@ -1,10 +1,11 @@
-// kushi v5.4.0 — interactive setup wizard.
+// kushi v5.4.2 — interactive setup wizard.
 // Non-interactive overrides (used by tests + CI):
-//   KUSHI_WIZARD_ROOT     — engagement root path
-//   KUSHI_WIZARD_HOSTS    — comma list: clawpilot,vscode  (or "both")
-//   KUSHI_WIZARD_GLOBAL   — "y" or "n"
-//   KUSHI_INSTALL_ROOT    — override ~/.copilot/ for install target (test isolation)
-//   KUSHI_SKIP_INSTALL    — "1" to skip the actual install step (tests)
+//   KUSHI_WIZARD_ROOT      — engagement root path
+//   KUSHI_WIZARD_HOSTS     — comma list: clawpilot,vscode  (or "both")
+//   KUSHI_WIZARD_GLOBAL    — "y" or "n"
+//   KUSHI_WIZARD_WORKSPACE — "y" or "n" — scaffold cwd as a kushi workspace
+//   KUSHI_INSTALL_ROOT     — override ~/.copilot/ for install target (test isolation)
+//   KUSHI_SKIP_INSTALL     — "1" to skip the actual install step (tests)
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -41,7 +42,7 @@ function makePrompter() {
     const v = process.env[key];
     return (typeof v === 'string' && v.length > 0) ? v : null;
   };
-  if (fromEnv('KUSHI_WIZARD_ROOT') || fromEnv('KUSHI_WIZARD_HOSTS') || fromEnv('KUSHI_WIZARD_GLOBAL')) {
+  if (fromEnv('KUSHI_WIZARD_ROOT') || fromEnv('KUSHI_WIZARD_HOSTS') || fromEnv('KUSHI_WIZARD_GLOBAL') || fromEnv('KUSHI_WIZARD_WORKSPACE')) {
     return { interactive: false, ask: async (_q, _def, envKey) => fromEnv(envKey) };
   }
   if (!process.stdin.isTTY) {
@@ -60,15 +61,23 @@ function makePrompter() {
 export async function runSetupWizard({ args = [] } = {}) {
   const detectedRoot  = detectEngagementRoot();
   const detectedHosts = detectHosts();
+  const cwd           = process.cwd();
+  const cwdHasKushi   = fs.existsSync(path.join(cwd, '.kushi'));
+  const defaultWorkspace = cwdHasKushi ? 'n' : 'y';
   const p = makePrompter();
 
   console.log('');
-  console.log('  kushi setup wizard — 3 questions, then I install.');
+  console.log('  kushi setup wizard — 4 questions, then I install.');
   console.log('');
 
   const root  = (await p.ask('  Where is your engagement root?', detectedRoot, 'KUSHI_WIZARD_ROOT')) || detectedRoot;
   const hosts = (await p.ask('  Install for clawpilot / vscode / both?', detectedHosts, 'KUSHI_WIZARD_HOSTS')) || detectedHosts;
   const wantGlobal = (await p.ask('  Enable global wiki at ~/.kushi-global/?', 'y', 'KUSHI_WIZARD_GLOBAL')) || 'y';
+  const wantWorkspace = (await p.ask(
+    `  Scaffold current directory (${cwd}) as a kushi workspace?${cwdHasKushi ? ' (already present)' : ''}`,
+    defaultWorkspace,
+    'KUSHI_WIZARD_WORKSPACE',
+  )) || defaultWorkspace;
 
   if (p.close) p.close();
 
@@ -76,6 +85,8 @@ export async function runSetupWizard({ args = [] } = {}) {
     engagementRoot: root,
     hosts: hosts.toLowerCase(),
     globalWiki: /^y/i.test(wantGlobal),
+    workspaceInstall: /^y/i.test(wantWorkspace),
+    workspacePath: cwd,
   };
 
   console.log('');
@@ -83,6 +94,7 @@ export async function runSetupWizard({ args = [] } = {}) {
   console.log(`    engagement root: ${answers.engagementRoot}`);
   console.log(`    hosts:           ${answers.hosts}`);
   console.log(`    global wiki:     ${answers.globalWiki ? 'yes' : 'no'}`);
+  console.log(`    workspace:       ${answers.workspaceInstall ? `yes (${cwd})` : 'no'}`);
   console.log('');
 
   if (process.env.KUSHI_SKIP_INSTALL === '1') {
@@ -122,6 +134,25 @@ export async function runSetupWizard({ args = [] } = {}) {
     }
   }
 
+  if (answers.workspaceInstall) {
+    try {
+      const { main } = await import('./main.mjs');
+      await main({
+        force: false,
+        yes: true,
+        noSettings: false,
+        noInstructions: false,
+        target: 'vscode',
+        profile: undefined,
+        withWorkiq: false,
+        workiqPath: undefined,
+        skipWorkiqCheck: true,
+      });
+    } catch (err) {
+      console.error(`  workspace install skipped: ${err.message}`);
+    }
+  }
+
   console.log('');
   console.log('  ✅ wizard complete — next steps:');
   console.log('    kushi doctor');

package/src/setup-wizard.test.mjs

@@ -31,18 +31,20 @@ async function withEnv(envOverrides, fn) {
 }
 
 test('setup-wizard: env-driven cases (sequential to avoid env race)', async (t) => {
-  await t.test('case 1: env overrides resolve all three prompts', async () => {
+  await t.test('case 1: env overrides resolve all four prompts', async () => {
     const root = path.join(TESTTMP, `wizard-root-${Date.now()}-1`);
     fs.mkdirSync(root, { recursive: true });
     const result = await withEnv({
       KUSHI_WIZARD_ROOT: root,
       KUSHI_WIZARD_HOSTS: 'clawpilot',
       KUSHI_WIZARD_GLOBAL: 'n',
+      KUSHI_WIZARD_WORKSPACE: 'n',
       KUSHI_SKIP_INSTALL: '1',
     }, () => runSetupWizard());
     assert.equal(result.engagementRoot, root, 'root from env');
     assert.equal(result.hosts, 'clawpilot', 'host from env');
     assert.equal(result.globalWiki, false, 'global wiki off');
+    assert.equal(result.workspaceInstall, false, 'workspace off');
   });
 
   await t.test('case 2: "both" hosts retained in answers', async () => {
@@ -52,6 +54,7 @@ test('setup-wizard: env-driven cases (sequential to avoid env race)', async (t)
       KUSHI_WIZARD_ROOT: root,
       KUSHI_WIZARD_HOSTS: 'both',
       KUSHI_WIZARD_GLOBAL: 'n',
+      KUSHI_WIZARD_WORKSPACE: 'n',
       KUSHI_SKIP_INSTALL: '1',
     }, () => runSetupWizard());
     assert.equal(result.hosts, 'both');
@@ -64,6 +67,7 @@ test('setup-wizard: env-driven cases (sequential to avoid env race)', async (t)
       KUSHI_WIZARD_ROOT: installRoot,
       KUSHI_WIZARD_HOSTS: 'clawpilot',
       KUSHI_WIZARD_GLOBAL: 'y',
+      KUSHI_WIZARD_WORKSPACE: 'n',
       KUSHI_SKIP_INSTALL: '1',
       KUSHI_INSTALL_ROOT: installRoot,
     }, () => runSetupWizard());
@@ -71,4 +75,18 @@ test('setup-wizard: env-driven cases (sequential to avoid env race)', async (t)
     assert.equal(result.globalWiki, true);
     assert.equal(result.engagementRoot, installRoot);
   });
+
+  await t.test('case 4: workspace scaffold opt-in records cwd', async () => {
+    const root = path.join(TESTTMP, `wizard-root-${Date.now()}-4`);
+    fs.mkdirSync(root, { recursive: true });
+    const result = await withEnv({
+      KUSHI_WIZARD_ROOT: root,
+      KUSHI_WIZARD_HOSTS: 'clawpilot',
+      KUSHI_WIZARD_GLOBAL: 'n',
+      KUSHI_WIZARD_WORKSPACE: 'y',
+      KUSHI_SKIP_INSTALL: '1',
+    }, () => runSetupWizard());
+    assert.equal(result.workspaceInstall, true, 'workspace install requested');
+    assert.equal(result.workspacePath, process.cwd(), 'workspace path = cwd');
+  });
 });