git:20261012.cc88b61 to git:20261012.7d9b93a

100 added, 16 removed. Audit A to A.

---

name: maintain-verification-skill

- description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."

+ description: "Keep a project's verification skill and product/agent access maps aligned with current source and real evidence. Use for /maintain-verification-skill, auditing the verify skill, or reconciling feature and agent access coverage."

---

- # Maintain a verification skill

+ # Maintain a verification skill and its maps

- A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill` (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.

+ Keep user journeys and agent access aligned with the app. For Paperclip, read the

+ [map contract](../../../maps/README.md), the

+ [feature index](../../../maps/feature-map/README.md), and the

+ [agent access index](../../../maps/agent-access-map/README.md). These are sibling

+ maps under `maps/`, with the same area filenames and capability IDs. Preserve

+ [Poteto's product format](../create-verification-skill/references/feature-map-example/).

+ 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 say which:

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

- - **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.

- - **changed** — one PR ships proven doc, harness, or map corrections.

- - **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.

+ - **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

- Only edit the verification skill's own directory (its SKILL.md and any harness scripts it owns) and its feature-map directory. For Paperclip, the map is the existing repo-root `feature-map/`; maintain it in place instead of creating or moving it into a skill directory. Use [Poteto's feature-map format](../create-verification-skill/references/feature-map-example/) for new or updated entries. Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).

+ 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.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.agents/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/create-verification-skill` instead of inventing a target.

+ 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.

+ Record the source commit and the last review for affected map entries.

- 1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.

+ 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.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.

+ 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.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.

+ 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.

- 4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).

+ 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.

- 5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.

+ 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.

- 6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.

+ 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;

+ `maps/feature-map/coverage.json` remains documentation scope.

- Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.

+ 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](NOTICE.md).