Validate

Check tasks, docs, and templates for quality and reference integrity

Validate

The knowns validate command checks your project for broken references, missing fields, and quality issues before AI starts coding.

What It Checks

Reference integrity — do task and doc references resolve?
Task quality — has title? Valid status/priority? Unchecked AC on done tasks?
Doc health — has title? Has description? Stale references?
Template validity — do .hbs files exist? Do they parse correctly?

Usage

# Validate everything
knowns validate

# Validate specific scope
knowns validate --scope tasks
knowns validate --scope docs
knowns validate --scope templates

# Validate a single entity
knowns validate --entity abc123        # single task
knowns validate --entity specs/auth    # single doc

# Strict mode (warnings become errors)
knowns validate --strict

# Auto-fix supported issues
knowns validate --fix

# JSON output for CI/CD
knowns validate --json

Flags

Flag	Description
`--scope`	`all` (default), `tasks`, `docs`, `templates`, `sdd`
`--entity`	Validate a single entity by task ID or doc path
`--strict`	Treat warnings as errors
`--fix`	Auto-fix supported issues
`--json`	Output as JSON
`--plain`	Plain text output (for AI agents)

SDD Validation

Use --scope sdd to check Spec-Driven Development coverage — verifies that tasks linked to specs have acceptance criteria and proper fulfills mappings.

knowns validate --scope sdd

Output Example

ERROR   [abc123] Parent task "xyz789" not found
WARN    [def456] Task is done but AC #1 is not checked: Add tests
INFO    [readme] Doc has no description

Summary: 1 error(s), 1 warning(s), 1 info

CI/CD Integration

# GitHub Actions
- name: Validate project
  run: knowns validate --strict

The exit code reflects validity — non-zero when errors are found.

MCP Tool

The same validation engine is available via MCP (v0.20 consolidated format):

validate({
  scope: "all",
  entity: "abc123",
  strict: false,
  fix: false
})