v1.60.2.0 feat: add complete ship handoffs

AGENTS.md

@@ -43,7 +43,7 @@ Invoke them by name (e.g., `/office-hours`).
 
 | Skill | What it does |
 |-------|-------------|
-| `/ship` | Run tests, review, push, open PR. Workspace-aware version queue. |
+| `/ship` | Run tests, review, push, open PR, and return a full engineering handoff plus concise Why / What / How. UI changes require matched Before/After proof before push. Workspace-aware version queue. |
 | `/land-and-deploy` | Merge the PR, wait for CI and deploy, verify production health. |
 | `/canary` | Post-deploy monitoring loop using the browse daemon. |
 | `/landing-report` | Read-only dashboard for the workspace-aware ship queue. |

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [1.60.2.0] - 2026-07-19
+
+## **Every `/ship` now ends with a complete engineering handoff and a plain-language answer.**
+## **UI changes cannot be pushed without faithful before/after evidence.**
+
+`/ship` previously optimized the mechanics of landing code but left its final user-facing report underspecified. A successful run could end at a PR URL, omit important engineering context, or describe a UI change without proving what visually changed. This release makes the completion contract explicit across supported hosts.
+
+### What this means for builders
+
+Every ship attempt now reports the outcome, root cause, decisions, implementation, verification, operational risk, remaining work, and any decision required. The literal final section is an extremely concise **Why / What / How** explanation. User-visible UI changes additionally require matched Before/After screenshots from faithful base and current states before the push; missing evidence blocks the ship instead of becoming a waivable footnote.
+
+### Itemized changes
+
+#### Changed
+
+- `ship/SKILL.md.tmpl`: adds the mandatory full engineering handoff, makes `### Put simply` the final response section, and moves UI screenshot evidence into the pre-push verification gate.
+- Generated Claude, Codex, and Factory ship skills and golden fixtures carry the same completion contract.
+- The UI evidence contract pins provenance, route/state/data/viewport/theme/zoom parity, safe test data, inline artifact paths, and a hard stop before push or PR creation when a faithful comparison is impossible.
+
+#### For contributors
+
+- `test/ship-completion-report.test.ts` regression-locks every required heading, ordering, UI gate, screenshot contract, and final plain-language section across the template and three host variants.
+- `test/skill-llm-eval.test.ts` adds both an instruction-quality judge and a three-scenario behavior eval covering non-UI success, complete UI evidence, and blocked incomplete UI evidence.
+- Ship coverage/touchfile routing now selects the deterministic and LLM completion tests. Focused verification: 505 passed, 27 evals skipped without API credentials, 0 failed; a manual authenticated Sonnet behavior run passed all three scenarios.
+
 ## [1.60.1.0] - 2026-07-09
 
 ## **The /autoplan dual-voice eval is back on the board, catching real regressions.**

README.md

@@ -163,7 +163,10 @@ You:    /qa https://staging.myapp.com
         [opens real browser, clicks through flows, finds and fixes a bug]
 
 You:    /ship
+Claude: [full engineering handoff: outcome, root cause, decisions,
+         implementation, verification, risk, remaining work, next decision]
         Tests: 42 → 51 (+9 new). PR: github.com/you/app/pull/42
+        Put simply: Why / What / How
 ```
 
 You said "daily briefing app." The agent said "you're building a chief of staff AI" — because it listened to your pain, not your feature request. Eight commands, end to end. That is not a copilot. That is a team.
@@ -194,7 +197,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/qa-only` | **QA Reporter** | Same methodology as /qa but report only. Pure bug report without code changes. |
 | `/pair-agent` | **Multi-Agent Coordinator** | Share your browser with any AI agent. One command, one paste, connected. Works with OpenClaw, Hermes, Codex, Cursor, or anything that can curl. Each agent gets its own tab. Auto-launches headed mode so you watch everything. Auto-starts ngrok tunnel for remote agents. Scoped tokens, tab isolation, rate limiting, activity attribution. |
 | `/cso` | **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 17 false positive exclusions, 8/10+ confidence gate, independent finding verification. Each finding includes a concrete exploit scenario. |
-| `/ship` | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. |
+| `/ship` | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR, then return a full engineering handoff plus concise Why / What / How. UI changes require matched Before/After proof before push. |
 | `/land-and-deploy` | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." |
 | `/canary` | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. |
 | `/benchmark` | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. |

VERSION

@@ -1 +1 @@
-1.60.1.0
+1.60.2.0

docs/skills.md

@@ -19,7 +19,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
 | [`/qa-only`](#qa) | **QA Reporter** | Same methodology as /qa but report only. Use when you want a pure bug report without code changes. |
 | [`/scrape`](#scrape) | **Browser Data Extractor** | Pull data from a web page. First call prototypes via `$B`; subsequent calls on a matching intent run a codified browser-skill in ~200ms. |
 | [`/skillify`](#skillify) | **Skill Codifier** | Walks back through your conversation, finds the last `/scrape` prototype, synthesizes script + test + fixture, runs the test, asks before committing. |
-| [`/ship`](#ship) | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. One command. |
+| [`/ship`](#ship) | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR, then return a full engineering handoff plus concise Why / What / How. UI changes require matched Before/After proof before push. |
 | [`/land-and-deploy`](#land-and-deploy) | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." |
 | [`/canary`](#canary) | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures using the browse daemon. |
 | [`/benchmark`](#benchmark) | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. Track trends over time. |
@@ -657,6 +657,12 @@ Every `/ship` run builds a code path map from your diff, searches for correspond
 
 `/ship` checks the [Review Readiness Dashboard](#review-readiness-dashboard) before creating the PR. If the Eng Review is missing, it asks — but won't block you. Decisions are saved per-branch so you're never re-asked.
 
+### Engineering handoff and UI proof
+
+Every `/ship` attempt ends with the same complete report, whether it succeeds or stops: outcome, root cause, decisions, implementation, verification, operational risk, remaining work, and any decision you need to make. The last section compresses the result into an extremely concise **Why / What / How**.
+
+For a user-visible UI change, `/ship` captures matched **Before** and **After** screenshots from faithful base and current states before push. Route, app state, data, viewport, theme, and zoom must match. If the comparison cannot be produced safely and faithfully, `/ship` stops before pushing or creating the PR instead of waiving the evidence.
+
 A lot of branches die when the interesting work is done and only the boring release work is left. Humans procrastinate that part. AI should not.
 
 ---

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.60.1.0",
+  "version": "1.60.2.0",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",

ship/SKILL.md

@@ -843,7 +843,7 @@ branch name wherever the instructions say "the base branch" or `<default>`.
 
 # Ship: Fully Automated Ship Workflow
 
-You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and output the PR URL at the end.
+You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and include the PR URL in the final engineering handoff.
 
 **Only stop for:**
 - On the base branch (abort)
@@ -1246,7 +1246,11 @@ Before pushing, re-verify if code changed during Steps 4-6:
 
 2. **Build verification:** If the project has a build step, run it. Paste output.
 
-3. **Rationalization prevention:**
+3. **UI evidence gate:** For a user-visible UI diff, produce the matched
+   Before/After evidence from Step 22 before push. If unavailable, STOP; do not
+   push or create/update the PR/MR.
+
+4. **Rationalization prevention:**
    - "Should work now" → RUN IT.
    - "I'm confident" → Confidence is not evidence.
    - "I already tested earlier" → Code changed since then. Test again.
@@ -1415,3 +1419,64 @@ through `gstack-version-bump`; never hand-roll the VERSION/package.json write.
 - **Never push without fresh verification evidence.** If code changed after Step 5 tests, re-run before pushing.
 - **Step 7 generates coverage tests.** They must pass before committing. Never commit failing tests.
 - **The goal is: user says `/ship`, next thing they see is the review + PR URL + auto-synced docs.**
+
+---
+
+## Step 22: Full engineering handoff
+
+End every ship attempt with this report, even when stopped. Use each heading;
+write `Not applicable` briefly when a category does not apply.
+
+```markdown
+## Engineering summary
+
+### Outcome
+What shipped (version, branch, commit, PR/MR URL), or what blocked it.
+
+### Problem and root cause
+What was wrong or missing, why, and the supporting evidence.
+
+### Investigation and decisions
+Key findings, alternatives, decisions, and why this approach won.
+
+### Implementation
+Changed behavior, components, data paths, APIs, migrations, infrastructure, and docs.
+
+### Verification
+Fresh test/build/typecheck/lint/behavior/review/CI/deploy evidence; mark pass/fail/skipped.
+
+### Risks and operational impact
+Tradeoffs, compatibility, rollout/migration, observability, rollback.
+
+### Remaining work
+Unfinished work. Write `None` when the completion contract is fully satisfied.
+
+### Decision required
+The user's next decision. Write `None` when no decision is required.
+```
+
+### UI before/after evidence
+
+For user-visible UI changes, include matched **Before** and **After** screenshots:
+
+1. Use a pre-change capture only if it faithfully represents the base; otherwise run the merge-base/base revision in an isolated worktree or use its known deployment.
+2. Capture the current branch after implementation and verification.
+3. Match route, application state, data, viewport, theme, and zoom. Use safe test data; never expose credentials, customer data, or private information.
+4. Show `![Before](path)` and `![After](path)` inline; include both artifact paths.
+5. Do not commit screenshot artifacts unless the repository explicitly requires it.
+
+If a faithful comparison is impossible, use the same report with Outcome blocked,
+mark UI evidence incomplete, and STOP before Step 17. Do not push, create/update
+the PR/MR, claim UI completion, or offer a waiver.
+
+### Put simply
+
+Final response section; nothing follows. Be intuitive, extremely concise, precise:
+
+```markdown
+### Put simply
+
+- **Why:** The problem this solves.
+- **What:** What is now different for the user or system.
+- **How:** The essential mechanism, without unnecessary implementation detail.
+```

ship/SKILL.md.tmpl

@@ -34,7 +34,7 @@ triggers:
 
 # Ship: Fully Automated Ship Workflow
 
-You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and output the PR URL at the end.
+You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and include the PR URL in the final engineering handoff.
 
 **Only stop for:**
 - On the base branch (abort)
@@ -367,7 +367,11 @@ Before pushing, re-verify if code changed during Steps 4-6:
 
 2. **Build verification:** If the project has a build step, run it. Paste output.
 
-3. **Rationalization prevention:**
+3. **UI evidence gate:** For a user-visible UI diff, produce the matched
+   Before/After evidence from Step 22 before push. If unavailable, STOP; do not
+   push or create/update the PR/MR.
+
+4. **Rationalization prevention:**
    - "Should work now" → RUN IT.
    - "I'm confident" → Confidence is not evidence.
    - "I already tested earlier" → Code changed since then. Test again.
@@ -535,3 +539,64 @@ through `gstack-version-bump`; never hand-roll the VERSION/package.json write.
 - **Never push without fresh verification evidence.** If code changed after Step 5 tests, re-run before pushing.
 - **Step 7 generates coverage tests.** They must pass before committing. Never commit failing tests.
 - **The goal is: user says `/ship`, next thing they see is the review + PR URL + auto-synced docs.**
+
+---
+
+## Step 22: Full engineering handoff
+
+End every ship attempt with this report, even when stopped. Use each heading;
+write `Not applicable` briefly when a category does not apply.
+
+```markdown
+## Engineering summary
+
+### Outcome
+What shipped (version, branch, commit, PR/MR URL), or what blocked it.
+
+### Problem and root cause
+What was wrong or missing, why, and the supporting evidence.
+
+### Investigation and decisions
+Key findings, alternatives, decisions, and why this approach won.
+
+### Implementation
+Changed behavior, components, data paths, APIs, migrations, infrastructure, and docs.
+
+### Verification
+Fresh test/build/typecheck/lint/behavior/review/CI/deploy evidence; mark pass/fail/skipped.
+
+### Risks and operational impact
+Tradeoffs, compatibility, rollout/migration, observability, rollback.
+
+### Remaining work
+Unfinished work. Write `None` when the completion contract is fully satisfied.
+
+### Decision required
+The user's next decision. Write `None` when no decision is required.
+```
+
+### UI before/after evidence
+
+For user-visible UI changes, include matched **Before** and **After** screenshots:
+
+1. Use a pre-change capture only if it faithfully represents the base; otherwise run the merge-base/base revision in an isolated worktree or use its known deployment.
+2. Capture the current branch after implementation and verification.
+3. Match route, application state, data, viewport, theme, and zoom. Use safe test data; never expose credentials, customer data, or private information.
+4. Show `![Before](path)` and `![After](path)` inline; include both artifact paths.
+5. Do not commit screenshot artifacts unless the repository explicitly requires it.
+
+If a faithful comparison is impossible, use the same report with Outcome blocked,
+mark UI evidence incomplete, and STOP before Step 17. Do not push, create/update
+the PR/MR, claim UI completion, or offer a waiver.
+
+### Put simply
+
+Final response section; nothing follows. Be intuitive, extremely concise, precise:
+
+```markdown
+### Put simply
+
+- **Why:** The problem this solves.
+- **What:** What is now different for the user or system.
+- **How:** The essential mechanism, without unnecessary implementation detail.
+```

test/fixtures/golden/claude-ship-SKILL.md

@@ -843,7 +843,7 @@ branch name wherever the instructions say "the base branch" or `<default>`.
 
 # Ship: Fully Automated Ship Workflow
 
-You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and output the PR URL at the end.
+You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and include the PR URL in the final engineering handoff.
 
 **Only stop for:**
 - On the base branch (abort)
@@ -1246,7 +1246,11 @@ Before pushing, re-verify if code changed during Steps 4-6:
 
 2. **Build verification:** If the project has a build step, run it. Paste output.
 
-3. **Rationalization prevention:**
+3. **UI evidence gate:** For a user-visible UI diff, produce the matched
+   Before/After evidence from Step 22 before push. If unavailable, STOP; do not
+   push or create/update the PR/MR.
+
+4. **Rationalization prevention:**
    - "Should work now" → RUN IT.
    - "I'm confident" → Confidence is not evidence.
    - "I already tested earlier" → Code changed since then. Test again.
@@ -1415,3 +1419,64 @@ through `gstack-version-bump`; never hand-roll the VERSION/package.json write.
 - **Never push without fresh verification evidence.** If code changed after Step 5 tests, re-run before pushing.
 - **Step 7 generates coverage tests.** They must pass before committing. Never commit failing tests.
 - **The goal is: user says `/ship`, next thing they see is the review + PR URL + auto-synced docs.**
+
+---
+
+## Step 22: Full engineering handoff
+
+End every ship attempt with this report, even when stopped. Use each heading;
+write `Not applicable` briefly when a category does not apply.
+
+```markdown
+## Engineering summary
+
+### Outcome
+What shipped (version, branch, commit, PR/MR URL), or what blocked it.
+
+### Problem and root cause
+What was wrong or missing, why, and the supporting evidence.
+
+### Investigation and decisions
+Key findings, alternatives, decisions, and why this approach won.
+
+### Implementation
+Changed behavior, components, data paths, APIs, migrations, infrastructure, and docs.
+
+### Verification
+Fresh test/build/typecheck/lint/behavior/review/CI/deploy evidence; mark pass/fail/skipped.
+
+### Risks and operational impact
+Tradeoffs, compatibility, rollout/migration, observability, rollback.
+
+### Remaining work
+Unfinished work. Write `None` when the completion contract is fully satisfied.
+
+### Decision required
+The user's next decision. Write `None` when no decision is required.
+```
+
+### UI before/after evidence
+
+For user-visible UI changes, include matched **Before** and **After** screenshots:
+
+1. Use a pre-change capture only if it faithfully represents the base; otherwise run the merge-base/base revision in an isolated worktree or use its known deployment.
+2. Capture the current branch after implementation and verification.
+3. Match route, application state, data, viewport, theme, and zoom. Use safe test data; never expose credentials, customer data, or private information.
+4. Show `![Before](path)` and `![After](path)` inline; include both artifact paths.
+5. Do not commit screenshot artifacts unless the repository explicitly requires it.
+
+If a faithful comparison is impossible, use the same report with Outcome blocked,
+mark UI evidence incomplete, and STOP before Step 17. Do not push, create/update
+the PR/MR, claim UI completion, or offer a waiver.
+
+### Put simply
+
+Final response section; nothing follows. Be intuitive, extremely concise, precise:
+
+```markdown
+### Put simply
+
+- **Why:** The problem this solves.
+- **What:** What is now different for the user or system.
+- **How:** The essential mechanism, without unnecessary implementation detail.
+```