shipper_close_not_planned

shipper_close_not_planned

Preview or apply closing one Shipper issue as not planned. The first call returns dependent-recovery impact and a confirmation token; repeat with that token to apply.

When to use

Use this only to withdraw one Shipper issue with the terminal not-planned outcome. This is a two-call reviewed operation: omit confirmation_token and reason to receive confirmation_required, the current token, and a structured dependent-recovery impact report; review every disposition, then repeat with that exact token and a required non-blank reason. The reason is preserved verbatim in an ordinary MCP-attributed local note headed ## Reason for Closing as Not Planned; it remains visible in closed issue detail and can be retracted through the ordinary note-retraction tool. The note and tombstone commit atomically before dependent recovery or GitHub convergence. Store-only performs no GitHub write. Mirror-on projects the note as a GitHub comment, including when the mirror is already closed, and converges labels and closure afterward. Projection failure does not undo the local closure: applied output includes mirror_pending details and warning text directing the caller to shipper issue reconcile --repair. Retrying or reconciling projects the one existing note without duplicating the local note or GitHub comment. Existing callers receive the new validation error on apply; there is no versioned compatibility alias. If the target or impact changed, the second call does not mutate and returns a fresh preview and token. The impact discriminated union reports return_to_new, pending with active_lock or closure_hold, unmoved with failed or pr_in_flight, and no_action with already_new; an empty dependents array explicitly means no open dependents. On apply, Groomed through Planned dependents return to New while remaining blocked on their unchanged blocker set; packaged Rework and review-stage dependents remain in flight. The tool offers no completed outcome and does not clean the target issue’s development artifacts.

Behavior hints

• destructiveHint: true — The tool makes one issue terminal as not planned. It offers no completed outcome and performs no branch, worktree, pull request, or other development-artifact cleanup.
• idempotentHint: true — Retrying the same call is expected to be safe once the target state is reached.
• 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.
confirmation_token	string	no	-	Omit to preview. To apply, pass the exact token from the latest confirmation_required response; a stale token returns a refreshed preview without mutation.
reason	string	no	-	Required when applying the not-planned closure with a confirmation token. Omit it when requesting a preview; stored verbatim as an attributed issue note.

Output schema

Name	Type	Required	Default	Description
status	enum: confirmation_required, applied	yes	-	-
outcome	enum: closed, already-not-planned	no	-	For applied responses, whether this call closed or repaired the issue, or found it already not planned.
confirmation_token	string	no	-	-
impact	object	yes	-	-
mirror_pending	array	no	-	-

Example call

{
  "issue": "S#42"
}

Example result

First response (no mutation):
{
  "structuredContent": {
    "status": "confirmation_required",
    "confirmation_token": "<token>",
    "impact": {
      "target": { "local_id": 42, "github_issue_number": 123 },
      "dependents": [
        {
          "kind": "return_to_new",
          "dependent": { "local_id": 43, "github_issue_number": 124, "title": "Publish documentation" },
          "stage_label": "shipper:planned"
        }
      ]
    }
  }
}

Second call:
{ "issue": "S#42", "confirmation_token": "<token>", "reason": "Superseded by the consolidated workflow" }

Applied response:
{
  "structuredContent": {
    "status": "applied",
    "outcome": "closed",
    "impact": {
      "target": { "local_id": 42, "github_issue_number": 123 },
      "dependents": [
        {
          "kind": "return_to_new",
          "dependent": { "local_id": 43, "github_issue_number": 124, "title": "Publish documentation" },
          "stage_label": "shipper:planned"
        }
      ]
    }
  }
}

Error modes

• Local issue-state replica not initialized: Local issue-state replica is not initialized for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
• Local issue-state replica present but not fully reconciled: Local issue-state replica is present but not fully reconciled for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
• Local issue-state replica schema unsupported: Local issue-state replica has an unsupported schema for owner/repo. Locally reconstructable older replicas migrate automatically on first issue-state access. Run shipper issue reconcile --repair for supported local-ID V3 blocker imports requiring GitHub data or ordinary current-store repair. Numeric snapshots in issues/<GitHub-number>.json or _pending-blocker-imports/legacy/<GitHub-number>.json refuse the entire store, listing all affected records and leaving existing local issue state unchanged. This Shipper version no longer migrates GitHub-number issue snapshots. Use a Shipper release from before this change to migrate the store before retrying this version. Fresh or recreated stores retain initial blocked-state imports and interrupted-import retries after metadata becomes reconciled; local-ID V3 stored blocker lists can complete locally in store-only mode.
• Local issue-state replica malformed: Local issue-state replica is malformed for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
• Running issue-state reader stale: The running Shipper issue-state reader is stale for owner/repo: observed store schema v10 is newer than supported schema v9. Restart or reconnect the MCP client and server. If a freshly launched server remains incompatible, update the installed Shipper release or rebuild the source checkout before reconnecting. Preserve the issue-state store unchanged.
• Invalid preview/apply combination: Valid combinations: preview supplies canonical input “issue” alone; apply supplies “issue”, nonblank “confirmation_token”, and nonblank “reason” together.
• Unknown issue: Could not find Shipper issue S#.
• Pull request reference: PR # is a pull request, not a Shipper issue. When known, the error continues: Close as not planned on its backing issue S# (GitHub #).
• Active-run lock: S# (GitHub #) is locked by PID , acquired at . Use ‘shipper unlock S# —force’ to force unlock it.
• Stale confirmation token: The target or dependent impact changed. The call returns confirmation_required with a fresh report and token and performs no closure.
• Authoritative local completed tombstone: The only outcome conflict is an authoritative local completed tombstone: S# (GitHub #) is already closed as completed; close as not planned made no changes.
• Local terminal-transition failure: A pre-commit failure leaves the active snapshot and history unchanged. Recovery completes any committed note-and-tombstone journal before the issue is read again.
• Post-commit GitHub projection pending: The local closure remains successful. Text and structured mirror_pending output identify the failed writes; run shipper issue reconcile --repair after restoring GitHub access.

Related tools

• shipper_get_issue
• shipper_list_issues