contextia trace

contextia trace performs a reverse lookup: given a file or directory path, it shows which specs and norms apply. This is the inverse of contextia show --implementations — instead of “which files implement this spec?”, it answers “which specs govern this file?”.

Synopsis

contextia trace <path> [OPTIONS]

Arguments

Argument	Description
path	File or directory path relative to the project root

Options

Option	Short	Description
--no-norms		Exclude norms from the output
--no-specs		Exclude specs from the output
--depth <level>	-d	Detail level: meta, summary, full (default: meta)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

How tracing works

Contextia uses two sources to determine which artifacts govern a file:

1. Top-down (paths field): Each spec and norm declares which paths it covers in its paths frontmatter field using glob patterns (e.g., src/auth/**). Contextia matches the input path against these patterns.

2. Bottom-up (annotations): If the file contains @spec or @decision annotations in comments, these are also reported.

Both sources are combined and deduplicated in the output.

Examples

Trace a single file:

$ contextia trace src/auth/oauth.py
  src/auth/oauth.py is governed by:

  Specs:
    SPEC-AUTH-001  Authentication Flow          (via paths: src/auth/**)
    SPEC-AUTH-002  Authorization Rules           (via annotation at line 34)

  Norms:
    NORM-SEC-001   No secrets in source code     (via scope: **/*.py)
    NORM-TEST-001  Every module has unit tests   (via scope: src/**)

Trace a directory:

$ contextia trace src/api/
  src/api/ is governed by:

  Specs:
    SPEC-API-002   REST API Conventions          (via paths: src/api/**)
    SPEC-API-005   API Rate Limiting             (via paths: src/api/middleware/**)

  Norms:
    NORM-SEC-001   No secrets in source code     (via scope: **/*.py)
    NORM-API-001   All endpoints require auth    (via scope: src/api/**)

Trace without norms:

$ contextia trace src/auth/tokens.py --no-norms
  src/auth/tokens.py is governed by:

  Specs:
    SPEC-AUTH-001  Authentication Flow           (via paths: src/auth/**)

JSON output:

$ contextia trace src/auth/oauth.py --json
{
  "path": "src/auth/oauth.py",
  "specs": [
    {
      "id": "SPEC-AUTH-001",
      "title": "Authentication Flow",
      "match": "paths",
      "pattern": "src/auth/**"
    },
    {
      "id": "SPEC-AUTH-002",
      "title": "Authorization Rules",
      "match": "annotation",
      "line": 34
    }
  ],
  "norms": [
    {
      "id": "NORM-SEC-001",
      "title": "No secrets in source code",
      "match": "scope",
      "pattern": "**/*.py"
    }
  ]
}

Context format for agents:

$ contextia trace src/auth/oauth.py --format context
src/auth/oauth.py
specs: SPEC-AUTH-001 (paths), SPEC-AUTH-002 (annotation:34)
norms: NORM-SEC-001 (scope), NORM-TEST-001 (scope)

Use cases

• Before editing a file: Check which specs and norms apply so you know the behavioral contract.
• Code review: Verify that changes to a file are consistent with its governing specifications.
• AI agent context: An agent can call trace on a file before modifying it to load the relevant specs.

Behavior

• Paths are resolved relative to the project root. Both src/auth/oauth.py and ./src/auth/oauth.py work.
• If no specs or norms match, the command prints “No governing artifacts found” and exits with code 0.
• The annotation scan respects comment_syntax from config.yaml.
• Directory traces match all artifacts whose paths or scope patterns overlap with the given directory.