skills-integrity lint: retired namespaces, dead skill paths, frontmatter drift

[aarontrowbridge]

Closes #1045.

What

Standing teeth for the skill-integrity loop (spec spec-20260913-skill-integrity-loop): a zero-dep CLI lint at packages/extension/scripts/lint-skills.mjs plus a vitest suite (test/skills_integrity.test.ts) and a lint:skills package script.

Rules

rule	severity	catches
amico-plugin	error	retired amico-plugin:* namespace refs (F09)
companion	error	companion file referenced from a SKILL.md that doesn't exist — resolved inside the skill's own dir only; markdown-link .md targets + backticked paths carrying a directory component; placeholders (<...>, {...}, *), .. escapes, absolute and URL refs are not resolved (conservative by design)
name / surface	error	frontmatter name: ≠ directory; surface: outside {public, internal, entitled}
agents	warning	values outside the known role set — ontology sweep is a later slice; warnings never fail the lint

Exit codes follow the skill_drift_lint contract: 0 ok (warnings/known allowed), 1 errors, 2 usage/pre-flight.

Decisions recorded (per the issue's acceptance note)

• workspaceStorage guard (spec O1): a --dir containing workspaceStorage is refused outright (exit 2) — the deployed copy is a build artifact, never a source.
• The --known escape hatch (scripts/lint-skills-known.txt) carries the exact current occurrences: 14 unique companion refs across 4 skills (develop, migrate-research-project, paper-writer, research) — backticked cross-references to other trees (project scaffolding like docs/*.md, ledger/*, the opencode agent card) that cannot be mechanically resolved. Format is path:rule with an optional :ref third segment (small extension over the issue's path:rule) so exemptions pin the exact referenced path and a new dead ref in the same file still fails. Unknown rule names in the file exempt nothing (typo-safe).
• F09 scope note: the repo source tree has zero live amico-plugin: refs (the only amico-plugin strings are backticked repo names in provenance notes — no colon, not the namespace). F09's offenders (code-review, finishing-branch, parallel-agents) live in the deployed workspaceStorage copy, which the lint refuses to scan by design. The rule is still the standing teeth: any new amico-plugin: ref fails.
• The lint runs against any --dir (e.g. armonissima/skills via dream — cadence-based per spec O2); --json output feeds the findings ledger.

Out of scope (per the issue)

No SKILL.md content changes; no CI wiring (spec O3 — local bash gate until the fleet-boundary wave lands); no packages/extension/modes/ edits (spec O4).

Tests

pnpm --filter amicode exec vitest run test/skills_integrity.test.ts — 6/6 green: fixture RED (planted amico-plugin: ref, dead companions, name/surface drift, unknown agent warning), known-exemption pass/fail matrix, workspaceStorage refusal, and green over the real tree with the checked-in known list.

Full suite pnpm --filter amicode test: 3394 passed; the 6 failures (chat_bridge ×2, service_runner, cli_gate, skill_drift_lint fleet-regressions ×2) reproduce identically on pristine origin/main in this worktree — pre-existing environment dependencies (staged bins, vendored engine binary, fleet packages), not this change.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 3f47fc13-9523-416d-bb26-39ec62495d01

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}