kushi-agents 3.4.2 → 3.13.0

package/plugin/templates/snapshot/onenote-page.template.md

@@ -1,28 +1,97 @@
-# OneNote Page: <Page Title>
+---
+page_title:    "<page title>"
+section:       "<one_sectionName>"
+notebook:      "<notebookName>"
+section_id:    "<one_sectionFileId>"
+wdpartid:      "<wdpartid from enumerate>"
+last_modified: "<as reported by WorkIQ>"
+last_status:   "captured | BODY-NOT-EXPOSED | user-pasted | enumeration-only"
+attempts:      <int>
+last_attempt:  "<ISO-8601>"
+captured_at:   "<ISO-8601 if captured/user-pasted, else empty>"
+---
+
+# OneNote Snapshot — Page: <page title>
+
+- **Project:** <project>
+- **Section:** <notebookName> / <one_sectionName> (`<one_sectionFileId>`)
+- **Page wdpartid:** `<wdpartid>`
+- **Last modified:** <as reported by WorkIQ>
+- **Capture status:** `<last_status>`
+- **Attempts:** <int>
+- **Last attempt:** <ts>
+- **Source basis:** WorkIQ enumerate + per-page verbatim probe (pull-onenote v2.5.0). Graph `/me/onenote/*` skipped per workspace policy. Per-page retry registry: `.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>.one_pages`.
+
+<!-- IF last_status == "captured" or "user-pasted" -->
+
+## AI Narrative Summary
+
+<3+ paragraphs covering what the page is about, structure, key points, anything noteworthy.>
+
+## Body (verbatim)
+
+<full page body — NOT a summary, NOT a paraphrase. Reproduce content exactly as exposed by the enterprise retrieval surface, or exactly as the user pasted it.>
+
+## Source Basis
+
+- Tool used: WorkIQ (canonical Step B query) | user-paste
+- Captured at: <ISO-8601>
+
+<!-- ELSE IF last_status == "BODY-NOT-EXPOSED" -->
+
+## Page body
+
+❌ **page-body-unavailable: WorkIQ returned BODY-NOT-EXPOSED on attempt <N>.**
+
+> Per `pull-onenote` v2.5.0 § "Empirical contract": WorkIQ OneNote body retrieval is non-deterministic — the same page may return a body on a later refresh. This page IS registered for retry in `.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>.one_pages` and will be re-attempted on every refresh until `last_status` becomes `captured` or `user-pasted`. Inferring the page contents from adjacent emails or chat traffic is forbidden.
+
+### next_step
+
+- (automatic) Next refresh will retry the verbatim body fetch (attempt <N+1>).
+- (manual) Paste the verbatim page body to upgrade to `user-pasted`. Update the registry entry's `last_status` and `captured_at` accordingly, and append an AI Narrative Summary above the body.
+
+### Page metadata
+
+| Field | Value |
+|---|---|
+| Page title | `<title>` |
+| Section | <notebook> / <section> |
+| wdpartid | `<wdpartid>` |
+| Last modified (per WorkIQ) | <date> |
+| Capture status | `BODY-NOT-EXPOSED` |
+| Attempts so far | <N> |
+| Last attempt | <ts> |
+
+## Source Basis
+
+- Tool used: WorkIQ (Step A enumerate succeeded; Step B per-page probe returned BODY-NOT-EXPOSED).
+- Graph `/me/onenote/*` not attempted — workspace policy blocks `Notes.Read.All` admin consent.
+
+<!-- ELSE IF last_status == "enumeration-only" -->
+
+## Page body
+
+⚠️ **enumeration-only** — page enumerated in the section index, but no per-page body fetch attempted yet.
+
+> Per `pull-onenote` v2.5.0: this is a transient state. The next refresh run will attempt Step B and either upgrade to `captured` or downgrade to `BODY-NOT-EXPOSED`.
+
+### next_step
+
+- (automatic) Next refresh will attempt the verbatim body fetch.
+
+## Source Basis
+
+- Tool used: WorkIQ Step A enumerate only. No Step B attempted in this run.
 
-> **Snapshot.** Replaced on every refresh.
-> Section: <section name>
-> Notebook: <notebook name>
-> Last modified: <YYYY-MM-DD HH:mm TZ> by <author>
-> Last fetched: <YYYY-MM-DD HH:mm TZ>
-
-## Source Basis
-- Tool used: <WorkIQ | Graph (often 40001) | user-paste>
-- Mutable hint: `one_sectionFileId` = <id>
-
-## Body (verbatim)
-
-<full page body — NOT a summary, NOT a paraphrase. Reproduce content as faithfully as the source allows.>
-
----
-
-> Edits to this page during refresh windows are captured in `stream/<week>_onenote-stream.md`.
 
 ## Validation
 
-> Thoroughness detector checklist — per `thoroughness-detector.instructions.md`.
+Per `thoroughness-detector.instructions.md`, the writer must tick all that apply before saving:
 
-- [ ] bodies-present (full body, not just metadata/link)
-- [ ] metadata-fields-complete
-- [ ] no-link-only-stubs
-- [ ] coverage-notes-explain-any-gaps
+- [ ] yaml front-matter present with `page_title`, `section`, `notebook`, `section_id`, `wdpartid`, `last_status`, `attempts`, `last_attempt`
+- [ ] `last_status` is one of: `captured` | `BODY-NOT-EXPOSED` | `user-pasted` | `enumeration-only`
+- [ ] If `last_status == captured` or `user-pasted`: AI Narrative Summary (3+ paragraphs) AND verbatim Body section are present and non-empty
+- [ ] If `last_status == BODY-NOT-EXPOSED`: explicit marker, `next_step` block, and metadata table all present; NO inferred or paraphrased body content
+- [ ] If `last_status == enumeration-only`: explicit transient marker present; NO body content of any kind
+- [ ] Page is registered in `.project-evidence/m365/m365-mutable.json#knownSections.<projectKey>.one_pages` with matching `last_status` and `attempts`
+- [ ] No fabrication: nothing in this file came from adjacent emails, chats, or other sources to "fill in" what WorkIQ did not return

package/plugin/templates/weekly/meetings-stream.template.md

@@ -58,7 +58,8 @@ _2–4 sentence overview of meetings this week for this project: how many, key t
 - **Actual Attendees:** {{PEOPLE}}
 - **No-shows:** {{PEOPLE}}
 - **Purpose / Stated Agenda:** _one or two paragraphs — what this meeting was for, what was on the agenda, what was the framing._
-- **Source basis:** _transcript (Copilot recap) | transcript (raw VTT) | reconstructed from meeting chat (no transcript) | partial — chat + recap only._
+- **Source basis:** _transcript (raw VTT) | transcript (WorkIQ summary, not raw) | reconstructed from meeting chat (no transcript) | partial — chat + recap only | ❌ source-expired-or-unrecoverable._
+- **Verbatim folder (REQUIRED):** `Evidence/<alias>/meetings/verbatim/<YYYY-MM-DD-HHMM>_<slug>/` — raw immutable capture (chat-messages.json/md, transcript.vtt or transcript-source.md, recording-url.txt, attachments/, coverage.md). All assertions below cite files inside this folder per `meetings-verbatim-required.instructions.md`.
 
 #### Detailed Discussion Summary
 _Multi-paragraph narrative of what was actually discussed end-to-end. Do NOT compress to 3 bullets. Include who said what, what context emerged, what was challenged, what was confirmed. This is the section that lets a State-file reader reconstruct the meeting without watching the recording._
@@ -99,10 +100,11 @@ _Every substantive exchange. Collapse only routine acks ("got it", "thanks"). Fo
 - _e.g._ Customer requested executive sponsor reciprocal commitment from Microsoft.
 
 #### Artifacts
-- Recording: {{URL}}
-- Transcript: {{URL}}
-- Copilot recap: {{URL}}
-- Shared files / decks / docs: {{URL list}}
+- **Verbatim folder:** `Evidence/<alias>/meetings/verbatim/{{YYYY-MM-DD-HHMM}}_{{slug}}/`
+- Recording (live URL — expires): {{URL}} _(also persisted in verbatim/recording-url.txt)_
+- Transcript: {{URL}} _(raw VTT in verbatim/transcript.vtt if available)_
+- Copilot recap: {{URL}} _(in verbatim/recap-card.md)_
+- Shared files / decks / docs: {{URL list}} _(downloaded copies in verbatim/attachments/)_
 
 #### Coverage Notes
 - _What was retrievable vs what wasn't_ — e.g. "Transcript not generated; reconstructed from 47-message chat thread + Copilot recap card. Decisions and Action Items high confidence; Transcript Walk-Through derived from chat exchange timestamps."
@@ -179,4 +181,7 @@ _Generated from Teams meetings (calendar + transcripts + recordings + Copilot re
 - [ ] action-items-have-owner-and-due
 - [ ] transcript-walk-through-present
 - [ ] no-link-only-stubs
-- [ ] coverage-notes-explain-any-gaps
+- [ ] coverage-notes-explain-any-gaps
+- [ ] verbatim-folder-exists-per-meeting (REQUIRED v3.10.0 — sibling `verbatim/<YYYY-MM-DD-HHMM>_<slug>/` dir per meeting block, enforced by self-check D13.a)
+- [ ] verbatim-folder-non-empty (at least chat-messages.json OR transcript.* OR transcript-source.md beyond captured-at.txt — D13.b)
+- [ ] transcript-class-file-present (REQUIRED v3.10.1 — `transcript.vtt` OR `transcript.txt` OR `transcript-source.md` non-empty; chat alone is NOT a transcript — D13.c). Run the exhaustive cascade per `meetings-verbatim-required.instructions.md`: `m365_get_transcript` → Graph REST `/onlineMeetings/.../transcripts/.../content` → `m365_get_facilitator_notes` → WorkIQ strict full-text pull → recording download.

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/');