Publish Release Pr

---
name: publish-release-pr
description: 'Use when a human runs /publish-release-pr to ship a versioned, redaction-gated PR with evidence. Not for tag-and-push releases — use release-gate.'
disable-model-invocation: true
---

# Publish release PR

## Contract

| Field | Bound contract |
|---|---|
| Trigger | The user runs /publish-release-pr on a branch. |
| Authority | Human-only. The model executes read-only verification steps directly. Every commit, tag, push, and PR creation is proposed and waits for explicit human confirmation before it runs. No remote or irreversible mutation happens without it. |
| Side effect | Versioned commits, a tag, and a redaction-gated PR carrying a complete evidence body, published to the remote. |
| Done | A versioned PR exists on the remote with its complete evidence body. |

## Refusals

- Remote or irreversible mutation without explicit human confirmation: rejected. Every commit, tag, push, and PR creation waits for confirmation.
- In-branch test failures: stop. The developer must fix their own broken tests before shipping.
- Redaction HIGH finding in the PR body or title: block (exit 3). Rotate the credential and redact before creating or editing the PR; no skip.
- Running workflow-owned steps by hand: rejected when the request touches steps owned by the CI/CD workflow, deployment pipeline, or publishing platform.

## Inputs

- A current git branch with changes to ship. The base branch is auto-detected from the remote default; supply it explicitly only when detection is ambiguous.
- Optional: a plan file in the repo. When present, its completion is audited and reported in the PR body.
- Optional: an existing open PR for the branch. When present, its body is regenerated from this run's fresh results and its Greptile comments are addressed.

## Procedure

1. Detect the base branch and probe mergeability. Identify the base branch from the remote default. Fetch `origin/<base>` and run a read-only conflict probe: `git merge-tree --write-tree HEAD origin/<base>` exits zero with a tree hash when the merge is clean, or non-zero with conflict hunks when the branches have diverged. When a PR already exists, `gh pr view --json mergeStateStatus` gives the same answer over the API. Do not merge here — the actual merge waits for the step-11 confirmation gate so no history mutation happens during verification. On conflict hunks, stop and show them. **Done when**: mergeability is probed and the result (clean or conflicted) is reported, or complex conflicts are shown.
2. Run the test suites under an evidence ledger. Read the project's documented test command first; otherwise detect the runtime from marker files and offer the matching runner, never installing a second framework beside a working one. Run each suite through a transparent wrapper that records `{command, exit, working-tree fingerprint, log path}` per lane. Cite that record later instead of re-running when the content has not changed. **Done when**: every test lane has a record in the evidence ledger.
3. Triage every test failure by ownership. For each failing test, classify it against the branch diff: in-branch if the failing test file or the code it exercises was changed on this branch; pre-existing if neither was touched and the failure is unrelated. When ambiguous, default to in-branch. Stop on in-branch failures. For pre-existing failures, present the choice (fix now, log a P0 TODO, blame-and-assign, or skip) and act on the answer; a chosen fix is committed separately. **Done when**: every failure is classified and in-branch failures are stopped or pre-existing failures are resolved.
4. Audit test coverage of the diff. Trace every changed codepath and user flow, diagram each branch and error path, and mark gaps with a quality score. Count test files before and after. Apply the regression rule: when the diff broke previously-working behavior, write a regression test immediately. Run the coverage gate against the project's configured minimum and target (defaults 60% / 80%); below target, offer to generate more tests (max two passes); below minimum, require an explicit override. Embed the coverage diagram in the PR body. **Done when**: the coverage audit is complete with diagram and gate verdict.
5. Audit plan completion and scope drift. When a plan file is present, extract every actionable item, verify each against the diff (DONE / PARTIAL / NOT DONE / CHANGED / UNVERIFIABLE, with cross-repo and external-state items confirmed per-item by the human, never blanket-confirmed), and report completion, deferred items, and any scope drift. When no plan file exists, report that. **Done when**: plan completion is audited or its absence is reported.
6. Run the pre-landing review. Engineering review is the only review that gates shipping: it must be clean (or globally skipped) within 7 days, else this step runs its own review with a critical pass (SQL and data safety, LLM output trust boundary) and an informational pass, each finding carrying a confidence score and a quoted motivating line. Always run the adversarial review on every diff: a Claude adversarial pass plus a Codex adversarial challenge; diffs over 200 lines also get a Codex structured review whose `[P1]` markers gate (FAIL asks to fix now, PASS continues). For frontend changes, run the lite design check. Surface CEO and design reviews as informational only; they never block. **Done when**: the engineering review is clean or globally skipped, and the adversarial review is complete.
7. Address Greptile comments when a PR already exists. Fetch the PR's Greptile review comments. For each, fix the issue (tag FIXED), mark it a false positive with evidence (tag FALSE POSITIVE), or note it was already fixed with the fixing commit SHA (tag ALREADY FIXED); suppressed known-false-positives are skipped silently. If any fix was applied, re-run the tests before continuing. Omit the Greptile section entirely when no PR existed yet. **Done when**: every Greptile comment is dispositioned or the section is omitted.
8. Classify version state and bump. Classify the version state against the base: FRESH does the bump; ALREADY_BUMPED skips the bump but runs a queue-drift check and, if the queue moved, asks whether to rebump or keep current; DRIFT_STALE_PKG repairs the manifest to match VERSION; DRIFT_UNEXPECTED stops for manual reconciliation. Decide the bump level from the diff (MICRO under 50 trivial lines, PATCH 50+ with no feature signal, MINOR on a feature signal or 500+ lines, MAJOR on milestones or breaking changes). Pick the slot queue-aware so it does not collide with a sibling workspace; on collision, ask whether to advance past or abort and sync. Write VERSION, the manifest, and existing npm lockfiles (4-digit sort keys). **Done when**: the version is bumped or the state is classified and acted on.
9. Write the CHANGELOG. Enumerate every commit on the branch and read the full diff. Group commits by theme and write one unified entry under `## [X.Y.Z.W] - YYYY-MM-DD` with Added / Changed / Fixed / Removed sections. Cross-check: every commit must map to at least one bullet. Lead each bullet with what the user can now do. Do not ask the user to describe changes. **Done when**: the CHANGELOG entry is written with every commit mapped to a bullet.
10. Update TODOS.md. Cross-reference the project's TODOS.md against the diff and move completed items to the Completed section with the version and date. Create or reorganize the file only with human confirmation. A TODOS failure never stops the ship. **Done when**: TODOS.md is updated or the failure is noted without blocking.
11. **Preview the ship and confirm before commit and tag.** Present a consolidated preview: the branch, the base-merge plan from step 1 (merge `origin/<base>` with `--no-edit` when the probe reported divergence), the new version, the CHANGELOG entry, the planned commit list, the tag name, and the intended `v<NEW_VERSION>` PR title. Wait for explicit human confirmation before creating any commit or tag; if the user amends anything, return to the affected step with the edit applied. **Done when**: the preview is presented and explicit confirmation to commit and tag is recorded, or the ship stops.
12. **Commit in bisectable chunks.** After the recorded confirmation, merge `origin/<base>` with `--no-edit` when step 1 reported divergence (auto-resolve only simple conflicts: VERSION, schema, CHANGELOG ordering; on complex conflicts, stop and show them). Group the diff into logical, independently-valid commits ordered infrastructure, then models and services, then controllers and views, each grouped with its tests. The final commit holds VERSION, CHANGELOG, and TODOS.md and carries the version tag. Squash WIP checkpoint commits into their logical commit first; never blind `git reset --soft` when non-WIP commits are present. **Done when**: after the recorded confirmation, the diff is committed in bisectable chunks with the version tag on the final commit.
13. **Run the verification gate.** Check the evidence ledger before any completion claim: every test lane must have a fresh record (within 24h) whose command and working-tree fingerprint match, allowing only the metadata paths (CHANGELOG, VERSION, manifest, digest). No fresh evidence, no done claim. **Done when**: every test lane has a fresh matching record.
14. **Push the branch.** Propose the push and wait for human confirmation. Push the branch to the remote. **Done when**: the branch is pushed after human confirmation.
15. **Sync documentation.** Dispatch the documentation-sync step in a fresh context; it updates docs with CHANGELOG clobber protection and risky-change gates, commits, pushes, and returns a documentation section for the PR body. On subagent failure, proceed without the section; do not block the ship. **Done when**: the documentation sync is dispatched and its section is returned or the failure is noted.
16. **Create the redaction-gated PR.** Compose the PR body from this run's fresh results: Summary, Test Coverage, Pre-Landing Review, Design Review, Eval Results, Greptile Review, Scope Drift, Plan Completion, Linked Spec, Verification Results, TODOS, Documentation, and a checked Test plan. The PR title must start with `v<NEW_VERSION>`. Write the body to a temp file and scan it at the sink with the redaction engine before sending: a HIGH credential finding blocks (exit 3, no skip, rotate and redact first); MEDIUM findings require per-finding confirmation, sterner on a public repo. **Done when**: the PR is created with a redaction-gated body or a HIGH finding blocks.
## Failure and recovery

- In-branch test failure: stop. The developer fixes their own broken tests before shipping; do not proceed.
- Complex merge conflict: stop and show the conflicts; do not auto-resolve ambiguous hunks.
- DRIFT_UNEXPECTED version state: stop for manual reconciliation; a manual edit bypassed the pipeline.
- Redaction HIGH finding in the PR body or title: block (exit 3). Rotate the credential and redact before creating or editing the PR; no skip.
- Subagent failure (coverage audit, documentation sync, plan completion): fall back to running the step inline or proceed without its section; partial results are better than none. Never block the ship on a subagent failure. A plan-completion audit that cannot run is surfaced explicitly, never silently passed.
- Verification gate without fresh evidence: no done claim. Re-run the affected lane to produce a fresh record.
- Partial-result rule: every step that completes leaves its evidence in the ledger or PR body; a later step that fails does not erase earlier evidence. Rollback is non-mutation: stop before the next irreversible step rather than undoing a published commit or tag. Never swallow an error or pretend the done predicate holds. The blocked result names the failing step, the verbatim error, and the exact human action that unblocks it.

## Output

A versioned PR on the remote whose body carries the complete evidence body (summary of every substantive commit, test results and coverage diagram, pre-landing and adversarial review findings, Greptile comment disposition, scope drift and plan completion, verification results, TODOS state, and documentation sync), with VERSION and CHANGELOG bumped.