ticket-lint

name	ticket-lint
description	Validate ticket files and inspect claim locks. Checks frontmatter schema, the status<->location invariant, unique numbers, and lock consistency (orphan/stale). Runs the bundled ticket-state.sh script. Use to check ticket health or before/after a batch of fixes.
argument-hint	[ticket-number] [--fix]
allowed-tools	Bash(*) Read Glob Grep

Ticket Lint

Validate the integrity of the project's ticket files and inspect the runtime claim locks. This is the read-only guardrail that keeps ticket-based state management from silently drifting: /ticket-triage, /ticket-fix, and /ticket-apply all run the same check as a gate before mutating anything.

All the logic lives in the bundled script ticket-state.sh — this skill resolves the ticket directory and drives that script.

Instructions

Step 1: Resolve the ticket directory

Read the host repo's root CLAUDE.md for a ticket-directory declaration (Tickets: / Ticket directory: line or a ## Tickets heading). Default: doc/tickets/. If <ticket-dir>/CLAUDE.md is missing, tell the user to run /ticket-init first and stop.

Step 2: Run lint

Invoke the bundled script (it must run inside the git repository):

${CLAUDE_PLUGIN_ROOT}/scripts/ticket-state.sh --dir <ticket-dir> lint [--all|NNNN] [--fix]

• No argument, or --all: lint every ticket.
• A ticket number in $ARGUMENTS: lint only that ticket.
• --fix in $ARGUMENTS: apply safe repairs only (normalize enum casing, relocate a file to match its status). Everything else is reported, not changed.

What the script checks:

• Frontmatter has the required keys (title, type, priority, status, created, updated) with valid enum values and YYYY-MM-DD dates.
• Filenames are NNNN-<kebab-subject>.md and ticket numbers are unique.
• status: resolved ⇔ file under resolved/ (and vice-versa).
• Lock consistency: warns on orphan locks (no matching ticket) and stale locks (older than the lock TTL).

The script exits non-zero (6) when any hard error remains. Relay the script's output to the user. If errors remain after a plain run, offer to re-run with --fix, but call out that a bad status value or a missing key needs a manual edit — --fix will not invent content.

Step 3: Inspect locks (when asked about in-flight work)

To show which tickets are currently claimed (and by whom / how old / on which branch), run:

${CLAUDE_PLUGIN_ROOT}/scripts/ticket-state.sh --dir <ticket-dir> status [NNNN]

Entries flagged STALE (older than the TTL) or DEAD-WORKTREE (their worktree is gone) are safe to clear — a subsequent /ticket-fix will steal them automatically, or the user can release one explicitly.

Notes

• Read-only by default. Without --fix, this skill never modifies ticket files; it only reports. --fix performs only the two safe repairs above.
• Locks live under .git, not in the working tree, so they are shared across all worktrees of the clone and are never committed. Clearing a stale lock has no effect on committed state.
• This skill does not commit. If --fix moved or edited files, use /commit-session to commit the result.