CI/CD Integration

Contextia’s check command verifies the integrity of your knowledge layer: specs, decisions, norms, tasks, and annotations. Running it in CI ensures that documentation stays synchronized with code as the project evolves.

Why check in CI?

Without automated checking, knowledge artifacts drift from code. Specs reference files that no longer exist. Annotations point to deleted specs. Decisions are marked as accepted but have no implementing code. Over time, the knowledge layer becomes unreliable, and agents stop trusting it.

contextia check --ci catches these issues on every pull request.

Basic GitHub Actions workflow

Create .github/workflows/contextia.yml:

name: Contextia Check

on:
  pull_request:
    paths:
      - '.contextia/**'
      - 'src/**'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Install Contextia
        run: uv tool install contextia

      - name: Run integrity check
        run: contextia check --ci --format json > contextia-report.json

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: contextia-report
          path: contextia-report.json

The paths filter ensures the workflow only runs when knowledge artifacts or source files change, saving CI minutes on documentation-only or infrastructure changes.

Exit codes

contextia check uses exit codes to signal results:

Exit code	Meaning
0	All checks passed
1	One or more violations found
2	Configuration error (missing config.yaml, invalid schema)

In --ci mode, the command never prompts for input and always exits with a clear code.

What gets checked

The check command validates several categories of integrity:

Spec integrity

• Every spec has a valid id, title, and status.
• All decisions referenced in spec frontmatter exist in .contextia/system/rationale/.
• All norms referenced in spec frontmatter exist in .contextia/system/norms/.
• All paths listed in spec frontmatter exist in the filesystem.

Decision and norm integrity

• Every decision has a valid id, title, and status.
• Every norm has a valid id, title, and status.
• Back-references are consistent (if SPEC-001 references DEC-001, DEC-001 should reference SPEC-001).

Task integrity

• Every task has a valid id, title, status, and kind.
• All specs referenced in task frontmatter exist.
• Active tasks have corresponding directories in work/active/.

Annotation integrity

• Every @spec annotation in source code references a spec that exists.
• Every @decision annotation references a decision that exists.
• No orphan annotations (pointing to deleted artifacts).
• Bidirectional consistency: if a spec lists paths: [src/auth.py] and src/auth.py has no @spec annotation for that spec, a warning is raised.

Note

Bidirectional consistency warnings are informational by default, not blocking. You can promote them to errors with check.strict_bidirectional: true in config.yaml.

JSON output format

With --format json, the output is machine-parseable:

{
  "version": "1.0",
  "timestamp": "2026-03-02T14:30:00Z",
  "summary": {
    "total_checks": 47,
    "passed": 45,
    "warnings": 1,
    "errors": 1
  },
  "violations": [
    {
      "severity": "error",
      "category": "spec_integrity",
      "message": "Spec SPEC-012 references decision DEC-099 which does not exist",
      "file": ".contextia/system/specs/SPEC-012.md",
      "field": "decisions"
    },
    {
      "severity": "warning",
      "category": "annotation_integrity",
      "message": "File src/auth/login.py has @spec SPEC-001 but SPEC-001 does not list this path",
      "file": "src/auth/login.py",
      "line": 5
    }
  ]
}

You can pipe this to jq for custom processing:

# Count errors only
contextia check --format json | jq '.violations | map(select(.severity == "error")) | length'

# List all files with violations
contextia check --format json | jq '[.violations[].file] | unique'

Using baselines for incremental adoption

When adding Contextia to an existing project, you likely have many pre-existing inconsistencies. The baseline feature lets you suppress known violations so that CI only fails on new ones.

Creating a baseline

Run the check and save the current violations as accepted:

contextia check --create-baseline

This writes .contextia/.baseline.json containing the fingerprints of all current violations. Commit this file.

How the baseline works

On subsequent runs, contextia check compares current violations against the baseline:

• Known violations (in baseline): reported as informational, do not cause failure.
• New violations (not in baseline): cause failure.
• Resolved violations (in baseline but no longer occurring): reported as resolved. The baseline can be updated to remove them.

# Update baseline to remove resolved violations
contextia check --update-baseline

Tip

Set a team goal to reduce the baseline by a fixed number per sprint. Over time, the baseline shrinks to zero and you have full integrity checking.

Custom reporting with GitHub PR comments

You can post check results as PR comments using the GitHub CLI:

- name: Run check and comment
  if: github.event_name == 'pull_request'
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    RESULT=$(contextia check --ci --format json)
    ERRORS=$(echo "$RESULT" | jq '.summary.errors')
    WARNINGS=$(echo "$RESULT" | jq '.summary.warnings')

    BODY="## Contextia Check\n\n"
    if [ "$ERRORS" = "0" ]; then
      BODY+="All checks passed. "
    else
      BODY+="**${ERRORS} error(s) found.** "
    fi
    BODY+="${WARNINGS} warning(s).\n\n"

    if [ "$ERRORS" != "0" ]; then
      BODY+="<details><summary>Violations</summary>\n\n"
      BODY+=$(echo "$RESULT" | jq -r '.violations[] | "- **\(.severity)**: \(.message) (`\(.file)`)"')
      BODY+="\n\n</details>"
    fi

    gh pr comment ${{ github.event.pull_request.number }} --body "$BODY"

Configuration options

Relevant settings in .contextia/config.yaml:

check:
  strict_bidirectional: false   # Promote bidirectional warnings to errors
  ignore_patterns:              # Skip these paths during annotation scan
    - "tests/fixtures/**"
    - "scripts/**"
  required_fields:              # Extra fields to require in frontmatter
    spec: [description, paths]
    decision: [date]

Running alongside other CI checks

Contextia check is fast (typically under 5 seconds for projects with 100+ artifacts) because it reads local files with no network calls. Place it early in your CI pipeline alongside linting:

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install tools
        run: |
          uv tool install contextia
          uv tool install ruff
      - name: Lint
        run: ruff check src/
      - name: Type check
        run: uv run mypy src/
      - name: Knowledge integrity
        run: contextia check --ci

Next steps

• Learn about Writing Effective Specs to minimize violations from the start.
• See the Migration Guide for adding Contextia to an existing project.
• Read the Configuration Reference for all check-related settings.