Publisher page

Extensions that carry engineering intent with the code.

Provenance is the first extension from Pedro Ribeiro: a lightweight annotation convention and VS Code experience for requirement, authorship, and compliance traceability.

View Provenance Annotation formats

1# pvnc.req: USER-1092
2# pvnc.reason: Sugar threshold added
3# pvnc.dnc: HMRC compliance
4# pvnc.source: ai.claude
5if order.category == "food" and order.sugar_content <= 2:

                  Do-not-change
                  Proceed with intention: HMRC compliance
                

Extensions

Published extensions

Provenance

Requirement and compliance traceability directly in code.

First extension

Embed structured annotations near the code they explain, then use the VS Code extension to highlight, search, aggregate, and warn on important traceability metadata.

View on GitHub

Formats Block and inline Authorship Human, AI, unknown Guardrails Do-not-change warnings Scope Parser-agnostic comments

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. Each block is independent and can be stacked into a timeline.

<pvnc>
  requirement: USER-1092 (jira, 2025-Q3)
  reason: Sugar threshold added
  do-not-change: HMRC compliance
  source: ai.claude
</pvnc>

Inline format

Use one comment line per key. Consecutive inline runs separated only by blank lines are grouped into a single annotation.

# pvnc.req: USER-1092
# pvnc.reason: High-sugar foods excluded
# pvnc.dnc: HMRC compliance
# pvnc.source: ai.claude

VS Code experience

Traceability that is visible and searchable.

Syntax highlighting

Keys, requirement IDs, reason text, sources, and guard entries render distinctly.

Authorship metric

The Provenance panel aggregates human, AI-authored, and unknown-source annotations.

Gutter icons

Annotated lines show authorship markers: AI, human, mixed, or unspecified.

Explorer badges

Opt-in file badges appear for opened, edited, or explicitly analyzed files.

Hover tooltips

Hovering surfaces full annotation content, including cross-references and timelines.

Do-not-change warnings

Guarded edits show a non-blocking warning so compliance-sensitive logic is intentional.

Key reference

Fields supported by Provenance.

Field	Inline	Purpose
requirement	pvnc.req	Work item that drove this code
reason	pvnc.reason	Human-readable explanation
source	pvnc.source	Authorship: human or AI assistant
invariant	pvnc.inv	Rule that must never be violated
do-not-change	pvnc.dnc	Load-bearing complexity guard
see-also	pvnc.see	Related files or ticket IDs

Configuration

Workspace settings.

{
  "provenance.gutterIcons": true,
  "provenance.explorerFileBadges": false,
  "provenance.warnOnDoNotChange": true,
  "provenance.guardedRangeLines": 30,
  "provenance.ticketSystems": {
    "jira": { "baseUrl": "https://yourcompany.atlassian.net", "apiToken": "" },
    "ado": { "organisation": "yourorg", "pat": "" },
    "github": { "owner": "your-org", "repo": "your-repo", "token": "" }
  }
}

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.