ai-for-dummies/.agents/skills/verify-contract/SKILL.md

name, description

name	description
verify-contract	Evolve scripts/verify.mjs across the Astro migration without losing coverage. Use whenever a verify assertion fails because of a refactor, or when adding checks for new architecture.

The verification contract

Read ../../context/verification.md first.

verify.mjs has 42 assertions pinning real content and interactions. They are the only thing preventing silent content loss during this migration, and they will all break, because they assert against files that stop existing.

The rule

A failing assertion is a question, not a bug to delete.

assertion fails
      ↓
does the user-visible fact it pins still exist?
      ├── yes → re-point the assertion at the new location
      └── no  → you deleted content. Put it back, or get sign-off.

grep -c 'throw new Error' scripts/verify.mjs must not decrease. If it must, the verification-engineer writes a one-line reason per removal in the task report. Nobody else may reduce coverage.

Translating assertions

Kind	Old	New
Content presence	html.includes('data-phase="plan"')	same token, read from dist/full-guide/index.html
Implementation detail	js.includes('renderTree')	assert the rendered output has the tree UI, not that a function is named that
Asset version	'app.js?v=20260904-vote-widget'	assert the built HTML references a hashed asset

Implementation-detail assertions are the dangerous ones: they look deletable. They are pinning a feature. Replace with an output-level assertion of the same feature; never drop.

Add the stronger check

Token matching cannot catch a dropped paragraph. Add rendered-text snapshots:

# before migrating
node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ > .agents/snapshots/models.txt
# after
node .agents/scripts/snapshot-route.mjs dist/models/index.html | diff .agents/snapshots/models.txt -

Commit the snapshots. They are the migration's regression net.

Extend audit-ui.mjs

It rejects external <script>/<link> but misses external URLs inside CSS — which is exactly how the broken Google Fonts @font-face in styles.css:1 got into a "dependency-free" site. Add:

if (/@import|src:\s*url\(['"]?https?:|url\(['"]?https?:/i.test(css))
  throw new Error(`${file} has an external CSS dependency`);