kushi-agents 5.2.0 → 5.3.0

package/README.md

@@ -154,6 +154,30 @@ Rules stored in `Evidence/<alias>/State/CLAUDE.md`. Read by `build-state`, `ask-
 
 ---
 
+## Global wiki (v5.3.0+)
+
+A per-user **global wiki** at `~/.kushi-global/State/` for cross-engagement knowledge — same Karpathy shape as a project `State/`, marked `scope: global`.
+
+```bash
+kushi global init                     # scaffold ~/.kushi-global/State/
+kushi global status                   # counts + last-modified summary
+kushi global ask "what's our confidence ladder pattern?"
+kushi global lint                     # privacy + structure pass
+
+# Project → global is explicit-only:
+kushi promote <project> <answer-page>          # refuses if identifiers detected
+kushi promote <project> <answer-page> --force  # redacts + writes target + back-link
+
+# Routing under ask-project:
+kushi ask <project> "..."                     # project-first (default)
+kushi ask <project> "..." --global            # global-first
+kushi ask <project> "..." --project-only      # suppress global
+```
+
+The global root honors `$KUSHI_GLOBAL_ROOT` (used by tests). There is no auto-promotion path — privacy is always your call. See `plugin/instructions/global-wiki.instructions.md` + `plugin/instructions/multi-wiki-routing.instructions.md`.
+
+---
+
 ## Three install profiles
 
 Kushi ships in three tiers. Pick how much you take — the default (`standard`) matches v2.x behavior end-to-end.

package/bin/cli.mjs

@@ -17,15 +17,55 @@ if (args.length > 0 && SKILL_VERBS.has(args[0])) {
 
 // ── lint verb (v5.1.0+) ──────────────────────────────────────────────────────
 if (args.length > 0 && args[0] === 'lint') {
+  if (args.includes('--global')) {
+    const { runGlobalLint } = await import('../src/global-wiki-cli.mjs');
+    await runGlobalLint();
+    process.exit(0);
+  }
   const project = args[1] || '';
   if (!project) {
-    console.error('\n  Usage: kushi lint <project>\n');
+    console.error('\n  Usage: kushi lint <project>\n         kushi lint --global\n');
     process.exit(1);
   }
   await dispatchLint(project);
   process.exit(0);
 }
 
+// ── global verb (v5.3.0+) ────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'global') {
+  const sub = args[1] || '';
+  const validSubs = ['init', 'status', 'ask', 'lint'];
+  if (!validSubs.includes(sub)) {
+    console.error('\n  Usage: kushi global init           Scaffold ~/.kushi-global/State/');
+    console.error('         kushi global status         Show counts + freshness');
+    console.error('         kushi global ask <question> Ask the global wiki');
+    console.error('         kushi global lint           Lint the global wiki\n');
+    process.exit(1);
+  }
+  const { runGlobalInit, runGlobalStatus, runGlobalAsk, runGlobalLint } = await import('../src/global-wiki-cli.mjs');
+  if (sub === 'init') await runGlobalInit();
+  else if (sub === 'status') await runGlobalStatus();
+  else if (sub === 'ask') await runGlobalAsk(args.slice(2).join(' '));
+  else if (sub === 'lint') await runGlobalLint();
+  process.exit(0);
+}
+
+// ── promote verb (v5.3.0+) ───────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'promote') {
+  const project = args[1] || '';
+  const page = args[2] || '';
+  if (!project || !page) {
+    console.error('\n  Usage: kushi promote <project> <page-path>\n');
+    console.error('  Copies a project State page into the global wiki with provenance metadata.');
+    console.error('  Refuses by default if customer identifiers are detected; pass --force after review.\n');
+    process.exit(1);
+  }
+  const force = args.includes('--force');
+  const { runPromote } = await import('../src/global-wiki-cli.mjs');
+  await runPromote(project, page, { force });
+  process.exit(0);
+}
+
 // ── hooks verb (v5.2.0+) ─────────────────────────────────────────────────────
 if (args.length > 0 && args[0] === 'hooks') {
   const sub = args[1] || '';
@@ -108,6 +148,7 @@ if (args.includes('--help') || args.includes('-h')) {
 
   Wiki maintenance (v5.1.0+):
     lint <project>       Run wiki-lint checks on State/ (contradictions, stale claims, orphans).
+    lint --global        Lint the global wiki at ~/.kushi-global/State/.
 
   Hooks & observability (v5.2.0+):
     hooks list <project>           List configured hooks for a project.
@@ -115,6 +156,14 @@ if (args.includes('--help') || args.includes('-h')) {
     explain <topic>                Explain a kushi concept (pedagogical, read-only).
     remember <rule>                Persist a project convention to CLAUDE.md.
 
+  Global wiki (v5.3.0+):
+    global init                    Scaffold ~/.kushi-global/State/ (env: KUSHI_GLOBAL_ROOT)
+    global status                  Show page counts + freshness for the global wiki.
+    global ask <question>          Search the global wiki specifically.
+    global lint                    Lint the global wiki (alias for 'lint --global').
+    promote <project> <page>       Move a project State page into global with redaction + back-link.
+                                   Refuses if customer identifiers are detected; --force after review.
+
   After install, talk to Kushi:
     bootstrap <project>     First-time setup
     refresh <project>       Incremental refresh + rebuild State/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "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": {
@@ -41,7 +41,7 @@
   },
   "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",
+    "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",
     "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "eval": "pwsh plugin/skills/eval/run-evals.ps1 -Skill",

package/plugin/agents/kushi.agent.md

@@ -54,6 +54,8 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 | `@Kushi teach <topic>` | standard+ | n/a (write-only) | v5.2.0 — `teach` — persist a reusable fact/preference/pattern to `.kushi/learnings/`. Lookup via `explain`. |
 | `@Kushi explain <topic>` | standard+ | n/a (read-only) | v5.2.0 — `teach` (explain mode) — retrieve a previously taught fact/preference/pattern from `.kushi/learnings/`. |
 | `@Kushi schema-evolve <project>` | standard+ | n/a | v5.2.0 — `schema-evolve` — detect schema drift in Evidence/ layouts and propose safe migrations with rollback plans. |
+| `@Kushi global init` / `status` / `ask <q>` / `lint` | standard+ | n/a | v5.3.0 — `global-wiki` — manage the per-user cross-engagement wiki at `~/.kushi-global/State/` (env `KUSHI_GLOBAL_ROOT` for tests). |
+| `@Kushi promote <project> <page>` | standard+ | n/a | v5.3.0 — `promote` — copy a project State page into the global wiki with identifier redaction + back-link + dual log. Refuses without `--force` when identifiers detected. |
 
 **Note on auto-routing**: `ask` does NOT require the `@Kushi ask` prefix. Any message that names a known project AND asks a question (what / who / when / status / summarize / etc.) auto-dispatches to `ask-project`. Producer verbs win in the unambiguous case.
 

package/plugin/instructions/global-wiki.instructions.md

@@ -0,0 +1,79 @@
+---
+name: "global-wiki"
+description: "v5.3.0 — Global wiki at ~/.kushi-global/State/ (env override KUSHI_GLOBAL_ROOT). Structurally identical to a project State/ wiki (Karpathy layout) but tagged scope: global in frontmatter. Holds cross-engagement patterns that don't belong in any one project. Never auto-populated — only explicit kushi promote moves content in. Linter checks for [!warning] potential-customer-leak callouts to enforce privacy posture."
+applies_to: "global init/status/ask/lint, promote, ask-project routing, teach routing"
+since: "kushi v5.3.0"
+---
+
+# global-wiki — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (living-wiki Karpathy pattern + Obsidian global-vault + Claude.md global-memory): adds a separate root, `scope: global` frontmatter marker, explicit-promotion-only contract, and a privacy linter (`potential-customer-leak`).
+
+The global wiki is a personal, cross-engagement knowledge base that lives **outside** any single project's `Evidence/<alias>/State/`. Consultants accumulate cross-cutting patterns — "how I structure FDE intake", "my preferred Status taxonomy", "tools and snippets that work across all customers" — and those patterns belong in a single durable home, not re-derived per engagement and not silently bleeding between projects.
+
+## Rules (HARD)
+
+### 1. Location
+
+- **Default:** `~/.kushi-global/State/` (`$HOME` on POSIX, `$env:USERPROFILE` on Windows).
+- **Override:** `$KUSHI_GLOBAL_ROOT` environment variable (absolute path; tilde-expanded). Tests MUST set this to `.testtmp/.kushi-global/` — never touch the real path.
+- The global root is **per-user**, never per-project, never per-host.
+
+### 2. Shape
+
+The global wiki MUST mirror the standard State/ layout (per `karpathy-state-layout.instructions.md` + `living-wiki.instructions.md`):
+
+```
+~/.kushi-global/State/
+├── index.md          # entry point, links to all pages
+├── log.md            # reverse-chronological op log (same format as project log.md)
+├── tour.md           # guided tour pointer (optional)
+├── hot.md            # hot-edits scratch (optional)
+├── conventions.md    # cross-engagement conventions / CLAUDE.md-shape rules
+├── answers/          # promoted Q&A pages
+├── reports/          # global lint reports, status snapshots
+└── _review-queue.md  # open privacy / contradiction items
+```
+
+Every markdown page in the global wiki MUST carry frontmatter with `scope: global`:
+
+```yaml
+---
+kushi_state_page: true
+scope: global
+---
+```
+
+The `scope: global` marker distinguishes a true global page from a project page that was *copied* locally for reference.
+
+### 3. Initialization
+
+- `kushi global init` creates the scaffold idempotently — re-running NEVER overwrites existing content.
+- Skips files that already exist; only adds missing scaffolding.
+- Logs `global-init` entry to `~/.kushi-global/State/log.md` on every run (even no-op).
+
+### 4. Privacy posture
+
+The global wiki crosses engagements. **Customer identifiers MUST NOT leak in.**
+
+- The promote operation runs an identifier scan and refuses unless explicit `--force` is given.
+- `kushi global lint` (and `kushi lint --global`) scans `*.md` under the global root for `> [!warning] potential-customer-leak` callouts (left there by promote when it had to redact).
+- The user is responsible for resolving those callouts before sharing the global wiki.
+
+### 5. Promotion is explicit only
+
+- Pages NEVER auto-promote from a project to global. The only path is `kushi promote <project> <page-path>`.
+- See `multi-wiki-routing.instructions.md` for the promotion contract + back-link rule.
+
+### 6. Storage outside engagement tree
+
+The global wiki lives **outside** any engagement root. Self-check `D40.global-wiki-shape` checks the configured location (env-overridden in CI) and is warn-only — the absence of `~/.kushi-global/` is normal until the user runs `kushi global init`.
+
+## References
+
+- `multi-wiki-routing.instructions.md` — routing across project + global
+- `living-wiki.instructions.md` — incremental + contradiction lifecycle (same rules apply)
+- `karpathy-state-layout.instructions.md` — page shape
+- `schema-evolve.instructions.md` — `global` scope was placeholdered here in v5.2.0; v5.3.0 honors it.
+- `wiki-lint.instructions.md` — finding classes; v5.3.0 adds `potential-customer-leak`.

package/plugin/instructions/multi-wiki-routing.instructions.md

@@ -0,0 +1,117 @@
+---
+name: "multi-wiki-routing"
+description: "v5.3.0 — Routing rules for project vs global wiki. ask-project: project-first; augment with global only if project confidence below threshold; --global forces global-first, --project-only suppresses global. build-state: project-only, never auto-promotes to global. lint-state: project-only; kushi lint --global lints global separately. teach: global-first for cross-cutting topics, project for project-specific. Promotion path: explicit kushi promote <project> <page>, never automatic."
+applies_to: "ask-project, build-state, lint-state, teach, promote"
+since: "kushi v5.3.0"
+---
+
+# multi-wiki-routing — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source: kushi previously had a single wiki per project. This doctrine formalizes the project↔global routing rules introduced in v5.3.0.
+
+Kushi maintains two kinds of wikis:
+
+| Kind | Path | Scope |
+|---|---|---|
+| **Project** | `Evidence/<alias>/State/` | One engagement only. |
+| **Global** | `$KUSHI_GLOBAL_ROOT` or `~/.kushi-global/State/` | Cross-engagement; per-user. |
+
+Every reader/writer skill MUST be explicit about which it touches.
+
+## Rules (HARD)
+
+### 1. ask-project — project-first, global-augment
+
+Default behavior (`kushi ask <project> <q>`):
+
+1. Resolve the project and run the standard project-scoped answer chain (per `ask-project/SKILL.md`).
+2. Compute the confidence (per `evidence-confidence-ladder.instructions.md`).
+3. **If confidence is `low` (or `medium` with `--global-augment` set in config)** → also query `$KUSHI_GLOBAL_ROOT/State/answers/` for matching topics and append a `## From your global wiki` section, citing each hit with `[global: <page>]`.
+4. **If confidence is `high`** → do NOT consult global (avoid noise).
+
+Flags:
+
+| Flag | Behavior |
+|---|---|
+| `--global` | Reverse the order: search global first, project second. Show provenance `[global]` first, `[project: <alias>]` second. |
+| `--project-only` | Hard-disable global consultation regardless of confidence. |
+| (none) | Default project-first + augment-on-low-confidence. |
+
+Source provenance MUST be visible per citation: `[project: <alias>]` vs `[global]`.
+
+### 2. build-state — project-only
+
+`build-state` writes to `Evidence/<alias>/State/` and **NEVER** writes to the global wiki. There is no auto-promotion path. Even if a fact has appeared in 10 projects, build-state does not move it to global — only the user, via `kushi promote`, does.
+
+### 3. lint-state — project-only by default
+
+- `kushi lint <project>` → lints the project State only. Unchanged from v5.1.0.
+- `kushi lint --global` → lints the global wiki at `$KUSHI_GLOBAL_ROOT/State/` separately. Same finding classes plus `potential-customer-leak` (see `global-wiki.instructions.md`).
+- Lint runs are independent; one does not implicitly run the other.
+
+### 4. teach — global-first for cross-cutting topics
+
+- For **cross-cutting topics** (kushi concepts, doctrines, releases — e.g. "explain confidence ladder", "how does CSC work"): `teach` consults the global wiki FIRST (if a matching page exists in `~/.kushi-global/State/answers/`), then falls back to in-repo doctrine, then to genealogy.
+- For **project-specific topics** ("how did we structure intake for AGCO?"): `teach` declines and suggests `kushi ask <project> <q>` instead — that's an `ask-project` job.
+- Citations distinguish `[global: <page>]` vs `[doctrine: <file>]` vs `[genealogy: <version>]`.
+
+### 5. Promotion path — explicit only
+
+`kushi promote <project> <page>` is the **only** way content moves project → global. See `Promote operation` below.
+
+Auto-promotion is intentionally not supported because:
+
+1. Customer-identifier detection is best-effort; the user must review.
+2. What is "cross-cutting" depends on the consultant, not the machine.
+3. Silent promotion would surprise the user — global is personal space.
+
+### 6. Demotion / removal
+
+There is no `kushi demote` in v5.3.0. To remove a global page the user deletes the file directly and appends a manual `log.md` entry. v6+ MAY add a managed demote verb.
+
+## Promote operation
+
+`kushi promote <project> <page-path>` performs the following, in order:
+
+1. **Resolve source.** Find `<engagement-root>/<project>/Evidence/<alias>/State/<page-path>`. Must exist.
+2. **Read source body + frontmatter.**
+3. **Run identifier scan** against the body. Uses the same heuristics as `schema-evolve`-style detection:
+   - Known customer aliases registered in `.settings.yml` `discovery.project_aliases:` or the alias folder name itself.
+   - The literal project name.
+   - Email addresses with non-Microsoft domains.
+   - High-confidence proper-noun runs that match `<project>` aliases (case-insensitive, word boundaries).
+4. **Build redaction list.** For each hit:
+   - Replace the literal string with `[REDACTED]` in the global copy.
+   - Record `{ pattern, count, line_numbers }` in the redactions list.
+5. **Refuse without `--force`** if the redactions list is non-empty. Print the list with line numbers and the human-review prompt. The user is expected to inspect, then re-run with `--force` (which writes the redacted body and adds a `> [!warning] potential-customer-leak` callout near each redaction site for the lint pass to track).
+6. **Write target.** Path: `$KUSHI_GLOBAL_ROOT/State/answers/<source-slug>.md` (slugify source filename; collisions append `-N`).
+   Frontmatter MUST contain:
+   ```yaml
+   ---
+   kushi_state_page: true
+   scope: global
+   promoted_from: "<project>/<alias>/<relative-source-path>"
+   promoted_at: "<ISO-8601 UTC>"
+   redactions: ["<pattern1>", "<pattern2>"]
+   ---
+   ```
+7. **Add back-link to source.** Append (or update) a callout in the source page:
+   ```markdown
+   > [!info] Promoted to global wiki
+   > <source-slug>.md @ <ISO-8601 UTC> · redactions: <N>
+   ```
+8. **Dual log.** Append a `promote` entry to BOTH:
+   - `<project>/Evidence/<alias>/State/log.md` (op = `promote`, title = `Promoted <slug> to global`).
+   - `$KUSHI_GLOBAL_ROOT/State/log.md` (op = `promote-in`, title = `Imported <slug> from <project>`).
+9. **Print summary** with both file paths.
+
+The operation is **atomic**: if any step fails (redaction refused, write denied, back-link fails), no writes are persisted. The implementation uses a stage-then-commit pattern.
+
+## References
+
+- `global-wiki.instructions.md` — global wiki location + privacy rules
+- `evidence-confidence-ladder.instructions.md` — confidence threshold for routing
+- `living-wiki.instructions.md` — same incremental + contradiction rules apply to both wikis
+- `wiki-lint.instructions.md` — finding classes; v5.3.0 adds `potential-customer-leak`
+- `schema-evolve.instructions.md` — identifier-detection heuristics reused here

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

@@ -72,6 +72,20 @@ When the user passes `--file-back` (or says "file this answer back", "save this
 
 The `--file-back` flag is OPTIONAL. Without it, ask-project behaves exactly as before (read-only, no writes).
 
+## --global / --project-only (v5.3.0+)
+
+Multi-wiki routing flags governed by `multi-wiki-routing.instructions.md`:
+
+| Flag | Behavior |
+|------|----------|
+| *(no flag)* | **Project-first.** Search project `Evidence/<alias>/State/` first; only fall back to the global wiki when project sources are missing/stale or no hit is found. Cite each hit with `[project: <alias>]` or `[global]`. |
+| `--global` | **Global-first.** Search `$KUSHI_GLOBAL_ROOT/State/answers/` first; fall back to the project. Use when you trust the cross-engagement note more than project state. |
+| `--project-only` | **Hard-suppress global.** Never read the global wiki for this question (privacy-sensitive or strictly project-internal). |
+
+Provenance is never silent. Every citation tags `[project: <alias>]` or `[global]`. If the answer mixes both, list each source with its provenance.
+
+The global wiki itself is opt-in (created via `kushi global init`). If it does not exist on disk, all three modes degrade silently to project-only.
+
 ## Inputs
 
 - `<project>` — fuzzy-matched project name. If multiple plausible matches, ask the user.

package/plugin/skills/global-wiki/.created-by-skill-creator

@@ -0,0 +1 @@
+global-wiki

package/plugin/skills/global-wiki/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "global-wiki"
+version: "1.0.0"
+description: "USE WHEN the user says 'init global wiki', 'kushi global init/status/ask/lint', 'show me my global wiki', or wants to manage the cross-engagement knowledge base at ~/.kushi-global/State/. DO NOT USE for promoting individual pages (use promote) or for project-scoped Q&A (use ask-project). Capability: scaffold + status + ask + lint over the per-user global wiki; honors $KUSHI_GLOBAL_ROOT for tests."
+---
+
+# Skill: global-wiki
+
+Manages the per-user global wiki at `$KUSHI_GLOBAL_ROOT` (default `~/.kushi-global/State/`). Structurally identical to a project `State/` wiki but tagged `scope: global` in every page's frontmatter. Holds cross-engagement patterns that consultants want to keep across projects.
+
+See `plugin/instructions/global-wiki.instructions.md` for the full doctrine and `multi-wiki-routing.instructions.md` for how readers + writers route between project and global.
+
+## Triggers
+
+- `kushi global init`
+- `kushi global status`
+- `kushi global ask <question>`
+- `kushi global lint`
+- "init my global wiki"
+- "what's in my global wiki"
+- "lint global"
+
+## Inputs
+
+- `<subcommand>` — one of `init`, `status`, `ask`, `lint`.
+- `<question>` — required for `ask`.
+
+## Step checklist
+
+- [ ] Step 1 — Resolve `$KUSHI_GLOBAL_ROOT` (env override) or fall back to `~/.kushi-global/`.
+- [ ] Step 2 — Dispatch to the requested sub-operation.
+- [ ] Step 3 — Print a one-line summary + paths.
+- [ ] Step 4 — Append a `log.md` entry on init / lint / ask-fileback.
+
+### Step 1 — Resolve global root
+
+Read `$env:KUSHI_GLOBAL_ROOT`. If unset, default to `$env:USERPROFILE/.kushi-global/` on Windows or `$HOME/.kushi-global/` on POSIX. Tests MUST set `$env:KUSHI_GLOBAL_ROOT='.testtmp/.kushi-global'` and NEVER touch the real path.
+
+### Step 2 — Sub-operations
+
+| Sub | Behavior |
+|---|---|
+| `init`   | Idempotent scaffold of `State/` with `index.md`, `log.md`, `conventions.md`, `_review-queue.md`, `answers/`, `reports/`. Every file carries `scope: global` frontmatter. |
+| `status` | Count pages by kind + report newest mtime + open review-queue items. |
+| `ask`    | Full-text scan of `State/answers/*.md` (case-insensitive, ≥3-char terms). Cite hits as `[global: <page>]`. |
+| `lint`   | Scan all `State/**/*.md` for `[!warning] potential-customer-leak` + `[!warning] Contradicted`. Severity = warning. |
+
+### Step 3 — Output
+
+Print resolved root, sub-operation result, and any actionable next steps.
+
+### Step 4 — Log
+
+- `init` → append `global-init` to `State/log.md`.
+- `lint` → append `global-lint` if findings produced.
+- `ask` with `--file-back` (future) → append `global-ask-fileback`.
+
+## Hard rules
+
+- **NEVER write to a project's Evidence/.** This skill is global-wiki only.
+- **NEVER auto-promote.** Promotion is a separate `promote` skill, user-invoked.
+- **Tests MUST use `$env:KUSHI_GLOBAL_ROOT='.testtmp/.kushi-global'`.** Real `~/.kushi-global/` is user data.
+- **Privacy posture.** When ask returns hits, never silently mix them with project results — provenance `[global]` MUST be visible on every citation.
+
+## Stop conditions
+
+- Sub-command missing → print usage, exit 1.
+- `ask` with no question → print usage, exit 1.
+- `status` / `lint` against an uninitialized root → report `not initialized` + suggest `kushi global init`.
+
+## Validation loop
+
+1. Run `pwsh plugin/skills/self-check/run.ps1 -Targeted D40`.
+2. Fix any findings, re-run.
+3. Repeat until self-check exits 0.
+
+## References
+
+- `../../instructions/global-wiki.instructions.md`
+- `../../instructions/multi-wiki-routing.instructions.md`
+- `../../instructions/log-format.instructions.md`
+- `../../instructions/karpathy-state-layout.instructions.md`
+- `../promote/SKILL.md` — the promotion verb
+
+## Issue Recovery
+
+If this skill exposes a reusable defect (e.g. a scaffold file missing from the template, a privacy heuristic that misses a customer pattern), fix the smallest correct repo-owned artifact first (`src/global-wiki.mjs` or the scaffold) and re-run `self-check -Targeted D40`.

package/plugin/skills/global-wiki/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill": "global-wiki",
+  "cases": [
+    {
+      "id": "global-init-creates-scaffold",
+      "name": "kushi global init creates index/log/conventions/_review-queue and answers/+reports/",
+      "input": "kushi global init",
+      "expected_assertions": [
+        { "type": "contains", "value": "State" },
+        { "type": "contains", "value": "Created" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "global-status-counts-pages",
+      "name": "kushi global status reports counts after init",
+      "input": "kushi global status",
+      "expected_assertions": [
+        { "type": "contains", "value": "Pages" },
+        { "type": "contains", "value": "Answers" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "global-ask-finds-hit",
+      "name": "kushi global ask returns a citation with [global] provenance when a matching page exists",
+      "input": "kushi global ask confidence ladder",
+      "expected_assertions": [
+        { "type": "contains", "value": "[global]" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "global-lint-clean-on-fresh-init",
+      "name": "kushi global lint emits no findings on a freshly-initialized wiki",
+      "input": "kushi global lint",
+      "expected_assertions": [
+        { "type": "contains", "value": "No findings" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

package/plugin/skills/promote/.created-by-skill-creator

@@ -0,0 +1 @@
+promote

package/plugin/skills/promote/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: "promote"
+version: "1.0.0"
+description: "USE WHEN the user says 'kushi promote <project> <page>', 'promote this answer to global', 'move this page to my global wiki', or wants to copy a project State page into the cross-engagement global wiki at ~/.kushi-global/. DO NOT USE for project Q&A (use ask-project) or for initializing the global wiki itself (use global-wiki). Capability: identifier-scan + redact + write + back-link + dual-log. Refuses without --force when customer identifiers are detected."
+---
+
+# Skill: promote
+
+Copies a single project State page into the global wiki (`$KUSHI_GLOBAL_ROOT/State/answers/`) with provenance metadata, an identifier-detection gate, and a back-link in the source page.
+
+This is the **only** path from project → global. Auto-promotion is intentionally not supported. See `multi-wiki-routing.instructions.md` § Promote operation for the contract.
+
+## Triggers
+
+- `kushi promote <project> <page-path>`
+- `kushi promote <project> <page-path> --force`
+- "promote this answer to global"
+- "move <page> into my global wiki"
+
+## Inputs
+
+- `<project>` — project name relative to cwd (or under `..`).
+- `<page-path>` — path to the source page. Accepted forms:
+  - Absolute path.
+  - Path relative to the project root (e.g. `Evidence/<alias>/State/answers/2026-05-27_<slug>.md`).
+  - Path relative to a discovered `Evidence/<alias>/State/` (e.g. `answers/<slug>.md`).
+  - Path relative to a plain `<project>/State/` (e.g. `answers/<slug>.md`).
+- `--force` — required when the identifier scan finds hits.
+
+## Step checklist
+
+- [ ] Step 1 — Resolve project root + source page.
+- [ ] Step 2 — Read source + run identifier scan.
+- [ ] Step 3 — Refuse without `--force` if hits detected; print review prompt.
+- [ ] Step 4 — Write redacted target with `scope: global` frontmatter.
+- [ ] Step 5 — Add `[!info] Promoted to global wiki` back-link in source.
+- [ ] Step 6 — Append `promote` entry to project `State/log.md`.
+- [ ] Step 7 — Append `promote-in` entry to global `State/log.md`.
+- [ ] Step 8 — Print summary.
+
+### Step 1 — Resolve
+
+Find the source via `resolveProjectRoot` + `resolveSourcePage` in `src/global-wiki-cli.mjs`. Echo the resolved absolute path before any write.
+
+### Step 2 — Identifier scan
+
+Use `detectIdentifiers()` from `src/global-wiki.mjs`. Patterns checked:
+
+- The literal project name (case-insensitive, word boundary).
+- The alias folder name (inferred from `Evidence/<alias>/` in the path).
+- Any extra aliases supplied (optional flag, future).
+- Non-Microsoft email addresses (`@*` where domain does not end in `microsoft.com`).
+
+Each hit records `{ pattern, kind, count, line_numbers }`.
+
+### Step 3 — Refuse gate
+
+If hits > 0 AND `--force` not supplied → refuse with exit code 2, print the hits with line numbers, suggest review. **No filesystem writes occur on refusal.**
+
+### Step 4 — Write target
+
+Target path: `$KUSHI_GLOBAL_ROOT/State/answers/<slug>.md` where `<slug>` = slugified source filename (lowercase, alnum + hyphens, ≤60 chars). Collisions append `-N`.
+
+Frontmatter MUST include:
+
+```yaml
+---
+kushi_state_page: true
+scope: global
+promoted_from: "<project>/<relative-source-path>"
+promoted_at: "<ISO-8601 UTC>"
+redactions: ["<pattern1>", "<pattern2>"]
+---
+```
+
+If any redactions occurred, append a `> [!warning] potential-customer-leak` callout listing the patterns so `global lint` tracks the open review item.
+
+### Step 5 — Back-link
+
+Append to the source page (idempotent — skip if the target slug is already linked):
+
+```markdown
+> [!info] Promoted to global wiki
+> answers/<slug>.md @ <iso> · redactions: <N>
+```
+
+### Step 6 / 7 — Dual log
+
+- Project `State/log.md`: `promote | Promoted <slug> to global (redactions: N)`.
+- Global `State/log.md`: `promote-in | Imported <slug> from <project> (redactions: N)`.
+
+### Step 8 — Print summary
+
+Echo `source`, `target`, `slug`, `redactions`, `promoted_at`.
+
+## Hard rules
+
+- **Atomic.** No partial state. If any step fails, no writes persist (stage-then-commit).
+- **--force is mandatory** when identifiers are detected. Never auto-redact without it.
+- **Tests use `$env:KUSHI_GLOBAL_ROOT='.testtmp/.kushi-global'`.** Real `~/.kushi-global/` is user data.
+- **Never modify project Evidence beyond the back-link.** No edits to the redacted lines in the source — only the global copy is redacted.
+- **Provenance frontmatter required.** `promoted_from`, `promoted_at`, `redactions` are MANDATORY on the global copy.
+
+## Stop conditions
+
+- Project unresolved → exit 1, ask the user to verify cwd.
+- Source page unresolved → exit 1.
+- Identifier hits without `--force` → exit 2, print hits.
+
+## Validation loop
+
+1. Run `pwsh plugin/skills/self-check/run.ps1 -Targeted D40`.
+2. Run `node --test src/promote.test.mjs`.
+3. Fix any findings + re-run.
+
+## References
+
+- `../../instructions/global-wiki.instructions.md`
+- `../../instructions/multi-wiki-routing.instructions.md`
+- `../../instructions/schema-evolve.instructions.md`
+- `../global-wiki/SKILL.md`
+
+## Issue Recovery
+
+If the identifier scan misses a customer pattern (false negative) or flags a non-identifier (false positive), fix the heuristic in `src/global-wiki.mjs::detectIdentifiers` first, add a regression case to `src/promote.test.mjs`, then re-run.