@tasks-md/lint

Validates TASKS.md files against the spec.

Install

npm install -g @tasks-md/lint

Or run directly with npx:

npx @tasks-md/lint TASKS.md

Usage

tasks-lint [--fix] <file|directory> [file|directory...]

Pass individual files or directories. Directories are scanned for .md files (non-recursive).

tasks-lint TASKS.md                    # single file
tasks-lint TASKS.md packages/          # file + directory
tasks-lint frontend/TASKS.md backend/  # monorepo
tasks-lint --fix TASKS.md              # auto-fix deterministic errors

Auto-fix mode

Use --fix to automatically correct deterministic errors in-place:

Removes completed ([x]) tasks and their metadata blocks
Cleans up consecutive blank lines left after removals

Ambiguous cases (priority reordering, dangling blockers) are reported but not auto-fixed.

When multiple files are passed, IDs are checked for uniqueness across all files and blocker references are resolved globally.

Validation Rules

Rule	Description
Header	First line must be `# Tasks`
Priority order	`## P0` through `## P3`, in ascending order
Valid priorities	Only P0–P3 allowed (P4+ is an error)
Checkbox format	Tasks must use `- [ ]` checkbox syntax
No completed tasks	`- [x]` tasks should be removed, not left checked
Task placement	Tasks must appear after a priority heading
ID format	`ID:` values must be kebab-case (`auth-fix`, not `Auth Fix`)
Unique IDs	No duplicate IDs within a file or across files
Valid blockers	`Blocked by:` must reference IDs that exist somewhere
No orphaned metadata	`ID:`, `Tags:`, etc. must be nested under a task
Policy in comment	`policy:` directives must be inside `<!-- -->` HTML comments
Policy not empty	`<!-- policy: -->` with no directive text is an error
Unclosed comments	HTML comments must have a closing `-->`

Exit Codes

Code	Meaning
`0`	All files valid
`1`	Validation errors found
`2`	Usage error (no args, file not found, no .md files)

CI Integration

Add to GitHub Actions:

- name: Lint TASKS.md
  run: npx @tasks-md/lint TASKS.md

Or validate all task files in a monorepo:

- name: Lint all task files
  run: npx @tasks-md/lint TASKS.md packages/

Example Output

ERROR: TASKS.md:1: first line must be '# Tasks', got '# Todo'
ERROR: TASKS.md:8: priority heading P1 out of order (after P2)
ERROR: TASKS.md:15: completed task should be removed, not checked off
ERROR: TASKS.md:22: ID 'Auth Fix' must be kebab-case (lowercase letters, numbers, hyphens)
ERROR: TASKS.md:30: blocked-by references unknown ID 'missing-task'

Checked 1 file(s), found 5 error(s)

License

MIT