kushi-agents 5.4.6 → 5.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.4.6",
+  "version": "5.5.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": {
@@ -16,9 +16,11 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@azure/identity": "^4.5.0",
     "@mozilla/readability": "^0.6.0",
     "jsdom": "^29.1.1",
-    "jsonc-parser": "^3.3.1"
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.6.0"
   },
   "keywords": [
     "vscode",
@@ -41,7 +43,9 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs src/global-wiki.test.mjs src/promote.test.mjs src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs",
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs src/global-wiki.test.mjs src/promote.test.mjs src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs plugin/runners/test/unit/*.test.mjs",
+    "test:runners": "node --test plugin/runners/test/unit/*.test.mjs",
+    "test:runners:integration": "node --test plugin/runners/test/integration/*.test.mjs",
     "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "eval": "pwsh plugin/skills/eval/run-evals.ps1 -Skill",
@@ -53,4 +57,5 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}
+

package/plugin/agents/kushi.agent.md

@@ -10,6 +10,8 @@ tools:
 
 Kushi is a multi-source evidence + state agentfor consulting / engineering engagements. It captures **snapshots** (current state of entities) and **streams** (timestamped events) from Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, and ADO, and renders an outcome-based **State** view.
 
+> **v5.5.0 — runner architecture.** All `bootstrap` / `refresh` / `pull-*` verbs dispatch to deterministic Node runners under `plugin/runners/*.mjs` (HTTP, paging, file IO, layout, ledger, week math, atomic writes). The SKILL.md files are thin pointers. The LLM only does discovery prompts (`discovery-prompts.instructions.md`), CSC rendering (`csc-rendering.instructions.md`), and Q&A — never HTTP or path templating. See `instructions/llm-vs-runner.instructions.md`. Migrate v4.x projects with `node plugin/runners/migrate-to-v550.mjs --project <P> --alias <A> [--dry-run]`.
+
 ## Install profiles
 
 Kushi ships in three profiles. The installed profile is recorded in `kushi-install.json` next to this agent file. Verbs that aren't installed for the current profile should be surfaced as: *"This verb requires the `<profile>` profile. Re-install with `npx kushi-agents --clawpilot --profile <profile> --force`."*

package/plugin/instructions/csc-rendering.instructions.md

@@ -0,0 +1,92 @@
+---
+name: "csc-rendering"
+version: "5.5.0"
+applyTo: "**/plugin/skills/**/SKILL.md"
+description: "How the LLM renders runner-captured evidence into Comprehensive Structured Capture (CSC) blocks under weekly/ + _Consolidated/."
+---
+
+# CSC rendering (kushi v5.5.0)
+
+In v5.5.0 **runners write raw evidence** to `Evidence/_shared/<source>/<id>/*.yml`,
+`Evidence/<alias>/<source>/<entity>/<YYYY-MM-DD>/items/<id>.yml`, and per-entity
+`index.md` previews. **The LLM renders those raw files** into Comprehensive
+Structured Capture (CSC) blocks under `Evidence/<alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md`
+and the cross-source roll-up under `Evidence/<alias>/_Consolidated/<YYYY-MM-DD>_consolidated.md`.
+
+## Canonical CSC block (every source)
+
+```
+## <Entity anchor> — <one-line subject>
+
+- **Source:** <source> · <crm|ado|email|teams|meetings|onenote|sharepoint>://...
+- **When:** <ISO datetime> (week <YYYY-MM-DD>)
+- **Who:** <name> <<email>>
+- **What:** <one-sentence factual summary>
+
+### Dates & Numbers
+- ...
+
+### Decisions
+- ...
+
+### Open questions
+- ...
+
+### Action items
+- [ ] <owner>: <ask> (due <date or "—">; source: <citation>)
+
+### Risks / Blockers / Dependencies
+- ...
+
+### Citations
+- <source>://<id> · <weekly path>:<line>
+```
+
+## Hard rules
+
+1. **Bullets only.** No prose paragraphs inside CSC blocks. Narrative belongs in the
+   meeting Detailed Discussion Summary or the consolidated roll-up.
+2. **One block per touched entity per week.** Re-runs upsert the same block by
+   entity anchor; never duplicate.
+3. **Every assertion carries a citation.** A bullet without a citation is a defect.
+4. **Don't invent dates, owners, or numbers.** If the runner's raw file doesn't
+   contain the value, the bullet says `(not in evidence)` — never a guess.
+5. **Internal vs confirmed (CRM).** Fields that only appear in internal Dataverse
+   notes render with the trailing tag `(internal Dataverse note)`. Customer-confirmed
+   fields appear without the tag and cite a customer-authored note/email/transcript.
+6. **Verbatim is mandatory for meetings.** Per-meeting CSC blocks MUST include
+   the Transcript Walk-Through section (chronological verbatim with timestamps)
+   when the runner reports `captured`. If the runner reports `body-unavailable`,
+   render a stub block citing the deferred-retry queue.
+
+## Source → required CSC sections
+
+| Source | Required sections beyond base |
+|--------|------------------------------|
+| crm | Dates & Numbers (stage transitions); Decisions (won/lost/stage changes) |
+| ado | Dates & Numbers (state changes, sprint changes); Decisions (closed/resolved) |
+| email | Decisions; Action items; (Citations include `internetMessageId`) |
+| teams | Decisions; Action items; (Citations include chat-id + message-id) |
+| meetings | Detailed Discussion Summary; Transcript Walk-Through; Next Steps (distinct from Action items); Risks/Blockers/Dependencies |
+| onenote | Decisions; Open questions; (Citations include `wdsectionfileid` + `wdpartid`) |
+| sharepoint | Dates & Numbers (file edit counts); Citations include `siteId/itemId` |
+
+## What the LLM does NOT do
+
+- Compute file paths for weekly/_Consolidated outputs — `lib/layout.mjs` does.
+- Re-fetch evidence — only the runner pulls.
+- Skip Citations sections to save space — they are mandatory.
+
+## Re-run / upsert semantics
+
+The LLM rewrites the entire weekly CSC file on every render — never appends. The
+runner's `_ledger.yml` is the source of truth for "is this cell captured", and
+the weekly CSC file is regenerated from the current set of `items/<id>.yml`.
+
+## Consolidation
+
+`Evidence/<alias>/_Consolidated/<YYYY-MM-DD>_consolidated.md` is generated from
+all `Evidence/<alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md` files.
+Order: meetings → email → teams → onenote → sharepoint → crm → ado.
+
+See `instructions/llm-vs-runner.instructions.md` for the broader boundary.

package/plugin/instructions/discovery-prompts.instructions.md

@@ -0,0 +1,70 @@
+---
+name: "discovery-prompts"
+version: "5.5.0"
+applyTo: "**/plugin/skills/**/SKILL.md"
+description: "The canonical LLM prompts for discovering integration IDs and boundary entities so the runners have something to pull."
+---
+
+# Discovery prompts (kushi v5.5.0)
+
+`bootstrap.mjs` scaffolds blank `integrations.yml` and `boundaries.yml` files.
+**The LLM is responsible for filling them in** via short, scoped discovery
+prompts to the user (or via WorkIQ where the user has granted access).
+
+## Hard rules
+
+1. **One question at a time.** Never bulk-ask "give me crm + ado + folders + chats
+   + sections + sites" — fatigue produces wrong answers. Ask per source, in the
+   order listed below.
+2. **Stop after each answer and write it to disk.** Use the runner's
+   `update-config` helper or hand-edit the yml; never hold values in chat memory
+   across turns.
+3. **Suggest, don't guess.** Use WorkIQ (`workiq ask -q "..."`) to suggest likely
+   `request_id`s, folder names, chat topics, etc. Always present them as
+   candidates the user must confirm — never pre-populate as facts.
+4. **Boundaries are per-user.** When discovering email folders or Teams chats,
+   the answers go under `Evidence/<alias>/boundaries.yml`, NOT the shared
+   `integrations.yml`.
+
+## Recommended order
+
+| Phase | Source | Prompt | Lands in |
+|-------|--------|--------|----------|
+| 1 | crm | "What is the CRM request_id (Dataverse Engagement ID) for this project? You can usually find it on the engagement record URL." | `integrations.yml#crm.request_id` |
+| 2 | ado | "What is the ADO engagement work-item id?" | `integrations.yml#ado.engagement_id` |
+| 3 | sharepoint | "Which SharePoint site(s) host project content? Paste the URLs." | `integrations.yml#sharepoint.sites[]` |
+| 4 | email | "Which mailbox folder(s) hold this project's email? Common names: '<customer name>', '<engagement code>', 'Project Inbox'." | `Evidence/<alias>/boundaries.yml#email.folders[]` |
+| 5 | teams | "Paste chat-ids for the 1:1s and group chats that discuss this project. Use `m365 list_chats` to find them." | `Evidence/<alias>/boundaries.yml#teams.chats[]` |
+| 6 | meetings | "List joinUrls for recurring or key meetings (or leave blank to auto-detect from calendar)." | `Evidence/<alias>/boundaries.yml#meetings.joinUrls[]` |
+| 7 | onenote | "Paste OneNote section URLs. The runner will resolve them to section_file_ids via map-first (`m365-mutable.json#knownSections`)." | `Evidence/<alias>/boundaries.yml#onenote.section_file_ids[]` |
+
+## Discovery via WorkIQ (suggest-mode)
+
+When the user can't immediately answer:
+
+```
+workiq ask -q "Suggest mailbox folders likely related to <project name>"
+workiq ask -q "Find Teams chats whose topic or recent messages mention <project name>"
+workiq ask -q "List OneNote sections under <notebook> matching <project>"
+```
+
+Present results as a numbered list; the user picks. Never write to boundaries
+without explicit confirmation.
+
+## What discovery does NOT do
+
+- Call the runner. Once values are written to `integrations.yml` /
+  `boundaries.yml`, the user (or `refresh-project`) decides when to run.
+- Discover for other users. Discovery only fills the current `<alias>`'s
+  `boundaries.yml`. Each user runs their own discovery.
+- Fall back to Graph/m365_* tools as "rescue" — WorkIQ-first doctrine still
+  applies for project capture.
+
+## Re-discovery
+
+When `refresh-project` reports `partial` or `no-activity` for a source over
+several weeks, re-run discovery for that source — the user may have created
+new folders, chats, or sections that aren't in boundaries.yml yet.
+
+See `instructions/llm-vs-runner.instructions.md` and
+`instructions/csc-rendering.instructions.md`.

package/plugin/instructions/llm-vs-runner.instructions.md

@@ -0,0 +1,90 @@
+---
+name: "llm-vs-runner"
+version: "5.5.0"
+applyTo: "**/plugin/skills/**/SKILL.md"
+description: "The v5.5.0 boundary contract between LLM markdown skills and deterministic Node runners under plugin/runners/."
+---
+
+# LLM-vs-runner boundary (kushi v5.5.0)
+
+## Doctrine
+
+In v5.5.0 every formerly-LLM-driven pull/refresh/bootstrap pipeline is split into two halves:
+
+| Half | Implementation | Responsibilities |
+|------|---------------|------------------|
+| **Runner** | `plugin/runners/*.mjs` + `plugin/runners/lib/*` | HTTP, paging, auth, file IO, layout, ledger, dedup, hash compare, atomic writes, ISO-week math, retry/defer queue, fixture mode. |
+| **LLM (SKILL.md)** | Markdown skill files under `plugin/skills/` | Discovery prompts, judgment on `partial` / `no-activity` / `body-unavailable`, user-facing summarization, CSC rendering, picking `--week` / `--source` / `--entity` for runs. |
+
+## Hard rules
+
+1. **No HTTP from chat.** The LLM MUST NOT call Graph, Dataverse, ADO REST, OneNote, SharePoint REST, or `m365_*` tools as a way of capturing project evidence. Discovery via WorkIQ is allowed; capture is runner-only.
+2. **No hand-rolled file paths.** The LLM MUST NOT compute Evidence/ paths. Use the runner's reported `files_written[]`.
+3. **No hand-rolled week math.** Always pass `--week YYYY-MM-DD` (Monday) or omit; never derive paths from dates in chat.
+4. **No PowerShell rescue scripts.** If a runner reports `failed`, fix the runner or its config — never paper over with a one-off script that writes Evidence/.
+5. **One-line JSON contract.** Every runner emits exactly one JSON line on stdout as its last line. The orchestrator (`refresh.mjs`) parses this; sub-agents must too.
+6. **Exit codes are stable.** `0` = ok/partial/no-activity (data is consistent), `1` = retryable, `2` = config error, `3` = auth error.
+
+## Runner CLI contract
+
+Every `pull-*.mjs`:
+
+```
+node plugin/runners/<source>.mjs --project <P> --alias <A> --entity <E> [--week YYYY-MM-DD] [--dry-run] [--force] [--fixture <path>]
+```
+
+`refresh.mjs` adds: `--source`, `--mode bootstrap|refresh`, `--max-parallel N`, `--fixture-dir <dir>`.
+
+## Status taxonomy (runner-emitted)
+
+- `captured` — items pulled and written.
+- `partial` — some items pulled, some failed; `errors[]` populated.
+- `no-activity` — zero items in the window (legit empty week).
+- `body-unavailable` — Graph returned shells but body fetch failed (meetings/onenote may defer).
+- `deferred` — retry enqueued; runner will retry after `RETRY_MIN_AGE_MIN.<source>` minutes.
+- `failed` — non-retryable failure for this cell.
+
+## What the LLM still owns
+
+- Asking the user for `request_id`, `engagement_id`, folder names, chat ids, joinUrls, section URLs, site URLs, when missing.
+- Rendering consolidated weekly CSC views over the runner-written `_shared/` and `<alias>/` files.
+- Diagnosing patterns across multiple runs (e.g. "all OneNote pages came back `body-unavailable` — likely the section was a triage section and pages have been moved").
+- Writing summaries, action items, and human reports under `Evidence/<alias>/refresh-reports/` and `_Consolidated/`.
+
+## Forbidden phrasings in SKILL.md
+
+- "First, fetch the messages via `m365_list_chat_messages`…" — runner does this.
+- "Compute the Monday of the ISO week…" — runner does this.
+- "Write the captured items to `Evidence/<alias>/<source>/<entity>/<week>/items.yml`…" — runner does this.
+- "If the body is unavailable, write a placeholder…" — runner emits `body-unavailable` and the orchestrator decides.
+
+## Self-check coverage (Phase 4)
+
+Probes D44–D47 will assert:
+- D44: every `pull-*` and `bootstrap-project` / `refresh-project` SKILL.md references its corresponding `.mjs` runner.
+- D45: no SKILL.md contains forbidden phrasings (HTTP verbs, manual path templates, week-math snippets).
+- D46: every runner has integration tests under `plugin/runners/test/integration/`.
+- D47: every runner emits a stdout JSON line on the happy path under fixture mode.
+
+## Legacy probe carve-out (v5.5.1)
+
+The following pre-v5.5.0 probes assumed SKILL.md inlined doctrine cites, validation loops, and orchestrator checklists. In v5.5.0+ those concerns live in the runner + its tests, so the probes **skip thin-pointer skills** (the same nine listed in `D44` `$v550Map`):
+
+| Probe | What it used to require | Where it lives now |
+|-------|------------------------|--------------------|
+| C12 | `evidence-thoroughness` cite in pull-* SKILL.md | runner: thoroughness retry loop |
+| D2  | `snapshot-vs-stream.instructions.md` cite in pull-* SKILL.md | runner JSDoc + integration tests |
+| D3  | "WorkIQ" in pull-* SKILL.md Tools section | runner's discovery code path |
+| D6  | `side-by-side-config` cite in bootstrap/refresh SKILL.md | runner: config-write helper |
+| D11 | `verbatim-by-default` + v3.7.6 contracts cite | runner: `lib/verbatim.mjs` + tests |
+| D12 | `m365-id-registry` tokens in SKILL.md | runner: `lib/id-registry.mjs` |
+| D17 | `fuzzy-disambiguation` cite in name→ID skills | runner: name→ID resolver |
+| D18 | `per-source-verification-gate` cite | runner: gate check before write |
+| D26 | `issue-recovery` cite | runner: error-classification helper |
+| D30.references-layout | `Load references/...` pointer when `references/` exists | runner loads its own packs |
+| D30.checklist-orchestrators | `- [ ]` items in orchestrator SKILL.md | `refresh.mjs` orchestrates |
+| D30.validation-loop | `## Validation loop` in writer SKILL.md | runner integration tests |
+| D34.retrofit-clean | skill-checker `--retrofit` non-additive gaps == 0 | n/a for thin-pointers |
+
+Non-thin-pointer skills (e.g. `pull-loop`, `pull-misc`, `aggregate-project`, `consolidate-evidence`) still get all of these checks.
+

package/plugin/runners/bootstrap.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// plugin/runners/bootstrap.mjs
+// Deterministic project scaffold. Idempotent. No HTTP.
+//
+// Creates (only if missing):
+//   <project>/integrations.yml                  ← project-shared template
+//   <project>/project-info.md                   ← project-shared placeholder
+//   <project>/external-links.yml                ← project-shared empty
+//   <project>/contributors.yml                  ← project-shared empty
+//   <project>/Evidence/                         ← shared evidence root
+//   <project>/Evidence/_shared/{crm,ado,sharepoint}/  ← project-scoped capture dirs
+//   <project>/Evidence/<alias>/boundaries.yml   ← per-user template
+//   <project>/Evidence/<alias>/external-links.local.yml  ← per-user empty
+//   <project>/Evidence/<alias>/{_discovery,_deferred-retries,refresh-reports,
+//                               email,teams,meetings,onenote,sharepoint,
+//                               crm-notes,ado-notes}/   ← per-user capture dirs
+//
+// Usage:
+//   node plugin/runners/bootstrap.mjs --project <P> --alias <A> [--force] [--dry-run]
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import YAML from 'yaml';
+import {
+  projectRoot, evidenceRoot, sharedRoot, sharedSourceDir,
+  aliasRoot, projectSharedFile, userFile, USER_FILES,
+} from './lib/layout.mjs';
+import { writeAtomic, pathExists } from './lib/evidence.mjs';
+
+function parseArgs(argv) {
+  const args = { force: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') args.project = argv[++i];
+    else if (a === '--alias') args.alias = argv[++i];
+    else if (a === '--force') args.force = true;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+  }
+  return args;
+}
+
+function help() {
+  return `Usage: node bootstrap.mjs --project <P> --alias <A> [--force] [--dry-run]`;
+}
+
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
+
+const INTEGRATIONS_TEMPLATE = {
+  crm: { instance: 'https://iscrm.crm.dynamics.com', table: 'incidents', request_id: null, record_id: null },
+  ado: { organization: 'IndustrySolutions', project: 'IS Engagements', apiVersion: '7.1', engagement_id: null },
+  sharepoint: { allowed_tenants: [] },
+};
+
+const BOUNDARIES_TEMPLATE = {
+  email: { mailbox: null, folders: [] },
+  teams: { chats: [] },
+  meetings: { joinUrls: [] },
+  onenote: { section_file_ids: [] },
+  sharepoint: { sites: [] },
+};
+
+const PROJECT_INFO_TEMPLATE = `# Project info
+
+- name:
+- customer:
+- engagement_id:
+- ado_root_work_item:
+- crm_request_id:
+- started:
+- contributors:
+`;
+
+const SHARED_DIRS = ['_shared/crm', '_shared/ado', '_shared/sharepoint'];
+const USER_DIRS = [
+  USER_FILES.discovery,
+  USER_FILES.deferredRetries,
+  USER_FILES.refreshReports,
+  'email', 'teams', 'meetings', 'onenote', 'sharepoint',
+  'crm-notes', 'ado-notes',
+];
+
+async function ensureDir(dir, dryRun, log) {
+  if (await pathExists(dir)) { log.existed.push(dir); return; }
+  log.created.push(dir);
+  if (!dryRun) await fs.mkdir(dir, { recursive: true });
+}
+
+async function ensureFile(file, content, { dryRun, force, log }) {
+  const exists = await pathExists(file);
+  if (exists && !force) { log.existed.push(file); return; }
+  log.created.push(file);
+  if (!dryRun) await writeAtomic(file, content, { skipIfUnchanged: !force });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log(help()); return 0; }
+  if (!args.project || !args.alias) {
+    console.error(help());
+    emit({ status: 'failed', errors: [{ signature: 'bad-args', message: 'required: --project --alias' }] });
+    return 2;
+  }
+
+  const root = projectRoot(args.project);
+  const log = { created: [], existed: [] };
+
+  // Project root
+  await ensureDir(root, args.dryRun, log);
+
+  // Project-shared files
+  await ensureFile(projectSharedFile(args.project, 'integrations'), YAML.stringify(INTEGRATIONS_TEMPLATE), { dryRun: args.dryRun, force: args.force, log });
+  await ensureFile(projectSharedFile(args.project, 'projectInfo'), PROJECT_INFO_TEMPLATE, { dryRun: args.dryRun, force: args.force, log });
+  await ensureFile(projectSharedFile(args.project, 'externalLinks'), YAML.stringify({ links: [] }), { dryRun: args.dryRun, force: args.force, log });
+  await ensureFile(projectSharedFile(args.project, 'contributors'), YAML.stringify({ contributors: [args.alias] }), { dryRun: args.dryRun, force: args.force, log });
+
+  // Evidence + _shared
+  await ensureDir(evidenceRoot(args.project), args.dryRun, log);
+  await ensureDir(sharedRoot(args.project), args.dryRun, log);
+  for (const sub of SHARED_DIRS) await ensureDir(path.join(evidenceRoot(args.project), sub), args.dryRun, log);
+
+  // Alias root + per-user dirs
+  await ensureDir(aliasRoot(args.project, args.alias), args.dryRun, log);
+  for (const sub of USER_DIRS) await ensureDir(path.join(aliasRoot(args.project, args.alias), sub), args.dryRun, log);
+
+  // Per-user files
+  await ensureFile(userFile(args.project, args.alias, 'boundaries'), YAML.stringify(BOUNDARIES_TEMPLATE), { dryRun: args.dryRun, force: args.force, log });
+  await ensureFile(path.join(aliasRoot(args.project, args.alias), 'external-links.local.yml'), YAML.stringify({ links: [] }), { dryRun: args.dryRun, force: args.force, log });
+  await ensureFile(path.join(aliasRoot(args.project, args.alias), '_ledger.yml'), YAML.stringify({ entries: {} }), { dryRun: args.dryRun, force: args.force, log });
+
+  emit({
+    status: 'ok',
+    project: root,
+    alias: args.alias,
+    created: log.created.map(p => path.relative(root, p) || '.'),
+    existed: log.existed.map(p => path.relative(root, p) || '.'),
+    dry_run: args.dryRun,
+  });
+  return 0;
+}
+
+main().then(code => { process.exitCode = code; }).catch(e => {
+  emit({ status: 'failed', errors: [{ message: e.message }] });
+  process.exit(1);
+});

package/plugin/runners/lib/config.mjs

@@ -0,0 +1,108 @@
+// plugin/runners/lib/config.mjs
+// Load + merge project-shared + per-user config files.
+// integrations.yml (project) ∪ boundaries.yml (per-user) — per-user wins on conflicts.
+// external-links.yml (project) ∪ external-links.local.yml (per-user).
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import {
+  projectSharedFile, userFile, aliasRoot, projectRoot,
+} from './layout.mjs';
+
+async function readYamlIfExists(p) {
+  try {
+    const s = await fs.readFile(p, 'utf8');
+    return YAML.parse(s) ?? {};
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw new Error(`config: failed to parse YAML ${p}: ${e.message}`);
+  }
+}
+
+/** Deep-merge: per-user wins, arrays from per-user replace (do not concat) by default. */
+export function mergeConfigs(shared, user, { arrayMode = 'replace' } = {}) {
+  if (shared == null) return clone(user);
+  if (user == null) return clone(shared);
+  if (Array.isArray(shared) || Array.isArray(user)) {
+    return arrayMode === 'concat'
+      ? clone([...(Array.isArray(shared) ? shared : []), ...(Array.isArray(user) ? user : [])])
+      : clone(Array.isArray(user) ? user : shared);
+  }
+  if (typeof shared !== 'object' || typeof user !== 'object') return clone(user);
+  const out = { ...shared };
+  for (const k of Object.keys(user)) {
+    out[k] = mergeConfigs(shared[k], user[k], { arrayMode });
+  }
+  return clone(out);
+}
+
+function clone(v) { return v == null ? v : JSON.parse(JSON.stringify(v)); }
+
+/**
+ * Load project-shared integrations.yml. Returns {} if absent.
+ */
+export async function loadProjectIntegrations(project) {
+  return (await readYamlIfExists(projectSharedFile(project, 'integrations'))) ?? {};
+}
+
+/**
+ * Load per-user boundaries.yml. Returns {} if absent.
+ */
+export async function loadUserBoundaries(project, alias) {
+  return (await readYamlIfExists(userFile(project, alias, 'boundaries'))) ?? {};
+}
+
+/**
+ * Load merged config for (project, alias):
+ *   { integrations, boundaries, merged, externalLinks, conflicts }
+ * - merged: integrations ∪ boundaries (per-user wins per key)
+ * - conflicts: list of keys where both sides set a primitive value differently
+ */
+export async function loadConfig(project, alias) {
+  const integrations = await loadProjectIntegrations(project);
+  const boundaries   = await loadUserBoundaries(project, alias);
+  const externalLinksProject = (await readYamlIfExists(projectSharedFile(project, 'externalLinks'))) ?? {};
+  const externalLinksUser    = (await readYamlIfExists(path.join(aliasRoot(project, alias), 'external-links.local.yml'))) ?? {};
+
+  const conflicts = collectConflicts(integrations, boundaries, []);
+  const merged = mergeConfigs(integrations, boundaries);
+  const externalLinks = mergeConfigs(externalLinksProject, externalLinksUser);
+
+  return { integrations, boundaries, merged, externalLinks, conflicts };
+}
+
+function collectConflicts(a, b, prefix) {
+  const out = [];
+  if (a == null || b == null) return out;
+  if (Array.isArray(a) || Array.isArray(b)) return out;
+  if (typeof a !== 'object' || typeof b !== 'object') {
+    if (a !== b) out.push({ path: prefix.join('.'), shared: a, user: b });
+    return out;
+  }
+  for (const k of Object.keys(b)) {
+    if (k in a) out.push(...collectConflicts(a[k], b[k], [...prefix, k]));
+  }
+  return out;
+}
+
+/**
+ * Validate that a project root exists and looks like a kushi customer_docs project
+ * (has either integrations.yml at root or an Evidence/ folder).
+ */
+export async function assertProject(project) {
+  const root = projectRoot(project);
+  try { await fs.stat(root); } catch { throw new Error(`config: project not found: ${root}`); }
+  const integrations = projectSharedFile(project, 'integrations');
+  const evidence = path.join(root, 'Evidence');
+  const hasI = await pathExists(integrations);
+  const hasE = await pathExists(evidence);
+  if (!hasI && !hasE) {
+    throw new Error(`config: ${root} is not a kushi project (no integrations.yml or Evidence/ found)`);
+  }
+  return root;
+}
+
+async function pathExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}

package/plugin/runners/lib/dedup.mjs

@@ -0,0 +1,42 @@
+// plugin/runners/lib/dedup.mjs
+// Entity-key hashing + stable item-id derivation for dedup.
+
+import crypto from 'node:crypto';
+
+/** Stable canonical entity key. */
+export function entityKey(source, entity, week = null) {
+  const e = String(entity).trim();
+  const base = `${source}::${e}`;
+  return week ? `${base}::${week}` : base;
+}
+
+/** Short stable hash (12 hex chars) of any string. */
+export function shortHash(s) {
+  return crypto.createHash('sha256').update(String(s)).digest('hex').slice(0, 12);
+}
+
+/**
+ * Compute a stable id for an item using the most-stable available fields,
+ * falling back to a content hash. Used to dedup captures across reruns.
+ */
+export function itemId(item) {
+  for (const f of ['id', 'graphId', 'itemId', 'messageId', 'eventId', 'recordId', 'pageId']) {
+    if (item && typeof item[f] === 'string' && item[f]) return item[f];
+  }
+  return shortHash(JSON.stringify(item ?? null));
+}
+
+/**
+ * Dedup an array of items by itemId, keeping first occurrence.
+ */
+export function dedupItems(items) {
+  const seen = new Set();
+  const out = [];
+  for (const it of items) {
+    const id = itemId(it);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(it);
+  }
+  return out;
+}