contextia check

contextia check validates the structural integrity of your .contextia/ directory. It detects broken references, orphan artifacts, malformed frontmatter, and other inconsistencies. Designed for both interactive use and CI/CD pipelines.

Synopsis

contextia check [OPTIONS]

Options

Option	Short	Description
--ci		CI mode: exit with code 1 if any errors are found
--baseline <path>		Compare against a baseline file; only report new issues
--rule <name>		Run only specific rules (repeatable)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

Validation rules

The following rules are checked. Each rule has a configurable severity in config.yaml:

Rule	Default severity	Description
orphan-spec	warning	Spec not referenced by any task or code annotation
broken-ref	error	Artifact references a non-existent ID
broken-link	error	Spec links field contains a non-existent ID
broken-path	warning	Spec paths field contains a glob matching no files
malformed-frontmatter	error	YAML frontmatter fails schema validation
missing-required-field	error	Required frontmatter field is absent
oversized-identity	warning	identity.md exceeds recommended token count
duplicate-id	error	Two or more artifacts share the same ID
stale-task	info	Task in active status with no session log for 7+ days
empty-scope	warning	Norm has no scope pattern defined

Severity configuration

Override default severities in config.yaml:

check:
  rules:
    orphan-spec: error        # promote to error for CI
    broken-path: info         # demote to informational
    oversized-identity: error # enforce identity size limits
  identity_max_tokens: 800    # threshold for oversized-identity

Examples

Run all checks:

$ contextia check
  ✓ 12 artifacts scanned

  ERRORS (2):
    broken-ref     TASK-007 references SPEC-AUTH-999 (not found)
    malformed-fm   .contextia/system/specs/SPEC-DB-003.md: missing required field "status"

  WARNINGS (1):
    orphan-spec    SPEC-OLD-001 is not referenced by any task or annotation

  2 errors, 1 warning, 0 info

CI mode for pipelines:

$ contextia check --ci
  ERRORS (2):
    broken-ref     TASK-007 references SPEC-AUTH-999 (not found)
    malformed-fm   SPEC-DB-003.md: missing required field "status"

  2 errors found. Exiting with code 1.
$ echo $?
1

Run specific rules only:

$ contextia check --rule broken-ref --rule broken-link
  ✓ 12 artifacts scanned (2 rules active)

  ERRORS (1):
    broken-ref     TASK-007 references SPEC-AUTH-999 (not found)

  1 error

Baseline comparison (show only new issues):

# Save a baseline
$ contextia check --json > .contextia/.cache/check-baseline.json

# Later, compare against it
$ contextia check --baseline .contextia/.cache/check-baseline.json
  ✓ 14 artifacts scanned

  NEW ISSUES (1):
    broken-ref     TASK-013 references DEC-099 (not found)

  1 new error (2 baseline issues suppressed)

JSON output:

$ contextia check --json
{
  "scanned": 12,
  "issues": [
    {
      "rule": "broken-ref",
      "severity": "error",
      "artifact": "TASK-007",
      "message": "references SPEC-AUTH-999 (not found)",
      "file": ".contextia/work/tasks/TASK-007.md"
    },
    {
      "rule": "orphan-spec",
      "severity": "warning",
      "artifact": "SPEC-OLD-001",
      "message": "not referenced by any task or annotation",
      "file": ".contextia/system/specs/SPEC-OLD-001.md"
    }
  ],
  "summary": { "errors": 1, "warnings": 1, "info": 0 }
}

CI/CD integration

Add to your GitHub Actions workflow:

- name: Check context integrity
  run: uvx contextia check --ci

Or in a pre-commit hook:

#!/bin/sh
uvx contextia check --ci --rule broken-ref --rule malformed-frontmatter

Behavior

• Without --ci, the command always exits with code 0, regardless of findings.
• With --ci, the command exits with code 1 if any issues at error severity are found.
• The --baseline option compares issues by rule + artifact + message. Resolved baseline issues are not reported.
• Running with no .contextia/ directory prints a suggestion to run contextia init and exits with code 2.