kushi-agents 6.1.2 → 6.2.0

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

@@ -0,0 +1,195 @@
+---
+name: "build-state"
+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."
+---
+
+# Skill: build-state
+
+## v4.9.0 — Reader fallback chain (HARD RULE; per `weekly-csc.instructions.md`)
+
+For every `<alias>/<source>/` accessed:
+
+1. **Primary**: read `Evidence/<alias>/<source>/_index/entities.yml`. For each entity needed, pull `latest_csc_file` + `latest_csc_block_offset`; open the weekly file and read the CSC block by entity anchor.
+2. **Secondary (no _index/, but weekly/ exists)**: walk `Evidence/<alias>/<source>/weekly/*.md` newest-first; parse `## <name> {#<anchor>}` headings; build an in-memory entity index for this query.
+3. **Legacy fallback (pre-v4.9.0)**: if `weekly/` is empty BUT `snapshot/` or `stream/` exist, read those. Cite as legacy.
+
+Citation form in this skill's output:
+- **New (v4.9.0)**: `[source: <alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md#<entity-anchor> · <iso-ts>]`
+- **Legacy (reading from snapshot/+stream/)**: append ` (legacy pre-v4.9.0 layout)` after the citation.
+
+Mark the answer / output footer with `Source-layout: weekly-csc | weekly-csc-plus-legacy | legacy-only` so the user knows whether a refresh would update the layout.
+
+Readers MUST NOT delete or modify legacy folders. Migration is out of scope for v4.9.0.
+
+Run this when the user says: "regenerate state for `<X>`", "rebuild State", "@Kushi state `<X>`". This skill makes NO source calls — it only reads Evidence and writes State.
+
+## Inputs
+
+- `<project>` — already-bootstrapped project.
+
+## Plan / Validate / Execute
+
+Per `plan-validate-execute.instructions.md`:
+
+1. **Plan** — before Step 2 (regenerate State files), serialize the proposed
+   state shape to `<project>/Evidence/_plan/build-state-plan.json`:
+   - `inputs[]` — every `_index/entities.yml` row, `weekly/*.md` file, and
+     legacy `snapshot/`/`stream/` fallback file the run intends to read.
+     Each entry: `{ source, alias, path, last_modified, included_in: [<state_file>, ...] }`.
+   - `proposed_state_files[]` — `{ id: "00..08", title, sections: [...],
+     citation_count, evidence_window: [from_iso, to_iso] }`.
+   - `proposed_open_questions[]` — `{ text, source_refs[] }` (the OQ list
+     Step 5 plans to write).
+   - `proposed_karpathy_emit[]` — the v5 Karpathy block paths planned for Step 6.
+2. **Validate** — for every `evidence_ref` in the plan, re-confirm the source
+   file exists and its `last_modified` matches the plan. Drop any reference
+   whose anchor no longer resolves (the underlying weekly file may have been
+   re-written between plan and execute). If validate drops > 20% of references
+   in any single State file, abort that file's write and surface the plan for
+   review.
+3. **Execute** — write `State/00..08_*.md` and the Karpathy outputs. Stamp each
+   State file's banner with the plan ID + validate-pass timestamp.
+
+The `_plan/` file is overwritten on every run and is safe to delete between
+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.
+
+- [ ] Step 1 — Read all Evidence
+- [ ] Step 2 — For each State file (00–08), regenerate
+- [ ] Step 3 — Conflict resolution
+- [ ] Step 4 — Citation density
+- [ ] Step 5 — Open Questions (mandatory every run)
+- [ ] Step 6 — v5 Karpathy emission (ADDITIVE; per `karpathy-state-layout.instructions.md`)
+- [ ] Step 7 — Banner
+
+### Step 1 — Read all Evidence
+
+For the resolved `<project>`, apply the v4.9.0 fallback chain for each `<alias>/<source>/`:
+- **Primary**: read `Evidence/<alias>/<source>/_index/entities.yml`; load entities via `latest_csc_file` + offset.
+- **Secondary**: if no `_index/`, walk `Evidence/<alias>/<source>/weekly/*.md` newest-first.
+- **Legacy fallback**: if `weekly/` is empty, read `Evidence/<alias>/<source>/snapshot/**/*.md` (current truth per entity) and `Evidence/<alias>/<source>/stream/**/*.md` (chronological events). Cite as `(legacy pre-v4.9.0 layout)`.
+- Walk `Evidence/_Consolidated/**/*.md` (multi-user merged where present).
+
+### Step 2 — For each State file (00–08), regenerate
+
+| State file | Pulls primarily from |
+|---|---|
+| 00_overview.md | snapshot/CRM/<id>.md, snapshot/sharepoint/files/*overview*.md, snapshot/onenote/pages/*overview*.md |
+| 01_decisions.md | stream/meetings/* (decision lines), stream/teams/* (decision lines), stream/email/* (decision lines), snapshot/ado/items/* (state changes) |
+| 02_stakeholders.md | snapshot/teams/chat-roster.md, snapshot/crm/<id>.md (engagement contacts), stream/email/* (sender/recipient analysis) |
+| 03_architecture-and-solution.md | snapshot/onenote/pages/*architecture*.md, snapshot/sharepoint/files/*arch*.md, stream/meetings/* (arch discussions) |
+| 04_workshops-and-key-meetings.md | snapshot/meetings/series-index.md, stream/meetings/* (per-meeting blocks) |
+| 05_action-items.md | stream/meetings/* (action lines), stream/teams/* (action lines), snapshot/ado/items/* |
+| 06_risks-and-issues.md | stream/meetings/* (risk lines), stream/email/* (escalations), snapshot/ado/items/* (risk-tagged) |
+| 07_timeline-and-milestones.md | snapshot/crm/<id>.md (milestones), snapshot/ado/items/* (iterations), stream/meetings/* (date commits) |
+| 08_artifacts-and-deliverables.md | snapshot/sharepoint/tree.md + files/*, snapshot/onenote/pages/* |
+
+### Step 3 — Conflict resolution
+
+- Latest fact wins on conflicts (compare `as of YYYY-MM-DD` snapshots and stream event timestamps).
+- Preserve superseded values via `Supersedes:` line under the new entry.
+- Each State file ends with a `## Conflicts` section listing every superseded value with both citations.
+
+### Step 4 — Citation density
+
+Per `citation-ledger.instructions.md`: every assertion in every State file MUST have an inline citation. Snapshot citations use `as of YYYY-MM-DD`; stream citations use `· YYYY-MM-DD`. Where a fact is BOTH "currently true" AND "decided on date X", cite both.
+
+### Step 5 — Open Questions (mandatory every run)
+
+Update `<project>/State/09_open-questions.md`:
+- Scan new evidence for items that are conflicting, second-hand, low-fidelity, or that prompt a follow-up question → add as new `Q-NNN` rows under 🔴 Open / 🟡 Partial. Set Fidelity (Low/Medium/High), Category, Source, Asked Of, Needed By.
+- For every existing 🔴/🟡 row, check if new evidence answers it. If yes: flip to 🟢 Resolved, fill Answer + Source of Answer + Resolved On, fold the answer into the appropriate State file (00–08), record path in **Folded Into**. Never delete rows.
+- If a question is no longer relevant (scope cut, decision overtaken), flip to ⚫ Stale with reason.
+- Bump the file's `As of:` line. Briefly mention in run-log how many opened / partial / resolved / staled.
+
+### Step 6 — v5 Karpathy emission (ADDITIVE; per `karpathy-state-layout.instructions.md`)
+
+After Steps 1–5 produce the legacy 00–09 files, ALSO emit the v5 layout:
+
+1. Ensure category folders exist under `<project>/State/`:
+   `people/`, `opportunities/`, `adoworkitems/`, `decisions/`, `risks/`,
+   `customerasks/`, `meetings/`, `artifacts/`.
+2. For each entity surfaced via the reader-fallback chain, write one
+   markdown file using `..\..\templates\state\page.template.md`. Filename
+   slug = lowercase ascii of the entity title (alphanumeric + hyphen, ≤80
+   chars), with `.md` suffix. Place it in the matching category folder.
+   The front-matter MUST include `kushi_state_page: true`, the canonical
+   `entity_ids: [...]` (graph node ids), and a `related: [...]` array of
+   other state-page paths (relative, slash-separated) discovered via graph
+   edges (`decides`, `discusses`, `action-item-tracks`, `references`,
+   `produced-by`, `follow-up-of`, `same-thread`, `participant-of`).
+3. Regenerate `<project>/State/index.md` from
+   `..\..\templates\state\index.template.md` by enumerating every file
+   under `State/**/*.md` whose front-matter has `kushi_state_page: true`,
+   grouped by category, sorted by filename. The index MUST be fully
+   overwritten each run.
+4. Append a new dated entry to `<project>/State/log.md`
+   (from `..\..\templates\state\log.template.md`):
+   `## YYYY-MM-DD HH:mm UTC — build-state run by <alias>` plus a short
+   summary (`pages_written: N`, `categories_touched: …`,
+   `legacy_files_rewritten: 00..09`).
+5. Ensure `<project>/State/CLAUDE.md` and `<project>/State/AGENTS.md` exist
+   and are byte-identical copies of
+   `..\..\templates\state\CLAUDE.template.md` (per the doctrine — Windows
+   does not honor symlinks reliably, so we copy).
+6. `[[wikilink]]` rendering: page bodies SHOULD use the
+   `[[category/slug]]` form for cross-references; the build does not need
+   to resolve these — they are render-time hints for human + agent
+   readers.
+
+v5 emission is gated on `m365Mutable.state.layout: "karpathy"` (default
+true). If set to `"legacy"`, skip Step 6.
+
+### Step 7 — Banner
+
+Top of every State file:
+
+```markdown
+> _As of: YYYY-MM-DD HH:mm. Regenerated by @Kushi build-state. Source: Evidence/ weekly CSC + legacy snapshots + streams._
+```
+
+`Source-layout: weekly-csc | weekly-csc-plus-legacy | legacy-only` (append to banner to reflect which layout was actually read).
+
+## Triggers
+
+- "regenerate state for `<X>`"
+- "rebuild state"
+- "@Kushi state `<X>`"
+- "re-render State after I fixed `<file>`"
+
+## Changelog
+
+- **v4.0.0 (kushi v5.0.0, 2026-05-26)**: ADDITIVE Karpathy-style emission — per-entity pages under `State/<category>/`, `State/index.md`, `State/log.md`, `State/CLAUDE.md`, `State/AGENTS.md`. Distinguished by `kushi_state_page: true`. Legacy 00–09 synthesis is retained for `full` profile parity. Gated on `m365Mutable.state.layout` (default `karpathy`). See `..\..\instructions\karpathy-state-layout.instructions.md`.
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted state`
+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.

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

@@ -0,0 +1,31 @@
+{
+  "skill": "build-state",
+  "version": "1.0.0",
+  "description": "Karpathy State layout — index.md + log.md + per-category folders.",
+  "cases": [
+    {
+      "id": "bs-state-index",
+      "name": "fixture State/index.md has kushi_state_page front-matter",
+      "input": "validate state fixture",
+      "fixture": "evals/fixtures/fixture-acme",
+      "canary": true,
+      "grader_type": "script",
+      "args": { "read_fixture": "State/index.md" },
+      "expected_assertions": [
+        { "type": "regex-match", "pattern": "kushi_state_page:\\s*true" }
+      ]
+    },
+    {
+      "id": "bs-state-log-exists",
+      "name": "fixture State/log.md exists",
+      "input": "verify log",
+      "fixture": "evals/fixtures/fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "State/log.md" },
+        { "type": "file-exists", "path": "State/index.md" }
+      ]
+    }
+  ]
+}

package/plugin/skills/dashboard/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: "dashboard"
+version: "1.0.0"
+description: "USE WHEN the user says \"@Kushi dashboard <X>\" OR after refresh-project/bootstrap-project completes AND <project>/Evidence/_graph/project-graph.json exists. DO NOT USE before link-entities has produced a graph (no-op without it). Capability: renders single self-contained <project>/dashboard.html via Cytoscape.js v3 + cose-bilkent, Clawpilot theme variables, two-view tabs (Graph + Timeline), source/alias/date filters, fuzzy search, side panel with cited CSC blocks."
+---
+
+# Skill: dashboard
+
+> **v5.0.0 — Single-file HTML dashboard producer.** See
+> `..\..\instructions\dashboard-artifact.instructions.md` for the full
+> contract: inputs, outputs, theming, views, filters, search, side panel.
+>
+> **Theming uses the Clawpilot `web-artifacts-builder` skill.** All CSS
+> variables (`--bg`, `--fg`, `--accent`, `--surface`, `--border`, …) come from
+> that skill's theme contract so the dashboard adopts the user's Clawpilot
+> palette when opened inside Clawpilot, and falls back to a default
+> light/dark scheme in a vanilla browser.
+
+## When to run
+
+- Automatically as part of `refresh-project` (after `link-entities` +
+  `build-state`) and `bootstrap-project` (same chain).
+- Manually: `@Kushi dashboard <project>`.
+
+## Inputs
+
+- `<project>` — already-bootstrapped project root.
+- `<project>/Evidence/_graph/project-graph.json` — REQUIRED. Missing graph →
+  skill is a no-op (dashboard is not produced).
+- `<project>/Evidence/<alias>/<source>/_index/entities.yml` — OPTIONAL per
+  contributor / source.
+- `<project>/State/index.md` — OPTIONAL. Used to populate the side panel's
+  "State pages" list.
+
+## Output
+
+- `<project>/dashboard.html` — single self-contained HTML file.
+
+## Steps
+
+
+## Step checklist
+
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+
+- [ ] Step 1 — Verify inputs
+- [ ] Step 2 — Collect data
+- [ ] Step 3 — Render
+- [ ] Step 4 — Verify
+
+### Step 1 — Verify inputs
+
+If `<project>/Evidence/_graph/project-graph.json` does not exist, exit
+cleanly with a one-line message ("no graph — run `link-entities` first").
+Do NOT produce a dashboard.
+
+### Step 2 — Collect data
+
+1. Read the graph JSON.
+2. Walk all `Evidence/<alias>/<source>/_index/entities.yml` files and merge
+   their entries into a single index map keyed by entity id (used by the
+   side panel to surface `latest_csc_file` quickly).
+3. Read `State/index.md` if present; parse the v5 state pages it lists.
+
+### Step 3 — Render
+
+Invoke the embedder:
+
+```pwsh
+pwsh plugin/templates/dashboard/embedder.ps1 `
+    -TemplatePath plugin/templates/dashboard/dashboard.template.html `
+    -OutPath <project>/dashboard.html `
+    -GraphJsonPath <project>/Evidence/_graph/project-graph.json `
+    -IndexJsonPath <intermediate> `
+    -StateJsonPath <intermediate>
+```
+
+The embedder substitutes the `__GRAPH_JSON__`, `__INDEX_JSON__`, and
+`__STATE_JSON__` placeholders in the template with the stringified JSON of
+the collected data, and writes the result to `<project>/dashboard.html`.
+
+### Step 4 — Verify
+
+Confirm `<project>/dashboard.html` exists and is non-empty. Open the file
+in a browser (manual verification step — not automated here) to confirm:
+the graph view renders, the side panel opens on node click, filters work.
+
+## Hard rules
+
+- The output is a **single self-contained HTML file**. No external CDN
+  fetches at view time.
+- Theming uses the Clawpilot `web-artifacts-builder` skill's CSS variables.
+- Idempotent — the file is fully regenerated on every run.
+- NEVER write outside `<project>/dashboard.html`.
+
+## Triggers
+
+- "dashboard `<X>`"
+- "build dashboard for `<X>`"
+- "@Kushi dashboard `<X>`"
+- (auto) end of `refresh-project` / `bootstrap-project`
+
+## References
+
+- `..\..\instructions\dashboard-artifact.instructions.md`
+- `..\..\instructions\entity-graph.instructions.md`
+- `..\..\instructions\karpathy-state-layout.instructions.md`
+- `..\..\instructions\issue-recovery.instructions.md`
+- Clawpilot user skill: `web-artifacts-builder` (theme variables, single-HTML
+  packaging contract).
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (template placeholder mismatch,
+data shape drift, theming regression), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md):
+fix the template or embedder first, re-render, verify in browser, then
+re-run self-check D22.dashboard.
+
+## Changelog
+
+- **v1.0.0 (kushi v5.0.0, 2026-05-26)**: initial release. Cytoscape.js v3 +
+  cose-bilkent + Clawpilot theme variables; two-view tabs; side panel;
+  filters; fuzzy search.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted dashboard`
+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.

package/plugin/skills/dashboard/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill": "dashboard",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for dashboard. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "dashboard-smoke-1",
+      "name": "dashboard produces a non-empty response",
+      "input": "synthetic dashboard probe — canary smoke",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": ".+"
+        }
+      ]
+    },
+    {
+      "id": "dashboard-smoke-2",
+      "name": "dashboard echoes case id",
+      "input": "case-id dashboard-smoke-2",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "dashboard-smoke-2"
+        }
+      ]
+    }
+  ]
+}

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"
+    }
+  ]
+}