backlog-lint

/backlog-lint

Mechanically verify the backlog lifecycle invariants the workflow skills otherwise enforce through prose. Prose enforcement fails open (a missing tool, a stale skill copy, an agent that skipped a step); this script fails closed and is identical in every environment.

Usage

/backlog-lint                 # lint the repo's backlog_root (default: backlog/)
/backlog-lint <path>          # lint a specific backlog root

What you do

1. Resolve lint.js the standard way — probe which exists, once: ~/.claude/skills/backlog-lint/lint.js (local personal copy), else the workflow-skills plugin's …/skills/backlog-lint/lint.js (Glob for **/workflow-skills/skills/backlog-lint/lint.js under ~/.claude/ if the plugin root isn't obvious).
2. Run it from the target repo's root: node <resolved-lint.js-path> [backlog-root]. It reads backlog_root from .claude/repo-conventions.yaml when no argument is given.
3. Relay the output: errors (exit 1) are real contract violations to fix; warnings are advisory. Do not "fix" findings by weakening the data (e.g. never delete a depends-on to silence a dangling reference — resolve why it dangles).

What it checks

#	Check	Severity
E1–E2	proposal.md frontmatter present; status ∈ not-started/in-progress/ready/blocked/done/archived; priority ∈ P0/P1/P2; name/effort/owner non-placeholder	error
E3–E4	depends-on entries resolve to real feature folders; no cycles	error
E5	status: done with a FAIL row in verification.md	error
E6	epic-criteria IDs match EC-n bullets in the epic README	error
E7–E8	epic README features-table rows match real folders and their frontmatter status	error
W1	feature folder missing from its epic's features table	warning
W2	status: done with no verification.md (predates the verification contract)	warning
W3	epic has features but no EC-n exit criteria	warning

Wiring it into a consuming repo (recommended)

• Pre-push: add node <path>/lint.js to the repo's pre-push checks so a broken lifecycle state never reaches a PR.
• CI: a GitHub Actions step on PRs touching backlog/** — this makes the done-before-verified defect class structurally impossible regardless of which agent or human edited the backlog:

- name: backlog-lint
  if: ${{ hashFiles('backlog/**') != '' }}
  run: node .claude/skills/backlog-lint/lint.js   # or the plugin-installed path

• Epic completion nudge: a merge-triggered job that runs the linter and, when an epic's last feature flips done, comments "run /epic-review <epic> --completion" — mechanically closing the trigger gap that suggestions-in-reports leave open.

Hard rules

1. The script is the authority. Do not re-derive these checks in prose or "interpret" a failure away — fix the data or escalate to the user.
2. Never auto-edit backlog content to make the linter pass without saying exactly what changed and why; status flips in particular belong to the skills that own them (feature-implement Stage 6a, epic-review).