# Re-verification contract

The bundle's locators are redundant by design — each one narrows the search,
none of them is trusted blind. Before cutting code, the worker fetches the
**live** page and re-checks the evidence. Restyles move things; a CSS path
from yesterday can point at the wrong node today.

## The helper

```js
import { reverify } from 'annotate-loop/reverify';

const bundle = JSON.parse(readFileSync('data/annotations/<id>.json', 'utf8'));
const liveUrl = bundle.pageUrl; // re-fetch the same page
const html = await (await fetch(liveUrl)).text();
const report = reverify(bundle, html, { currentUrl: liveUrl });

report.verdict; // 'fresh' | 'relocated' | 'stale'
report.reason;  // human-readable one-liner
report.score;   // passing signals
report.total;   // checkable (non-skipped) signals
report.checks;  // [{ signal, result: 'pass'|'fail'|'skip', detail }]
```

## Signals

| Signal | What it checks | Skipped when |
|---|---|---|
| `component-hint` | `#id` / landmark / `tag.class` / bare `data-component` label present in HTML | hint empty |
| `css-path` | Terminal segment (id preferred, else tag + classes) present | path empty |
| `xpath` | Id anchor present | positional xpath (needs a DOM — reported, not guessed) |
| `element-text` | 48-char text excerpt present | no excerpt |
| `page-url` | Live URL origin + pathname match the bundle URL | `currentUrl` not passed |

## Verdicts

- **`fresh`** — every checkable signal confirms the spot. Implement against
  the bundle locators.
- **`relocated`** — some signals confirm, some miss. The spot likely shifted:
  open the live page, use the surviving signals (usually the component hint
  or id anchor) to find the element by eye, then edit.
- **`stale`** — nothing confirms (or the bundle has no checkable evidence).
  Do not edit from this bundle: re-capture the annotation or ask for a fresh
  pointer.

## Notes

- The helper is dependency-free and DOM-free (pure string checks), so it runs
  in CI, workers, or edge runtimes — not just Node.
- Screenshots are orientation aids, not locators: they never decide the
  verdict.
- When `page-url` fails but locators pass, the page likely moved routes —
  confirm the canonical URL before editing.