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

[0xquinto]

Why

maintain-verification-skill lets a pass end with "all features exercised" and nothing per feature to check, and lets a harness defect ride along as a footnote. Both happened on a real nine-feature map maintained with this skill four times in six days. The report is now a table the pass has to fill, and an open harness gap blocks the pass. A small structural lint for skills comes with it, because the authoring playbook asked for a validation step that nothing ran.

Scope

• pstack/skills/maintain-verification-skill/SKILL.md: the pass ends in a coverage table (feature, source, live, evidence, disposition) with closed vocabularies and derives clean, changed or blocked from it. Locate searches .claude/skills, .cursor/skills and .agents/skills by frontmatter name and features/README.md. A map check the verification skill ships runs before hand hygiene. Readers get paths, not contents, run on the swarm workers model, and return the prerequisites their recipe needs. The live pass runs on the runtime the repo pins, uses a recipe driver when one ships, and reruns the map check and doctor after the last edit. Run notes route to a show-me-your-work log. Em dashes and arrows in the body go from 16 to 0.
• pstack/skills/poteto-mode/scripts/lint-skills.py: frontmatter has name and description, the slugified name matches the directory, relative links and backticked paths under the skill resolve, bold principle-* references name a skill. Dashes and arrows are counted, never blocking. --self-test plants six defects and requires each to be caught.
• pstack/skills/poteto-mode/playbooks/authoring-a-skill.md: step 2 points at the lint.

Blast Radius

Only agents that invoke /maintain-verification-skill or read the authoring playbook. No runtime code, no plugin manifest change. The lint is opt-in and reports 47 skills clean on this branch.

Verification

• python3 pstack/skills/poteto-mode/scripts/lint-skills.py --self-test: 6 planted defects caught, 3 clean fixtures pass.
• python3 pstack/skills/poteto-mode/scripts/lint-skills.py pstack/skills: 47 skills clean.
• The skill text ran a full maintenance pass on a private nine-feature verification skill: nine parallel readers, all nine features driven live, seven map files corrected, one harness defect fixed and re-driven, outcome changed with the table in the PR body.

---

Note

Low Risk
Documentation and agent-skill workflow only; no product runtime or CI wiring unless teams opt into running the lint script.

Overview
maintain-verification-skill no longer allows vague “all features exercised” wrap-ups. The pass must produce a per-feature coverage table (source, live, evidence, disposition) with fixed column vocabularies, and clean / changed / blocked are derived from that table—e.g. an open harness-gap or missing live result forces blocked, not a PR footnote. The workflow is expanded into seven explicit steps: broader skill discovery under .claude / .cursor / .agents, optional map-check before hygiene, source readers on the swarm workers model with prerequisite reporting for unreachable, pinned-runtime live driving with doctor/evidence/cleanup invariants, and post-edit map check + doctor before shipping. Run notes move to an uncommitted .audit/maintain-<skill>.tsv log.

Skill authoring now validates via new pstack/skills/poteto-mode/scripts/lint-skills.py: frontmatter name/description, slug match to directory, resolvable links and backticked paths under the skill, and principle-* skill references; dash/arrow counts are informational (--dashes). The authoring-a-skill playbook’s step 2 points at this script instead of a manual checklist.

^{Reviewed by Cursor Bugbot for commit f4588ce. 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 1 potential issue.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

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