spectracebeta

Spec drift

What the drift note in a verification comment means, when it appears, and what to do about it.

This page explains the "Possible drift" line a verification comment can carry, so you can tell a related change from a missing reference.

Prerequisites

  • The pull request resolved to a requirement through an explicit reference in its branch name, title, or description. See Linking a PR to a requirement.
  • Some files in the repository are linked to requirements through traceability links — created from the VS Code extension, by an AI agent calling spectrace_requirements_link_file, or automatically by a verified pull request that named its requirement (see Linking a PR to a requirement).

What drift is

Spec drift, in Spectrace, means the requirement a pull request says it implements disagrees with the requirement its changed files are linked to. It is detected during requirement resolution, not during verification.

When the pull request names a requirement explicitly, Spectrace also looks up which requirements are linked to the changed files and takes the top ten by link count. If the named requirement is among them, the comment footer reads "Confirmed by file traceability". If it is not, and traceability has a top hit for a different requirement whose links have been seen in the last 180 days, that disagreement is drift. A link is "seen" when it is created and again every time a verified pull request touches its file — so a requirement finished months ago, whose links nothing has confirmed since, stops contradicting new work in those files.

Drift does not change the verdict. The explicit reference wins, and the pull request is verified against the requirement you named. The note is information for the reader.

What it looks like

The note is a single line in the pull request comment, above the footer, on any comment tier:

**⚠ Possible drift** — this also touches 3 files linked to `sss-042` (Rate-limit webhook deliveries), which isn't referenced. Related change, or a missing reference?

The count is the number of changed files linked to the other requirement, and the other requirement is named by reference and title. When that requirement has no reference number, its title is quoted instead.

When it does not appear

  • The pull request resolved through file traceability rather than an explicit reference (rung 2). Those results carry no confirmation and no drift note.
  • The changed files have no traceability links to any requirement, so there is nothing to disagree with.
  • The named requirement is among the top linked requirements for the changed files. In that case the footer says it was confirmed instead.
  • The conflicting requirement's links are stale — none of them has been seen in the last 180 days. Old links still count for the rung-2 fallback, but they no longer generate drift warnings.

What to do

Read the note as a question, because that is what it is. Two answers are common:

  • Related change. The pull request legitimately touches code shared with the other requirement, and the reference is right. No action; the note also appears in the check run's summary (which mirrors the comment) but has no effect on the check's conclusion.
  • Missing or wrong reference. The work is really against the other requirement, or against both. Put the correct requirement's reference in the branch name or title and push a commit or reopen the pull request. Spectrace verifies against one requirement per pull request; if the change genuinely spans two, name the primary one and mention the other in the description.

A third possibility is that the traceability links are stale — a file was linked to a requirement it no longer implements. Left alone, this resolves itself: once nothing has confirmed those links for 180 days they stop producing drift notes. To silence the note sooner, remove the link with an authenticated DELETE /api/v1/requirements/{requirementId}/linked-files/{linkId} request, where linkId is the traceability link's id (the VS Code extension's Unlink Current File from Requirement command is a placeholder that does not remove links yet), and the note stops appearing on the next run.

Scope of the feature

Drift is a line in the comment (and in the check run summary that mirrors it) only. Spectrace does not store drift findings, and there is no drift dashboard, history, or notification. If you want a record, the pull request comment is it.

What done looks like

You have handled a drift note when either the reference matches the work and you have moved on, or you have corrected the reference and the next run's comment carries no note — or reads "Confirmed by file traceability".

If the note keeps appearing on every push for a change you consider related, that is expected: each run re-derives it from the same links, and there is no way to dismiss it.