maintain-verification

Audit VERIFY.md contracts and feature maps for stale tasks, paths, and coverage claims.

Updated Sep 5, 2026
One-click install
npx skills add https://github.com/douglasjarquin/sum --skill maintain-verification-douglasjarquin
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: maintain-verification
Source: https://github.com/douglasjarquin/sum/tree/main/.agents/skills/maintain-verification
Command: npx skills add https://github.com/douglasjarquin/sum --skill maintain-verification-douglasjarquin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Feature maps and verification contracts rot the moment application behavior changes, leaving stale task references, dead paths, broken links, and unproven coverage claims that nobody notices until a release breaks. ## Core Features & Use Cases - Static Verification Audit: Runs verify_audit.py to detect placeholders, stale mise tasks, stale paths, unlinked maps, duplicate scenario IDs, and unsupported automated coverage claims without executing any code. - Change-to-Map Reconciliation: With --base <merge-base>, matches changed source files against map references, flags unmapped changes, and records a --rationale for purely internal changes. - Proof Freshness Tracking: Compares the newest run record against current contract and map hashes, reporting proof as current, stale, or none, and writes a JSON audit record separating authored edits from run results. - Use Case: Before reporting a behavior-changing task, run the audit against the merge base to confirm the diff, feature IDs, tests, and map entries agree, then update only the affected map rows and cite the audit record in the PR. ## Quick Start Ask the agent to audit this repository's verification contract and feature maps against the merge base and report any stale tasks, paths, or unmapped changes.

Frequently Asked Questions about maintain-verification

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a repository's feature maps for stale references?

Run python3 .agents/skills/maintain-verification/scripts/verify_audit.py --base <merge-base> from the repository. It reads VERIFY.md and the linked maps, checks mise tasks, backticked paths, links, and coverage claims, and fails with findings until they are resolved.

How do I handle a code change that no feature map covers?

Either update the affected map's entry points, variants, expected states, and coverage, or record a rationale with --rationale explaining why the internal change needs no map row. Without one of these, the audit reports an unmapped-change finding.

Does the verification audit run tests or modify files?

No. The audit only reads text and Git state; it never edits a map, runs a check, or marks anything verified. Actual proof comes from separately running verify_run.py and capturing evidence for the driven rows.

What are the requirements to run verify_audit.py?

The script needs Git, mise, and Python 3.11 or newer for tomllib, plus a VERIFY.md with a ```verify TOML block at the repository root. It works in any clone without sum, Herdr, or paths outside the repository.

Why does the audit report proof as stale or none?

Proof is stale when VERIFY.md or a map changed after the newest run record, so that record no longer proves the current maps. Proof is none when no run record exists under the artifact directory, meaning the maps have never been exercised.