pstack: maintain-verification-skill ends in a coverage table; add lint-skills.py

pstack/skills/maintain-verification-skill/SKILL.md

@@ -1,39 +1,58 @@
 ---
 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: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, a coverage table as the report, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."
 disable-model-invocation: true
 ---
 
 # Maintain a verification skill
 
-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.
+A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill`, or for any project-local verification skill with a feature map. The unit of rigor is the feature. Cover every feature file from source, drive every feature live, and report both in one table. Not every bullet needs its own drive.
 
 ## Outcomes
 
-Pick one, and say which:
+The pass ends in exactly one outcome. The coverage table decides which one, not your impression of the run.
 
-- **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.
+- **blocked.** A feature has no `live` result, a `disposition` says `harness-gap open`, or a proven fix could not ship. Say what blocked it and which features it affects. No PR.
+- **changed.** The verification skill's directory has a diff of proven corrections. One PR.
+- **clean.** Every feature has source and live coverage and the skill's directory has no diff. No branch, no PR.
+
+Product gaps never change the outcome. They are the app's problem and go under the table.
 
 ## Edit scope
 
-Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). 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).
+Edit only the verification skill's own directory: its `SKILL.md`, `features/`, and any helper scripts it owns. Never edit product code during a run. A behavior the map describes that the app no longer does is either doc drift, which you fix in the map, or a product regression, which you report. Do not paper a regression over in the docs.
+
+## The pass
+
+1. **Locate the target.** An argument to the skill names it. Otherwise search `.claude/skills`, `.cursor/skills`, and `.agents/skills` for a directory whose `SKILL.md` frontmatter `name` starts with `verify-` and that has `features/README.md`. One match is the target. Several matches, ask which. No match, stop and point at `/create-verification-skill`. Never invent a target.
+
+2. **Check the map mechanically.** If the skill ships a structural check of its own map (a `map-check` or `check-map` helper named in its body), run it first and fix what it reports. If it ships none, hand-check the README against its sibling files for missing, extra, duplicate, or dead entries, and treat the missing check as a harness gap worth one small helper. No generated inventory.
+
+3. **Source wave.** Launch one read-only subagent per feature file, all at once, on the `swarm workers` model. Give each the path of its feature file and the path of the skill's `SKILL.md`, not their contents. Each answers "how does this user-facing feature work?" from source, flags likely doc drift with `file:line` citations, and returns one live-verification recipe. Readers never drive the app and never edit files. Return shape: feature summary, source entry points, drift with citations or `none`, one recipe, and the prerequisites the recipe needs (runtime version, installed deps, fixtures, secrets by name, network, external services). The prerequisites are what let you report a feature as `unreachable` with its concrete cause.
+
+4. **Reconcile.** Every feature file has a returned summary before you continue. Merge overlapping recipes into as few app states as practical. Spot-check cited drift. Do not re-prove clean claims. Sweep recent churn (`git log` since the skill's last commit) for user-facing surfaces missing from the map. Name a concrete source path before calling a feature missing.
+
+5. **Live pass.** Required even when source looks clean. You drive. Readers never do. Follow the verification skill's own Launch section for the instance model. Servers and UIs get one long-lived instance driven serially. Short-lived CLIs get a fresh isolated session per drive. Run on the runtime the repo pins (`engines`, the CI image), not whatever the shell has. When the skill ships a helper that drives its recipes and asserts their observables, run it and drive by hand only what it cannot reach. When it ships none and the map is stable, one such helper is the cheapest harness fix you can make. Drive every feature at least once. Hold three invariants for the whole pass, whatever fails:
+   - **Doctor before you drive.** Run the skill's doctor before the first drive, on each fresh session where sessions are the unit, and after any failed drive. When doctor cannot see the failure (a wedged UI on a healthy process), reset to a known state or relaunch. Never hope. An instance the doctor will not own is foreign. Do not drive it.
+   - **Evidence survives every cleanup.** After each cleanup, check the evidence at its named location. Do not assume.
+   - **Nothing a drive started outlives its usefulness.** Clean failed-iteration residue whether the session is stuck, exited, or shared. For a shared instance, clean the residue, not the instance.
 
-## Pass
+   A doctor failure caused by skill drift is drift. Fix it under edit scope, restart only what the fix invalidated, and retry once before calling the pass blocked. A feature you cannot reach is `unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route you tried. A prerequisite the map omits is drift. Re-drive every harness fix live before it ships. Tear down after the last drive of the run, re-drives included. Evidence stays.
 
-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 `.cursor/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/create-verification-skill` instead of inventing a target.
+6. **Triage.** Every anomaly gets a row and one disposition. A wrong or missing user-POV description is doc drift. Fix it. Working behavior the harness cannot drive is a harness gap. Fix it. Helper rules are the same as at generation, scripts executable and their invocation shown in the skill body. A harness gap you leave open makes the pass blocked, not a footnote in the PR. App behavior that is broken is a product gap. Report it with the command and the observed result, and keep it out of the PR.
 
-1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
+7. **Report and ship.** Write the coverage table below and derive the outcome from it. For changed, re-read every changed file, run the map check and the doctor once more after the last edit (an edit to the skill can break its own checks), then open one PR whose body carries the table. For clean or blocked, open no PR. Reply with the table and the outcome either way.
 
-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.
+## The coverage table
 
-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.
+One row per feature file. Closed vocabularies per column. The table is the proof. A sentence like "all features exercised" is not.
 
-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).
+| feature | source | live | evidence | disposition |
+|---|---|---|---|---|
+| the feature file | `clean`, or `drift: <one line>` | `pass`, `fail: <one line>`, or `unreachable: <prerequisite>, <route tried>` | path of the captured proof | `none`, `doc-drift fixed`, `harness-gap fixed`, `harness-gap open`, or `product-gap reported` |
 
-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.
+Under the table, list each product gap as command, expected, observed, and give the map check's final result.
 
-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.
+## Run notes
 
-Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.
+Keep the run's decisions in a show-me-your-work log at `.audit/maintain-<skill>.tsv`, one row per drive and per triage call. Do not commit it.

pstack/skills/poteto-mode/playbooks/authoring-a-skill.md

@@ -3,7 +3,7 @@
 **You own the skill's voice.**
 
 1. Use the **create-skill** skill (Cursor's built-in for authoring SKILL.md files).
-2. Validate the skill: frontmatter has `name` and `description`, referenced files exist, cross-skill links resolve.
+2. Validate the skill with `scripts/lint-skills.py <skill-dir>` (in the poteto-mode skill): frontmatter has `name` and `description`, `name` matches the directory, referenced files exist, principle references resolve. `--dashes` counts the dashes and arrows unslop bans.
 3. Test cases if structural. Skip if subjective.
 4. Run **Opening a PR**.