Git Versioned Annotations

Git Versioned Annotations displays explanatory comments without inserting them into source files. Each annotation file is keyed by the exact Git blob it describes, so opening an older commit or either side of a diff shows the annotation for that version.

Core behavior

• Source text, saves, compilers, formatters, and ordinary Git diffs remain unchanged.
• A concise summary is always visible at the end of its target line.
• Optional Markdown details appear on hover.
• Ctrl+Alt+C copies the summary at the cursor.
• Ctrl+Shift+Alt+C copies the complete annotation at the cursor.
• Working files, git: history documents, and both diff sides use the same renderer.

Repository setup

Track a small .code-annotations.json file in the source repository:

{
  "schema": 1,
  "store": ".code-annotations",
  "remote": "git@github.com:owner/project-annotations.git"
}

The .code-annotations directory is a separate nested Git repository and must be ignored by the source repository:

/.code-annotations/

On the first file opened in a trusted workspace, the extension clones a missing store from remote. Once per VS Code session it also attempts a fast-forward update. If the network is unavailable, an existing local store remains readable. Annotation authoring is handled separately, allowing coding agents to be denied access to annotation contents.

The annotation store is append-only at the blob-record level: keep old object records so historical files and both sides of old diffs remain annotated.

Annotation task CLI

The VSIX includes dist/annotation-cli.js, so the independent annotation task does not need a second package. Locate an installed extension with code --locate-extension fsotm.git-versioned-annotations and run the script with Node.

Materialize a proposal against exact source blobs from a commit:

node <extension>/dist/annotation-cli.js materialize \
  --source-repo <repository> --commit <commit> \
  --mode source-commit --input <proposal.json>

Use --mode baseline-backfill for the one-time current-baseline migration. For a conditional post-merge audit, use --mode merge-audit --reviewed-from-merge <merge-commit>; the CLI rejects a non-merge commit or a reviewed commit that differs from --commit.

Each completed materialization writes an idempotent receipt under runs/<mode>/<commit>.json. Repeating the same task safely skips it. Existing annotations with different IDs are retained; an incoming annotation replaces only the same ID. Validate every record, receipt, and target position with:

node <extension>/dist/annotation-cli.js validate-store --source-repo <repository>

After a merge, run a deterministic coverage check before starting any AI audit:

node <extension>/dist/annotation-cli.js merge-coverage \
  --source-repo <repository> --commit <merge-commit> --extension .gd

The command returns requiresAudit: true only when a final changed file has no exact blob record. Repeat --extension for additional source types.

Proposal format:

{
  "schema": 1,
  "repository": "github.com/owner/project",
  "files": [
    {
      "source_path": "src/example.gd",
      "annotations": [
        {
          "id": "boundary-input-index",
          "line": 41,
          "character": "eol",
          "kind": "boundary",
          "summary": "The UI already validated this index."
        }
      ]
    }
  ]
}

Annotation record

Records live at objects/<first-two-characters>/<git-blob-oid>.json:

{
  "schema": 1,
  "repository": "github.com/owner/project",
  "blob": "4096b40a6bbbfbeb24af434bbf5d92c9c2008964",
  "source_path": "src/example.gd",
  "generated_from_commit": "abc123",
  "annotations": [
    {
      "id": "boundary-input-index",
      "line": 41,
      "character": "eol",
      "kind": "boundary",
      "summary": "This function receives an index already validated at the UI boundary.",
      "details_markdown": "The UI converts raw input once. Internal code therefore treats the index as trusted."
    }
  ]
}

Line numbers are zero-based. Summaries must be non-empty single-line strings. Details are optional Markdown.

Commands

• Git Versioned Annotations: Refresh Annotations
• Git Versioned Annotations: Copy Annotation Summary at Cursor
• Git Versioned Annotations: Copy Full Annotation at Cursor

Security boundary

Ignoring the nested repository prevents accidental inclusion in ordinary source searches and diffs. It is not an access-control boundary. Deny the annotation-store path in coding-agent filesystem permissions when annotation contents must never enter the coding context.