kushi-agents 3.12.1 → 3.14.0

package/.github/copilot-instructions.kushi.md

@@ -0,0 +1,38 @@
+## Kushi — Project Evidence Agent
+
+This workspace has [Kushi](https://gim-home.github.io/kushi/) installed under `.kushi/`. Kushi captures multi-source project evidence (Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO) via **WorkIQ** and answers cited questions over the captured evidence.
+
+### Routing — no `@Kushi` prefix required
+
+When the user types any of the following verbs followed by a project name, route to the corresponding Kushi prompt in `.kushi/prompts/` (no `@Kushi` needed):
+
+| Verb                       | Prompt to run                              |
+| -------------------------- | ------------------------------------------ |
+| `bootstrap <project>`      | `/pull-all-bootstrap`                      |
+| `refresh <project>`        | `/pull-all-refresh`                        |
+| `aggregate <project>`      | `/pull-all-aggregate`                      |
+| `state <project>`          | `/rebuild-state`                           |
+| `consolidate <project>`    | `/consolidate-evidence`                    |
+| `status <project>`         | `/show-run-log`                            |
+| `ask <project> <question>` | `/ask-project` (auto-routes to evidence Q&A) |
+
+Project Q&A also auto-dispatches when the user names a known project under the engagement root **and** asks a question about it — no prefix needed.
+
+### Hard rules (enforced by Kushi skills)
+
+- **WorkIQ-first** for all M365 sources. `m365_*` / Microsoft Graph calls are only allowed as a classified fallback after a documented WorkIQ failure.
+- **Every assertion** in any Kushi output (State files, Evidence summaries, consolidated reports, Open Questions) MUST carry an inline citation: `[source: <alias>/<folder>/<file> · YYYY-MM-DD]`.
+- **Read-only Q&A** — `ask` never triggers any `pull-*` skill. Stale evidence (>14d) prompts the user to refresh; Kushi does not auto-refresh.
+- **No cross-project bleed** — answers must be grounded only in the named project's `Evidence/` + `State/` + `snapshot/`.
+- **Never reach out** — Kushi does not send Teams/email/CRM-note/ADO-comment on the user's behalf unless they explicitly request it that turn. Recommendations go into the project's Open Questions, not into outbound sends.
+
+### Layout
+
+- `.kushi/agents/kushi.agent.md` — orchestrator (also addressable as `@Kushi`)
+- `.kushi/prompts/` — verb prompts (`/pull-*`, `/ask-project`, etc.)
+- `.kushi/skills/` — per-source pull + render skills
+- `.kushi/instructions/` — doctrine (citations, WorkIQ-first, freshness gates)
+- `.kushi/reference-packs/` — bundled domain doctrine (override at project / user / packaged layers)
+- `.kushi/kushi-install.json` — profile manifest written by the installer
+
+Full docs: <https://gim-home.github.io/kushi/>

package/bin/cli.mjs

@@ -26,6 +26,7 @@ if (args.includes('--help') || args.includes('-h')) {
     --dest <path>       Override destination (relative for vscode, absolute for clawpilot)
     --force             Overwrite existing destination without asking
     --no-settings       Skip .vscode/settings.json update (vscode target only)
+    --no-instructions   Skip .github/copilot-instructions.md merge (vscode target only)
     --help, -h          Show this help
 
   After install, talk to Kushi:
@@ -55,6 +56,7 @@ const options = {
   dest: getFlag('--dest'),
   force: args.includes('--force'),
   noSettings: args.includes('--no-settings'),
+  noInstructions: args.includes('--no-instructions'),
   target,
   profile: getFlag('--profile'),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "3.12.1",
+  "version": "3.14.0",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     "src/",
     "plugin/",
     ".github/config/m365-auth.json.example",
-    ".github/config/m365-mutable.json.example"
+    ".github/config/m365-mutable.json.example",
+    ".github/copilot-instructions.kushi.md"
   ],
   "engines": {
     "node": ">=18.0.0"

package/plugin/instructions/crm-internal-vs-confirmed.instructions.md

@@ -8,7 +8,7 @@ applyTo: "**"
 
 **A CRM field value is NEVER automatically a confirmed fact.** A Dataverse field update records an internal decision; it does not prove the decision has been (a) communicated to the customer, (b) approved by deal desk / finance / legal, or (c) confirmed in a customer-facing transcript, note, email, or meeting artifact.
 
-Adapted into kushi from Nova doctrine (see `fde-grounding.instructions.md > CRITICAL: CRM Field Values vs. Confirmed Facts`).
+Adapted into kushi from prior doctrine (see `fde-grounding.instructions.md > CRITICAL: CRM Field Values vs. Confirmed Facts`).
 
 ## Three states every CRM-sourced assertion must be classified into
 

package/plugin/instructions/engagement-root-resolution.instructions.md

@@ -12,7 +12,7 @@ The **engagement-root** is the parent folder that contains all of the user's eng
 Resolve `<engagement-root>` in this order — first match wins:
 
 1. **`<USER_HOME>/.copilot/project-evidence.yml`** — read `engagement_root:` field (preferred).
-2. **`customer_workspace/FDEDocs/`** — if the user's workspace has this symlink, follow it. Common in NOVA-style installs.
+2. **`customer_workspace/FDEDocs/`** — if the user's workspace has this symlink, follow it. Common in FDE-style installs.
 3. **Ask the user** once and persist the answer to `<USER_HOME>/.copilot/project-evidence.yml engagement_root`.
 
 ## Live config location

package/plugin/learnings/crm.md

@@ -14,7 +14,7 @@ A live Dataverse REST probe afternoon of 2026-05-18 — `GET /new_frontierengine
 ### Why this was a defect
 The pull-crm SKILL `Resolution order` section already documented the 4-step sequence (title → account → recent-slice → ask) — but bootstrap was not actually executing it. It appears bootstrap relied on a WorkIQ-only / metadata-only probe that didn't reach Dataverse, then silently wrote `disabled: true`. That is the worst possible disposition: it pretends there is no CRM record, hides the failure from future refreshes, and the project loses CRM evidence entirely.
 
-Adjacent observation: Nova (sibling tool) does this resolution sequence in its bootstrap and would not have missed FE-2026-001791. The doctrine was present in kushi but the execution path was weak.
+Adjacent observation: equivalent sibling tooling performs this resolution sequence in its bootstrap and would not have missed FE-2026-001791. The doctrine was present in kushi but the execution path was weak.
 
 ### Fix
 - New HARD-rule instruction `plugin/instructions/crm-bootstrap-discovery.instructions.md` — `disabled: true` is ONLY allowed after the FULL 4-step REST sequence returns 0 AND the user is presented with top candidates. Auth/reachability failures must leave the boundary EMPTY (with `reason: 'crm-auth-unavailable-<date>'`) so the next refresh retries — NEVER write `disabled: true`.

package/plugin/learnings/onenote.md

@@ -98,7 +98,7 @@ The first eight `pull-onenote` versions used prose phrasing (`"sectionFileId <id
 
 1. WorkIQ does NOT honor `wdsectionfileid = <id>` as filter syntax — it routes to summary mode AND returns "OneNote internal properties not exposed as searchable fields" refusal text.
 2. The wdpartid GUIDs we observed in earlier runs were **URL fragments inside SharePoint Doc.aspx hyperlinks** that WorkIQ rendered as response footnotes — not search-index extractor outputs.
-3. The Nova-pattern (natural-language query naming the section + notebook by display name and the page by quoted title) is the actual working pattern. It returned a real verbatim body for the HCA `4/3 - HCA with Jay and Martin` page.
+3. The natural-language WorkIQ pattern (query naming the section + notebook by display name and the page by quoted title) is the actual working pattern. It returned a real verbatim body for the HCA `4/3 - HCA with Jay and Martin` page.
 4. **Body retrieval is non-deterministic** — the same 4/3 page returned a verbatim body at 19:42 PDT and `BODY-NOT-EXPOSED` at 19:48 PDT, same query, no edits. The M365 search index's exposure of OneNote bodies oscillates over time.
 5. **The blocker for months was the WorkIQ EULA.** Without `workiq accept-eula`, every OneNote query silently returns nothing useful. This is a one-time setup step, not a per-call gate.
 
@@ -112,7 +112,7 @@ The first eight `pull-onenote` versions used prose phrasing (`"sectionFileId <id
 
 **HCA result (2026-05-14):** 18 pages enumerated. 1 captured verbatim (4/3). 15 pending retry (BODY-NOT-EXPOSED). 2 enumeration-only (will be probed in Step B on next refresh).
 
-**Key lesson:** when a doctrine is grounded in pattern-matching against tool responses (e.g. "field names route to extractor"), validate it empirically against the live tool BEFORE shipping. The v3.7.8 doctrine was internally consistent and self-citing but never actually tested end-to-end — the 4/3 success that motivated v3.7.9 happened only after honestly retracting v3.7.8 and replicating the Nova workflow step-by-step.
+**Key lesson:** when a doctrine is grounded in pattern-matching against tool responses (e.g. "field names route to extractor"), validate it empirically against the live tool BEFORE shipping. The v3.7.8 doctrine was internally consistent and self-citing but never actually tested end-to-end — the 4/3 success that motivated v3.7.9 happened only after honestly retracting v3.7.8 and replicating the natural-language WorkIQ workflow step-by-step.
 
 
 ## 2026-05-14 — v3.7.9 retraction + v3.8.0 architectural pivot

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

@@ -342,7 +342,7 @@ Used ONLY when:
 - The previous run hit auth-required and retry-cooldown has not elapsed (24h), OR
 - The user explicitly requests WorkIQ-only for diagnostic comparison.
 
-Canonical WorkIQ Step B query (the Nova-pattern):
+Canonical WorkIQ Step B query (natural-language pattern):
 
 > Return the FULL readable content verbatim of the page titled `<title>` in my OneNote section `<one_sectionName>` in notebook `<one_notebookName>`. Do not summarize. Do not paraphrase. If the body is not exposed, say so explicitly with the literal phrase `BODY-NOT-EXPOSED` on its own line.
 

package/src/copilot-instructions.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const KUSHI_BEGIN_MARKER = '<!-- BEGIN kushi-agents (managed — do not edit between markers) -->';
+export const KUSHI_END_MARKER = '<!-- END kushi-agents -->';
+
+const MARKER_REGEX = new RegExp(
+  `${escapeRegex(KUSHI_BEGIN_MARKER)}[\\s\\S]*?${escapeRegex(KUSHI_END_MARKER)}`,
+);
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Wrap the source content in our managed-block markers.
+ * @param {string} source
+ * @returns {string}
+ */
+function buildBlock(source) {
+  return `${KUSHI_BEGIN_MARKER}\n${source.trim()}\n${KUSHI_END_MARKER}\n`;
+}
+
+/**
+ * Merge the Kushi section into .github/copilot-instructions.md using
+ * managed-block markers. Three behaviors:
+ *
+ *   - File missing       → create it with a brief header + our block
+ *   - File has markers   → replace block content in place (idempotent upgrade)
+ *   - File without markers → append our block at the end, preserving user content
+ *
+ * @param {string} projectRoot
+ * @param {string} sourcePkgDir – root of the npm package (for reading the source template)
+ * @returns {{ action: 'created' | 'updated-block' | 'appended-block' | 'unchanged', path: string }}
+ */
+export function mergeCopilotInstructions(projectRoot, sourcePkgDir) {
+  const srcTemplate = path.join(
+    sourcePkgDir,
+    '.github',
+    'copilot-instructions.kushi.md',
+  );
+
+  if (!fs.existsSync(srcTemplate)) {
+    return { action: 'unchanged', path: '', reason: 'source template missing' };
+  }
+
+  const sourceContent = fs.readFileSync(srcTemplate, 'utf-8');
+  const block = buildBlock(sourceContent);
+
+  const githubDir = path.join(projectRoot, '.github');
+  const targetPath = path.join(githubDir, 'copilot-instructions.md');
+  const displayPath = '.github/copilot-instructions.md';
+
+  fs.mkdirSync(githubDir, { recursive: true });
+
+  if (!fs.existsSync(targetPath)) {
+    const header = `# Copilot Instructions\n\n_This file is auto-loaded by GitHub Copilot Chat into every chat turn in this workspace._\n\n`;
+    fs.writeFileSync(targetPath, header + block, 'utf-8');
+    return { action: 'created', path: displayPath };
+  }
+
+  const existing = fs.readFileSync(targetPath, 'utf-8');
+
+  if (MARKER_REGEX.test(existing)) {
+    const updated = existing.replace(MARKER_REGEX, block.trimEnd());
+    if (updated === existing) {
+      return { action: 'unchanged', path: displayPath };
+    }
+    fs.writeFileSync(targetPath, updated, 'utf-8');
+    return { action: 'updated-block', path: displayPath };
+  }
+
+  const separator = existing.endsWith('\n\n')
+    ? ''
+    : existing.endsWith('\n')
+      ? '\n'
+      : '\n\n';
+  fs.writeFileSync(targetPath, existing + separator + block, 'utf-8');
+  return { action: 'appended-block', path: displayPath };
+}

package/src/main.mjs

@@ -14,6 +14,7 @@ import {
 import { promptForDestination } from './prompt.mjs';
 import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
+import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import {
   resolveProfile,
   makeIncludeFilter,
@@ -48,7 +49,7 @@ function resolveProfileForInstall(profileName) {
 
 /**
  * Orchestrator: prompt -> copy -> settings -> summary.
- * @param {{ dest?: string, force?: boolean, noSettings?: boolean, target?: string, profile?: string }} options
+ * @param {{ dest?: string, force?: boolean, noSettings?: boolean, noInstructions?: boolean, target?: string, profile?: string }} options
  */
 export async function main(options = {}) {
   const version = getVersion();
@@ -150,6 +151,22 @@ async function installVscode(options, resolved, version) {
     console.log('\n  Skipped .vscode/settings.json (--no-settings)');
   }
 
+  if (!options.noInstructions) {
+    const result = mergeCopilotInstructions(projectRoot, PKG_ROOT);
+    const labelByAction = {
+      'created': 'Created',
+      'updated-block': 'Updated managed Kushi block in',
+      'appended-block': 'Appended managed Kushi block to existing',
+      'unchanged': 'Unchanged',
+    };
+    if (result.action !== 'unchanged' || result.path) {
+      const label = labelByAction[result.action] || 'Touched';
+      console.log(`\n  ${label} ${result.path}`);
+    }
+  } else {
+    console.log('\n  Skipped .github/copilot-instructions.md (--no-instructions)');
+  }
+
   const { copied: projCopied, skipped: projSkipped } = copyProjectFiles(PKG_ROOT);
   if (projCopied.length > 0) {
     console.log('\n  Copied project files to .github/');

package/src/settings.mjs

@@ -4,12 +4,12 @@ import { modify, applyEdits, parse, printParseErrorCode } from 'jsonc-parser';
 import { SETTINGS_MAP } from './constants.mjs';
 
 /**
- * Merge Nova settings into .vscode/settings.json (JSONC-safe).
+ * Merge Kushi settings into .vscode/settings.json (JSONC-safe).
  * Creates the file and directory if they don't exist.
  * Additive-only: never removes existing entries.
  *
  * @param {string} projectRoot – the user's project root (cwd)
- * @param {string} destination – relative destination path (e.g. ".nova")
+ * @param {string} destination – relative destination path (e.g. ".kushi")
  * @returns {{ created: boolean, keysAdded: string[], keysUnchanged: string[] }}
  */
 export function mergeSettings(projectRoot, destination) {