Maintain a project verification guide

Use this when

A project already has an agent verification guide and a feature map, and you need to check that the guide still matches the current app.

This runbook maintains the verification guide and its owned feature map or harness. It does not authorize changes to product behavior.

Outcome

Finish with one clear result:

• Clean: Every mapped feature was checked against source and exercised live. No correction is needed.
• Changed: Proven corrections to the verification guide, feature map, or its harness are ready to hand off.
• Blocked: Full coverage or a safe correction could not be completed. State exactly what prevented it and what remains unverified.

Steps

1. Locate the verification guide

Find the project-local guide that explains how to launch and drive the app and links to a feature map. If there are several plausible guides, ask which one to maintain. If none exists, stop and use Create a project verification guide instead of inventing a target.

Read the guide, feature-map index, each feature entry, and the harness scripts owned by that guide. Keep edits within those files. Do not edit product code; if observed app behavior is broken, report it separately as a product issue.

2. Check the feature map

Compare the feature-map index with its sibling feature files. Correct missing, extra, duplicate, or dead entries. Keep this inventory lightweight; do not generate a separate inventory system.

3. Check source coverage

For every feature entry, inspect the relevant source and report:

• What the user-facing feature does and the source locations that implement it.
• Any likely mismatch between the app and the guide.
• One concrete live-verification path for the feature.

When parallel agents are available, delegate one read-only source review per feature. Those reviewers do not drive the app or edit files. The coordinating agent gathers every result, checks cited mismatches, merges overlapping live paths, and owns all app interaction. If parallel review is unavailable, perform the source reviews one at a time.

Also inspect recent changes for user-facing features missing from the map. Add a feature only when you can point to a concrete source path that proves it exists. Do not recheck source claims that have not changed and have no evidence of drift.

4. Exercise every feature live

Run the verification guide’s own launch and session instructions. A source review alone is not enough. Exercise every feature in the map at least once, using the real user path and the named harness. Capture evidence at the location specified by the guide.

Maintain these safeguards throughout the pass:

• Before the first drive, health-check the instance with the guide’s read-only doctor step. Repeat the check after a failed drive and for each fresh session when sessions are isolated. If the interface is wedged but the process check passes, reset to a known state or relaunch before continuing.
• Preserve evidence from completed drives through every cleanup. Check the artifacts at their named locations; do not assume they survived.
• Clean up residue from every drive, including failed attempts. Stop only processes started by this run. For a shared instance, remove only this run’s residue and leave the shared instance running.

If the guide’s doctor check fails because the guide itself has drifted, correct that guide or its owned harness, restart only what the correction invalidated, and retry once before marking the run blocked. Re-drive a feature after any harness fix that affects it.

If a feature cannot be reached, report it as unreachable only after recording the prerequisite that prevented access and the route you attempted. Check whether the feature map already documents that prerequisite; if it does not, correct the map. Do not mark the feature as verified.

5. Triage what you found

• Guide drift: The app works, but the user-facing description, steps, prerequisites, or feature map are wrong or missing. Correct the verification materials.
• Harness gap: The user path works, but the guide’s harness cannot drive or observe it. Fix the guide-owned harness, document its invocation, and verify the affected feature again.
• Product issue: The app itself behaves incorrectly. Record the steps and evidence for the user; keep product code changes out of this maintenance pass.

6. Clean up and report

After the final drive and any re-verification, tear down the instances this run started. Confirm evidence remains available. Keep concise run notes in a scratch location and do not commit those notes.

Report the outcome as clean, changed, or blocked. Name the features covered, any unreachable prerequisites, confirmed drift, changes made, evidence locations, and remaining gaps. For changed work, re-read every changed file. If the project uses pull requests, keep corrections in one focused PR; otherwise hand off the verified change set. Clean and blocked outcomes do not need a PR.

Done when

• Every feature-map entry was checked against source and exercised live, or an exact prerequisite and attempted route are recorded for each unreachable feature.
• The feature index and its files agree, and any newly discovered feature has a concrete source path.
• Guide or harness drift is corrected and re-verified; product issues are reported without changing product code.
• Evidence survives cleanup, and no process or scratch state from the run remains unintentionally active.
• The clean, changed, or blocked outcome and any remaining coverage gaps are reported accurately.