shipper_reset

shipper_reset

Reset eligible packaged work to preserving Rework, including repeat Rework resets, or use existing backward targets and failed same-stage recovery. Required-check failures retain evidence and unpublished work through renewal; checks remain required. Requires an explicit stage. Supports dry-run preview mode and refuses fresh issue locks.

When to use

Publication failures and reset scope

A terminal publication report is written only after an attempted Git push remains unsuccessful under the existing retry policy. An observed nonzero pre-push hook status establishes local pre-push rejection. A Git rejection naming the attempted destination establishes remote rejection; GitHub is named only when the repository/destination evidence supports that attribution. Affirmative transport evidence establishes transport failure. Otherwise the cause is unavailable. Executor failure or capacity denial alone does not establish transport or hook rejection. Preparation, PR-service, teardown, and local-only failures remain separate. A failed publication does not establish missing or invalid agent output or invent a failing check.

The report captures independently available source branch, checkout path, full commit ID, and observation time immediately before the terminal attempt. Its approximate plain reachable-commit count compares the tip with the locally available destination remote-tracking ref. Only proven local absence selects the labelled configured-base fallback. A failed comparison leaves the count/ref/fallback unavailable with separate reasons. These diagnostic reads perform no remote lookup, fetch, staleness analysis, topology assessment, or uncommitted-file inventory.

The combined raw excerpt, including omission markers, is limited to 4096 UTF-8 bytes without splitting characters. Metadata, full paths, tips, and unavailable reasons sit outside that limit. Publication evidence files are under ~/.shipper/logs/ and show their actual path plus complete, incomplete, or unavailable status. An available path alone does not imply complete evidence. Agent/session logs are separately labelled and are not the publication evidence log.

Destructive reset discovers exactly the selected/invoking checkout plus the existing named managed clone. Local lineage repositories have only their selected checkout. Missing managed clones are not created or refreshed, and arbitrary clones are not searched. Checkouts sharing a canonical Git common directory are one branch set with their aliases displayed; separate clones with identical branch names remain distinct plans. Existing branch-recognition tiers are unchanged.

Before deletion, the preview shows each branch’s owning checkout, full tip or tip-unavailable reason, delete/retain/skip disposition, aliases, and discovery limitations. Normal main/user/linked checkouts holding a recognized branch are protected and retained; eligible issue worktrees are removed before branch deletion. Unknown identity, eligibility, or safety is skipped with a reason and reported as incomplete discovery. An unavailable tip alone does not prohibit an otherwise eligible deletion. CLI force skips confirmation only and still prints this preview. MCP dry-run is read-only; direct confirmed execution displays the same captured scan before its outcomes and preserves existing confirm_discard semantics. Desktop confirmation consumes its displayed plan; a missing or consumed preview requires a fresh preview.

Operations identify their owning checkout and distinguish successful deletion, intentional retention, already-absent/missing skips, and failed discovery or cleanup. Safe cleanup continues in other known locations after failures; scan, prune, deletion, or required-holder removal failures prevent full-success wording and the final success transition. PR/remote cleanup remains once per issue under existing guards. A later reset invocation rescans for retry. There is no added local tip/identity/safety re-verification between a captured preview and deletion; existing operation-level reclamation and PR guards still apply.

New validated publication-failure comment groups and captured run-history diagnosis survive reset as historical evidence. A reset, later transition, or newer different failure makes the older report historical rather than restoring current Failed state. Older Agent Failure headings are not inferred or rewritten. Preserving Rework keeps its existing eligibility, token, package, branch, and history behavior with empty destructive plans. These observations and best-effort cleanup provide no new retention or recovery guarantee.

Continuation lookup uncertainty stops the stage before preparation or agent launch, records ordinary Failed state when available, and returns nonzero. Diagnostics identify the issue, stage, and underlying history, state, or ref problem and say “continuation could not be determined.” Repair that problem, then explicitly run shipper recover S#123 before retry. Repair alone or restart does not clear persisted Failed. Ordinary Reset, including Rework and --force, is refused while this failure is active. Continuation-lookup recovery takes precedence over grooming and packaged recovery and restores the original raw workflow label (including PR Open or Ready), branch, evidence, route, and associations without renewing the review allowance. If failure state could not be recorded, explicit Recover verifies the unchanged stage and branch context read-only and acknowledges a definitive lookup without writing a reset event. Uncertainty still refuses recovery. Confirmed non-applicability permits ordinary execution without broadening eligibility. When applicable work was recorded but its branch is confirmed absent, run output states exactly: “S# : preserved work was recorded on , but that branch was not found.” This notice makes no claim of loss or safety. There is no automatic repair or new flag. New automatic check stops apply only to independently acquired hosted checks. Hosted-check external obstruction and unchanged-revision stalled remediation enter Failed over Rework while retaining useful fixes, package/branch/PR identity, answers, evidence and delivery debt. Obstruction requires concrete evidence, cause, external remedy and final-HEAD applicability after same-pass fixes; red status, main-branch match or missing tools alone are insufficient. The mechanical backstop requires a completed current V4 check-only review with retained answers and identical fresh failures on unchanged HEAD after refresh/rerun/flake opportunities. Nits are neutral; changed/passed/new/material/pending/unavailable evidence and request-changes bodies veto it. Sandbox limitations remain ordinary investigation. A skipped review consumes no allowance and each stop counts once toward terminal safety. No report, answer, resolution or retry waives required checks or permits red ship/merge. Remedy/restart alone stays Failed. Preserving shipper reset S#123 --to rework and eligible shipper recover S#123 renew allowance on unchanged HEAD, preserve unpublished work and history, and require fresh normal verification. Existing eligibility, locks, closure holds and confirmation rules apply. Missing/divergent retained refs refuse retry. Read current or historical diagnosis, local procedures and pending delivery with issue view/get-issue, including roundless failures. Local verification uses existing prose summaries and relevant comments, without a structured local evidence report. Every attempted non-permission local failure, including apparently unrelated or pre-existing failures, requires an anchored 🔴 must-fix: comment on the most relevant changed line and REQUEST_CHANGES, then ordinary Rework fixes or prose replies. Permission-denied and unattempted checks are limitations, never passes or waivers; all previously required checks stay required. Local-only workflows have no local-evidence automatic stop; the ordinary review-round cap still applies. Historical local observations and failure records remain readable without migration. Outstanding historical local findings receive ordinary prose replies and never authorize a new automatic stop. Upgrade alone does not clear findings, renew allowance, or recover Failed. Publication and hook diagnostics and required hook execution remain unchanged. Design, Plan, Implement, Review, Rework, and Ready name next work. Designed simple issues next Implement; complex or undecided issues next Plan. Packaged work next Review in either PR mode. Ready means ready for final integration, not shipped. New stays separate; held and failed are excluded (hold wins), while blocked, locked, paused, and running retain membership. CLI/MCP retain six next-step groups; desktop has five columns, with Implement combining Implement and Rework for the same population and attention exclusions. Current nextStep and nextStepPipeline are additive; completed-stage pipeline fields, labels, filters, commands, reset arguments, and historical records retain their meanings. Maintained label descriptions automatically refresh during next normal setup or maintenance, without separate initialization; successful cache skips repeats and force refresh reads again. Read-only status makes no label writes. Reset wording leads with the next step and completed-stage target. Design drops target groomed and clear route; Plan drops target designed for complex or undecided and refuse simple without changing route; Implement drops prefer preserving rework when offered by existing reset eligibility, otherwise designed for simple, planned otherwise. The authoritative package preview can refuse confirmation without destructive fallback. Deliberate Start over is in the card Reset menu with cleanup confirmation. Review and Ready reject drops; non-failed same-column drops do nothing, including Rework in Implement. The current-state Rework badge disappears on return to Review; other bounces receive no badge. Plan column differs from —to planned, whose next step is Implement. Existing backward eligibility, failed retry, preserving Rework, active restrictions, confirmations, work-loss warnings, and preservation guarantees apply. Rework is the recommended preserving reset from PR Open, Ready, or Rework, and from a failed issue without a stage. It requires an open linked PR under GitHub PR policy or a reachable pinned local change under no-PR policy. Legacy reviewed labels normalize to PR Open for this check. All routes retain their route; early stages do not qualify merely because they hold a package. Missing, closed, merged, or unverifiable evidence refuses the reset without changes; inspect or repair the association with shipper issue reconcile --repair, or recover the local package first. Rework preserves the package, association, branches, worktrees, route and review history, and clears failure. Repeat Rework resets are real operations. Next, Ship, and auto-ship dispatch Rework to implementation, which freezes one situation: a current held-round pin selects review rework; otherwise a newer roundless merge-conflict entry selects merge rework; every other case is a roundless continuation of the retained packaged change with no correction delta, new reset instruction, accepted plan, or accepted design. Review rework requires one nonblank fix or reasoned won’t-fix disposition for each outstanding local finding and supplied unresolved external thread, durably delivers successes, and applies configured best-effort resolution. An unreadable pin or incomplete dispositions after one correction fail without advancing. Merge rework requires no review replies. All situations reuse the preserved branch and open pull request without changing its metadata. Every successful explicit packaged preserving reset and eligible active packaged-change recovery restarts the five-round review allowance, including repeated Rework resets, unchanged revisions, and exhausted allowances. Package identity, full review history, findings, dispositions, and Rework context are preserved; renewal resolves no findings and grants no approval. Eligibility, destinations, and independent retry limits are unchanged. Count completed approved, addressed, superseded, and zero-finding reviews since the latest established renewal in append order; attempts without a completed review consume nothing. The first five completed reviews may reject into Rework; a sixth rejection enters durable Failed over Rework and retains its round, while a sixth approval may advance under existing approval rules. Automatic transitions and rejections, ordinary retries, restart/resume, grooming recovery, superseded-branch restoration, refused actions, and cancellation do not renew. Renewal belongs to the local logical commit even when projection repair is pending; repair grants no second renewal. A committed pending action reports its operation ID and says not to repeat it: store access finishes the existing operation. Recovery uses Recovery committed; local recovery pending for this outcome. For pre-release retained packages, affirmative historical preserving reset or packaged-recovery evidence, including recorded Rework operator-reset history, establishes the latest renewal. Without such evidence the existing full count remains. Upgrade alone leaves Failed intact. Current-allowance progress can be 0 of 5 or 6 of 5; historical round numbers and order never change and may exceed six. Replacement package identities start independently. Every successful Rework reset records operator-reset; automatic review rejection records review-reject and pins its newly retained current-package round, while merge conflicts use merge-conflict. Rejections supersede only older unaddressed, unsuperseded current-package rounds and count every completed matching round since the latest renewal toward the current five-round allowance; an addressed zero-finding round still counts. A sixth rejection enters durable Failed over Rework with its round pinned. Recover by retaining Rework and that retained pin, never by returning to Design. Replacement packages start a fresh count. Manual reset selects the newest eligible round, while a later roundless entry takes precedence, and never invents rejection. PR identity and the durable local package UUID scope retrieval. History survives restart. Before commitment, failures leave prior state unchanged. After commitment, Reset committed; local recovery pending means store access finishes the journal operation; do not repeat reset. These entries publish no GitHub reviews or comments and add no history screen. For targets other than Rework, use this destructive fallback when an issue must move backward to an earlier workflow stage, or to the current stage only when a failed issue still carries that stage label. Prefer shipper_recover when a saved question session, preserved groom output, or packaged work remains recoverable. Prefer dry-run first. Reset-to-New separately discloses preserved grooming output and saved question sessions with their answered-round counts, then discards them only after the local transition commits. Reset also warns before discarding a pinned local change or closing an open pull request. Use confirm_discard: true as the sole MCP acknowledgement for discarding a question session, grooming output, pinned local change, or open pull request. Reset stages are route-aware: simple routes offer Rework, Designed, Groomed, and New; complex and undecided routes additionally offer Planned. Rework is the recommended branch-preserving choice for packaged changes. The stored route is cleared back to undecided exactly when Design will re-run — at the groomed and new stages — while designed, planned, and rework preserve it, including an escalated simple-to-complex route; that clearing writes its own route history entry. Deleting a remote branch that reset already selected for cleanup skips Git’s pre-push hook, so pre-push verification never begins for that deletion and no verification record is created for it; a verification record always means a hook actually started, so its absence here is expected. That exception covers reset cleanup deletion only — branch creation, branch updates, and branch deletion outside reset keep their existing pre-push verification, and no reusable verification-skipping capability is exposed. While this mutation is awaiting cleanup transport, every read-only MCP tool remains available: locally answerable reads, including reads of the issue being reset, return a coherent durable snapshot, and externally backed reads still pay their own dependency latency. Repository switching is fail-fast: it never waits for active work or queues a later state change. Issue locks still exclude another mutation on the same issue. See the Architecture concept page for the full durable-snapshot semantics.

Behavior hints

• destructiveHint: true — The tool can remove or rewrite workflow artifacts and should be used carefully.
• openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	integer | string	yes	-	Shipper issue reference. S# (GitHub #) accepts ordinary surrounding whitespace and requires the current mirror. Bare numbers are Shipper local IDs first; S# is accepted; gh: and # explicitly target a mapped GitHub issue; GitHub issue URLs are accepted. Responses return S# first with GitHub # second when mapped.
stage	enum: new, groomed, designed, planned, rework	yes	-	Use rework for confirmed preserving packaged-work reset from PR Open, Ready, Rework, or failed without a stage. Alias-normalized legacy work receives the same protection.
dry_run	boolean	no	-	When true, preview preservation or cleanup without making changes.
preview_token	string	no	-	Return the Rework dry-run token unchanged on execution. A stale token refuses reset; direct execution creates its own current preview. Rework does not require confirm_discard.
confirm_discard	boolean	no	-	Required as true for a non-dry-run reset that discards a saved grooming question session, preserved grooming output, or a pinned local change. It also acknowledges open-pull-request destruction.

Deprecated input aliases (one-release compatibility)

The following deprecated aliases are accepted for this release only:

• target → stage

An alias-only call succeeds and prepends this warning text for each alias:

• Deprecated input “target” was accepted as “stage”; it is supported for this release only and will be rejected in the next release.

The same ordered warnings are returned in _meta["shipper/deprecation-warnings"] as { alias, replacement, removal: "next-release" } entries. Supplying both an alias and its canonical input is rejected, even when their values are equal. These aliases will be rejected in the next release; use the canonical inputs now.

Example call

{
  "issue": 42,
  "stage": "groomed",
  "dry_run": true
}

Example result

Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages
Reset preview for S#42 (GitHub #123):
Target: Design — completed-stage target: groomed (shipper:groomed); route cleared to undecided
Labels to remove: shipper:planned
Label to add: shipper:groomed
Dry run only; no changes made.

Error modes

• Destructive discard acknowledgement required: No changes made. Retry shipper_reset with confirm_discard: true to discard preserved work and continue.
• Pull request target: S# (GitHub #) resolves to GitHub #, which is a pull request, not an issue.
• Closed issue: S# (GitHub #) is closed. Reset only works on open issues.
• Active lock: S# (GitHub #) is locked by PID , acquired at . Retry shipper_unlock with force: true and its confirmation_token to force unlock it.
• Already at target for non-failed issue: S# (GitHub #) is already at shipper:. Reset only works backward.
• Target ahead of current stage: shipper: is ahead of the current stage shipper:. Reset only works backward.
• Route-ineligible target: Reset to is unavailable because this issue has a route; a route never records .
• Partial reset failure: failed: ()
• Scan, execution, or GitHub failure: Scan/execute/GitHub failure:

Related tools

• shipper_get_issue
• shipper_recover
• shipper_unlock