Skip to content
Open
12 changes: 11 additions & 1 deletion harness/pstack/claude-code/docs/guide/06-verify-and-ship.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 11 additions & 1 deletion pstack/docs/guide/06-verify-and-ship.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,17 @@ Apps change, and feature maps go out of date. Run this at least once a day, idea
/maintain-verification-skill
```

[`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. `clean` means full coverage and nothing to ship. `changed` means one PR of proven corrections, confined to the verification skill's own directory. `blocked` names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of hiding it with a doc edit.
[`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. `clean` means full coverage and nothing to ship. `changed` means proven corrections, confined to the verification skill's own directory. Standalone runs ship those corrections in one PR. `blocked` names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of hiding it with a doc edit.

If another workflow already owns delivery for the task, say so. Maintenance then hands its result back instead of opening a PR:

```text
/maintain-verification-skill
This task's workflow keeps delivery ownership. Return the corrections, coverage,
commands, results, and evidence to it. Don't commit or open a PR.
```

Maintenance still completes its source and live checks and preserves evidence after cleanup. Having another workflow installed does not change a standalone run.

## Prove a property with a formal verification skill

Expand Down
8 changes: 6 additions & 2 deletions pstack/skills/maintain-verification-skill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ A feature map rots the moment the app changes. This skill is the upkeep loop for
Pick one, and say which:

- **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.
- **changed** — proven doc, harness, or map corrections are ready for delivery through step 6.
- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.

## Edit scope
Expand All @@ -34,6 +34,10 @@ Only edit the verification skill's own directory (its SKILL.md, features/, and a

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.

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.
6. **Ship or hand back.** Re-read every changed file first. Then check the request for a named delivery owner: a statement from the user or the calling workflow that someone else owns delivery, commits, or publication for this task, such as "X owns delivery" or "don't open a PR".
- **Owner named: hand back.** Return the outcome, changed files, coverage and gaps, exact commands with observed results, and retained evidence paths to that owner. Make no commit, branch, or PR; the owner does that. A clean or blocked run still returns its report and evidence; say that no publication is needed, not that no handoff is needed.
- **No owner named: ship.** This is the normal case, including unattended runs; do not ask or wait for an owner. For changed, open one PR of proven corrections and report its link. For clean or blocked, open no PR and report the outcome and coverage honestly.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Claude Code · Anthropic · claude-fable-5-2 · medium * walkthrough

"Including unattended runs; do not ask or wait" is deliberate. Without it, one unattended standalone run fixed the drift and then stopped because nobody had named an owner.


An installed workflow alone names no owner. Until a PR exists the corrections are ready, not shipped.

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