kushi-agents 6.1.1 → 6.2.0

package/package.json

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

package/plugin/instructions/agentskills-compliance.instructions.md

@@ -0,0 +1,144 @@
+---
+name: "agentskills-compliance"
+description: "Spec-compliance doctrine. Aligns every plugin/skills/<name>/SKILL.md with the conventions from https://agentskills.io/skill-creation/best-practices and /optimizing-descriptions. Defines size caps, load-on-trigger layout, gotchas, checklists, validation loops, plan-validate-execute, defaults-not-menus, and description-optimization rules. Enforced by self-check D30."
+applies_to: "every plugin/skills/<name>/SKILL.md"
+since: "kushi v5.0.1"
+---
+
+# agentskills-compliance — doctrine
+
+A SKILL.md is loaded **fully** into the agent's context window the moment it triggers. Every token competes with the conversation, system prompt, and other active skills. Compliance with the agentskills.io best-practices is therefore not stylistic — it is a context-budget contract.
+
+Authoritative external references:
+
+- <https://agentskills.io/skill-creation/best-practices>
+- <https://agentskills.io/skill-creation/optimizing-descriptions>
+
+## Rules (HARD)
+
+### 1. Size cap
+
+Every `plugin/skills/<name>/SKILL.md` MUST be:
+
+- ≤ **500 lines**, AND
+- ≤ **5000 tokens** (approximated by `char_count / 4`).
+
+Oversize SKILLs MUST be split per rule 2 below. Enforced by `self-check D30.skill-size`.
+
+### 2. Load-on-trigger layout
+
+`plugin/skills/<name>/SKILL.md` contains:
+
+- front-matter (`name`, `version`, `description`)
+- one-paragraph purpose
+- `## Gotchas` (top 5) — pull-* skills MUST have this
+- numbered or checklist procedure
+- `## Validation loop` (writer skills)
+- output contract
+
+Bulk content (full canonical WorkIQ prompts, full error-mode taxonomies, deep schema details, worked examples) moves to `plugin/skills/<name>/references/<topic>.md`. Standard reference filenames:
+
+| File | Contents |
+|------|----------|
+| `references/canonical-prompts.md` | Full WorkIQ prompt text (tier A/B/C, CSC, recovery) |
+| `references/error-modes.md` | Error taxonomy with retry semantics |
+| `references/taxonomy.md` | CSC schema deep details (where source-specific) |
+| `references/examples.md` | Full worked examples |
+| `references/playwright-fallback.md` | Opt-in fallback procedures |
+
+Every reference cited from SKILL.md MUST be cited with an **explicit trigger**, not a passive link. Trigger templates:
+
+```
+> Load references/canonical-prompts.md when constructing the WorkIQ query for this source.
+> Load references/error-modes.md if the API returns non-200, or WorkIQ returns "throttled".
+> Load references/playwright-fallback.md only when WorkIQ body-retrieval rate stays poor across ≥2 refreshes.
+```
+
+Enforced by `self-check D30.references-layout`.
+
+### 3. Gotchas (top 5)
+
+Every `pull-*` SKILL.md MUST surface its top 5 gotchas in a `## Gotchas` section near the top (immediately after the H1 / opening paragraph; before `## Steps` or `## Procedure`).
+
+Format: bullet list. Each bullet starts with the **concrete failure mode**, then the correction.
+
+```markdown
+## Gotchas
+
+- **Moved pages keep original wdsectionfileid** → if a section returns `page-body-unavailable` or zero `wdpartid` entries, the pages were authored elsewhere and moved. Open OneNote desktop, drag pages back into target section, retry.
+- **WorkIQ tier C requires ONE page per call** — batching multiple pages into a single ask returns empty results. Loop over pageIds, one call each.
+```
+
+Pull from `plugin/learnings/<source>.md` if present; else extract from the SKILL body itself. Enforced by `self-check D30.gotchas-section`.
+
+### 4. Checklists for orchestrators
+
+Orchestrator SKILLs (`bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour`) MUST use GitHub checkbox syntax `- [ ]` for their step lists so progress is trackable in tooling and in conversation.
+
+```markdown
+- [ ] Step 1 — Resolve engagement root.
+- [ ] Step 2 — Resolve project alias.
+- [ ] Step 3 — Preflight per source.
+```
+
+Enforced by `self-check D30.checklist-orchestrators`.
+
+### 5. Validation loops (writer skills)
+
+Every skill that writes files to `Evidence/`, `State/`, `_graph/`, `dashboards/`, or `tours/` MUST end with a `## Validation loop` section:
+
+```markdown
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted <area>`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.
+```
+
+Enforced by `self-check D30.validation-loop`.
+
+### 6. Plan-validate-execute (link-entities + build-state)
+
+See `plan-validate-execute.instructions.md`. The skill writes a plan JSON, validates against a source of truth, then executes.
+
+### 7. Defaults not menus
+
+Pick ONE tool for each procedure step. Alternatives are escape hatches and MUST live in `references/` (e.g. `references/playwright-fallback.md`), not in the main SKILL body. The SKILL.md procedure does not enumerate alternatives.
+
+### 8. Procedures over declarations
+
+Write what the agent must DO, not what the skill IS. Imperative voice, concrete steps.
+
+### 9. Description optimization
+
+Per <https://agentskills.io/skill-creation/optimizing-descriptions> the `description:` front-matter is the sole trigger signal. It MUST describe **WHEN to use** the skill (trigger conditions), not just what it does. Convention for kushi skills:
+
+```yaml
+description: "USE WHEN <situational trigger> AND <precondition>. DO NOT USE for <near-miss>. <one-line capability summary>."
+```
+
+- BAD: `"Pulls OneNote pages and saves them as markdown."`
+- GOOD: `"USE WHEN refreshing project evidence for a known kushi project AND the project boundaries.onenote.section_ids list is non-empty. DO NOT USE for global OneNote search or non-kushi note capture."`
+
+Hard limit: 1024 characters. Enforced loosely by `self-check D30.description-optimized` (checks for the literal substring `USE WHEN` or `WHEN ` near the start of `description:`).
+
+## Migration checklist (per oversized SKILL)
+
+- [ ] Move full WorkIQ prompts → `references/canonical-prompts.md`
+- [ ] Move full error taxonomy → `references/error-modes.md`
+- [ ] Move source-specific schema details → `references/taxonomy.md`
+- [ ] Move opt-in fallbacks (Playwright, Edge profile bootstrap) → `references/playwright-fallback.md`
+- [ ] Add `## Gotchas` (top 5)
+- [ ] Add `## Validation loop` (if writer)
+- [ ] Replace inline blocks with "Load references/&lt;file&gt; when …" pointers
+- [ ] Bump skill version (minor) since structure changed
+- [ ] Re-run `self-check D30` and `npm test`
+
+## References
+
+- `instructions/plan-validate-execute.instructions.md`
+- `instructions/capture-learnings.instructions.md`
+- `instructions/issue-recovery.instructions.md`

package/plugin/instructions/dashboard-artifact.instructions.md

@@ -0,0 +1,132 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Interactive HTML dashboard. Single self-contained `<project>/dashboard.html` rendered from `_graph/project-graph.json` + `_index/entities.yml` (per source) + `State/index.md`. Uses Cytoscape.js v3 + cose-bilkent layout, two-view tabs (Graph + Timeline), source/alias/date filters, fuzzy search, and a side panel that surfaces weekly CSC blocks on node click. Theming follows the Clawpilot `web-artifacts-builder` skill (CSS variables). Idempotent — regenerated every run."
+---
+
+# Dashboard Artifact — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+Stakeholders ask "what happened on this engagement?" and we hand them
+markdown nobody reads. v5.0.0 ships a single HTML file that visualizes the
+project graph and lets the reader click any node to surface the cited CSC
+block. No server, no build, no install — just open the file.
+
+## Output
+
+- **Path:** `<engagement-root>/<project>/dashboard.html`
+- **Producer:** `dashboard` skill.
+- **Idempotency:** the file is **fully regenerated** every run. The producer
+  embeds the latest graph + indices + state catalog inline. There is no
+  external fetch at view time; the file opens from any path on any browser.
+
+## Input contract
+
+The dashboard reads three things (all OPTIONAL; missing inputs gracefully
+degrade the view):
+
+1. `<project>/Evidence/_graph/project-graph.json` — nodes + edges.
+2. `<project>/Evidence/<alias>/<source>/_index/entities.yml` for every
+   contributor / source — surfaces `latest_csc_file` + per-entity weekly
+   pointers used by the side panel.
+3. `<project>/State/index.md` — list of v5 State pages, used to populate the
+   side panel's "State pages" section.
+
+If `_graph/project-graph.json` is missing, the dashboard is not produced.
+(Self-check D22.dashboard enforces this.)
+
+## Output contract
+
+A **single self-contained HTML file** with:
+
+- All JS libraries inlined (no CDN at view time).
+- All graph + index + state data inlined via
+  `<script id="graph-data" type="application/json">...</script>`
+  (and sibling `index-data` / `state-data` scripts).
+- All CSS inlined using Clawpilot theme variables (per the
+  `web-artifacts-builder` skill).
+
+## Rendering stack
+
+- **Cytoscape.js v3.x** for graph rendering (Q2 = B locked in the v5 plan).
+  v3.x because it is the current major; v3 ships an ES5-friendly minified
+  build that inlines cleanly into a single HTML file.
+- **cytoscape-cose-bilkent** layout for force-directed node placement.
+- **Optional fuzzy search:** inline `fuse.js` (≈ 9 KB minified) OR a 30-line
+  bespoke fuzzy matcher in the template — producer's choice based on the
+  final inline size budget.
+
+CDN URLs are referenced at template **author time** for traceability, but
+the bytes themselves are **embedded inline** in
+`plugin/templates/dashboard/dashboard.template.html`. The shipped file does
+NOT fetch from any CDN at view time.
+
+## Theming
+
+Follows the Clawpilot `web-artifacts-builder` skill. The template MUST use
+CSS variables (`--bg`, `--fg`, `--accent`, `--surface`, `--border`, etc.)
+defined by that skill so the dashboard adopts the user's Clawpilot theme when
+opened inside Clawpilot, and falls back to a Clawpilot-default light/dark
+scheme when opened in a vanilla browser.
+
+## Views
+
+The dashboard exposes two views via top-level tabs:
+
+1. **Graph view** — Cytoscape canvas. Nodes colored by `source`. Edge style
+   varies by `kind`. Default layout: `cose-bilkent`. Pan + zoom +
+   click-to-select.
+2. **Timeline view** — CSS-grid layout with one column per ISO week (computed
+   from `last_touched_iso` across all nodes). Within each column, nodes are
+   stacked + grouped by source. Click selects same as Graph view.
+
+## Side panel
+
+Clicking a node opens a side panel showing:
+
+- Title + source pill + last_touched date.
+- `weekly_refs` — each rendered as a collapsible block. When expanded, the
+  block loads the cited CSC anchor inline (HTML-rendered markdown extracted
+  client-side from the embedded weekly file text, or — if the file body is
+  too large to inline — a click-through link to the file path).
+- Incoming + outgoing edges with their evidence snippets + kind pill.
+- Related State pages (resolved via `State/index.md`) as `[[wikilink]]`
+  click-throughs that open `State/<category>/<slug>.md`.
+
+## Filters
+
+A header strip exposes:
+
+- **Source** — multi-select pill list of the seven source families.
+- **Alias** — multi-select of contributors who touched the project.
+- **Date range** — slider over ISO-week buckets between
+  `min(first_seen_iso)` and `max(last_touched_iso)` across all nodes.
+
+Filter application is client-side; no re-fetch.
+
+## Search
+
+A search box (top-right of header) does fuzzy match on node `title`.
+Selecting a hit pans the Graph view to the node and opens the side panel.
+
+## Configuration
+
+Producer reads from the user's `m365-mutable.json` /
+`integrations.yml#dashboard.*` (no required keys today; reserved for future
+options like `dashboard.layout` override or `dashboard.maxNodes`).
+
+## Self-check
+
+`D22.dashboard` enforces:
+
+- If `_graph/project-graph.json` exists, `<project>/dashboard.html` exists.
+- WARN (not fail) if `dashboard.html` is older than the graph file (suggests
+  the user ran `link-entities` standalone without `dashboard`).
+
+## Cross-references
+
+- `entity-graph.instructions.md` — input schema (source of truth).
+- `karpathy-state-layout.instructions.md` — `State/index.md` is one of the
+  inputs.
+- `web-artifacts-builder` (Clawpilot user skill) — theming + single-HTML
+  packaging contract.

package/plugin/instructions/evidence-layout-canonical.instructions.md

@@ -62,8 +62,8 @@ Concretely, a pull skill MUST NOT create or write to any of these (representativ
 | `<project>/_Weekly Summaries/` | `<project>/Evidence/<alias>/<source>/weekly/` |
 | `<project>/Meetings/` (at project root) | `<project>/Evidence/<alias>/meetings/` |
 | `<project>/Teams/` (at project root) | `<project>/Evidence/<alias>/teams/` |
-| `<project>/SharePoint/` (at project root) | `<project>/Evidence/<alias>/sharepoint/` |
-| `<project>/CRM/`, `<project>/ADO/` (at project root) | `<project>/Evidence/<alias>/{crm,ado}/` |
+| `<project>/SharePoint/` (at project root) | `<project>/Evidence/_shared/sharepoint/` (project-scoped; v6.1.2+) |
+| `<project>/CRM/`, `<project>/ADO/` (at project root) | `<project>/Evidence/_shared/{crm,ado}/` |
 | any `<project>/<source>-context/`, `<project>/<source>-summary/`, etc. | `<project>/Evidence/<alias>/<source>/weekly/` |
 
 `State/`, `Reports/`, `integrations.yml` are the **only** top-level siblings of `Evidence/` that pull/refresh skills are allowed to leave alone (they are written by `build-state`, `aggregate-project`, and bootstrap respectively — not by pull-* skills).
@@ -83,7 +83,7 @@ If alias is ambiguous (legacy folder pre-dates multi-user), default to the curre
 
 By contract, downstream skills walk:
 
-- `Evidence/*/email/`, `Evidence/*/teams/`, `Evidence/*/meetings/`, `Evidence/*/onenote/`, `Evidence/*/sharepoint/`, `Evidence/*/crm/`, `Evidence/*/ado/`
+- `Evidence/*/email/`, `Evidence/*/teams/`, `Evidence/*/meetings/`, `Evidence/*/onenote/`, `Evidence/_shared/sharepoint/`, `Evidence/_shared/crm/`, `Evidence/_shared/ado/`
 
 Anything outside these paths is invisible to them — by design. The path IS the contract. There is no "also scan sibling folders" fallback.
 

package/plugin/instructions/guided-tour.instructions.md

@@ -0,0 +1,100 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Guided tour. Auto-generated week-in-review markdown walkthrough at `<project>/State/tour.md`. Score: `recency_weight × cross_ref_count`. recency_weight = exp(-days_since_last_touched / 14). cross_ref_count = degree in the graph. DFS through edges in priority order (decides → action-item-tracks → discusses → references → others). Default top-N = 10 (configurable via `m365Mutable.tour.topN`)."
+---
+
+# Guided Tour — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+After link-entities + build-state, the project has a graph and a wiki, but
+nothing tells a reader **where to start**. The tour is a small ranked
+walkthrough that picks the most-recent, highest-degree entities and DFS-walks
+their connections in order of edge importance.
+
+## Output
+
+- **Path:** `<engagement-root>/<project>/State/tour.md`
+- **Producer:** `tour` skill.
+- **Idempotency:** fully regenerated each run.
+- **Empty case:** if `_graph/project-graph.json` has zero nodes, `tour.md` is
+  written with a single line: `_No graph nodes — run @Kushi refresh first._`
+
+## Scoring
+
+For each node N in the graph:
+
+```
+days_since = max(0, today - last_touched_iso)        # in whole days, UTC
+recency_weight = exp(- days_since / 14)              # 14-day half-life ≈ ln(2)/14 ≈ 0.0495
+cross_ref_count = degree(N)                          # in + out edges, dedupe by edge identity
+score(N) = recency_weight × cross_ref_count
+```
+
+Sort nodes by `score` descending. Take the top-N (default 10; configurable
+via `m365Mutable.tour.topN` in the user's per-project mutable config).
+
+## DFS ordering
+
+Tour stops are emitted in DFS order starting from the highest-scored node:
+
+1. Start with the highest-scored unvisited node → emit it as the next stop.
+2. Pick the next node by walking that node's edges in **edge priority order**:
+   1. `decides`
+   2. `action-item-tracks`
+   3. `discusses`
+   4. `references`
+   5. (any other kind in `entity-graph.instructions.md` taxonomy)
+   Within a priority bucket, prefer the edge whose target has the highest
+   unvisited `score`.
+3. Skip nodes already visited (cycle break).
+4. If the DFS hits a dead end before reaching N stops, restart from the
+   next-highest-scored unvisited node.
+5. Stop after N stops emitted.
+
+## Per-stop markdown shape
+
+```markdown
+## <ordinal>. <Node title>
+
+> _Why this matters:_ <one-line synthesis — recency + degree + dominant edge
+> kind, e.g. "Touched 3 days ago; ties together 5 ADO items and 2 CRM
+> opportunities."_
+
+- **Source:** `<source>` · last touched `YYYY-MM-DD`
+- **Cite:** [`<alias>/<source>/weekly/<file>#<anchor>`](<relative path>)
+- **Related State pages:** [[slug-a]] · [[slug-b]] · …
+```
+
+Citations MUST resolve on disk (D23.tour enforces this).
+
+## Header
+
+The file starts with:
+
+```markdown
+---
+kushi_tour: true
+generated_at: <ISO-8601 UTC>
+generated_by_alias: <alias>
+top_n: <N>
+score_basis: "recency_weight × cross_ref_count (14-day half-life)"
+---
+
+# Guided Tour — <project>
+
+> _Auto-generated week-in-review. <N> top entities by recency × cross-reference count._
+```
+
+## Self-check
+
+`D23.tour` enforces:
+
+- If `_graph/project-graph.json` has ≥ 1 node, `State/tour.md` exists.
+- Every tour stop's citation resolves to an existing weekly file + anchor.
+
+## Cross-references
+
+- `entity-graph.instructions.md` — source of nodes + edge taxonomy.
+- `karpathy-state-layout.instructions.md` — `[[wikilink]]` resolution rules
+  used by per-stop "Related State pages".

package/plugin/instructions/karpathy-state-layout.instructions.md

@@ -0,0 +1,124 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Karpathy-style State/ layout. The State/ folder adopts the convention (index.md + log.md + CLAUDE.md + AGENTS.md + `[[wikilinks]]`) so external wiki tools (Understand-Anything, Obsidian, Foam, GitHub-pages wiki viewers) render it without custom work. Backward-compatible with v4.x State/ — v5 pages are distinguished by `kushi_state_page: true` front-matter."
+---
+
+# Karpathy State Layout — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+Today `State/` is a kushi-private synthesis layout. Adopting the
+Karpathy-pattern wiki convention (`index.md` + `log.md` + `[[wikilinks]]`)
+makes State/ readable by any wiki tool — most importantly
+Understand-Anything's `/understand-knowledge` skill, which already does
+community clustering, entity extraction, and graph rendering for free
+**if we adopt their conventions**.
+
+## Required files
+
+Every v5.0.0+ project that has been touched by `build-state` has these under
+`<engagement-root>/<project>/State/`:
+
+| File | Purpose |
+|---|---|
+| `index.md` | Catalog of v5 State pages, grouped by category. Each entry is a `[[wikilink]]`. **Always regenerated** by `build-state` from the set of pages with `kushi_state_page: true` front-matter. |
+| `log.md` | Chronological refresh log. **Appended** (never rewritten) — one entry per `refresh-project` or `bootstrap-project` run with: ISO timestamp, alias, mode (`bootstrap` / `refresh`), sources pulled, entities-added count, entities-updated count, link-entities edges-added count. |
+| `CLAUDE.md` | Operating doc for AI agents reading the project — "this is a kushi project, use `[[wikilinks]]`, cite `Evidence/<alias>/<source>/weekly/...` for every claim." Written from `plugin/templates/state/CLAUDE.template.md` on first run; **preserved if user-edited** thereafter (mtime check; if hash diverges from template hash, do not overwrite). |
+| `AGENTS.md` | **Copy** of `CLAUDE.md` for hosts that look for `AGENTS.md` (Codex, OpenAI agents SDK). NOT a symlink — Windows file-system compat. Written from `plugin/templates/state/AGENTS.template.md` (which is byte-identical to `CLAUDE.template.md`); preserved if user-edited. |
+
+## v5 State page convention
+
+A v5 State page is any `State/<category>/<slug>.md` with `kushi_state_page: true`
+in its front-matter.
+
+### Page categories (closed set)
+
+| Category | Folder | Typical content |
+|---|---|---|
+| People | `State/people/` | Per-stakeholder page. Role, org, interactions, decisions touched. |
+| Opportunities | `State/opportunities/` | Per-CRM-opportunity page. Stage, $ size, decisions, asks. |
+| ADOWorkItems | `State/adoworkitems/` | Per-ADO work item that spans multiple weeks. State, owner, related meetings. |
+| Decisions | `State/decisions/` | Per-cross-source decision. Date, decider, what changed, citations. |
+| Risks | `State/risks/` | Per-risk page. Owner, status, mitigation, citations. |
+| CustomerAsks | `State/customerasks/` | Per-ask page. Asker, ask text, status, evidence. |
+| Meetings | `State/meetings/` | Per-recurring-meeting-series page. Attendees, cadence, recent decisions. |
+| Artifacts | `State/artifacts/` | Per-document/deck/file page. Source link, key bullets, related decisions. |
+
+Folder names are lowercase, no spaces. `build-state` creates them on demand.
+
+### Required front-matter
+
+```yaml
+---
+kushi_state_page: true
+category: opportunity              # one of: people | opportunity | ado-work-item | decision | risk | customer-ask | meeting | artifact
+entity_ids: ["crm://entity=opportunity/id=<guid>"]
+related: ["[[ushak-smith]]", "[[northwind-weekly-sync]]"]
+last_synthesized_iso: "2026-05-26T20:00:00Z"
+synthesized_by_alias: "ushak"
+---
+```
+
+- `entity_ids` MUST list at least one id that matches a node id in
+  `_graph/project-graph.json`. (Self-check D21.state enforces this.)
+- `related` is a list of `[[slug]]` wikilinks to other State pages.
+- `last_synthesized_iso` is the ISO timestamp of the producing `build-state`
+  run.
+
+### Wikilink rules
+
+- `[[slug]]` resolves to `State/<category>/<slug>.md`. The category folder
+  is inferred from the target page's `category` front-matter.
+- Slugs are **lowercase-kebab-case** derived from the page title (e.g.
+  "Northwind FY26 Renewal" → `northwind-fy26-renewal`). Producers MUST emit slugs
+  deterministically so two runs converge on the same filename.
+- `[[slug|display text]]` is allowed and rendered the way every wiki tool
+  renders it.
+- A wikilink whose target does not exist on disk is a **defect** flagged by
+  self-check D21.state. `build-state` MUST emit pages in dependency order so
+  every emitted wikilink resolves at end-of-run.
+
+## When to emit a v5 State page
+
+`build-state` emits one page per **cross-source entity** in
+`_graph/project-graph.json` — defined as: any node with ≥ 2 incoming/outgoing
+edges OR present in ≥ 2 distinct weeks (per `weekly_refs`).
+
+Nodes that fail both gates are NOT promoted to a State page; they remain
+addressable via the graph and `weekly/` directly.
+
+One file per cross-source entity. If two nodes legitimately share a slug
+(name collision), append a short stable suffix derived from the source +
+last 6 chars of the id (e.g. `ushak-smith-ado-9f3c2a`).
+
+## Backward compatibility
+
+- Pages **without** `kushi_state_page: true` in front-matter are LEFT ALONE.
+  v4.x synthesis files (e.g. `State/00_overview.md`, `State/05_action-items.md`)
+  continue to live in `State/` and are produced by the v4.x synthesis path
+  inside `build-state` (which v5.0.0 retains for `full` profile parity).
+- `State/index.md` regeneration only enumerates v5 pages (those with the
+  flag). Legacy synthesis files are not referenced from `State/index.md`;
+  their existing front-matter / cross-links remain valid.
+- No migration. No deletion. Users may continue to use v4.x State files
+  indefinitely; v5 pages live alongside.
+
+## Self-check
+
+`D21.state` enforces this layout:
+
+- Every `State/<category>/*.md` with `kushi_state_page: true` has all required
+  front-matter fields.
+- Every `entity_ids` value matches a node in `_graph/project-graph.json`.
+- Every `[[wikilink]]` in a v5 page resolves to an existing v5 page on disk.
+- `State/index.md` lists every v5 page that exists.
+
+## Cross-references
+
+- `entity-graph.instructions.md` — source of node identity for `entity_ids`.
+- `guided-tour.instructions.md` — `State/tour.md` is a sibling artifact that
+  uses the same wikilinks.
+- `dashboard-artifact.instructions.md` — dashboard consumes `State/index.md`
+  to render the side panel's "State pages" section.
+- `host-portability.instructions.md` — `CLAUDE.md` / `AGENTS.md` mirroring
+  rationale.

package/plugin/instructions/schema-evolve.instructions.md

@@ -0,0 +1,73 @@
+# Schema evolve
+
+> Doctrine: `schema-evolve.instructions.md` — kushi v5.2.0+
+
+## Purpose
+
+Allows users to teach kushi project-specific conventions that persist across runs. When a user says "from now on always do X for this project," kushi captures the rule and applies it in all future operations.
+
+## Storage location
+
+Rules are stored in `Evidence/<alias>/State/CLAUDE.md` under the project's evidence tree.
+
+**Decision rationale**: `CLAUDE.md` is the Karpathy-pattern file for agent-specific conventions (already present in the State layout since v5.0.0). Placing rules here means:
+- They're versioned alongside evidence (git-tracked engagement roots get history).
+- They're co-located with the State pages that apply them.
+- They're readable by any agent (not kushi-specific format).
+
+## Rule format
+
+Rules are appended to `CLAUDE.md` with structure:
+
+```markdown
+## Rule: <short-title>
+
+- **Added**: 2026-05-29T14:30:00Z
+- **Scope**: project | alias | global
+- **Source**: user (natural language) | schema-evolve skill
+
+<rule text as stated by the user>
+```
+
+## Scope levels
+
+| Scope | Stored at | Applies to |
+|-------|-----------|------------|
+| `project` | `Evidence/<alias>/State/CLAUDE.md` | All operations on this project |
+| `alias` | `Evidence/<alias>/State/CLAUDE.md` | Only this contributor's operations |
+| `global` | `~/.kushi/conventions.md` | All projects (future — v5.3.0) |
+
+v5.2.0 implements `project` scope only. `alias` and `global` are documented for forward compatibility.
+
+## How rules are applied
+
+1. At the start of `build-state`, `ask-project`, and `refresh-project`, the skill reads `Evidence/<alias>/State/CLAUDE.md`.
+2. Rules are parsed into a list and included as context for the operation.
+3. Rules affect preferences (formatting, naming, emphasis) but NEVER override hard doctrine (WorkIQ-only, verbatim-by-default, CSC format).
+
+## Conflict resolution
+
+- Hard doctrine always wins over user rules.
+- Later rules override earlier rules on the same topic.
+- If a rule contradicts doctrine, it's logged as a warning but not applied.
+
+## CLI verb
+
+`kushi remember <rule>` — captures a rule at project scope.
+
+Auto-detection: when the user says "from now on...", "always...", "never...", "for this project..." in `ask-project`, the skill offers to persist it as a convention.
+
+## Examples
+
+```
+> kushi remember "always use 'Northwind' not 'Healthcare Accelerator' in summaries"
+> kushi remember "treat John Smith as the primary EM for this project"
+> kushi remember "CRM entity 'opportunity' maps to our internal term 'deal'"
+```
+
+## References
+
+- `karpathy-state-layout.instructions.md` — CLAUDE.md file in State layout
+- `living-wiki.instructions.md` — rules interact with incremental State maintenance
+- `build-state` skill — reads rules at start of run
+- `ask-project` skill — reads rules + offers to capture new ones