Maintain a verification skill and its maps

Keep user journeys and agent access aligned with the app. For Paperclip, read the map contract, the feature index, and the agent access index. These are sibling maps under maps/, with the same area filenames and capability IDs. Preserve Poteto's product format. Agent companions follow the shared contract; they do not duplicate user recipes.

An API endpoint, an OpenAPI actor label, a declared scenario tool and an admitted production agent path are different evidence. Verify which permitted agent surface can actually express an operation. Track source review, operation review and executed proof separately. A source-only baseline is useful, but cannot certify complete coverage or live behavior.

Outcomes

Pick one and report source scope, live scope and remaining gaps separately:

• clean — the requested scope got source and live coverage, with no corrections.
• changed — proven skill/map/check corrections are ready to review; name any access gaps or unexecuted coverage that remains.
• blocked — requested coverage or a proven correction could not finish; name the unmet prerequisite and evidence captured so far.

A targeted audit covers its named areas; do not present it as a full pass. A full pass reads every area from source and exercises every reachable feature, plus relevant permitted-agent and denial paths. Report unreachable prerequisites and not-run operations rather than silently reducing the scope.

Edit scope

For Paperclip, edit the target verification skill, these maintenance instructions when needed, maps/, and the map-specific structural check scripts/check-maps.mjs / scripts/check-maps.test.mjs. Fix references to those maps in contributor docs or skill instructions when their locations/IDs change. Keep the maps in maps/{feature-map,agent-access-map}/, outside skill directories.

For other projects, maintain their existing verification skill and map locations; the Paperclip directory convention does not authorize relocating another repo. Never edit product APIs, permission enforcement, tool bindings or UI behavior in a maintenance run. Record product/access gaps for implementation separately; a permission denial is not authorization to widen access.

Pass

0. Locate the target and scope. Find the project-local verification skill (usually .agents/skills/verify-*/). Several candidates: ask which; none: point to /create-verification-skill. Honor a requested narrower audit. Use Git diff/history to identify affected sources. Record the source revision and review evidence in the PR or evidence report, not a shared map ledger.

1. Check both indexes. Pair same-named feature and agent files, then match stable sub-feature IDs. Fix orphan/missing entries and broken references. For Paperclip run node scripts/check-maps.mjs. This checks structure, not API authorization, real tool bindings or live behavior.

2. Source wave. Use read-only subagents per area, with each reader owning the feature file and its access companion; schedule within available slots. Readers never edit or drive the app. Each returns the user capability/source entry points, likely drift with citations, meaningful operations, their APIs, actor/grant/resource/run/mode boundaries, real agent entry points by surface, missing access/discovery/policy decisions, and a concise verification recipe. Follow recent changes to routes, contracts, authorization, native tool admission, CLI and MCP as well as UI. Inspect actual route/service policy; compare it with OpenAPI and production bindings, not only scenario catalogs.

3. Reconcile both maps. Spot-check cited drift and merge recipes into as few app states as practical. Every affected business operation needs an API and a permitted agent path, or an explicit gap. A dedicated tool is optional when existing API/CLI/MCP fallback suffices. Distinguish native/remote access from legacy REST and personal assistant OAuth. Record field/scope limits, unavailable clients, protocol requirements and native fallback restrictions. Keep justified local/developer/operator exceptions, but split shared data operations from presentation. A board-only route records a restriction and any existing request/result handoff; an unresolved delegation question stays visible. Split broad baselines into per-operation records before marking them operation-reviewed. Add newly discovered capabilities only with concrete source; add their companion at the same time. Each feature recipe carries its own navigation metadata. Discovery generates the feature and access indexes; do not register new areas in shared READMEs or commit generated output. Keep durable Storybook verification routes in the affected feature recipe.

4. Live pass. Required for a verification maintenance pass even if source looks clean. The coordinator owns serial driving, using the target skill's existing launch/doctor/evidence/cleanup workflow and Paperclip's existing API/runner/MCP fixtures. Exercise the real user path and the relevant actual agent path separately. For access checks use the permitted agent identity, run, mode and target; assert results and relevant denials. A board request or board test-as-agent does not replace agent-credential proof. Use disposable fixtures for mutation/denial tests and record simulated providers honestly. Never assume an optional client is admitted to a native run.

   Keep three invariants: health-check before driving and after surprises; verify captured evidence survives cleanup; clean up everything the drive owned once no longer needed. Reset a wedged UI even if process health passes. Follow the target skill's session model: one long-lived owned server/UI instance, or isolated short-lived CLI sessions. After a skill-induced failure, fix within edit scope and retry once, restarting only what was invalidated. Record missing auth/provider/environment prerequisites and attempted paths. Re-drive changed harness helpers before shipping them. Final teardown follows the last proof attempt and preserves evidence.

5. Triage and record. User description/recipe drift updates the product map; endpoint/path/permission/discovery drift updates its companion. Missing or broken product behavior stays a product gap, with evidence. Never rewrite a recipe or mark an access exception to bless a failure. Map evidence states remain source-only/not-run unless an actual proof supports the named operation and surface. Keep run artifacts/results in the evidence location or issue; the generated maps/generated/coverage.json is a page-reference inventory, not passing test evidence.

6. Review corrections. Re-read changed files, check paired IDs/references and run the smallest relevant validation. Report outcome and source/live coverage honestly. If shipping is requested or already authorized, update the existing task PR where appropriate, or create at most one PR of proven corrections. A clean pass needs no branch or PR. Do not implement access-policy changes merely to make the maintenance report green.

Keep concise run notes and proof artifacts in the target skill's named evidence location; do not commit ephemeral run logs as map content.

Origin and license: NOTICE.md.