Prevent handoff with failed validation or PR checks

.patchmill/skills/brainstorming/scripts/start-server.sh

@@ -1,4 +1,4 @@
-#!/nix/store/zh1ijdhb6gng1509b1zrilb6xlzx60j6-bash-5.3p9/bin/bash
+#!/usr/bin/env bash
 # Start the brainstorm server and output connection info
 # Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
 #

.patchmill/skills/brainstorming/scripts/stop-server.sh

@@ -1,4 +1,4 @@
-#!/nix/store/zh1ijdhb6gng1509b1zrilb6xlzx60j6-bash-5.3p9/bin/bash
+#!/usr/bin/env bash
 # Stop the brainstorm server and clean up
 # Usage: stop-server.sh <session_dir>
 #

.patchmill/skills/landing/SKILL.md

@@ -36,11 +36,17 @@ safe and confirms the issue was closed:
 }
 ```
 
-For everything else, create or update a pull request and return `pr-created`
-final JSON. Prefer PR fallback for visual UI changes, migrations, large
-refactors, dependency updates, security-sensitive changes, and anything that
-needs human product, UX, or architecture review. Include a `landingDecision`
-that explains why human review is required:
+For everything else, create or update a pull request and follow the configured
+implementation skill's post-PR check readiness procedure. Do not return final
+`pr-created` JSON immediately after creating the PR. Wait for observable
+required checks; repair code-related test/lint/format/type-check/build failures
+through the configured worker loop; and return an operator blocker for
+cancelled, timed-out, infrastructure, permissions, quota, billing, or host
+service failures. Return `pr-created` only after required checks pass. Prefer PR
+fallback for visual UI changes, migrations, large refactors, dependency updates,
+security-sensitive changes, and anything that needs human product, UX, or
+architecture review. Include a `landingDecision` that explains why human review
+is required:
 
 ```json
 {

.patchmill/skills/patchmill-skill-pack.json

@@ -1,15 +1,15 @@
 {
   "pack": {
     "name": "patchmill-recommended",
-    "version": "2026.07.1",
+    "version": "2026.07.2",
     "source": {
       "type": "github-release",
       "repository": "obra/superpowers",
       "tag": "v6.0.3",
       "tarballUrl": "https://github.com/obra/superpowers/archive/refs/tags/v6.0.3.tar.gz"
     }
   },
-  "installedAt": "2026-07-17T15:49:12.965Z",
+  "installedAt": "2026-07-19T09:54:15.578Z",
   "skillDir": ".patchmill/skills",
   "metadataFile": "patchmill-skill-pack.json",
   "files": [
@@ -31,11 +31,11 @@
     },
     {
       "path": ".patchmill/skills/brainstorming/scripts/start-server.sh",
-      "sha256": "40684112a967c8a2afe4c1ea0662c2decfab4916407b3f20f29ae468ece6c7f3"
+      "sha256": "a4e5ae84275bcaacd2f84345afeabe59cf7b00ba080e123da7cc1fb226f12847"
     },
     {
       "path": ".patchmill/skills/brainstorming/scripts/stop-server.sh",
-      "sha256": "a9816fb097000f082ede8bd7b359a258d3fea7fbe2a6bfd9a399b9a1647358ee"
+      "sha256": "0b5ccbbd57f62d3ed88993f7940b5ee0e5c0fc9b21c550c623da4f6292e47daf"
     },
     {
       "path": ".patchmill/skills/brainstorming/spec-document-reviewer-prompt.md",
@@ -75,7 +75,7 @@
     },
     {
       "path": ".patchmill/skills/patchmill-visual-evidence/scripts/capture-visual-evidence.cjs",
-      "sha256": "0aa8dcdc1e8e7cc2af7a3490ce13fc26b0be7fdb27ec75785e65481ca193c55a"
+      "sha256": "ca8dbf9c16c6e4b8ac0069edc003aef19d4bc35e033de3f1e653d3d08cd17380"
     },
     {
       "path": ".patchmill/skills/receiving-code-review/SKILL.md",
@@ -91,20 +91,28 @@
     },
     {
       "path": ".patchmill/skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md",
-      "sha256": "9bd9e7576469c45ca4e96b0dfc0d675415fb3cdd0e8f1581b3da77c740e6ad24"
+      "sha256": "f86341c2285e8628cccac057283e948d2779433e71fe4ded1f3ade8f0536c748"
     },
     {
       "path": ".patchmill/skills/single-subagent-dev-with-codex-and-thermo-reviews/prompts/implement-plan.md",
       "sha256": "86d5a737650d9b3bcb929e6aacf14389d1dc2bd003f10559130b2ba8a6f51828"
     },
     {
       "path": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md",
-      "sha256": "dbc5087dd349cfe46d6a251370fb71462f5114d3965e39e834e6dd7d249912dd"
+      "sha256": "9a476033ae8f332500f4955e6e1dc4d464eb83b206733ee95dfdb519b6150a75"
     },
     {
       "path": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/prompts/final-review.md",
       "sha256": "8fc9f11c9a55dba64842e634ffc658c8c0fec00ec9896023987a7b05b3d78fdf"
     },
+    {
+      "path": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/prompts/final-validation-review.md",
+      "sha256": "1e1a8f5ede275d8684896361c3708a4295285f8d50f0570c06b0c54c9a2e41e2"
+    },
+    {
+      "path": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/prompts/fix-pr-checks.md",
+      "sha256": "2922c730896b7b46181dd266863cc33d03185059464456e92a01a7629e077a79"
+    },
     {
       "path": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/prompts/fix-review-findings.md",
       "sha256": "5fc263f3d353360bb59967f3e0b3f84bdc5b6aec819a3c6bd8e2cb786ffa856a"
@@ -117,6 +125,10 @@
       "path": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/rubrics/cursor-thermo-nuclear-code-quality-review.md",
       "sha256": "b9df382a7afe8d16418bb5a996e17d99c6095f39ccaefd6222eb9fcc824daabe"
     },
+    {
+      "path": ".patchmill/skills/subagent-dev-with-validation-and-pr-checks/SKILL.md",
+      "sha256": "e8c1412fb3928592ec0c268de980941a0e3fedf909e6c5ad095f0465c6fe816c"
+    },
     {
       "path": ".patchmill/skills/subagent-driven-development/SKILL.md",
       "sha256": "41ab239a6ad1c487cd839fdac972a8c9cf0f5e90efa59a63f963767864f0df4c"
@@ -127,15 +139,15 @@
     },
     {
       "path": ".patchmill/skills/subagent-driven-development/scripts/review-package",
-      "sha256": "45a8a9a83fe0819657def3420378874be1b31af9c9fcf85b210bf43cff23ba53"
+      "sha256": "0c0629f6e2c46fc8bf68dcfb8a247ab24eb548b7004fe494035e6fcba9b5cdfb"
     },
     {
       "path": ".patchmill/skills/subagent-driven-development/scripts/sdd-workspace",
-      "sha256": "157565e949c519c0153995a9d541c370a9b3468341dfa2143ec37fa41a5c89b6"
+      "sha256": "9430befaff459ed862415b700c1a9efe45fd34838a684802a1d8320de0c3a007"
     },
     {
       "path": ".patchmill/skills/subagent-driven-development/scripts/task-brief",
-      "sha256": "3f3a8f1c8cf031d903710731e9f1b621bd7ad418715bca079476463d77e16371"
+      "sha256": "5380283f00bffa99ab82ae78482b7d248abe10655129c72ca7050bdc0b6a85e1"
     },
     {
       "path": ".patchmill/skills/subagent-driven-development/task-reviewer-prompt.md",
@@ -163,7 +175,7 @@
     },
     {
       "path": ".patchmill/skills/systematic-debugging/find-polluter.sh",
-      "sha256": "29f8756a433415b6fb2153775b40e7dfc9ac8f7d06a134a4ad5fea269a8851e6"
+      "sha256": "6462747eae9b175ac145b78bcfaeab755654a75e32637f08eb633f065a9e1d7c"
     },
     {
       "path": ".patchmill/skills/systematic-debugging/root-cause-tracing.md",
@@ -259,7 +271,7 @@
     },
     {
       "path": ".patchmill/skills/writing-skills/render-graphs.js",
-      "sha256": "9522a06eaf880c7850b88772c2a3646a7d23e8c96d5498cda5d24440849835f2"
+      "sha256": "ccda971a87bb185f8febf81c56b556a20d026fa980c17b35fa3e8824fbb37852"
     },
     {
       "path": ".patchmill/skills/writing-skills/testing-skills-with-subagents.md",

.patchmill/skills/patchmill-visual-evidence/scripts/capture-visual-evidence.cjs

@@ -1,4 +1,4 @@
-#!/nix/store/zvj0hl7rhh0ccr5vkcg3ijs3xm3sgyac-nodejs-24.16.0/bin/node
+#!/usr/bin/env node
 const fs = require("node:fs");
 const path = require("node:path");
 const { execFileSync } = require("node:child_process");

.patchmill/skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md

@@ -9,22 +9,23 @@ description:
 # Patchmill Single Subagent Dev with Codex and Thermo Reviews
 
 Execute the entire approved implementation plan with one Pi `worker` subagent,
-then close the work with the same two mandatory full-worktree review loops used
-by Patchmill's stricter final-readiness skill: Codex first, thermo-nuclear
-second.
+then close the work with Codex, thermo-nuclear, and final validation-readiness
+review before landing.
 
 **Core principle:** one implementation subagent preserves plan-level continuity;
-final full-worktree reviews catch integration, regression, and structural issues
-before Patchmill lands or opens a PR.
+final full-worktree reviews and validation readiness catch integration,
+regression, structural, and known command failures before Patchmill lands or
+opens a PR.
 
 ## Required sub-skills and agents
 
 - **REQUIRED SUB-SKILL:** Use `superpowers:verification-before-completion`
   before claiming success.
 - Use Pi `subagent` with `worker` for the single initial implementation pass.
-- Use Pi `subagent` with the canonical `reviewer` agent for both final review
-  passes.
-- Use Pi `subagent` with `worker` to fix accepted final-review findings.
+- Use Pi `subagent` with the canonical `reviewer` agent for both final code
+  review passes and the final validation-readiness review.
+- Use Pi `subagent` with `worker` to fix accepted final-review findings, final
+  validation findings, and code-related failed PR checks.
 - Requires the sibling `../subagent-dev-with-codex-and-thermo-reviews/` skill
   directory for shared final-review prompts and rubrics. If those files are
   missing, stop and ask instead of recreating or substituting them.
@@ -157,15 +158,70 @@ landing:
 Do not use the thermo-nuclear pass as permission for broad unapproved rewrites.
 Escalate scope or architecture changes to the human first.
 
-### 7. Complete Patchmill handoff
+### 7. Run final validation-readiness review
 
-After both final review loops are closed:
+Only start this after the Codex and thermo-nuclear review loops are closed.
+Refresh base SHA, current HEAD, `git status --short`, plan/spec paths, required
+validation commands, and prior validation evidence.
 
-1. Run final verification commands.
-2. Summarize implementation commits, validation, Codex review result,
-   thermo-nuclear review result, and any deferred findings.
-3. Continue with the configured landing skill or Patchmill PR/direct-land
+Dispatch a fresh-context, review-only `reviewer` using
+`../subagent-dev-with-codex-and-thermo-reviews/prompts/final-validation-review.md`.
+The reviewer must run every feasible required final command and treat any
+repository-fixable non-zero result as an Important or Critical finding. Every
+base-to-head file is in scope, including materialized plan/spec files and files
+created by earlier workflow commits.
+
+Prior passing summaries are evidence only. They do not permit the reviewer to
+skip commands. Landing is blocked until the reviewer returns `pass` or
+`pass-with-deferred-minor-findings`.
+
+### 8. Fix final validation findings
+
+When the validation-readiness reviewer reports repository-fixable findings:
+
+1. Synthesize the accepted validation findings with exact commands, concise
+   output, and affected paths.
+2. Dispatch `worker` using the sibling
+   `../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-review-findings.md`
+   contract.
+3. Require focused fixes, appropriate validation, and a Conventional Commit.
+4. Refresh HEAD, worktree status, and validation evidence.
+5. Re-run the final validation-readiness review.
+
+If validation is blocked by external tooling, infrastructure, credentials, or
+operator action, return the existing blocked contract with evidence. Never
+classify a branch-added failing file as out of scope merely because the
+implementation worker did not edit it.
+
+### 9. Complete landing and verify PR checks
+
+After all three final review gates are closed:
+
+1. Summarize implementation commits, passing validation, Codex review, thermo
+   review, final validation-readiness review, and deferred findings.
+2. Continue with the configured landing skill or Patchmill PR/direct-land
    instructions.
+3. For direct landing, return `merged` only after the final validation-readiness
+   review passed.
+4. For PR fallback, create or update the pull request, then obtain its URL and
+   current head SHA before returning final JSON.
+5. Wait for all observable required PR checks using configured host tooling.
+6. If all required checks pass, return the normal `pr-created` final JSON with
+   only current passing validation evidence.
+7. If test, lint, formatting, type-check, or build checks fail, collect failed
+   check names, URLs, and failed-step logs. Dispatch `worker` using
+   `../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-pr-checks.md`,
+   then wait for replacement checks after its push.
+8. Allow at most two PR-check repair passes. If code-related checks still fail,
+   return the existing blocked contract with the remaining failures and links.
+9. Treat cancelled, timed-out, infrastructure, permissions, quota, billing, or
+   host-service failures as operator blockers. Do not dispatch a code-repair
+   worker for them.
+
+For GitHub, use `gh pr checks` and `gh run view --log-failed` or equivalent
+supported commands. For Forgejo/Gitea, use the configured `tea` or API tooling.
+If required checks cannot be observed, report that limitation rather than
+claiming the PR is ready.
 
 ## Supporting files
 
@@ -175,20 +231,27 @@ After both final review loops are closed:
   shared final reviewer subagent contract.
 - `../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-review-findings.md`
   — shared worker fix subagent contract.
+- `../subagent-dev-with-codex-and-thermo-reviews/prompts/final-validation-review.md`
+  — shared final validation-readiness reviewer contract.
+- `../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-pr-checks.md` —
+  shared worker contract for code-related failed PR checks.
 - `../subagent-dev-with-codex-and-thermo-reviews/rubrics/armin-codex-review-prompt.md`
   — shared Armin Ronacher adaptation of the Codex review prompt.
 - `../subagent-dev-with-codex-and-thermo-reviews/rubrics/cursor-thermo-nuclear-code-quality-review.md`
   — shared Cursor Team Kit thermo-nuclear code quality review rubric.
 
 ## Rationalization checks
 
-| Temptation                                                          | Reality                                                                |
-| ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| "This plan has many tasks, so I should use fresh workers per task." | Not in this skill. Use one initial worker for all plan tasks.          |
-| "Final reviews can replace validation."                             | No. Validate before final reviews, then review the validated worktree. |
-| "Codex and thermo are both code reviews, so one pass is enough."    | No. They are separate rubrics and separate loops.                      |
-| "A reviewer can fix a small issue while reviewing."                 | No. Final reviewers are review-only. Use worker fix passes.            |
-| "Thermo feedback permits broad cleanup."                            | No. Escalate unapproved scope or architecture changes first.           |
+| Temptation                                                          | Reality                                                                                                                          |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| "This plan has many tasks, so I should use fresh workers per task." | Not in this skill. Use one initial worker for all plan tasks.                                                                    |
+| "Final reviews can replace validation."                             | No. Validate before final reviews, then review the validated worktree.                                                           |
+| "Codex and thermo are both code reviews, so one pass is enough."    | No. They are separate rubrics and separate loops.                                                                                |
+| "A reviewer can fix a small issue while reviewing."                 | No. Final reviewers are review-only. Use worker fix passes.                                                                      |
+| "Thermo feedback permits broad cleanup."                            | No. Escalate unapproved scope or architecture changes first.                                                                     |
+| "The failing file was not edited by the implementation worker."     | Base-to-head scope includes every workflow commit and materialized artifact. Fix the required validation failure before landing. |
+| "The PR exists, so handoff is complete."                            | PR fallback is complete only after observable required checks pass or an operator blocker is reported.                           |
+| "Retry CI until it eventually passes."                              | Run no more than two code-repair passes; classify external failures instead of looping.                                          |
 
 ## Red flags
 
@@ -203,6 +266,11 @@ Never:
 - Skip re-review after accepted fixes.
 - Ignore uncommitted or untracked implementation changes.
 - Proceed to landing with unresolved Critical or Important findings.
+- Proceed to landing after a required validation command exits non-zero.
+- Dismiss branch-added plan/spec or workflow artifacts as unchanged.
+- Return `pr-created` before observable required checks finish.
+- Dispatch code workers for infrastructure or operator failures.
+- Run more than two PR-check repair passes.
 
 ## Dispatch shape reference
 
@@ -226,11 +294,31 @@ subagent({
 });
 ```
 
+Final validation uses fresh reviewer context:
+
+```typescript
+subagent({
+  agent: "reviewer",
+  context: "fresh",
+  task: "Use ../subagent-dev-with-codex-and-thermo-reviews/prompts/final-validation-review.md with the final scope and required commands below...",
+  output: false,
+});
+```
+
 Fix passes should use the normal implementation worker:
 
 ```typescript
 subagent({
   agent: "worker",
-  task: "Use ../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-review-findings.md for the accepted review findings below...",
+  task: "Use ../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-review-findings.md for accepted review or validation findings below...",
+});
+```
+
+PR-check repair uses the normal worker context:
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Use ../subagent-dev-with-codex-and-thermo-reviews/prompts/fix-pr-checks.md for failed check evidence below...",
 });
 ```