maintain-verification-skill: cleanup granularity, re-doctor, evidence checks

[poteto]

Summary

Follow-up to #150: four bugbot comments posted 39s before the merge, all valid literal-reading interactions in the live-pass paragraph. One coherent tightening:

• Failed-drive cleanup happens at the granularity of what failed — a stuck per-drive session is killed; a shared long-lived instance is never torn down mid-pass.
• After a failed drive on a long-lived instance: re-run doctor before the next feature; relaunch only if doctor fails.
• The doctor-drift retry path now includes cleanup + relaunch before the retry.
• Every cleanup is followed by confirming captured evidence still exists (mirrors the generator's proof rule).

Replies with fix references going on the original #150 threads.

---

Note

Low Risk
Documentation-only change to the maintain-verification-skill procedure; no product or runtime code.

Overview
Live pass (step 4) in maintain-verification-skill is rewritten so coordinators follow three invariants for the whole run instead of a long procedural checklist.

Invariant 1 (health): Only drive after doctor — before the first drive, on each new session when sessions are the unit, and again after any failed drive; if doctor can’t see a wedged UI on a healthy process, reset or relaunch instead of continuing blindly.

Invariant 2 (evidence): After cleanup, confirm prior proof artifacts still exist at the paths the verification skill names (aligned with the generator’s evidence rule).

Invariant 3 (cleanup): Clear failed-drive residue without keeping junk past that drive’s usefulness; on a shared long-lived instance, clean residue only — don’t tear down the instance mid-pass.

Doctor failures from skill drift still get one in-scope fix and retry, with restart limited to what the fix invalidated before marking the pass blocked. Unreachable features, harness re-proofs, and final teardown behavior are unchanged in intent.

^{Reviewed by Cursor Bugbot for commit 6c352ab. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: Unhealthy relaunch omits cleanup
  • Both relaunch paths now clean up unhealthy instances while preserving healthy instances after doctor drift.
• ✅ Fixed: Failed drive leaves instance poisoned
  • Shared-instance failures now reset in-app state to a known baseline or clean up and relaunch when a safe reset is impossible.
• ✅ Fixed: Non-stuck failed drives skip cleanup
  • Per-drive failures now run the skill's cleanup even when the failed session already exited, followed by evidence verification.

Or push these changes by commenting:

@cursor push 1ba3a2e092

Preview (1ba3a2e092)

diff --git a/pstack/skills/maintain-verification-skill/SKILL.md b/pstack/skills/maintain-verification-skill/SKILL.md
--- a/pstack/skills/maintain-verification-skill/SKILL.md
+++ b/pstack/skills/maintain-verification-skill/SKILL.md
@@ -30,7 +30,7 @@
 
 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.
 
-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). Health-check at the skill's own granularity: doctor before driving a long-lived instance, and per session where sessions are the unit. Never drive past a failing doctor — but a doctor that fails because the *skill* drifted is itself drift: fix it under edit scope, then clean up, relaunch, and retry once before calling the pass `blocked`. Exercise every feature at least once. When a drive fails, clean up at the granularity of what failed: kill a stuck per-drive session; for a shared long-lived instance, don't tear it down mid-pass — re-run doctor instead, and only relaunch if doctor says the instance is no longer healthy. After any cleanup, confirm the evidence captured so far still exists at its named location before continuing (same rule as the generator's proof step). 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 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). Health-check at the skill's own granularity: doctor before driving a long-lived instance, and per session where sessions are the unit. Never drive past a failing doctor — but a doctor that fails because the *skill* drifted is itself drift: fix it under edit scope and re-run the corrected doctor. If it still reports an unhealthy instance, clean up, relaunch, and retry once before calling the pass `blocked`. Exercise every feature at least once. When a drive fails, clean up the failed iteration at the granularity of what failed: for a per-drive session, run the skill's cleanup even if the session already exited; for a shared long-lived instance, reset the failed drive's in-app state to a known baseline without tearing down a healthy instance, then re-run doctor. If the shared instance is unhealthy or cannot be safely reset, clean it up, relaunch, and re-run doctor. After any cleanup or reset, confirm the evidence captured so far still exists at its named location before continuing (same rule as the generator's proof step). 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).
 
 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.

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Per-session doctor check dropped
  • Restored explicit doctor checks for every isolated session when sessions are the launch unit.

Or push these changes by commenting:

@cursor push bdf97b7a5c

Preview (bdf97b7a5c)

diff --git a/pstack/skills/maintain-verification-skill/SKILL.md b/pstack/skills/maintain-verification-skill/SKILL.md
--- a/pstack/skills/maintain-verification-skill/SKILL.md
+++ b/pstack/skills/maintain-verification-skill/SKILL.md
@@ -30,7 +30,7 @@
 
 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.
 
-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 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 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 and per 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).
 
 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.

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit cdf5f0d. Configure here.}