feat(ship): project-local /ship adaptation — checklist + runbook (closes #155)#159
Merged
Conversation
Implements issue #155 — project-local /ship adaptation. Two new files: - .claude/skills/review/checklist.md — atomic-agents-shaped Pre-Landing Review checklist drawn from CLAUDE.md §"Design principles". Two-pass severity (CRITICAL: Backend Protocol Invariants, Cost Gate Placement, Audit Trail Shape, Atomic Write Discipline, LLM Output Trust Boundary, Schema/API Break Detection; INFORMATIONAL: Spec/Impl Drift, Public Surface Hygiene, Markdown-Config Aesthetic, Progressive Disclosure, Deprecation Shim Freshness, Test Conformance, CHANGELOG Hygiene, Documentation Match-to-Reality, One-Level Constraints, Concurrency, LLM Prompt Issues). Severity + confidence calibration matches gstack format. Honest about semantic-not-mechanical categories (tune confidence to 5-7 unless verified by reading source). - docs/deployment/release-runbook.md — release runbook documenting the two-mode /ship workflow (PR-level update vs. release cut), the prerequisite local gstack /ship template patch + reapply procedure after gstack-upgrade, Step 9.1 anticipated specialist false-positive patterns, Codex-rate-limited reviewer roster fallbacks, and the load-bearing Operator Manual Surface Check Before Merge section covering what /document-release misses on this project (PR #157's 21 doc-sync gaps incident cited verbatim as the historical why). Pairs with the local-only gstack template patch on the fix/ship-no-version-fallback branch in ~/.claude/skills/gstack/ that adds Step 9 missing-checklist fallback + Step 12 NO_VERSION_FILE mode + Step 13 mode dispatch + Step 19 mode-aware PR title prefix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per docs/deployment/versioning.md "Per-PR expectations" — every PR adds its own bullet under [Unreleased]. Bullet describes the project-local review checklist + release runbook landed in the previous commit, plus the paired local gstack template patch (NO_VERSION_FILE mode + missing- checklist fallback) living on the fix/ship-no-version-fallback branch in ~/.claude/skills/gstack/. Closes #155. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds discoverability for `docs/deployment/release-runbook.md` (new in this PR) — README's Deployment shapes list now includes it as the seventh operator runbook, and CLAUDE.md's "Where things live" table gets a row pointing at it. The bundled `/document-release` discoverability rule caught the gap: every doc file should be reachable from README or CLAUDE.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
CI's uv sync was missing --extra openai, so the OpenAI-compatible + Moonshot backend tests added in v0.13.0 fail with `openai SDK not installed; required for 'openai' backend`. 26 failures + 46 errors per matrix entry; main has been red since the v0.13.0 backend commits landed (e.g., eff6825 feat(llm): OpenAI + Moonshot backends; PR #157 v0.13.0 release merged red). Local uv run pytest passes because dev .venv has openai installed. CI's pip install -e . does not pull the extra. Fix is one line: add --extra openai to the workflow's uv sync invocation. Surfaced by /ship Step 17/19 on PR #159 (this PR). Per feedback_always_ship.md, "Pre-existing without receipts is a lazy claim" — receipts: PR #157 + last 3 commits on main all show pytest FAILURE on both 3.11 and 3.12; first failure traces to the OpenAI backend additions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #155. Project-local
/shipadaptation so the skill runs end-to-end on this project's tag+CHANGELOG release model. Three commits:feat(ship): project-local review checklist + release runbook(ed6c3d3) — adds the two new files that resolve the issue's first and third acceptance bullets:.claude/skills/review/checklist.md— atomic-agents-shaped Pre-Landing Review checklist drawn from CLAUDE.md §"Design principles". Two-pass severity, confidence calibration matching gstack format, honest about semantic-vs-mechanical categories.docs/deployment/release-runbook.md— two-mode workflow (PR-level update vs. release cut), prerequisite gstack patch + reapply procedure, anticipated Step 9.1 specialist false-positives, Codex-rate-limited reviewer-roster fallback, and the load-bearing Operator Manual Surface Check Before Merge section covering what/document-releasemisses (PR v0.13.0 release: LLMBackend protocol + arc closure + methodology drift recovery #157's 21 doc-sync gaps incident cited as the historical why).chore(changelog): note project-local /ship adaptation under [Unreleased](d9abf30) — perdocs/deployment/versioning.md"Per-PR expectations" — every PR adds its own bullet under[Unreleased].docs: link new release-runbook from README + CLAUDE.md(cba7ad6) —/document-releasesubagent dispatch in Step 18 caught two real doc-sync gaps: README's "six operator runbooks" claim (would have gone stale) and CLAUDE.md "Where things live" table (missing the new runbook row). Auto-fixed inline.Paired local gstack patch (NOT in this PR)
A separate, local-only patch lives on the
fix/ship-no-version-fallbackbranch in~/.claude/skills/gstack/:.claude/skills/review/checklist.mdis missing (warn-and-continue rather than STOP).NO_VERSION_FILEprobe + dispatch (PR-level update vs. release cut) for projects without a VERSION file. Uses anawkstate machine to extractCHANGELOG_VERSIONwhile skipping fenced code-block examples (caught by Opus adversarial review —grep -m1was picking up0.2.0from a### BREAKINGexample).SHIP_MODE(PR-level validates[Unreleased]has bullets and stops on empty; release-cut promotes[Unreleased]to a dated header).v<NEW_VERSION>mandate). This PR title is the first dogfood of PR-level mode.The runbook in this PR documents the reapply procedure after
gstack-upgrade. The patch is filed for upstream consideration as a separate design-discussion issue atgarrytan/gstack, not blocking this PR.Test Coverage
No new application code paths.
uv run pytestshows 928 passed in 40.50s — unchanged from main. Coverage audit (Step 7) skipped per workflow rule for docs-only diffs.Pre-Landing Review
Two rounds of Opus adversarial review per
docs/methodology.md§"Reviewer roster" (Codex rate-limited):/document-release, (c) wrong gstack patch target. All resolved in the revised plan.NO_VERSION_FILEawareness, (c) Step 19 forcing nonsensicalv<X.Y.Z>PR title prefix in PR-level mode. All resolved on the gstack feature branch in additional commits (791f04b fix(ship): address Opus adversarial-review findings)./document-releasecoverage clarification, specialist-pattern reframe as speculative).Step 9 of
/shipitself re-applied the now-landed project-local checklist against this diff: Pre-Landing Review: No issues found (the diff is pure markdown docs/config; load-bearing categories all N/A for this PR's surface).Documentation
Doc-sync sweep alongside this PR's new artifacts:
docs/deployment/release-runbook.mdto the Deployment shapes list (now seven operator runbooks, not six).docs/deployment/release-runbook.mdrow to the §"Where things live" table so the new runbook is one-hop reachable from the canonical entry-point doc.Verified surfaces that did NOT need updates (per the runbook's own operator manual surface check):
atomic_agents/__init__.py__version__still0.13.0;__all__unchanged (no new public symbols this PR).pyproject.tomlversionstill0.13.0; matches CHANGELOG's latest dated header.What's shippedtable + version badge + §Status — no change.Acceptance criteria (issue #155)
/shipruns end-to-end on this project with no hard-failure step — confirmed by this PR's invocation.docs/deployment/versioning.mdis the source of truth for the project's versioning (no VERSION file) — runbook cross-links to it; no VERSION file added./shipfallback when no checklist is present — both delivered (project-local file in this PR + built-in fallback on the gstack branch)./document-releaseequivalent for this project (or document the manual sync responsibility in the release runbook) — runbook's "Operator Manual Surface Check Before Merge" section covers the surfaces the subagent misses, with a per-surface checklist.Follow-ups (filed inline, tracked, not blocking)
garrytan/gstackproposing platform-agnostic versioning (no-VERSION-file mode) per their own "Platform-agnostic design" ethos. Local gstack branch is reference. (Tracking in this repo as a follow-up; will file after this PR lands so the runbook can link to the upstream issue.)Test plan
uv run pytest— 928 passed, 0 failed (Step 5)/shipStep 12NO_VERSION_FILEprobe returnsCHANGELOG_VERSION: 0.13.0(not0.2.0from the fenced code-block example — awk fix working)/shipStep 13 PR-level mode validates[Unreleased]has 2 lines of content; does not promote header/shipStep 19 PR-level mode does NOT prefix title withv0.13.0(this PR title is the proof)bun test test/skill-validation.test.ts test/gen-skill-docs.test.ts— 707 passed, 0 failed (after each gstack edit)🤖 Generated with Claude Code