kushi-agents 6.1.2 → 6.2.0

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/promote/.created-by-skill-creator

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

package/plugin/skills/promote/SKILL.md

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

package/plugin/skills/promote/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "promote",
+  "cases": [
+    {
+      "id": "promote-refuses-on-customer-name",
+      "name": "kushi promote refuses without --force when a customer name is detected",
+      "input": "kushi promote acme answers/2026-05-27_confidence-ladder.md",
+      "expected_assertions": [
+        { "type": "contains", "value": "refused" },
+        { "type": "contains", "value": "identifier" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "promote-force-writes-redacted",
+      "name": "kushi promote --force writes the redacted target + back-link + dual logs",
+      "input": "kushi promote acme answers/2026-05-27_confidence-ladder.md --force",
+      "expected_assertions": [
+        { "type": "contains", "value": "Promoted" },
+        { "type": "contains", "value": "redacts" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "promote-clean-page-no-redactions",
+      "name": "kushi promote on a customer-free page writes immediately with zero redactions",
+      "input": "kushi promote acme answers/2026-05-27_generic-pattern.md",
+      "expected_assertions": [
+        { "type": "contains", "value": "Promoted" },
+        { "type": "contains", "value": "redacts: 0" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

package/plugin/skills/schema-evolve/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: "schema-evolve"
+version: "1.0.0"
+description: "USE WHEN the user says 'from now on always do X', 'remember this rule', 'kushi remember <rule>', or wants to teach kushi a project-specific convention that persists across runs. DO NOT USE for one-time instructions (just answer inline) or for modifying doctrine (edit the .instructions.md file directly). Capability: captures user-stated conventions to Evidence/<alias>/State/CLAUDE.md, reads them back at the start of build-state/ask-project/refresh runs."
+---
+
+# Skill: schema-evolve
+
+Captures user-stated project conventions and persists them to `Evidence/<alias>/State/CLAUDE.md` so future runs respect them automatically.
+
+## Triggers
+
+- "from now on always do X for this project"
+- "remember that Y means Z"
+- `kushi remember <rule>` (CLI verb)
+- "for this project, always treat A as B"
+- "never include X in summaries for this project"
+
+## Inputs
+
+- `<rule>` — free-text convention statement.
+- `<project>` — engagement name (resolved from context or explicit).
+
+## Procedure
+
+1. **Resolve project** — identify the target project via fuzzy match or current context.
+2. **Parse rule** — extract the convention from user's statement. Normalize to declarative form.
+3. **Validate against doctrine** — check if the rule conflicts with hard doctrine (WorkIQ-only, CSC format, etc.). If conflict: warn user, explain why, do NOT persist.
+4. **Write to CLAUDE.md** — append the rule with timestamp + scope metadata to `Evidence/<alias>/State/CLAUDE.md`.
+5. **Confirm** — echo back the persisted rule and explain when it will be applied.
+
+## Step checklist
+
+- [ ] Step 1 — Resolve project + State path
+- [ ] Step 2 — Parse + validate rule
+- [ ] Step 3 — Append to CLAUDE.md
+- [ ] Step 4 — Confirm to user
+
+### Step 1 — Resolve project
+
+Resolve `<engagement-root>/<project>/Evidence/<alias>/State/`. If CLAUDE.md doesn't exist, create it with the v5.0.0 header:
+
+```markdown
+---
+kushi_state_page: true
+---
+
+# CLAUDE.md — Project Conventions
+
+Rules captured via `schema-evolve` skill. Read by build-state, ask-project, refresh-project at run start.
+```
+
+### Step 2 — Parse + validate
+
+Normalize user's statement:
+- "from now on always X" → "Always X"
+- "never do Y" → "Never Y"
+- "treat A as B" → "Treat A as B"
+
+Validate: if the rule would override hard doctrine (`workiq-only`, `verbatim-by-default`, `csc` format), reject with explanation.
+
+### Step 3 — Append to CLAUDE.md
+
+Append after existing content:
+
+```markdown
+## Rule: <short-title>
+
+- **Added**: <ISO-8601 timestamp>
+- **Scope**: project
+- **Source**: user (natural language)
+
+<normalized rule text>
+```
+
+### Step 4 — Confirm
+
+Print:
+> ✅ Rule captured: "<rule>"
+> Applied to: <project> (project scope)
+> Active in: build-state, ask-project, refresh-project
+
+## Gotchas
+
+1. **Hard doctrine override**: Rules CANNOT override WorkIQ-only, CSC format, verbatim-by-default, or evidence layout. Warn and refuse.
+2. **Duplicate rules**: If a near-identical rule exists, update the existing one (bump timestamp) rather than duplicating.
+3. **CLAUDE.md missing**: Create it with proper frontmatter on first rule capture.
+4. **No evidence modification**: Rules affect interpretation/presentation only — never modify raw evidence files.
+5. **Scope creep**: v5.2.0 is project-scope only. Don't promise global scope.
+
+## Validation loop
+
+After writing:
+1. Re-read `CLAUDE.md` — verify the new rule appears.
+2. Parse all rules — verify valid structure (heading, metadata, text).
+3. Run self-check: `pwsh plugin/skills/self-check/run.ps1 -Targeted schema-evolve`
+
+## References
+
+- `schema-evolve.instructions.md` — doctrine for convention persistence
+- `karpathy-state-layout.instructions.md` — CLAUDE.md role in State layout
+- `living-wiki.instructions.md` — incremental State maintenance
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (doctrine gap, missing cross-reference), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/schema-evolve/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "skill": "schema-evolve",
+  "cases": [
+    {
+      "id": "schema-evolve-capture",
+      "name": "Captures a user rule to CLAUDE.md",
+      "input": "kushi remember always use 'Northwind' not 'Healthcare Accelerator' in summaries",
+      "expected_assertions": [
+        { "type": "contains", "value": "CLAUDE.md" },
+        { "type": "contains", "value": "Rule" },
+        { "type": "contains", "value": "Northwind" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "schema-evolve-doctrine-conflict",
+      "name": "Rejects rule that conflicts with hard doctrine",
+      "input": "kushi remember never use WorkIQ, always use Graph API directly",
+      "expected_assertions": [
+        { "type": "contains", "value": "conflict" },
+        { "type": "contains", "value": "WorkIQ" },
+        { "type": "not_contains", "value": "Rule captured" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "schema-evolve-natural-language",
+      "name": "Auto-detects convention from natural language",
+      "input": "from now on for this project always treat John as the EM",
+      "expected_assertions": [
+        { "type": "contains", "value": "John" },
+        { "type": "contains", "value": "rule" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

package/plugin/skills/skill-checker/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: "skill-checker"
+version: "1.0.0"
+description: "USE WHEN the user says \"check skill\", \"lint skill\", \"retrofit skill\", \"audit skills\", \"npx kushi-agents check-skill ...\", or before merging a PR that touches plugin/skills/. DO NOT USE for runtime evidence validation (use ask-project) or for running evals (use the eval skill). Capability: lints any plugin/skills/<name>/ against the agentskills.io blueprint (frontmatter, sections, size caps, evals presence); offers a non-destructive --retrofit + --apply that adds missing section stubs without overwriting existing content; can invoke the skill-creator eval-review viewer."
+---
+
+# Skill: skill-checker
+
+The lint + retrofit harness for `plugin/skills/`. Companion to `skill-creator`. The two together close the authoring loop: `create-skill` scaffolds conformant; `check-skill` keeps it conformant + drags legacy skills up to spec.
+
+User triggers: "check skill", "lint skill", "audit skills", "retrofit skill", "is this skill conformant?", "kushi check-skill --all".
+
+Doctrine: [`plugin/instructions/skill-authoring.instructions.md`](../../instructions/skill-authoring.instructions.md).
+
+## USE WHEN
+
+- Before merging a PR that touches `plugin/skills/`.
+- After running `skill-creator/scaffold.ps1`, to verify the scaffold output passes lint.
+- Auditing the entire `plugin/skills/` tree against the blueprint (`-All`).
+- Migrating legacy skills written before v5.0.4 (`-Retrofit`, then `-Apply`).
+- Refreshing a skill's description per the optimization rules (`-OptimizeDescription`).
+
+## DO NOT USE FOR
+
+- Validating real customer evidence (use `ask-project` / `project-status`).
+- Running per-case evals (use the `eval` skill + `npm run eval`).
+- Authoring new skills (use `skill-creator`).
+
+## Gotchas
+
+- **Lint reuses self-check D30 + D33 logic** — it does not duplicate the checks. If you change blueprint rules, change them in `self-check/run.ps1` and re-run; this skill picks them up by delegating.
+- **Retrofit is additive only.** It never deletes or rewrites existing content. Missing sections are appended with `<!-- TODO(retrofit): fill in -->` markers. If a section exists but is wrong, retrofit flags it but won't touch it.
+- **`-Apply` requires `-Retrofit`.** Lint mode is read-only by design.
+- **No auto-commit.** Even after `-Apply`, the human reviews the diff and commits manually.
+- **`Evidence/_skill-checker/` is gitignored** — fix plans + scratch HTML stay local.
+
+## Step checklist
+
+- [ ] **Pick scope**: `-Skill <name>` (one) OR `-All`.
+- [ ] **Pick mode**: default (`-Lint`), `-Retrofit`, `-Retrofit -Apply`, `-OptimizeDescription`, `-Review`.
+- [ ] **Run**:
+
+  ```powershell
+  pwsh plugin/skills/skill-checker/check-skill.ps1 -Skill my-skill
+  pwsh plugin/skills/skill-checker/check-skill.ps1 -All -Retrofit -DryRun
+  pwsh plugin/skills/skill-checker/check-skill.ps1 -Skill my-skill -Retrofit -Apply
+  ```
+
+- [ ] **Inspect output** under `Evidence/_skill-checker/<skill>/` (fix plans) + stdout (findings).
+- [ ] **Re-run lint** after `-Apply` to confirm green.
+
+## Validation loop
+
+After running:
+
+1. Lint mode → if exit ≠ 0, fix the findings in the SKILL.md / evals.json directly and re-run.
+2. Retrofit mode → review the stdout diff; if it looks safe, re-run with `-Apply`.
+3. Apply mode → run `pwsh plugin/skills/self-check/run.ps1 -Deep -Targeted <skill>` to confirm no regressions.
+4. Optimize-description → review the diff; if good, copy the rewritten string into SKILL.md frontmatter manually.
+5. Commit.
+
+## Modes
+
+### `-Lint` (default)
+
+Runs the agentskills.io blueprint check. Calls `self-check/run.ps1 -Deep -Targeted <skill>` and filters its findings to the D30/D33-class codes that map to the blueprint. Exits non-zero if any blocking finding remains.
+
+### `-Retrofit`
+
+Compares actual structure to the blueprint and emits a fix plan:
+
+- Missing `## Gotchas` (pull-* / discovery skills) → append.
+- Missing `## Validation loop` (writer skills) → append.
+- Missing `## Step checklist` (orchestrators) → append.
+- Missing `evals/evals.json` → create starter.
+- Missing `USE WHEN` in description → flag (not auto-fixed — needs human review).
+- Description has marketing fluff → flag.
+
+Writes fix-plan JSON to `Evidence/_skill-checker/<skill>/fix-plan.json`. Stdout: human diff.
+
+### `-Apply` (requires `-Retrofit`)
+
+Executes the additive parts of the fix plan. Never overwrites; only appends sections + creates missing evals files. Stops short of any change marked `requires_human` in the plan.
+
+### `-OptimizeDescription`
+
+Reads the skill's current SKILL.md description, runs `skill-creator/optimize-description.ps1`, prints the diff. Never auto-applies.
+
+### `-Review`
+
+Invokes `skill-creator/generate-eval-review.ps1 -Skill <name>` — renders the HTML side-by-side viewer.
+
+## Arguments
+
+| Flag | Purpose |
+|---|---|
+| `-Skill <name>` | Target one skill. |
+| `-All` | Target every `plugin/skills/<name>/` except `eval`, `self-check`, `skill-creator`, `skill-checker`. |
+| `-Retrofit` | Emit the fix plan. |
+| `-Apply` | With `-Retrofit`, execute additive fixes. |
+| `-DryRun` | Print actions without writing. |
+| `-OptimizeDescription` | Run the description optimizer + diff. |
+| `-Review` | Render the eval-review HTML viewer. |
+| `-Output <path>` | Override the report / plan output path. |
+| `-Root <path>` | Override repo root. |
+| `-Json` | Emit a JSON report on stdout. |
+| `-StrictExit` | Exit 1 if any finding (else 0). |
+
+## How retrofit categorises gaps
+
+| Gap | Kind | Apply behaviour |
+|---|---|---|
+| No `evals/evals.json` | additive | creates starter file with 2 cases |
+| No `## Gotchas` (pull-*) | additive | appends stub block |
+| No `## Validation loop` (writer) | additive | appends stub block |
+| No `## Step checklist` (orchestrator) | additive | appends stub block |
+| Description missing `USE WHEN` | non-additive | flagged; needs human |
+| Description >1024 chars | non-additive | flagged; needs human |
+| SKILL.md >500 lines | non-additive | flagged; split into references/ |
+| Marketing words in description | non-additive | flagged; needs human |
+
+## Output paths
+
+- Fix plan JSON: `Evidence/_skill-checker/<skill>/fix-plan.json`
+- Dogfood report (manual rollup): `docs/audits/v5.0.4-skill-creator-dogfood.md`
+- Per-run summary (with `-Output`): wherever you direct it.
+
+## References
+
+- `plugin/instructions/skill-authoring.instructions.md` (doctrine)
+- `plugin/instructions/agentskills-compliance.instructions.md` (D30 rules this delegates to)
+- `plugin/instructions/skill-evals.instructions.md` (D33 rules)
+- `plugin/skills/self-check/run.ps1` (the underlying linter)
+- `plugin/skills/skill-creator/SKILL.md` (the partner authoring skill)
+- `docs/audits/v5.0.4-skill-creator-dogfood.md` (baseline retrofit run)
+- <https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md>