kushi-agents 5.0.4 → 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

package/bin/cli.mjs

@@ -15,6 +15,17 @@ if (args.length > 0 && SKILL_VERBS.has(args[0])) {
   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]
@@ -61,13 +72,17 @@ if (args.includes('--help') || args.includes('-h')) {
                          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>".
 `);
@@ -210,6 +225,53 @@ async function dispatchSkillVerb(verb, rest) {
   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];

package/package.json

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

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) |

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/wiki-lint.instructions.md

@@ -0,0 +1,110 @@
+---
+name: "wiki-lint"
+description: "v5.1.0 — Wiki lint finding classes for State/. Detects contradictions, stale claims, orphan pages, missing cross-refs, and data gaps. Each finding includes a ready-to-paste fix snippet. Adapted from sametbrr/llm-wiki-manager lint patterns. Authored to agentskills.io spec; deltas: kushi-specific finding classes (contradiction-flagged, stale-claim, orphan-page, missing-cross-ref, data-gap), fix-snippet convention."
+applies_to: "lint-state skill"
+since: "kushi v5.1.0"
+---
+
+# wiki-lint — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (sametbrr/llm-wiki-manager): kushi-specific finding classes mapped to State/ layout, Obsidian-callout aware, fix-snippet per finding (not just a diagnostic), integration with `_review-queue.md`.
+
+Adapted from [sametbrr/llm-wiki-manager](https://github.com/sametbrr/llm-wiki-manager) — wiki lint patterns.
+
+## Finding classes
+
+### 1. `contradiction-flagged`
+
+**What:** Count unresolved `> [!warning] Contradicted` callouts in State/ pages.
+
+**Detection:** Regex `^> \[!warning\] Contradicted` in any `State/**/*.md`.
+
+**Severity:** warning (informational — contradictions are expected during active projects).
+
+**Fix snippet:**
+```markdown
+<!-- To resolve: review both values, pick the correct one, then either:
+     (a) Delete the callout pair and keep the winning value, OR
+     (b) Add <!-- kushi:human-override --> above the old value to prevent auto-resolve. -->
+```
+
+### 2. `stale-claim`
+
+**What:** A claim in a State page is ≥ 60 days old (based on its `[source: ... · YYYY-MM-DD]` citation date) with no corroborating refresh since.
+
+**Detection:** Parse inline citations `[source: ... · YYYY-MM-DD]`; flag if the newest citation for an entity property is > 60 days old AND no `build-state` or `refresh` log entry touched that entity since.
+
+**Severity:** warning.
+
+**Fix snippet:**
+```markdown
+<!-- Stale claim (>60 days). Run '@Kushi refresh <project>' to pull fresh evidence,
+     then '@Kushi state <project>' to rebuild. If the claim is still valid, add a
+     corroborating citation from a recent source. -->
+```
+
+### 3. `orphan-page`
+
+**What:** A page in `State/` (with `kushi_state_page: true`) that is NOT linked from `index.md` or any other State page.
+
+**Detection:** Enumerate all `State/**/*.md` with `kushi_state_page: true`. For each, check if its path or `[[wikilink]]` slug appears in `index.md` or any sibling page body.
+
+**Severity:** warning.
+
+**Fix snippet:**
+```markdown
+<!-- Orphan page: not linked from index.md or any other State page.
+     Fix: add a [[category/slug]] link to index.md under the correct category heading,
+     OR delete this page if it was generated in error. -->
+```
+
+### 4. `missing-cross-ref`
+
+**What:** An entity mentioned in a page body (matching a known entity name from `Evidence/_graph/project-graph.json` nodes) but NOT listed in the page's `entity_ids` or `related` frontmatter arrays.
+
+**Detection:** Load entity names from graph nodes. For each State page, scan body for entity-name matches not in frontmatter.
+
+**Severity:** info.
+
+**Fix snippet:**
+```markdown
+<!-- Missing cross-ref: entity "<name>" mentioned in body but not in frontmatter.
+     Fix: add to `related:` array in front-matter:
+     related:
+       - category/entity-slug -->
+```
+
+### 5. `data-gap`
+
+**What:** A required section header is present in a State page but its body (content between that header and the next header or EOF) is empty or contains only whitespace/placeholder text.
+
+**Detection:** For each State page, parse `###` and `##` sections. Flag sections whose body is empty, contains only `<!-- TODO -->`, or is fewer than 2 non-blank lines.
+
+**Severity:** info.
+
+**Fix snippet:**
+```markdown
+<!-- Data gap: section "<heading>" has no content.
+     Fix: run '@Kushi refresh <project>' to pull evidence that populates this section,
+     or remove the section header if it's not applicable to this entity. -->
+```
+
+## Output format
+
+Each finding in the lint report:
+
+```markdown
+### <class>: <entity/page> — <short description>
+
+**File:** `State/<path>`
+**Line:** <N>
+**Fix:**
+<fix snippet>
+```
+
+## References
+
+- [sametbrr/llm-wiki-manager](https://github.com/sametbrr/llm-wiki-manager)
+- `living-wiki.instructions.md` (contradiction lifecycle)
+- `karpathy-state-layout.instructions.md` (page convention)

package/plugin/skills/_shared/Append-StateLog.ps1

@@ -0,0 +1,73 @@
+<#
+.SYNOPSIS
+Appends a canonical entry to State/log.md per log-format.instructions.md.
+
+.DESCRIPTION
+Idempotent helper called by every writer skill after completing a State/ write.
+Prepends (reverse-chronological) a new entry after the file header.
+
+.PARAMETER StateDir
+Path to the State/ directory (e.g., Evidence/<alias>/State/).
+
+.PARAMETER Op
+Operation name from the closed taxonomy: bootstrap, refresh, build-state, lint-state,
+ask-fileback, link-entities, dashboard, tour.
+
+.PARAMETER Title
+Short one-line title for the log entry.
+
+.PARAMETER Summary
+1–3 line summary body.
+
+.PARAMETER Sources
+Comma-separated source pointers.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$StateDir,
+    [Parameter(Mandatory)][ValidateSet('bootstrap','refresh','build-state','lint-state','ask-fileback','link-entities','dashboard','tour')][string]$Op,
+    [Parameter(Mandatory)][string]$Title,
+    [string]$Summary = '',
+    [string]$Sources = ''
+)
+
+$ErrorActionPreference = 'Stop'
+
+$logFile = Join-Path $StateDir 'log.md'
+$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm'
+$entry = "## [$timestamp] $Op | $Title`n"
+if ($Summary) { $entry += "`n$Summary" }
+if ($Sources) { $entry += "`nSources: $Sources" }
+$entry += "`n"
+
+if (-not (Test-Path $logFile)) {
+    # Create with header
+    $header = @"
+---
+kushi_state_log: true
+---
+
+# State Log
+
+$entry
+"@
+    New-Item -Path $logFile -ItemType File -Force | Out-Null
+    Set-Content -Path $logFile -Value $header -Encoding utf8NoBOM
+} else {
+    $content = Get-Content -Raw $logFile
+    # Insert after the header block (after "# State Log" line or after front-matter)
+    if ($content -match '(?ms)(^---\r?\n.*?\r?\n---\r?\n\r?\n# [^\r\n]+\r?\n)(.*)$') {
+        $headerPart = $Matches[1]
+        $bodyPart = $Matches[2]
+        $newContent = $headerPart + "`n" + $entry + "`n" + $bodyPart
+    } elseif ($content -match '(?ms)(^# [^\r\n]+\r?\n)(.*)$') {
+        $headerPart = $Matches[1]
+        $bodyPart = $Matches[2]
+        $newContent = $headerPart + "`n" + $entry + "`n" + $bodyPart
+    } else {
+        $newContent = $entry + "`n" + $content
+    }
+    Set-Content -Path $logFile -Value $newContent -Encoding utf8NoBOM
+}
+
+Write-Verbose "Appended log entry: [$timestamp] $Op | $Title"

package/plugin/skills/_shared/Update-StateIndex.ps1

@@ -0,0 +1,47 @@
+<#
+.SYNOPSIS
+Updates the "Last touched" pointer at the top of State/index.md per log-format.instructions.md.
+
+.DESCRIPTION
+Idempotent helper. Updates or inserts the "Last touched" line immediately after
+the front-matter block in index.md.
+
+.PARAMETER StateDir
+Path to the State/ directory.
+
+.PARAMETER Op
+Operation name (same taxonomy as Append-StateLog).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$StateDir,
+    [Parameter(Mandatory)][string]$Op
+)
+
+$ErrorActionPreference = 'Stop'
+
+$indexFile = Join-Path $StateDir 'index.md'
+$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm'
+$pointer = "> Last touched: $timestamp by $Op ([log](log.md))"
+
+if (-not (Test-Path $indexFile)) {
+    Write-Warning "index.md not found at $indexFile — skipping Update-StateIndex."
+    return
+}
+
+$content = Get-Content -Raw $indexFile
+$pointerPattern = '(?m)^> Last touched:.*$'
+
+if ($content -match $pointerPattern) {
+    $content = $content -replace $pointerPattern, $pointer
+} else {
+    # Insert after front-matter closing ---
+    if ($content -match '(?ms)(^---\r?\n.*?\r?\n---\r?\n)(.*)$') {
+        $content = $Matches[1] + "`n" + $pointer + "`n" + $Matches[2]
+    } else {
+        $content = $pointer + "`n`n" + $content
+    }
+}
+
+Set-Content -Path $indexFile -Value $content -Encoding utf8NoBOM
+Write-Verbose "Updated index.md: Last touched $timestamp by $Op"

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

@@ -42,6 +42,36 @@ The user does NOT need to type `/ask-project` or `@Kushi ask`. If the message:
 - **Freshness gate, not freshness auto-fix.** If the freshest source relevant to the question is older than `chat.freshness_warn_days` (default 14), warn the user and offer `@Kushi refresh <project>` — but NEVER auto-refresh.
 - **Reference packs may be consulted for domain doctrine.** When the question maps to a known reference-pack domain (currently only `fde/` — FDE stages, fitness, CRM status meanings, intake gates, risk categories, "MACC", "is this FDE-fit"), ALSO load the matching reference pack as additional grounding using the 3-layer override order (project → user → packaged). Cite reference-pack assertions with `[source: reference-packs/<pack>/<file>.md · <layer>]` where layer is `packaged` / `user-override` / `project-override`. Reference-pack content NEVER overrides project Evidence/ for facts about *this* project; it only provides definitions, gates, and rubrics.
 
+## --file-back option (v5.1.0+)
+
+When the user passes `--file-back` (or says "file this answer back", "save this answer"):
+
+1. After answering normally, write the Q+A to `Evidence/<alias>/State/answers/YYYY-MM-DD_<slug>.md`:
+   ```markdown
+   ---
+   question: "<the user's original question>"
+   asked_at: <ISO-8601 timestamp>
+   sources: [<list of cited source paths>]
+   ---
+
+   ## Answer
+
+   <the answer text, with citations preserved>
+
+   ## Sources
+
+   - <source 1>
+   - <source 2>
+   ```
+2. The `<slug>` is derived from the question: lowercase, alphanumeric + hyphens, ≤ 60 chars.
+3. Append `ask-fileback` entry to `State/log.md` via `Append-StateLog.ps1`:
+   - Title: `Filed answer: <slug>`
+   - Summary: one-line description of the question.
+4. Update `State/index.md` via `Update-StateIndex.ps1 -Op ask-fileback`.
+5. If `State/answers/` does not exist, create it.
+
+The `--file-back` flag is OPTIONAL. Without it, ask-project behaves exactly as before (read-only, no writes).
+
 ## Inputs
 
 - `<project>` — fuzzy-matched project name. If multiple plausible matches, ask the user.

package/plugin/skills/build-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "build-state"
-version: "4.0.0"
+version: "5.0.0"
 description: "USE WHEN the user says \"regenerate State for <X>\", \"rebuild State\", or \"@Kushi state <X>\" AND the project already has Evidence/ populated. DO NOT USE to pull new evidence (use refresh-project or pull-*). Capability: pure re-render — reads Evidence/_index/entities.yml + weekly CSC + legacy fallback, writes <project>/State/ in BOTH legacy 00–09 synthesis (full profile) AND Karpathy layout (index.md + log.md + per-entity pages + CLAUDE.md/AGENTS.md). Plan-validate-execute writer."
 ---
 
@@ -56,7 +56,23 @@ runs — transient working artifact, not authoritative truth.
 
 ## Steps
 
-
+
+## v5.1.0 — Incremental mode (HARD RULE; per `living-wiki.instructions.md`)
+
+Build-state is now incremental by default:
+
+1. **Read existing State/ pages.** Before regenerating, load every existing `State/**/*.md`.
+2. **Preserve human edits.** Content OUTSIDE `<!-- kushi:auto:start -->` / `<!-- kushi:auto:end -->` fences is NEVER modified.
+3. **Re-derive fenced regions only.** For each `<!-- kushi:auto:start section="<id>" -->` block, re-derive content from current evidence and replace the block contents.
+4. **Contradiction detection.** When a re-derived fact contradicts an existing fact (different value for same entity property):
+   - Wrap both in `> [!warning] Contradicted` / `> [!info] New value` callouts per `living-wiki.instructions.md`.
+   - Add entity to `_review-queue.md`.
+5. **Auto-resolve.** Apply the auto-resolve threshold from `living-wiki.instructions.md` (≥3 sources + ≥30 days old + no human override).
+6. **Log + index.** Append `build-state` entry to `State/log.md` via `Append-StateLog.ps1`. Update `State/index.md` via `Update-StateIndex.ps1`.
+
+When creating NEW pages (entity not previously in State/), wrap all auto-derived content in `<!-- kushi:auto -->` fences.
+
+
 ## Step checklist
 
 Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.

package/plugin/skills/lint-state/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: "lint-state"
+version: "1.0.0"
+description: "USE WHEN the user says 'lint state', 'check state health', 'wiki lint', 'kushi lint <project>', or 'find stale/orphan/contradictions in State'. DO NOT USE for evidence-level validation (use self-check) or for rebuilding State (use build-state). Capability: runs wiki-lint finding classes against Evidence/<alias>/State/, writes dated lint report, updates log.md + index.md."
+---
+
+# Skill: lint-state
+
+Run wiki-lint checks against a project's `State/` directory per `wiki-lint.instructions.md`. Reports contradictions, stale claims, orphan pages, missing cross-refs, and data gaps — each with a ready-to-paste fix snippet.
+
+## Triggers
+
+- "lint state for `<project>`"
+- "check state health"
+- "wiki lint `<project>`"
+- `kushi lint <project>` (CLI verb)
+- "find contradictions in State"
+- "any stale claims in `<project>`?"
+
+## Inputs
+
+- `<project>` — engagement name (fuzzy-matched per `engagement-root-resolution.instructions.md`).
+
+## Step checklist
+
+- [ ] Step 1 — Resolve project root + State/ path
+- [ ] Step 2 — Run finding-class checks
+- [ ] Step 3 — Generate lint report
+- [ ] Step 4 — Update log.md + index.md
+- [ ] Step 5 — Print summary
+
+### Step 1 — Resolve project root
+
+Resolve `<engagement-root>/<project>/Evidence/<alias>/State/` using standard engagement-root resolution. Verify `State/` exists; if not, advise running `build-state` first.
+
+### Step 2 — Run finding-class checks
+
+Per `wiki-lint.instructions.md`, execute each finding class:
+
+1. **contradiction-flagged**: scan `State/**/*.md` for `> [!warning] Contradicted` callouts.
+2. **stale-claim**: parse citations, flag entities with newest citation > 60 days old.
+3. **orphan-page**: find pages with `kushi_state_page: true` not linked from index.md or siblings.
+4. **missing-cross-ref**: cross-reference entity mentions against frontmatter `entity_ids`/`related`.
+5. **data-gap**: find section headers with empty/placeholder bodies.
+
+### Step 3 — Generate lint report
+
+Write `Evidence/<alias>/State/reports/lint-YYYY-MM-DD.md`:
+
+```markdown
+---
+generated_at: "YYYY-MM-DDTHH:MM:SSZ"
+generated_by: "lint-state v1.0.0"
+findings_count: N
+---
+
+# Lint Report — YYYY-MM-DD
+
+## Summary
+
+| Class | Count | Severity |
+|---|---|---|
+| contradiction-flagged | N | warning |
+| stale-claim | N | warning |
+| orphan-page | N | warning |
+| missing-cross-ref | N | info |
+| data-gap | N | info |
+
+**Total findings: N**
+
+## Findings
+
+### contradiction-flagged: <entity> — <description>
+...per wiki-lint.instructions.md format...
+```
+
+### Step 4 — Update log.md + index.md
+
+Call shared helpers:
+- `Append-StateLog.ps1 -Op lint-state -Title "Lint pass (<N> findings)"`
+- `Update-StateIndex.ps1 -Op lint-state`
+
+### Step 5 — Print summary
+
+One-line console output: `lint-state: <N> findings (<breakdown by class>). Report: State/reports/lint-YYYY-MM-DD.md`
+
+## Validation loop
+
+After writing outputs:
+1. Verify `State/reports/lint-YYYY-MM-DD.md` exists and has valid frontmatter.
+2. Verify `State/log.md` has the new entry at top.
+3. Verify `State/index.md` "Last touched" pointer is updated.
+
+## References
+
+- `../../instructions/wiki-lint.instructions.md`
+- `../../instructions/log-format.instructions.md`
+- `../../instructions/living-wiki.instructions.md`

package/plugin/skills/lint-state/evals/evals.json

@@ -0,0 +1,34 @@
+{
+  "skill": "lint-state",
+  "version": "1.0.0",
+  "description": "Wiki-lint checks against State/ — contradictions, stale claims, orphans, cross-refs, data gaps.",
+  "cases": [
+    {
+      "id": "lint-state-clean",
+      "name": "Lint a clean State/ with no findings",
+      "input": "Run lint against a well-maintained State/ directory with no contradictions, stale claims, or orphans.",
+      "expected_assertions": [
+        { "type": "regex-match", "target": "stdout", "pattern": "lint-state: 0 findings" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "lint-state-contradiction",
+      "name": "Lint detects contradiction callouts",
+      "input": "Run lint against a State/ directory with one unresolved > [!warning] Contradicted callout.",
+      "expected_assertions": [
+        { "type": "regex-match", "target": "stdout", "pattern": "contradiction-flagged=1" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "lint-state-orphan",
+      "name": "Lint detects orphan pages",
+      "input": "Run lint against a State/ directory with a page that has kushi_state_page: true but is not linked from index.md.",
+      "expected_assertions": [
+        { "type": "regex-match", "target": "stdout", "pattern": "orphan-page=1" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

package/plugin/skills/lint-state/lint.ps1

@@ -0,0 +1,218 @@
+<#
+.SYNOPSIS
+lint-state — runs wiki-lint checks against a project's State/ directory.
+
+.DESCRIPTION
+Implements the finding classes defined in wiki-lint.instructions.md:
+  - contradiction-flagged
+  - stale-claim
+  - orphan-page
+  - missing-cross-ref
+  - data-gap
+
+Writes a dated lint report to State/reports/, appends to State/log.md, updates
+State/index.md "Last touched" pointer.
+
+.PARAMETER StateDir
+Path to the State/ directory to lint.
+
+.PARAMETER GraphFile
+Optional path to project-graph.json for missing-cross-ref checks.
+
+.PARAMETER Quiet
+Suppress console output (for programmatic use).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$StateDir,
+    [string]$GraphFile,
+    [switch]$Quiet
+)
+
+$ErrorActionPreference = 'Stop'
+$findings = @()
+
+# --- Helpers ---
+function Add-LintFinding {
+    param([string]$Class, [string]$Severity, [string]$Entity, [string]$Description, [string]$File, [int]$Line, [string]$Fix)
+    $script:findings += [PSCustomObject]@{
+        class       = $Class
+        severity    = $Severity
+        entity      = $Entity
+        description = $Description
+        file        = $File
+        line        = $Line
+        fix         = $Fix
+    }
+}
+
+# --- Check 1: contradiction-flagged ---
+$stateFiles = Get-ChildItem -Path $StateDir -Recurse -Filter '*.md' -ErrorAction SilentlyContinue
+foreach ($f in $stateFiles) {
+    $lines = Get-Content -Path $f.FullName -ErrorAction SilentlyContinue
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match '^\s*>\s*\[!warning\]\s*Contradicted') {
+            $entity = $f.BaseName -replace '-', ' '
+            Add-LintFinding 'contradiction-flagged' 'warning' $entity "Unresolved contradiction callout" $f.FullName ($i + 1) "Review both values, pick the correct one. Delete callout pair and keep winner, or add <!-- kushi:human-override --> to prevent auto-resolve."
+        }
+    }
+}
+
+# --- Check 2: stale-claim ---
+$staleDays = 60
+$now = Get-Date
+foreach ($f in $stateFiles) {
+    $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+    if (-not $content) { continue }
+    $citations = [regex]::Matches($content, '\[source:[^\]]*\xB7\s*(\d{4}-\d{2}-\d{2})\]')
+    if ($citations.Count -eq 0) { continue }
+    $newestDate = $null
+    foreach ($m in $citations) {
+        try {
+            $d = [datetime]::ParseExact($m.Groups[1].Value, 'yyyy-MM-dd', $null)
+            if (-not $newestDate -or $d -gt $newestDate) { $newestDate = $d }
+        } catch {}
+    }
+    if ($newestDate -and ($now - $newestDate).TotalDays -gt $staleDays) {
+        $entity = $f.BaseName -replace '-', ' '
+        Add-LintFinding 'stale-claim' 'warning' $entity "Newest citation is $([math]::Round(($now - $newestDate).TotalDays)) days old (threshold: $staleDays)" $f.FullName 0 "Run '@Kushi refresh <project>' then '@Kushi state <project>' to pull fresh evidence. If claim is still valid, add a corroborating citation from a recent source."
+    }
+}
+
+# --- Check 3: orphan-page ---
+$indexFile = Join-Path $StateDir 'index.md'
+$indexContent = ''
+if (Test-Path $indexFile) { $indexContent = Get-Content -Raw $indexFile }
+$allPageContent = ''
+foreach ($f in $stateFiles) {
+    if ($f.FullName -ne (Resolve-Path $indexFile -ErrorAction SilentlyContinue)) {
+        $allPageContent += (Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue) + "`n"
+    }
+}
+foreach ($f in $stateFiles) {
+    $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+    if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+    $slug = $f.BaseName
+    $relPath = $f.FullName.Replace($StateDir, '').TrimStart('\', '/') -replace '\\', '/'
+    if ($indexContent -notmatch [regex]::Escape($slug) -and $allPageContent -notmatch [regex]::Escape($slug)) {
+        Add-LintFinding 'orphan-page' 'warning' $slug "Page not linked from index.md or any sibling" $f.FullName 0 "Add [[$(Split-Path $relPath -Parent)/$slug]] to index.md under the correct category heading, or delete this page if generated in error."
+    }
+}
+
+# --- Check 4: missing-cross-ref ---
+if ($GraphFile -and (Test-Path $GraphFile)) {
+    try {
+        $graph = Get-Content -Raw $GraphFile | ConvertFrom-Json
+        $entityNames = @()
+        if ($graph.nodes) { $entityNames = $graph.nodes | ForEach-Object { $_.name } | Where-Object { $_ } }
+        foreach ($f in $stateFiles) {
+            $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+            if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+            foreach ($name in $entityNames) {
+                if ($name.Length -lt 3) { continue }
+                if ($content -match [regex]::Escape($name) -and $content -notmatch "entity_ids:.*$([regex]::Escape($name))" -and $content -notmatch "related:.*$([regex]::Escape($name))") {
+                    # Check frontmatter more carefully
+                    if ($content -match '(?ms)^---\r?\n(.*?)\r?\n---') {
+                        $fm = $Matches[1]
+                        if ($fm -notmatch [regex]::Escape($name)) {
+                            Add-LintFinding 'missing-cross-ref' 'info' ($f.BaseName -replace '-',' ') "Entity '$name' mentioned in body but not in frontmatter" $f.FullName 0 "Add to related: array in front-matter."
+                        }
+                    }
+                }
+            }
+        }
+    } catch {
+        Write-Warning "Could not parse graph file: $_"
+    }
+}
+
+# --- Check 5: data-gap ---
+foreach ($f in $stateFiles) {
+    $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+    if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+    $lines = Get-Content -Path $f.FullName
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match '^#{2,3}\s+(.+)$') {
+            $heading = $Matches[1]
+            # Look at content until next heading or EOF
+            $bodyLines = @()
+            for ($j = $i + 1; $j -lt $lines.Count; $j++) {
+                if ($lines[$j] -match '^#{2,3}\s+') { break }
+                if ($lines[$j].Trim() -and $lines[$j].Trim() -ne '<!-- TODO -->' -and $lines[$j].Trim() -ne '<!-- TODO(retrofit) -->') {
+                    $bodyLines += $lines[$j]
+                }
+            }
+            if ($bodyLines.Count -lt 2 -and $heading -notmatch '^(State Log|State Index|Review Queue)') {
+                Add-LintFinding 'data-gap' 'info' ($f.BaseName -replace '-',' ') "Section '$heading' has no meaningful content" $f.FullName ($i + 1) "Run '@Kushi refresh <project>' to pull evidence for this section, or remove the header if not applicable."
+            }
+        }
+    }
+}
+
+# --- Generate report ---
+$reportsDir = Join-Path $StateDir 'reports'
+if (-not (Test-Path $reportsDir)) { New-Item -Path $reportsDir -ItemType Directory -Force | Out-Null }
+
+$dateStr = Get-Date -Format 'yyyy-MM-dd'
+$reportFile = Join-Path $reportsDir "lint-$dateStr.md"
+$timestamp = Get-Date -Format 'yyyy-MM-ddTHH:mm:ssZ'
+
+$classCounts = @{}
+foreach ($f2 in $findings) {
+    if (-not $classCounts.ContainsKey($f2.class)) { $classCounts[$f2.class] = 0 }
+    $classCounts[$f2.class]++
+}
+
+$report = @"
+---
+generated_at: "$timestamp"
+generated_by: "lint-state v1.0.0"
+findings_count: $($findings.Count)
+---
+
+# Lint Report — $dateStr
+
+## Summary
+
+| Class | Count | Severity |
+|---|---|---|
+"@
+
+$classOrder = @('contradiction-flagged','stale-claim','orphan-page','missing-cross-ref','data-gap')
+foreach ($cls in $classOrder) {
+    $count = if ($classCounts.ContainsKey($cls)) { $classCounts[$cls] } else { 0 }
+    $sev = if ($cls -match 'contradiction|stale|orphan') { 'warning' } else { 'info' }
+    $report += "| $cls | $count | $sev |`n"
+}
+
+$report += "`n**Total findings: $($findings.Count)**`n`n## Findings`n"
+
+foreach ($f2 in $findings) {
+    $report += "`n### $($f2.class): $($f2.entity) — $($f2.description)`n`n"
+    $report += "**File:** ``$($f2.file)```n"
+    if ($f2.line -gt 0) { $report += "**Line:** $($f2.line)`n" }
+    $report += "**Fix:** $($f2.fix)`n"
+}
+
+Set-Content -Path $reportFile -Value $report -Encoding utf8NoBOM
+
+# --- Update log + index ---
+$sharedDir = Join-Path $PSScriptRoot '..\_shared'
+$appendLog = Join-Path $sharedDir 'Append-StateLog.ps1'
+$updateIndex = Join-Path $sharedDir 'Update-StateIndex.ps1'
+
+if (Test-Path $appendLog) {
+    & $appendLog -StateDir $StateDir -Op 'lint-state' -Title "Lint pass ($($findings.Count) findings)" -Summary "Classes: $(($classCounts.Keys | Sort-Object | ForEach-Object { "$_=$($classCounts[$_])" }) -join ', ')" -Sources "State/**/*.md"
+}
+if (Test-Path $updateIndex) {
+    & $updateIndex -StateDir $StateDir -Op 'lint-state'
+}
+
+# --- Console output ---
+if (-not $Quiet) {
+    $breakdown = ($classCounts.Keys | Sort-Object | ForEach-Object { "$_=$($classCounts[$_])" }) -join ', '
+    Write-Host "lint-state: $($findings.Count) findings ($breakdown). Report: $reportFile"
+}
+
+# Return findings as output for programmatic use
+$findings

package/plugin/skills/self-check/SKILL.md

@@ -71,6 +71,8 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D32.multi-host | Multi-host install integrity | validates `src/multi-host.mjs` exports + `bin/cli.mjs` flag handling, then performs a temp-dir dry-run install for BOTH supported hosts (Clawpilot + VS Code Chat) under a fake `$HOME` in `$env:TEMP`. Asserts SKILL.md + agent file + skills/ + prompts/ + skills-metadata.json with a kushi entry are present, then asserts a clean uninstall. NEVER touches the real `~/.copilot/` or `~/.vscode/`. See `multi-host-install.instructions.md`. |
 | D33.evals | Skill evals framework integrity | every `plugin/skills/<name>/` (except `eval`) ships `evals/evals.json` with ≥ 2 cases and ≥ 1 assertion per case; the runner (`plugin/skills/eval/run-evals.ps1`) and schema (`plugin/skills/eval/evals.schema.json`) are present; `evals/baseline.json` exists (warn-only). Six sub-checks: `D33.evals-exist`, `D33.evals-schema`, `D33.evals-min-cases`, `D33.evals-have-assertions`, `D33.eval-runner-exists`, `D33.baseline-exists`. See `skill-evals.instructions.md`. |
 | D34.creator-conformance | skill-creator + skill-checker harness integrity (v5.0.4+) | validates `scaffold.ps1` + `check-skill.ps1` ship and are parseable; every skill carrying the `.created-by-skill-creator` marker passes `check-skill --lint` clean; `check-skill --all --retrofit --dry-run` shows no non-additive gaps; the dogfood report at `docs/audits/v5.0.4-skill-creator-dogfood.md` is fresh (≤14 days). Five sub-checks: `D34.skill-creator-exists`, `D34.skill-checker-exists`, `D34.creator-output-conforms`, `D34.retrofit-clean`, `D34.dogfood-report-fresh`. See `skill-authoring.instructions.md`. |
+| D35.log | State log (v5.1.0+) | `State/log.md` exists, `## [` headings match canonical format, timestamps reverse-chronological. Sub-checks: `D35.log-exists`, `D35.log-format`, `D35.log-monotonic`. |
+| D36.contradictions | Contradictions (v5.1.0+) | `> [!warning] Contradicted` callouts well-formed, `_review-queue.md` fresh, `<!-- kushi:auto -->` fences balanced. Sub-checks: `D36.callout-syntax`, `D36.review-queue-fresh`, `D36.no-silent-overwrite`. |
 | **CSC weekly-layout checks (kushi v4.9.0)** | | gated on `Resolve-EngagementRoots` — no-ops on the kushi repo itself. |
 | D11.csc | CSC entity coverage + depth | every `Evidence/<alias>/<source>/weekly/*-csc.md` has ≥ 1 entity heading; per-source minimum bullet count + populated-section count (meetings 25/6, email 8/4, teams 6/3, onenote 10/4, sharepoint 8/3, crm 12/5, ado 8/4). Coverage-Notes-only blocks (low-signal escape) are exempt. |
 | D12.csc | CSC section order | every entity block's `###` section headings appear in the canonical order: Participants → Topics → Q&A → Who Said What → Decisions → Dates & Numbers → Action Items → Next Steps → Open Questions → Risks → Customer Asks → Artifacts → Coverage Notes. |
@@ -83,7 +85,7 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D19.csc | CSC legacy write guard | WARN if `snapshot/` or `stream/` contains a file modified after the v4.9.0 release date (2026-05-26). Reads of legacy layouts remain supported. |
 | **v5.0.0 cross-source / state / dashboard / tour checks** | | gated on `Resolve-EngagementRoots` — no-ops on the kushi repo itself. |
 | D20.graph | Entity-graph well-formed | `Evidence/_graph/project-graph.json`: valid JSON, has `schema/project/generated_at/nodes/edges`, every edge `kind` is in the closed taxonomy (`references`/`decides`/`action-item-tracks`/`discusses`/`produced-by`/`follow-up-of`/`same-thread`/`participant-of`), every edge endpoint resolves to a node. See `entity-graph.instructions.md`. |
-| D21.state | Karpathy State layout | when any `State/**/*.md` has front-matter `kushi_state_page: true`, the sibling `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md` MUST exist, `CLAUDE.md` and `AGENTS.md` MUST be byte-identical, and every v5 page MUST live under one of the closed-set category folders (`people/`, `opportunities/`, `adoworkitems/`, `decisions/`, `risks/`, `customerasks/`, `meetings/`, `artifacts/`). See `karpathy-state-layout.instructions.md`. |
+| D21.state | Karpathy State layout | `kushi_state_page: true` pages require sibling `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md`; pages live under closed-set category folders. See `karpathy-state-layout.instructions.md`. |
 | D22.dashboard | Dashboard produced + substituted | when `project-graph.json` exists, `<project>/dashboard.html` MUST exist, MUST NOT still contain the literal `__GRAPH_JSON__` placeholder (would indicate embedder failure), and MUST reference Cytoscape. See `dashboard-artifact.instructions.md`. |
 | D23.tour | Tour citations resolve | every `- **Cite:** [`<path>`]` row in `<project>/State/tour.md` MUST resolve to a real file under `<project>/Evidence/`. See `guided-tour.instructions.md`. |
 

package/plugin/skills/self-check/run.ps1

@@ -120,7 +120,7 @@ if (-not (Test-Path $pluginDir)) {
     exit 2
 }
 
-$skillDirs = Get-ChildItem $skillsDir -Directory | Sort-Object Name
+$skillDirs = Get-ChildItem $skillsDir -Directory | Where-Object { $_.Name -notmatch '^\.' -and $_.Name -notmatch '^_' } | Sort-Object Name
 $skillNames = $skillDirs.Name
 $instructionFiles = Get-ChildItem $instructionsDir -Filter '*.instructions.md' -EA SilentlyContinue
 $promptFiles = Get-ChildItem $promptsDir -Filter '*.prompt.md' -EA SilentlyContinue
@@ -264,7 +264,7 @@ if (Test-Path $pluginJsonFile) {
                 $chain += $name
                 return $chain
             }
-            $skillNames = (Get-ChildItem $skillsDir -Directory).Name
+            $skillNames = (Get-ChildItem $skillsDir -Directory | Where-Object { $_.Name -notmatch '^\.' -and $_.Name -notmatch '^_' }).Name
             $promptStems = (Get-ChildItem (Join-Path $pluginDir 'prompts') -File -Filter '*.prompt.md' -ErrorAction SilentlyContinue) `
                 | ForEach-Object { $_.Name -replace '\.prompt\.md$','' }
             $instructionStems = (Get-ChildItem (Join-Path $pluginDir 'instructions') -File -Filter '*.instructions.md' -ErrorAction SilentlyContinue) `
@@ -1663,7 +1663,7 @@ process.stdout.write(JSON.stringify(out));
     }
 
     $skillsRoot = Join-Path $Root 'plugin/skills'
-    $skillDirs = Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $_.Name -notin @('eval', 'self-check') }
+    $skillDirs = Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $_.Name -notin @('eval', 'self-check') -and $_.Name -notmatch '^_' }
     foreach ($sd in $skillDirs) {
         $evalsFile = Join-Path $sd.FullName 'evals/evals.json'
         if (-not (Test-Path $evalsFile)) {
@@ -1778,6 +1778,136 @@ process.stdout.write(JSON.stringify(out));
     }
 }
 
+    # === D35.log — State/log.md format and presence (v5.1.0+) ===
+    # Validates that writer-touched State dirs have log.md and that entries match canonical format.
+    # Operates on .testtmp/ fixtures or real engagement roots.
+    $logFixtureDir = Join-Path $Root '.testtmp'
+    $logTestDirs = @()
+    if (Test-Path $logFixtureDir) {
+        $logTestDirs += Get-ChildItem -Path $logFixtureDir -Recurse -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -eq 'State' -and (Test-Path (Join-Path $_.FullName 'log.md')) }
+    }
+    # Also check real engagement roots if available
+    foreach ($engRoot in (Resolve-EngagementRoots -RepoRoot $Root)) {
+        Get-ChildItem -Path $engRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+            $stateDir = Join-Path $_.FullName 'State'
+            if (Test-Path $stateDir) { $logTestDirs += Get-Item $stateDir }
+        }
+    }
+
+    foreach ($sd in $logTestDirs) {
+        $logMd = Join-Path $sd.FullName 'log.md'
+
+        # D35.log-exists
+        if (-not (Test-Path $logMd)) {
+            Add-Finding 'D35.log-exists' 'State log' 'warning' "State directory '$($sd.FullName)' has no log.md" "Add log.md per log-format.instructions.md. Run build-state to auto-create it." $sd.FullName 0
+            continue
+        }
+
+        # D35.log-format — every ## [ heading matches canonical format
+        $logLines = Get-Content -Path $logMd -ErrorAction SilentlyContinue
+        $prevTs = $null
+        $formatOk = $true
+        $monotonicOk = $true
+        foreach ($line in $logLines) {
+            if ($line -match '^\#\#\s+\[') {
+                if ($line -notmatch '^\#\#\s+\[\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}\]\s+\S+\s+\|\s+.+$') {
+                    Add-Finding 'D35.log-format' 'State log' 'warning' "log.md heading does not match canonical format: $line" "Heading must be: ## [YYYY-MM-DD HH:MM] <op> | <title>. See log-format.instructions.md." $logMd 0
+                    $formatOk = $false
+                    break
+                }
+                # D35.log-monotonic — timestamps non-decreasing (newest first = decreasing)
+                if ($line -match '^\#\#\s+\[(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2})\]') {
+                    try {
+                        $ts = [datetime]::ParseExact($Matches[1], 'yyyy-MM-dd HH:mm', $null)
+                        if ($prevTs -and $ts -gt $prevTs) {
+                            Add-Finding 'D35.log-monotonic' 'State log' 'warning' "log.md timestamps not reverse-chronological: $($Matches[1]) appears after an earlier timestamp" "Entries should be prepended (newest first). Re-order or re-run build-state." $logMd 0
+                            $monotonicOk = $false
+                            break
+                        }
+                        $prevTs = $ts
+                    } catch {}
+                }
+            }
+        }
+    }
+
+    # === D36.contradictions — contradiction handling integrity (v5.1.0+) ===
+    # Validates callout syntax, review-queue freshness, and build-state non-fenced preservation.
+    $contradictionDirs = @()
+    if (Test-Path $logFixtureDir) {
+        $contradictionDirs += Get-ChildItem -Path $logFixtureDir -Recurse -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -eq 'State' }
+    }
+    foreach ($engRoot in (Resolve-EngagementRoots -RepoRoot $Root)) {
+        Get-ChildItem -Path $engRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+            $stateDir = Join-Path $_.FullName 'State'
+            if (Test-Path $stateDir) { $contradictionDirs += Get-Item $stateDir }
+        }
+    }
+
+    foreach ($sd in $contradictionDirs) {
+        $mdFiles = Get-ChildItem -Path $sd.FullName -Recurse -Filter '*.md' -ErrorAction SilentlyContinue
+
+        # D36.callout-syntax — every > [!warning] Contradicted callout has required structure
+        foreach ($mf in $mdFiles) {
+            $content = Get-Content -Raw $mf.FullName -ErrorAction SilentlyContinue
+            if (-not $content) { continue }
+            if ($content -match '>\s*\[!warning\]\s*Contradicted') {
+                # Must have 'by' clause and a following > [!info] block
+                if ($content -notmatch '>\s*\[!warning\]\s*Contradicted\s+by\s+') {
+                    Add-Finding 'D36.callout-syntax' 'Contradictions' 'warning' "Callout in $($mf.Name) missing 'by <source>' clause" "Format: > [!warning] Contradicted by <skill> run <date>. See living-wiki.instructions.md." $mf.FullName 0
+                }
+            }
+        }
+
+        # D36.review-queue-fresh — if _review-queue.md has open items, most recent log entry is within 30 days
+        $reviewQueue = Join-Path $sd.FullName '_review-queue.md'
+        if (Test-Path $reviewQueue) {
+            $rqContent = Get-Content -Raw $reviewQueue -ErrorAction SilentlyContinue
+            # Check if review-queue has data rows (not just header + separator)
+            $rqLines = ($rqContent -split '\r?\n') | Where-Object { $_ -match '^\|' -and $_ -notmatch '^\|\s*-' -and $_ -notmatch '^\|\s*Entity' }
+            if ($rqLines.Count -gt 0) {
+                # Has table rows (open items)
+                $logMd2 = Join-Path $sd.FullName 'log.md'
+                if (Test-Path $logMd2) {
+                    $logContent2 = Get-Content -Raw $logMd2
+                    $recentEntry = $false
+                    if ($logContent2 -match '(?m)^\#\#\s+\[(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2})\]') {
+                        try {
+                            $lastTs = [datetime]::ParseExact($Matches[1], 'yyyy-MM-dd HH:mm', $null)
+                            if (((Get-Date) - $lastTs).TotalDays -le 30) { $recentEntry = $true }
+                        } catch {}
+                    }
+                    if (-not $recentEntry) {
+                        Add-Finding 'D36.review-queue-fresh' 'Contradictions' 'warning' "_review-queue.md has open items but most recent log entry is >30 days old" "Run 'lint-state' or 'build-state' to refresh. Open contradictions need periodic review." $reviewQueue 0
+                    }
+                }
+            }
+        }
+
+        # D36.no-silent-overwrite — build-state preserves non-fenced regions
+        # This check validates the invariant by looking for the fencing pattern.
+        # If State pages exist with kushi:auto fences AND content outside fences,
+        # verify the file has not been fully regenerated (check mtime consistency).
+        # For the fixture-based test: run build-state twice, assert non-fenced bytes unchanged.
+        # In self-check, we do a structural check: if a page has content outside fences,
+        # verify it also has content INSIDE fences (indicating incremental mode is active).
+        foreach ($mf in $mdFiles) {
+            $content = Get-Content -Raw $mf.FullName -ErrorAction SilentlyContinue
+            if (-not $content) { continue }
+            if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+            if ($content -match '<!-- kushi:auto:start') {
+                # Good — page uses fencing. Verify fence pairs are balanced.
+                $starts = ([regex]::Matches($content, '<!-- kushi:auto:start')).Count
+                $ends = ([regex]::Matches($content, '<!-- kushi:auto:end')).Count
+                if ($starts -ne $ends) {
+                    Add-Finding 'D36.no-silent-overwrite' 'Contradictions' 'warning' "$($mf.Name) has mismatched kushi:auto fence pairs ($starts starts, $ends ends)" "Every <!-- kushi:auto:start --> must have a matching <!-- kushi:auto:end -->. Fix the fencing." $mf.FullName 0
+                }
+            }
+        }
+    }
+
 # === Output ===
 if ($Targeted) {
     # Filter findings to those whose code, surface, file path, or message contain the substring.

package/plugin/skills/skill-checker/check-skill.ps1

@@ -88,7 +88,7 @@ function Get-TargetSkills {
         return @(Get-Item -LiteralPath $d)
     }
     if ($All) {
-        return Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $excludeFromAll -notcontains $_.Name }
+        return Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $excludeFromAll -notcontains $_.Name -and $_.Name -notmatch '^_' }
     }
     throw "Specify -Skill <name> or -All."
 }

package/plugin/templates/state/answers.README.md

@@ -0,0 +1,7 @@
+# State/answers/
+
+This folder contains filed-back Q&A answers from `ask-project --file-back`.
+
+Each file is named `YYYY-MM-DD_<slug>.md` and contains the question, answer, and source citations.
+
+These are durable knowledge artifacts — they persist across refreshes and serve as a queryable FAQ for the project.

package/plugin/templates/state/hot.template.md

@@ -0,0 +1,12 @@
+---
+kushi_state_hot: true
+generated_at: "{{generated_at}}"
+---
+
+# Hot — {{project}}
+
+> _Auto-generated. Entities touched in the last 7 days, ranked by recency. Content between fences is regenerated on every build-state run._
+
+<!-- kushi:auto:start section="hot-entities" -->
+{{hot_entities}}
+<!-- kushi:auto:end section="hot-entities" -->

package/plugin/templates/state/review-queue.template.md

@@ -0,0 +1,10 @@
+---
+kushi_state_review_queue: true
+---
+
+# Review Queue
+
+> _Open contradictions requiring human review. Updated by build-state when contradictions are detected. Cleared when resolved (auto or manual)._
+
+| Entity | Property | Old value | New value | Flagged | Sources |
+|---|---|---|---|---|---|

package/src/eval-runner.test.mjs

@@ -35,7 +35,7 @@ test('eval-runner: evals.schema.json validates structurally', () => {
 test('eval-runner: every plugin/skills/<name>/ (except eval/) has evals/evals.json that parses', () => {
   const skillsDir = path.join(repoRoot, 'plugin/skills');
   const skills = fs.readdirSync(skillsDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && d.name !== 'eval')
+    .filter((d) => d.isDirectory() && d.name !== 'eval' && !d.name.startsWith('_'))
     .map((d) => d.name);
   const missing = [];
   for (const skill of skills) {