kushi-agents 5.0.3 → 5.1.0

package/README.md

@@ -7,6 +7,8 @@
 [![host: VS Code](https://img.shields.io/badge/host-VS%20Code-007acc)](https://gim-home.github.io/kushi/)
 [![spec: agentskills.io](https://img.shields.io/badge/spec-agentskills.io-22c55e)](https://agentskills.io/skill-creation/best-practices)
 
+> **v5.1.0 — Living wiki.** Build-state is now incremental: human edits outside `<!-- kushi:auto -->` fences are preserved, contradictions are flagged with Obsidian-compatible callouts (`> [!warning]`), and a new `lint-state` skill monitors wiki health. State/ is a valid [Obsidian](https://obsidian.md) vault — callout syntax, Dataview-compatible frontmatter, and `[[wikilinks]]` all work natively.
+
 > **v5.0.1 spec-compliance pass.** Every `plugin/skills/<name>/SKILL.md` follows the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices) and [optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) guides: ≤ 500 lines & ≤ 5000 tokens, load-on-trigger references, top-5 gotchas, checklist orchestrators, validation loops, plan-validate-execute for graph + State writers, and "USE WHEN …" descriptions. Enforced by `self-check -Deep` D30.*.
 
 > **Project lineage:** for the *why* behind each release — what built on what, what trade-offs were accepted, what external work inspired which design — see [`docs/genealogy.md`](docs/genealogy.md). Every release MUST add an entry there before tagging (enforced by `self-check` D31.genealogy).
@@ -74,6 +76,21 @@ Apply [a]ll · [s]elect · [n]one?
 
 Try it: `npx kushi-agents --clawpilot --profile preview` · How-to: [Two-way ADO update](https://gim-home.github.io/kushi/how-to/two-way-ado-update/) · Roadmap: [`docs/concepts/roadmap.md`](docs/concepts/roadmap.md).
 
+## Obsidian compatible
+
+`State/` is a valid [Obsidian](https://obsidian.md) vault out of the box:
+
+- **Callout syntax** — contradictions use `> [!warning]` / `> [!info]` callouts (native Obsidian rendering).
+- **Dataview compatible** — every State page has YAML frontmatter (`kushi_state_page: true`, `entity_ids`, `related`, timestamps) queryable by [Dataview](https://blacksmithgu.github.io/obsidian-dataview/).
+- **Wikilinks** — cross-references use `[[category/slug]]` form, resolvable by Obsidian's link resolver.
+- **No binary assets required** — all content is plain Markdown. No images, no custom plugins needed.
+
+To use: point Obsidian at `<project>/State/` as a vault. The `index.md` serves as the home page, `log.md` is the activity feed, and category folders (`people/`, `decisions/`, etc.) are navigable in the sidebar.
+
+> **Note:** Obsidian is optional. State/ works identically without it — the conventions are designed to be tool-agnostic while being Obsidian-first for teams that use it.
+
+<!-- Screenshot placeholder: Obsidian rendering of State/ with contradiction callouts visible. No binary screenshots committed — use text descriptions or link to docs site. -->
+
 ---
 
 ## Three install profiles
@@ -235,6 +252,19 @@ npm pack --dry-run
 
 The self-check validates frontmatter, agent inventory, prompt → skill routing, profile manifest, reference packs, cross-links, the verbs table in this README, and the layout diagram in `docs/reference/where-things-live.md`. Full reference: [docs/reference/self-check.md](docs/reference/self-check.md).
 
+## Authoring a new skill (v5.0.4+)
+
+Adding a new skill takes one command + a per-skill lint loop:
+
+```powershell
+node bin/cli.mjs create-skill --name my-thing --type writer --description "Generates the foo report from State/"
+node bin/cli.mjs check-skill --name my-thing
+node bin/cli.mjs check-skill --name my-thing --retrofit --apply   # auto-fix additive findings
+npm run eval -- my-thing
+```
+
+Full walkthrough: [`docs/contributing/skill-authoring.md`](docs/contributing/skill-authoring.md). Doctrine: [`plugin/instructions/skill-authoring.instructions.md`](plugin/instructions/skill-authoring.instructions.md). Repo-wide dogfood baseline: [`docs/audits/v5.0.4-skill-creator-dogfood.md`](docs/audits/v5.0.4-skill-creator-dogfood.md).
+
 ## Evaluating skills (v5.0.3+)
 
 Every skill ships per-case evals at `plugin/skills/<name>/evals/evals.json`, aligned with the [agentskills.io evaluating-skills spec](https://agentskills.io/skill-creation/evaluating-skills). Doctrine: [`plugin/instructions/skill-evals.instructions.md`](plugin/instructions/skill-evals.instructions.md).

package/bin/cli.mjs

@@ -5,6 +5,27 @@ import { runMultiHost } from '../src/multi-host.mjs';
 
 const args = process.argv.slice(2);
 
+// ── skill-authoring verbs (v5.0.4+) ─────────────────────────────────────────
+// Dispatch directly to the skill-creator / skill-checker pwsh scripts.
+const SKILL_VERBS = new Set(['create-skill', 'check-skill', 'optimize-description', 'review-evals']);
+if (args.length > 0 && SKILL_VERBS.has(args[0])) {
+  const verb = args[0];
+  const rest = args.slice(1);
+  await dispatchSkillVerb(verb, rest);
+  process.exit(0);
+}
+
+// ── lint verb (v5.1.0+) ──────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'lint') {
+  const project = args[1] || '';
+  if (!project) {
+    console.error('\n  Usage: kushi lint <project>\n');
+    process.exit(1);
+  }
+  await dispatchLint(project);
+  process.exit(0);
+}
+
 if (args.includes('--help') || args.includes('-h')) {
   console.log(`
   Usage: npx kushi-agents [options]
@@ -41,13 +62,27 @@ if (args.includes('--help') || args.includes('-h')) {
 
     --help, -h          Show this help
 
+  Skill authoring (v5.0.4+):
+    create-skill <name> --type <pull|writer|orchestrator|other> --description "<d>"
+                         Scaffold a new plugin/skills/<name>/ tree.
+    check-skill <name>   Lint a skill against the agentskills.io blueprint.
+    check-skill --all [--retrofit [--apply]]
+                         Audit (or retrofit) every skill in plugin/skills/.
+    optimize-description <skill>
+                         Rewrite a skill's description per the optimizer rules.
+    review-evals <skill> Render an HTML side-by-side eval-review viewer.
+
+  Wiki maintenance (v5.1.0+):
+    lint <project>       Run wiki-lint checks on State/ (contradictions, stale claims, orphans).
+
   After install, talk to Kushi:
     bootstrap <project>     First-time setup
     refresh <project>       Incremental refresh + rebuild State/
     state <project>         Re-render State/ from existing Evidence
     consolidate <project>   Merge per-user evidence
     status <project>        Show run-log
-    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes)
+    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes, --file-back to save)
+    lint <project>          Run wiki-lint checks on State/
 
   In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
 `);
@@ -114,3 +149,133 @@ function getFlag(flag) {
   const match = args.find((a) => a.startsWith(prefix));
   return match ? match.slice(prefix.length) : undefined;
 }
+
+// ── skill-authoring verb dispatch (v5.0.4+) ─────────────────────────────────
+async function dispatchSkillVerb(verb, rest) {
+  const { spawnSync } = await import('node:child_process');
+  const path = await import('node:path');
+  const url = await import('node:url');
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const repoRoot = path.resolve(here, '..');
+  const creatorDir = path.join(repoRoot, 'plugin', 'skills', 'skill-creator');
+  const checkerDir = path.join(repoRoot, 'plugin', 'skills', 'skill-checker');
+
+  let script, scriptArgs = [];
+  switch (verb) {
+    case 'create-skill': {
+      // Usage: kushi create-skill <name> [--type <t>] [--description "<d>"] [--force]
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (!name) {
+        console.error('Usage: kushi-agents create-skill <name> --type <pull|writer|orchestrator|other> --description "USE WHEN ... DO NOT USE FOR ..."');
+        process.exit(1);
+      }
+      const type = pickFlag(rest, '--type') || 'other';
+      const desc = pickFlag(rest, '--description') || `USE WHEN ${name} is invoked. DO NOT USE FOR unrelated tasks.`;
+      script = path.join(creatorDir, 'scaffold.ps1');
+      scriptArgs = ['-Name', name, '-Type', type, '-Description', desc];
+      if (rest.includes('--force')) scriptArgs.push('-Force');
+      if (rest.includes('--dry-run')) scriptArgs.push('-DryRun');
+      break;
+    }
+    case 'check-skill': {
+      // Usage: kushi check-skill <name> | --all  [--retrofit] [--apply]
+      script = path.join(checkerDir, 'check-skill.ps1');
+      const allFlag = rest.includes('--all') || rest.includes('-All');
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (allFlag) scriptArgs.push('-All');
+      else if (name) scriptArgs.push('-Skill', name);
+      else {
+        console.error('Usage: kushi-agents check-skill <name> | --all  [--retrofit] [--apply] [--dry-run]');
+        process.exit(1);
+      }
+      if (rest.includes('--retrofit')) scriptArgs.push('-Retrofit');
+      if (rest.includes('--apply')) scriptArgs.push('-Apply');
+      if (rest.includes('--dry-run')) scriptArgs.push('-DryRun');
+      if (rest.includes('--json')) scriptArgs.push('-Json');
+      break;
+    }
+    case 'optimize-description': {
+      // Usage: kushi optimize-description <skill>
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (!name) {
+        console.error('Usage: kushi-agents optimize-description <skill>');
+        process.exit(1);
+      }
+      script = path.join(checkerDir, 'check-skill.ps1');
+      scriptArgs = ['-Skill', name, '-OptimizeDescription'];
+      break;
+    }
+    case 'review-evals': {
+      // Usage: kushi review-evals <skill>
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (!name) {
+        console.error('Usage: kushi-agents review-evals <skill>');
+        process.exit(1);
+      }
+      script = path.join(checkerDir, 'check-skill.ps1');
+      scriptArgs = ['-Skill', name, '-Review'];
+      break;
+    }
+    default:
+      console.error(`Unknown skill verb: ${verb}`);
+      process.exit(1);
+  }
+
+  const result = spawnSync('pwsh', ['-NoProfile', '-File', script, ...scriptArgs], { stdio: 'inherit' });
+  process.exit(result.status ?? 1);
+}
+
+async function dispatchLint(project) {
+  const { spawn } = await import('node:child_process');
+  const { resolve } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const scriptPath = resolve(__dirname, '..', 'plugin', 'skills', 'lint-state', 'lint.ps1');
+
+  const cwd = process.cwd();
+  const { readdirSync, existsSync } = await import('node:fs');
+  let stateDir = '';
+
+  const evidenceDir = resolve(cwd, project, 'Evidence');
+  if (existsSync(evidenceDir)) {
+    const aliases = readdirSync(evidenceDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith('_'));
+    for (const alias of aliases) {
+      const candidate = resolve(evidenceDir, alias.name, 'State');
+      if (existsSync(candidate)) { stateDir = candidate; break; }
+    }
+  }
+
+  if (!stateDir) {
+    const direct = resolve(cwd, project, 'State');
+    if (existsSync(direct)) { stateDir = direct; }
+  }
+
+  if (!stateDir) {
+    console.error(`\n  Could not find State/ directory for project '${project}'.`);
+    console.error(`  Looked in: ${evidenceDir}/*/State/ and ${resolve(cwd, project, 'State')}/`);
+    console.error(`  Run 'kushi state ${project}' first to build State/.\n`);
+    process.exit(1);
+  }
+
+  const child = spawn('pwsh', ['-NoProfile', '-File', scriptPath, '-StateDir', stateDir], {
+    stdio: 'inherit',
+    cwd: resolve(__dirname, '..'),
+  });
+
+  return new Promise((res, rej) => {
+    child.on('close', (code) => {
+      if (code !== 0) rej(new Error(`lint-state exited with code ${code}`));
+      else res();
+    });
+    child.on('error', rej);
+  });
+}
+
+function pickFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  const prefix = flag + '=';
+  const m = args.find((a) => a.startsWith(prefix));
+  return m ? m.slice(prefix.length) : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.0.3",
+  "version": "5.1.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",
+    "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",
     "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

@@ -17,8 +17,8 @@ Kushi ships in three profiles. The installed profile is recorded in `kushi-insta
 | Profile | What's installed | Verbs available |
 |---|---|---|
 | `core` | Aggregator only: `setup`, `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `vertex-link`, `emit-vertex`, `self-check`, `eval`, `intro` | `setup`, `aggregate`, `consolidate`, `status`, `pull`, `ask`, `vertex-link`, `emit-vertex` |
-| `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `fde-intake`, `fde-report`, `fde-triage` |
-| `full` | standard + `build-state` | standard + `state` |
+| `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `lint-state`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `lint`, `fde-intake`, `fde-report`, `fde-triage` |
+| `full` | standard + `build-state`, `link-entities`, `dashboard`, `tour` | standard + `state`, `link-entities`, `dashboard`, `tour` |
 | **`preview`** *(opt-in)* | standard + `propose-ado-update`, `apply-ado-update` | standard + `propose-ado`, `apply-ado` |
 
 The Evidence/ folder produced by `aggregate` is the **public contract** between Kushi and any downstream consumer (external rollup repo, BI tooling). See `docs/reference/evidence-contract.md`.
@@ -39,6 +39,7 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 | `@Kushi link-entities <project>` | standard+ | n/a (read-only) | v5.0.0 — `link-entities` writes `<project>/Evidence/_graph/project-graph.json` from per-source `_index/entities.yml` + weekly CSC bodies. Deterministic by default; opt-in LLM augment via `m365Mutable.graph.llm_infer`. |
 | `@Kushi dashboard <project>` | standard+ | n/a (read-only) | v5.0.0 — `dashboard` writes `<project>/dashboard.html` (single self-contained file). Cytoscape.js v3 + Clawpilot theme. |
 | `@Kushi tour <project> [--top N]` | standard+ | n/a (read-only) | v5.0.0 — `tour` writes `<project>/State/tour.md`, an auto-generated week-in-review walkthrough scored by `recency_weight × cross_ref_count` (14-day half-life). Default N=10. |
+| `@Kushi lint <project>` | standard+ | n/a (read-only) | v5.1.0 — `lint-state` runs wiki-lint checks against `State/` (contradictions, stale claims, orphans, missing cross-refs, data gaps). Writes `State/reports/lint-YYYY-MM-DD.md`. |
 | `@Kushi consolidate <project> last N days` | core+ | N days | `consolidate-evidence` only |
 | `@Kushi status <project>` | core+ | n/a | `project-status` — show run-log |
 | `@Kushi ask <project> <question>` | core+ | n/a (read-only) | `ask-project` — cited Q&A over Evidence/ (+ State/ on full) |
@@ -182,4 +183,6 @@ Meta skills (not called by verbs):
 | Skill | Role |
 |---|---|
 | `self-check` | Pre-commit consistency check across skills, instructions, prompts, and docs. Run with `pwsh plugin/skills/self-check/run.ps1` (or `./run.sh` on macOS/Linux) or by asking "kushi self-check". |
+| `skill-creator` | (v5.0.4) Scaffolds a new compliant skill — frontmatter + USE WHEN description + type-driven required section + starter evals. Run with `node bin/cli.mjs create-skill --name <kebab> --type <writer\|orchestrator\|pull\|other> --description "..."`. |
+| `skill-checker` | (v5.0.4) Lints + retrofits every SKILL.md against `skill-authoring.instructions.md`. Modes: `-Lint` / `-Retrofit` / `-Apply` / `-OptimizeDescription` / `-Review` / `-All`. Run with `node bin/cli.mjs check-skill --all`. |
 | `intro` | Self-introduction + interactive walkthrough. Triggered by "what is kushi", "what can you do", "kushi intro", "i'm new to kushi", "kushi help". |

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

@@ -0,0 +1,88 @@
+---
+name: "living-wiki"
+description: "v5.1.0 — Incremental-maintenance + contradiction-handling pattern for State/. Build-state preserves human edits outside <!-- kushi:auto --> fences; contradictions are flagged with callouts, never silently overwritten. Adapted from Karpathy's living-wiki gist. Authored to agentskills.io spec; deltas: adds incremental fencing convention + contradiction lifecycle + auto-resolve threshold not present in source."
+applies_to: "build-state, lint-state, all writers touching State/"
+since: "kushi v5.1.0"
+---
+
+# living-wiki — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (Karpathy's living-wiki gist): adds `<!-- kushi:auto -->` fencing convention, contradiction lifecycle (current → contradicted → superseded), auto-resolve threshold with 3 conditions, `_review-queue.md` open-contradiction tracker.
+
+Adapted from [Karpathy's living-wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). The core insight: a wiki maintained by both humans and machines must have clear ownership boundaries and explicit conflict resolution — silent overwrites destroy trust.
+
+## Rules (HARD)
+
+### 1. Incremental maintenance
+
+Every writer skill that touches `State/` MUST:
+
+- **Preserve human edits.** Content outside `<!-- kushi:auto:start -->` / `<!-- kushi:auto:end -->` fences is NEVER modified by automation. Writers only update derived sections between those fences.
+- **Never wipe the page.** If a page exists, read it first. Regenerate only the fenced regions. If the page does not exist, create it with fences around any auto-derived content.
+- **Fence hygiene.** Every auto-derived block MUST be wrapped:
+  ```markdown
+  <!-- kushi:auto:start section="<section-id>" -->
+  ...auto-derived content...
+  <!-- kushi:auto:end section="<section-id>" -->
+  ```
+  The `section` attribute identifies which derivation produced this block (e.g., `section="entity-summary"`, `section="related-entities"`).
+
+### 2. Contradiction handling
+
+When a new fact contradicts an existing claim (different value for the same entity property):
+
+- **Flag both claims** with Obsidian-compatible callouts:
+  ```markdown
+  > [!warning] Contradicted by build-state run 2026-05-28
+  > Previous value: "MACC $500K" [source: ushak/crm/weekly/2026-05-01_crm-csc.md#acme-opp · 2026-05-01]
+  
+  > [!info] New value (2026-05-28)
+  > Current value: "MACC $750K" [source: ushak/crm/weekly/2026-05-22_crm-csc.md#acme-opp · 2026-05-22]
+  ```
+- **Never silently overwrite.** The old value stays visible until explicitly resolved.
+- **Add to `_review-queue.md`** with entity, property, old value, new value, both sources, and date flagged.
+
+### 3. Contradiction lifecycle
+
+Each contradicted claim moves through states:
+
+| State | Meaning |
+|---|---|
+| `current` | Active, accepted truth. |
+| `contradicted` | A newer claim disagrees. Both are visible. |
+| `superseded` | Resolved — old claim is archived. The newer (or human-chosen) value wins. |
+
+### 4. Auto-resolve threshold
+
+A contradicted claim MAY be automatically marked `superseded` (and removed from `_review-queue.md`) when ALL of:
+
+1. The new claim has **≥ 3 corroborating sources from different surfaces** (e.g., meetings + CRM + email all agree on the new value).
+2. The contradicted claim is **≥ 30 days old** (based on its source citation date).
+3. The contradicted claim has **no human override marker** (`<!-- kushi:human-override -->` above the claim blocks auto-resolve).
+
+When auto-resolved, replace the callout pair with:
+```markdown
+> [!info] Auto-resolved 2026-06-28 — superseded by 3+ corroborating sources (meetings, crm, email)
+> Previous value archived: "MACC $500K" [source: ...]
+```
+
+### 5. `_review-queue.md`
+
+Located at `Evidence/<alias>/State/_review-queue.md`. Lists all open (unresolved) contradictions:
+
+```markdown
+# Review Queue
+
+| Entity | Property | Old value | New value | Flagged | Sources |
+|---|---|---|---|---|---|
+| Acme Opp | MACC | $500K | $750K | 2026-05-28 | crm, meetings |
+```
+
+Updated by `build-state` on every run. Cleared when contradictions are resolved (auto or manual).
+
+## References
+
+- [Karpathy's living-wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+- `karpathy-state-layout.instructions.md` (v5.0.0 base layout)
+- `wiki-lint.instructions.md` (contradiction-flagged finding class)

package/plugin/instructions/log-format.instructions.md

@@ -0,0 +1,78 @@
+---
+name: "log-format"
+description: "v5.1.0 — Canonical log format for State/log.md. Every writer appends reverse-chronological entries with grep-friendly headings. Adapted from axoviq-ai/synthadoc log-as-history pattern. Authored to agentskills.io spec; deltas: kushi-specific ops taxonomy, index.md 'Last touched' pointer, append-only rule."
+applies_to: "every writer skill that touches State/ (bootstrap-project, refresh-project, build-state, lint-state, link-entities, dashboard, tour, ask-project --file-back)"
+since: "kushi v5.1.0"
+---
+
+# log-format — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (axoviq-ai/synthadoc): kushi-specific op taxonomy (`bootstrap`, `refresh`, `build-state`, `lint-state`, `ask-fileback`, `link-entities`, `dashboard`, `tour`), `index.md` "Last touched" pointer, reverse-chronological append-only rule.
+
+Adapted from [axoviq-ai/synthadoc](https://github.com/axoviq-ai/synthadoc) — the log-as-grep-friendly-history pattern.
+
+## Rules (HARD)
+
+### 1. Canonical format
+
+Every entry in `Evidence/<alias>/State/log.md` MUST use this heading format:
+
+```markdown
+## [YYYY-MM-DD HH:MM] <op> | <title>
+
+<1–3 line summary>
+Sources: <comma-separated source pointers>
+```
+
+Example:
+```markdown
+## [2026-05-28 14:30] build-state | Incremental rebuild (3 entities updated)
+
+Re-derived people/jane-doe.md, decisions/macc-increase.md, risks/timeline-slip.md.
+Contradictions flagged: 1 (Acme Opp MACC). Auto-resolved: 0.
+Sources: ushak/crm/weekly/2026-05-22_crm-csc.md, ushak/meetings/weekly/2026-05-21_meetings-csc.md
+```
+
+### 2. Grep-friendly
+
+The heading format is designed for grep:
+```bash
+grep '^## \[2026-05-' log.md          # all May 2026 entries
+grep '^## \[.*\] build-state' log.md   # all build-state runs
+grep '^## \[.*\] lint-state' log.md    # all lint runs
+```
+
+### 3. Ops taxonomy (closed set)
+
+| Op | Writer skill | Meaning |
+|---|---|---|
+| `bootstrap` | bootstrap-project | First-time project setup |
+| `refresh` | refresh-project | Incremental evidence pull + state rebuild |
+| `build-state` | build-state | Pure re-render of State/ from Evidence/ |
+| `lint-state` | lint-state | Wiki lint pass over State/ |
+| `ask-fileback` | ask-project --file-back | Q&A answer written back to State/answers/ |
+| `link-entities` | link-entities | Cross-source graph rebuild |
+| `dashboard` | dashboard | Dashboard HTML regeneration |
+| `tour` | tour | Guided tour regeneration |
+
+### 4. Append-only, reverse-chronological
+
+- New entries are **prepended** (newest at top, after the front-matter and file header).
+- Entries are NEVER deleted or rewritten.
+- Readers scan top-down for recency.
+
+### 5. Index.md "Last touched" pointer
+
+After appending to `log.md`, the writer MUST also update the top of `State/index.md`:
+
+```markdown
+> Last touched: YYYY-MM-DD HH:MM by <op> ([log](log.md))
+```
+
+This single-line pointer lives immediately after the front-matter block of `index.md`.
+
+## References
+
+- [axoviq-ai/synthadoc](https://github.com/axoviq-ai/synthadoc)
+- `karpathy-state-layout.instructions.md` (log.md base contract)

package/plugin/instructions/skill-authoring.instructions.md

@@ -0,0 +1,147 @@
+---
+name: "skill-authoring"
+description: "v5.0.4 — How to author a new kushi skill so it ships conformant to the agentskills.io blueprint on day one. Codifies the required SKILL.md sections, file layout, evals starter, naming, and the description-optimization rules. Read this before running `npx kushi-agents create-skill`. Enforced by self-check D34.creator-conformance + by `kushi check-skill --lint`."
+applies_to: "every plugin/skills/<name>/ created from v5.0.4 onward; existing skills are audited via the dogfood gate"
+since: "kushi v5.0.4"
+---
+
+# skill-authoring — doctrine
+
+> Inspired by **Anthropic's [skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)**. Adapted to kushi's PowerShell-first stack, our 2-host install matrix, and the reality that the first 30 kushi skills were authored before any harness existed — hence the **retrofit** path in `skill-checker`.
+
+## Why this exists
+
+A SKILL.md is the prompt that loads into the agent the moment its trigger fires. Drift between intent and spec is silent until evals catch it (and only if there are evals). This doctrine + the `skill-creator` + `skill-checker` skills make conformant authoring the default, not an afterthought.
+
+## Required files per skill
+
+```text
+plugin/skills/<name>/
+├── SKILL.md                 ← REQUIRED — agent-loaded prompt; ≤500 lines, ≤5000 tokens
+├── evals/
+│   └── evals.json           ← REQUIRED — ≥2 cases, each with ≥1 assertion
+├── references/              ← OPTIONAL — load-on-trigger bulk content (>500 lines splits here)
+└── .created-by-skill-creator  ← OPTIONAL marker — set by `scaffold.ps1`; opts into the strict D34 gate
+```
+
+A skill MAY also ship a runner (`run.ps1`, `run.sh`, `*.mjs`) when it's a tool-skill (`self-check`, `eval`, `skill-checker`, etc.). Pure prompt-skills don't need one.
+
+## Required SKILL.md sections
+
+Every SKILL.md MUST have:
+
+1. **YAML frontmatter** — `name` (kebab-case, matches dir) + `description` (lead with `USE WHEN`).
+2. **`# Skill: <name>`** H1.
+3. **One-paragraph purpose** immediately after the H1.
+4. **At least one** of these procedure-shape sections, picked by skill **type**:
+   - `## Gotchas` — REQUIRED for `pull-*` and discovery skills (top-5 failure modes).
+   - `## Step checklist` — REQUIRED for orchestrators (`bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour`, etc.); use GitHub `- [ ]` checkboxes.
+   - `## Validation loop` — REQUIRED for writer skills (anything that writes to `Evidence/`, `State/`, `_graph/`, `dashboards/`, `tours/`).
+   - `## Steps` or `## Procedure` — acceptable for other skills, plus one of the three above where it applies.
+
+Skills can have more than one (e.g. `eval` ships all three). The checker is satisfied by **at least one** of `Gotchas` / `Step checklist` / `Validation loop` plus type-specific rules.
+
+## Description optimization (per agentskills.io)
+
+The `description:` is the sole trigger signal. Optimize it:
+
+```yaml
+description: "USE WHEN <situational trigger> AND <precondition>. DO NOT USE for <near-miss>. <one-line capability summary>."
+```
+
+Rules (enforced by `D30.description-optimized` + `skill-checker --optimize-description`):
+
+- Lead with `USE WHEN` (first 160 chars).
+- Include a `DO NOT USE` clause for the most likely near-miss invocation.
+- Be specific about the trigger (concrete user phrases or file/state conditions).
+- No marketing fluff ("powerful", "comprehensive", "blazing").
+- ≤1024 characters total.
+
+| Bad | Good |
+|---|---|
+| `"Pulls OneNote pages."` | `"USE WHEN refreshing project evidence for a known kushi project AND boundaries.onenote.section_ids is non-empty. DO NOT USE for global OneNote search."` |
+| `"Comprehensive eval framework."` | `"USE WHEN the user says 'run evals', 'eval canary', or before tagging a release. DO NOT USE for evidence validation of a real project."` |
+
+## Size caps
+
+- ≤ 500 lines (`D30.skill-size`)
+- ≤ 5000 tokens (~20 KB)
+
+When you exceed either, **split into `references/<topic>.md` files** and cite them with explicit triggers:
+
+```markdown
+Load `references/canonical-prompts.md` when constructing the WorkIQ query.
+Load `references/error-modes.md` if the API returns non-200.
+```
+
+Passive links (`[see foo](references/foo.md)`) do NOT count. The checker requires the literal substring `references/<file>.md` somewhere in SKILL.md if `references/` exists.
+
+## Evals (≥2 cases)
+
+Every skill MUST ship `evals/evals.json` validated against `plugin/skills/eval/evals.schema.json`. Per `skill-evals.instructions.md`:
+
+- `id`, `name`, `input`, `expected_assertions[]` (≥1), `grader_type` (`script` | `llm`).
+- ≥2 cases. Mark canary-worthy ones `"canary": true`.
+- Synthetic fixtures only — never real customer data.
+
+The `create-skill` scaffold emits a starter `evals.json` with one `file-exists` and one `regex-match` case so the skill ships green from minute one.
+
+## Naming conventions
+
+- **Skill directory + frontmatter `name`** — kebab-case, verb-led (`pull-onenote`, `consolidate-evidence`, `apply-ado-update`).
+- **Skill types** (informational; pick at create time so the scaffold picks the right sections):
+  - `pull` — fetches evidence from a source.
+  - `writer` — writes files to `Evidence/` or `State/`.
+  - `orchestrator` — coordinates other skills.
+  - `other` — utility / tool / meta.
+- **Instruction files** — `<topic>.instructions.md` in `plugin/instructions/`. Front-matter `name:` matches filename minus `.instructions.md`.
+
+## Contributor workflow
+
+```powershell
+# 1. Scaffold
+npx kushi-agents create-skill my-new-skill
+#   → answers: type (pull|writer|orchestrator|other), one-liner description
+#   → emits plugin/skills/my-new-skill/{SKILL.md, evals/evals.json}
+#   → marker file .created-by-skill-creator is written
+
+# 2. Fill in the placeholders (search for "TODO(skill-creator)")
+
+# 3. Validate
+npx kushi-agents check-skill my-new-skill        # lint mode
+npm run eval -- my-new-skill                     # run evals
+
+# 4. Optimize description before PR
+npx kushi-agents optimize-description my-new-skill
+#   → emits a rewritten description; you decide whether to apply
+
+# 5. Self-check + commit
+pwsh plugin/skills/self-check/run.ps1 -Deep
+git add plugin/skills/my-new-skill/
+git commit -m "v<x.y.z>: my-new-skill"
+```
+
+## Retrofit (existing skills predating the harness)
+
+Run `npx kushi-agents check-skill --all --retrofit` to identify gaps in legacy skills. `--apply` adds missing section stubs with `<!-- TODO(retrofit): fill in -->` markers — never overwrites existing content. The v5.0.4 dogfood report at `docs/audits/v5.0.4-skill-creator-dogfood.md` records the baseline.
+
+## Enforcement
+
+| Check | What it does |
+|---|---|
+| `D34.skill-creator-exists` | `plugin/skills/skill-creator/scaffold.ps1` is parseable. |
+| `D34.skill-checker-exists` | `plugin/skills/skill-checker/check-skill.ps1` is parseable. |
+| `D34.creator-output-conforms` | Every skill carrying `.created-by-skill-creator` passes `check-skill --lint`. |
+| `D34.retrofit-clean` | `check-skill --all --retrofit --dry-run` shows no unresolved non-additive gaps. |
+| `D34.dogfood-report-fresh` | `docs/audits/v5.0.4-skill-creator-dogfood.md` was touched within 14 days (warn-only). |
+
+## References
+
+- `plugin/instructions/agentskills-compliance.instructions.md` — the spec rules this builds on.
+- `plugin/instructions/skill-evals.instructions.md` — the evals doctrine.
+- `plugin/skills/skill-creator/SKILL.md` — the scaffolder.
+- `plugin/skills/skill-checker/SKILL.md` — the linter / retrofitter.
+- `docs/contributing/skill-authoring.md` — the human walkthrough.
+- <https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md> — upstream inspiration.
+- <https://agentskills.io/skill-creation/best-practices>
+- <https://agentskills.io/skill-creation/optimizing-descriptions>