Provenance

VS Code Extension

Requirement, authorship, and compliance traceability in code.

With Code Guard for enforced protection of critical regions.

v1.1.0

Embed structured annotations near the code they explain. The VS Code extension makes them visible, searchable, and linked to live ticket data. Code Guard adds CI-enforced fences around regions that must never change, with a formal two-commit removal workflow.

VS Code Marketplace View on GitHub

Formats Block and inline Authorship Human, AI, unknown Code Guard CI-enforced regions Scope Parser-agnostic

Why it exists

Code needs institutional memory at the point of use.

When an LLM helps with a codebase it has no institutional memory. It cannot know why a piece of code was written, what requirement drove it, or why an apparently redundant condition must not be removed.

Provenance keeps that context close to the implementation with a lightweight convention that works in any language with comments.

Annotation formats

Two formats, one parser.

Block format

Use <provenance> or the short alias <pvnc> in a doc comment or string literal. Ticket system name is the key. Stack multiple blocks to record the full change history.

<pvnc>
  jira: USER-1092 (2025-Q3)
  reason: Sugar threshold added — high-sugar foods excluded
  do-not-change: HMRC compliance — do not simplify
  source: ai.claude
</pvnc>

Inline format

One comment line per key — no wrapper needed. Consecutive runs separated only by blank lines are grouped into a single annotation.

# pvnc.jira: USER-1092
# pvnc.reason: High-sugar foods excluded
# pvnc.dnc: HMRC compliance — audited 2024-03
# pvnc.source: ai.claude

Code Guard

Structural fences for regions that must not change.

do-not-change: is an advisory annotation — fuzzy scope, no enforcement. Code Guard adds explicit guard_start / guard_end boundaries, CI enforcement on every pull request, and a mandatory two-commit removal workflow that creates an audit trail before any guarded region can be modified.

Marking a guard

Place the marker immediately after the annotating <pvnc> block. Block IDs are arbitrary — make them meaningful.

# pvnc.guard_start: block-hmrc-001
if order.category == "food" and \
   order.sugar_content <= 2:
    tax = 0.0
# pvnc.guard_end: block-hmrc-001

Removing a guard (two-commit workflow)

Commit a removal declaration first, then make the change in a second commit. The CI check enforces this order.

# pvnc.guard_removed: block-hmrc-001 \
#   : New HMRC directive 2026-Q2 supersedes

Run Provenance: Remove guard from the Command Palette to scaffold the declaration and commit message automatically.

VS Code experience

Traceability that is visible and searchable.

Hover tooltips

Hovering an annotation shows its full content with live ticket title and status — fetched from GitHub, Jira, ADO, or Linear without leaving the editor.

Gutter icons

Every annotated line shows a colour-coded icon: teal for AI, orange for human, amber shield for guard markers. Malformed guards show a warning label.

Code Guard region tint

Lines inside a guarded region get a configurable background tint. Editing any interior line triggers a warning with a scaffold removal button.

Do-not-change warnings

Editing code after a do-not-change: annotation shows a non-blocking warning. The field is highlighted in red in the hover tooltip.

Provenance panel

The sidebar aggregates authorship metrics, guard density, and a searchable, filterable list of every annotation across the workspace.

Contribution log

A JSONL log of every AI and human contribution travels with the repo — the full project history is available to new cloners without external tooling.

Key reference

Fields supported by Provenance.

Field	Inline	Purpose
github: · jira: · ado: · …	pvnc.github: · pvnc.jira: · …	Work item or page — any configured system name
reason	pvnc.reason	Human-readable explanation
source	pvnc.source	Authorship: human, ai.claude, ai.copilot, …
invariant	pvnc.inv	Rule that must never be violated
do-not-change	pvnc.dnc	Advisory guard — triggers an edit warning
see-also	pvnc.see	Related files or IDs (comma-separated)

Configuration

Workspace settings.

{
  "provenance.gutterIcons": true,
  "provenance.warnOnDoNotChange": true,
  "provenance.guardedRangeLines": 30,

  "provenance.codeGuard.enabled": true,
  "provenance.codeGuard.gutterHighlight": true,
  "provenance.codeGuard.regionTint": true,
  "provenance.codeGuard.regionTintColour": "#ff000011",
  "provenance.codeGuard.warnOnEdit": true,
  "provenance.codeGuard.ciStrictMode": true
}

Ticket system credentials (PATs, tokens) are stored in VS Code's encrypted secret storage — never in settings files. Use Provenance: Set up workspace config from the Command Palette to configure ticket integration interactively.

Supported languages

Parser-agnostic by design.

Python, TypeScript, JavaScript, Java, C#, C/C++, Rust, Go, Ruby, PHP, Kotlin, Swift, and any other language with line or block comments.