@skitterbyte/skitterspec-linear 10.6.0 → 10.7.0

package/assets/skills/spec-sync/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spec-sync
 description: Run the repo-wide spec-sync operations against Linear — what's linked, the workspace's states and projects, read-back verification, manual stamping, and bulk `apply --all <bucket>`. Run it bare for the repo-wide overview. Wraps the `spec-sync` CLI, which is a local devDependency and never on PATH, so this skill always states the full invocation. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Linear", "which states does the workspace have", or "mirror the whole backlog".
+disable-model-invocation: true
 ---
 
 # /spec-sync — the repo-wide Linear sync operations

package/assets/skills/spec-to-main/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spec-to-main
 description: Land an in-progress spec's branch onto main WITHOUT finishing it — rebase + fast-forward so the work reaches main (to run it in CI / a shared test env), while the worktree stays and the spec stays In Progress. Repeatable — land again as you commit more. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-to-main", "land this on main but keep going", "I need this on main to run tests before finishing", or "merge to main without completing the spec".
+disable-model-invocation: true
 ---
 
 # /spec-to-main — land the branch on main, keep the spec open
@@ -51,7 +52,7 @@ uncommitted changes, offer `/commit` and **stop**; don't auto-commit.
 back to base, re-isolates it into its worktree, clears the receipt), then prints
 the landing plan. Commit any live fixes to the branch first; it refuses if the
 primary checkout is dirty, or if a *different* spec holds it (release that one with
-`/spec-live main`).
+`/spec-live main`, which the user types).
 
 ## 3. Tests must be green before landing
 

package/bin/skitterspec-linear.js

@@ -41,6 +41,16 @@ const {
 async function main(argv) {
   const [cmd, ...rest] = argv
 
+// The check above asks whether src/ exists, which is inert in a workspace source
+// package — src/ is committed there. That is exactly where the other half of the
+// problem lives: a source package HAS a runnable bin and src, but its assets/ is
+// PRE-composition (seam markers still literal). Installing from it writes those
+// markers into the user's skills. So ask a second, positive question before any
+// install command runs.
+  if (cmd === 'init' || cmd === 'update') {
+    require('../src/init.js').assertComposedAssets()
+  }
+
   // Base help + what this distribution adds. Matched on the COMMAND SLOT only,
   // never the whole argv: `spec-sanitise --help` must reach that command's own
   // help, not be swallowed by the top-level one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.6.0",
+  "version": "10.7.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -185,23 +185,48 @@ async function cleanupReleaseTooling(dir, opts) {
 
 // --- spec-env: per-spec isolation engine (Phase 1: status + resolve) --------
 
-// Print provisioned specs, their slots, and port blocks from the registry.
+/**
+ * Print what is provisioned: every spec that owns a git worktree, with its slot
+ * and port block when it has one.
+ *
+ * The worktree — not the slot registry — is what "provisioned" means. `specEnvUp`
+ * allocates a slot only when `wantsDocker`, so a `Stack: worktree` spec never
+ * enters the registry and a project with `docker.enabled: false` has an
+ * permanently empty one. Reading the registry alone reported `no provisioned
+ * specs` while worktrees were standing.
+ *
+ * The registry is still read, but only to ANNOTATE a spec that has a slot — it
+ * is the authority on port blocks and nothing else.
+ *
+ * BLIND SPOT: a worktree removed behind git's back (`rm -rf` without
+ * `git worktree prune`) stays listed until pruned. That over-reports, which is
+ * the harmless direction for a read-only report.
+ */
 function specEnvStatus(dir, config) {
-  const registry = readRegistry(dir, config)
-  const names = Object.keys(registry.slots)
-  if (!names.length) {
+  const worktreePaths = liveWorktreePaths(dir)
+  const provisioned = allSpecs(dir, config, worktreePaths)
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+    // The primary checkout is itself in `git worktree list`; a spec is
+    // provisioned only when it has its OWN worktree, separate from it.
+    .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
+    .sort((a, b) => a.folder.localeCompare(b.folder))
+
+  if (!provisioned.length) {
     process.stdout.write('spec-env: no provisioned specs.\n')
     return
   }
+
+  const registry = readRegistry(dir, config)
   process.stdout.write('Provisioned specs:\n')
-  names
-    .sort((a, b) => registry.slots[a] - registry.slots[b])
-    .forEach((name) => {
-      const slot = registry.slots[name]
+  for (const { folder, wt } of provisioned) {
+    const slot = registry.slots[folder]
+    let ports = ''
+    if (slot !== undefined) {
       const off = portOffset(slot, config)
-      const hi = off + config.docker.portsPerSpec - 1
-      process.stdout.write(`  ${name}  slot ${slot}  ports ${off}-${hi}\n`)
-    })
+      ports = `  slot ${slot}  ports ${off}-${off + config.docker.portsPerSpec - 1}`
+    }
+    process.stdout.write(`  ${folder}${ports}\n    ${path.relative(dir, wt) || wt}\n`)
+  }
 }
 
 // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -209,10 +234,6 @@ function specEnvStatus(dir, config) {
 // opener). This creates no worktree and starts no stack — the caller runs the
 // printed commands. Keep the output's verb honest about that.
 function specEnvUp(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env up <spec>\n')
-    return
-  }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Live-safe: if this spec is already live on the primary checkout (its branch was
@@ -328,7 +349,7 @@ function gitReader(cwd) {
 // ancestor of it (fully landed), which lets teardown skip the unpushed guard.
 function worktreeGitState(worktreePath, base) {
   if (!fs.existsSync(worktreePath)) {
-    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false }
+    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false, remoteBranch: null }
   }
   const git = gitReader(worktreePath)
 
@@ -357,7 +378,41 @@ function worktreeGitState(worktreePath, base) {
   const pointing = git(['tag', '--points-at', 'HEAD'])
   const reachableFromTag = pointing !== null && pointing.length > 0
 
-  return { dirty, unpushed, merged, reachableFromTag }
+  // remoteBranch = the remote-tracking ref for this worktree's branch when one
+  // actually exists here (e.g. "origin/feat/thing"), else null. Teardown plans a
+  // remote delete off it, so it has to be a ref we can SEE — never an inference
+  // from the branch name, and never a bare assumption that `origin` has it.
+  //
+  // WHAT WOULD FOOL THIS, both left open deliberately:
+  //   * A STALE ref — the branch was deleted from another clone and this one
+  //     hasn't pruned. We plan a delete that no-ops: `git push --delete` errors
+  //     on a branch that isn't there, which is loud, not destructive.
+  //   * A branch pushed FROM ANOTHER MACHINE has no remote-tracking ref here, so
+  //     teardown misses it and the remote branch survives. That is the safe
+  //     direction — under-cleaning. Closing it means `git ls-remote`, which makes
+  //     every teardown network-dependent for what is cosmetic cleanup. Not done.
+  //
+  // Upstream first, so a non-`origin` remote is honoured; `--abbrev-ref` gives the
+  // short ref, and the verify catches an upstream configured for a ref that is
+  // gone. With no upstream (the branch was pushed without `-u`), ask each remote
+  // in turn rather than guessing a name.
+  let remoteBranch = null
+  const upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])
+  if (upstream && git(['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`]) !== null) {
+    remoteBranch = upstream
+  } else {
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'])
+    if (branch && branch !== 'HEAD') {
+      for (const remote of (git(['remote']) || '').split('\n').map((r) => r.trim()).filter(Boolean)) {
+        if (git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`]) !== null) {
+          remoteBranch = `${remote}/${branch}`
+          break
+        }
+      }
+    }
+  }
+
+  return { dirty, unpushed, merged, reachableFromTag, remoteBranch }
 }
 
 // A deterministic-enough compact timestamp for backup filenames (CLI-only; the
@@ -376,10 +431,6 @@ function compactTimestamp() {
 // the shared parent of every spec's worktree and harmless when empty; removing it
 // would just re-prompt on the next /spec-go (see spec: isolation-trusts-worktree-dir).
 function specEnvDown(dir, config, specArg, flags) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env down <spec> [--keep-volumes] [--force]\n')
-    return
-  }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // A worktree-only spec never held a slot but its worktree still needs removing,
@@ -419,6 +470,15 @@ function specEnvDown(dir, config, specArg, flags) {
   out.push('')
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  // Kept out of `run these:` on purpose — everything above is local and
+  // reversible-ish, while this reaches a shared remote. The skills ask before
+  // running it; a project that never wants to be asked sets
+  // `teardown.deleteRemoteBranch: "always"`, which folds it in above instead.
+  if (plan.remoteCommands && plan.remoteCommands.length) {
+    out.push('')
+    out.push('  remote branch — confirm with the user first:')
+    for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -482,6 +542,77 @@ function liveWorktreePaths(dir) {
   return paths
 }
 
+/**
+ * The spec to act on when the caller named none.
+ *
+ * Two signals, strongest first:
+ *
+ *   1. **The worktree you are standing in.** A spec-env verb run from inside a
+ *      spec's worktree means that spec — there is nothing to infer. This is the
+ *      case that carries the feature in practice: several worktrees at once is
+ *      the normal shape of this workflow, so "the only one" rarely resolves.
+ *   2. **The only spec that has a worktree**, when cwd says nothing (you are in
+ *      the primary checkout, or somewhere else entirely).
+ *
+ * `git worktree list` is the authority for both, and deliberately so. Two
+ * nearer-looking signals are wrong here:
+ *
+ *   - The **slot registry** covers only Docker specs — `specEnvUp` allocates a
+ *     slot exclusively when `wantsDocker`, so a `Stack: worktree` spec never
+ *     appears in it and a project with `docker.enabled: false` has a permanently
+ *     empty registry. Absence there says nothing about provisioning.
+ *   - The **`specs/in-progress/` bucket** says a spec is being worked on, not
+ *     that it has a worktree — and git does not track an empty directory, so the
+ *     bucket disappears the moment it empties.
+ *
+ * Three outcomes, never two: resolved → that spec; several candidates and no cwd
+ * hint → throw, listing them; none → throw, pointing at /spec-go. *Cannot tell*
+ * never becomes a guess.
+ *
+ * BLIND SPOT: a spec taken live with `/spec-live` has had its branch moved into
+ * the primary checkout and its worktree left on a detached HEAD — it still has a
+ * worktree, so it is still a candidate, which is correct. What would fool this is
+ * a worktree removed behind git's back (`rm -rf` without `git worktree prune`);
+ * git keeps listing it as prunable. That over-reports rather than under-reports,
+ * so the failure is an ambiguity error, never a wrong spec.
+ */
+function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
+  const worktreePaths = liveWorktreePaths(dir)
+  const provisioned = allSpecs(dir, config, worktreePaths)
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+    // The primary checkout is itself in `git worktree list`; a spec is
+    // provisioned only when it has its OWN worktree, separate from it.
+    .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
+    .sort((a, b) => a.folder.localeCompare(b.folder))
+
+  // 1. Standing inside a spec's worktree names it outright. Deepest match wins,
+  //    so a nested worktree is not shadowed by an ancestor one.
+  let here
+  try {
+    here = fs.realpathSync(path.resolve(cwd))
+  } catch {
+    here = path.resolve(cwd)
+  }
+  const inside = provisioned
+    .filter((s) => here === s.wt || here.startsWith(s.wt + path.sep))
+    .sort((a, b) => b.wt.length - a.wt.length)[0]
+  if (inside) return inside.folder
+
+  // 2. Otherwise only an unambiguous set answers.
+  if (provisioned.length === 1) return provisioned[0].folder
+  if (provisioned.length === 0) {
+    throw new Error(
+      'no spec given, and no spec has a worktree — name one explicitly, or run ' +
+        '/spec-go to provision it.',
+    )
+  }
+  throw new Error(
+    `no spec given, and ${provisioned.length} specs have worktrees — name the one ` +
+      `you mean, or run this from inside one:\n` +
+      provisioned.map((s, i) => `  ${i + 1}. ${s.folder}`).join('\n'),
+  )
+}
+
 // Resolve a spec argument the ONE way every spec-env subcommand resolves it:
 // against the primary checkout first, then the spec's own worktree, then every
 // other checkout git knows about. An in-progress spec is git-mv'd into
@@ -493,6 +624,10 @@ function liveWorktreePaths(dir) {
 // coordinate tokens always expand against `dir` (the primary checkout), so the
 // answer is identical whether the command was run from main or a worktree.
 function resolveSpecWithWorktree(dir, config, specArg) {
+  // Fill in a missing argument first: everything below (starting with
+  // path.basename) assumes a string, and every subcommand that reaches here is
+  // one where a missing spec was previously a usage error.
+  specArg = specArg || soleProvisionedSpec(dir, config)
   const { slug } = splitPrefix(path.basename(specArg))
   const { repo, repoSlug } = repoInfo(dir)
   const wtTokens = { repo, repoSlug, slug }
@@ -604,6 +739,15 @@ function specEnvPrune(dir, config, flags) {
   out.push('')
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  // Kept out of `run these:` on purpose — everything above is local and
+  // reversible-ish, while this reaches a shared remote. The skills ask before
+  // running it; a project that never wants to be asked sets
+  // `teardown.deleteRemoteBranch: "always"`, which folds it in above instead.
+  if (plan.remoteCommands && plan.remoteCommands.length) {
+    out.push('')
+    out.push('  remote branch — confirm with the user first:')
+    for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -611,10 +755,6 @@ function specEnvPrune(dir, config, flags) {
 // Queries git for the facts, prints the plan / block / no-op. The /spec-complete
 // skill executes the printed commands (and aborts a conflicting rebase).
 function specEnvIntegrate(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env integrate <spec>\n')
-    return
-  }
 
   // `dir` is already anchored on the primary checkout by the dispatch, so it is
   // both where the spec resolves and the target of the fast-forward — /spec-complete
@@ -734,8 +874,9 @@ function specEnvIntegrate(dir, config, specArg) {
 function specEnvHotfix(dir, config, positional, flags) {
   const action = positional[0]
   const specArg = positional[1]
-  if (action !== 'land' || !specArg) {
-    process.stdout.write('Usage: skitterspec spec-env hotfix land <spec> [--also <tag>]...\n')
+  // The action must be named; the spec may be omitted (resolved from the registry).
+  if (action !== 'land') {
+    process.stdout.write('Usage: skitterspec spec-env hotfix land [spec] [--also <tag>]...\n')
     return
   }
 
@@ -815,10 +956,6 @@ function specEnvHotfix(dir, config, positional, flags) {
 
 // Print the resolved identity/coordinates for a single spec.
 function specEnvResolve(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env resolve <spec>\n')
-    return
-  }
   const r = resolveSpecWithWorktree(dir, config, specArg)
   process.stdout.write(
     `spec:       ${r.folder} (${r.bucket})\n` +
@@ -836,8 +973,9 @@ function specEnvResolve(dir, config, specArg) {
 async function specEnvDev(dir, config, positional) {
   const action = positional[0]
   const specArg = positional[1]
-  if ((action !== 'up' && action !== 'down') || !specArg) {
-    process.stdout.write('Usage: skitterspec spec-env dev <up|down> <spec>\n')
+  // The action must be named; the spec may be omitted (resolved from the registry).
+  if (action !== 'up' && action !== 'down') {
+    process.stdout.write('Usage: skitterspec spec-env dev <up|down> [spec]\n')
     return
   }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
@@ -1035,11 +1173,6 @@ async function specEnvLive(dir, config, positional) {
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env live take <spec>\n')
-    return
-  }
-
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Probe the primary checkout's git state (IO stays here; the planner is pure).
@@ -1329,7 +1462,11 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n',
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n' +
+          '  [spec] is optional for up/down/dev/integrate/hotfix/resolve and live take:\n' +
+          '  omit it and the sole provisioned spec is used (several -> it lists them).\n' +
+          '  NOTE connect and live status keep their own meaning for a missing spec:\n' +
+          '  connect disconnects (= main), live status reports on the whole repo.\n',
       )
   }
 }

package/src/env/config.js

@@ -29,6 +29,7 @@
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
+ *     teardown: { deleteRemoteBranch },
  *     live:     { migrations: [ "glob", ... ] }  // migration globs → `live take`
  *               // refuses a branch that changes them (code-only v1)
  *     hotfix:   { bump, cherryPickMain, targets }  // `hotfix land`: patch-bump the
@@ -79,6 +80,12 @@ const DEFAULT_CONFIG = Object.freeze({
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
+  // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
+  // `spec-env down` does about the branch `/spec-go` pushed: "prompt" (default)
+  // plans the delete in its own confirm-first section for the skill to ask about,
+  // "never" omits it, "always" folds it into the run-blind command list. Only ever
+  // planned for a LANDED branch — see teardown.js.
+  teardown: Object.freeze({ deleteRemoteBranch: 'prompt' }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -109,6 +116,7 @@ function defaults() {
     branch: { ...DEFAULT_CONFIG.branch },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
+    teardown: { ...DEFAULT_CONFIG.teardown },
     live: { migrations: [] },
     hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
@@ -254,6 +262,17 @@ function mergeConfig(base, parsed) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
   }
 
+  // An unrecognised policy falls through to the default rather than erroring or
+  // being taken literally — a typo ("Always", "yes") must not silently become a
+  // stronger setting than the author typed, and "prompt" is the one value that
+  // cannot act without a human first.
+  if (isObject(parsed.teardown)) {
+    const policy = parsed.teardown.deleteRemoteBranch
+    if (policy === 'prompt' || policy === 'never' || policy === 'always') {
+      base.teardown.deleteRemoteBranch = policy
+    }
+  }
+
   if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }

package/src/env/teardown.js

@@ -13,6 +13,12 @@
  * Volumes are the only destructive action — dropped by default (reclaims disk)
  * unless `--keep-volumes`, and always backed up first when a `backupCommand` is
  * configured.
+ *
+ * `commands` is safe for a caller to run BLIND — that is the property the remote
+ * delete must not break. A remote branch delete reaches outside this machine, so
+ * it is returned in a separate `remoteCommands` array that the skills confirm
+ * with the user before running, and it never enters `commands` unless the
+ * project has opted in with `teardown.deleteRemoteBranch: "always"`.
  */
 
 const { expandTokens } = require('./resolve.js')
@@ -21,9 +27,10 @@ const { expandTokens } = require('./resolve.js')
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
  * @param {object} config normalised env config.
  * @param {object} flags { keepVolumes, force }
- * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag }, timestamp }
- * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
- *                     volumesDropped }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag,
+ *                     remoteBranch }, timestamp }
+ * @returns {object} { blocked, reason, commands, remoteCommands, backupCommand,
+ *                     backupPath, volumesDropped }
  */
 function planDown(spec, config, flags, ctx) {
   const { worktreeState = {}, timestamp } = ctx || {}
@@ -113,7 +120,57 @@ function planDown(spec, config, flags, ctx) {
     commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
   }
 
-  return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }
+  // --- delete the branch on the remote (planned, never run here) ---
+  //
+  // `/spec-go` pushes the branch at provision time, so a completed spec otherwise
+  // leaves a merged branch on the remote forever. Cleaning that up is the goal;
+  // doing it safely is the constraint.
+  //
+  // Gated on `landed` because until the branch is merged (or captured by a tag)
+  // the remote copy is the ONLY backup of the work — that is the whole reason
+  // `refuseTeardownIfUnpushed` exists, and deleting the remote branch of an
+  // unlanded spec would defeat it. `--force` deliberately does NOT enable this:
+  // force is for "I accept losing this worktree", not "also reach out and delete
+  // the backup". The same `landed` that decides `-D` vs `-d` decides this, so the
+  // two can never disagree about whether the commits are recoverable.
+  //
+  // A null `remoteBranch` plans nothing. An absence is not evidence — the branch
+  // may well be on a remote this clone cannot see (pushed from another machine),
+  // and the honest answer to "is there a remote branch?" is then "cannot tell",
+  // which routes to doing nothing.
+  const remoteCommands = []
+  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
+  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
+    // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
+    // itself contains slashes, so the remote is what remains once the exact
+    // "/<branch>" suffix is stripped — not the text before the first slash.
+    //
+    // If it does not end that way the ref maps to a differently-named branch on
+    // the remote (a push refspec, or push.default set to something exotic). We
+    // cannot tell what to delete, so we plan nothing rather than guess at a
+    // branch name on someone's shared remote.
+    const suffix = `/${spec.branch}`
+    if (worktreeState.remoteBranch.endsWith(suffix)) {
+      const remote = worktreeState.remoteBranch.slice(0, -suffix.length)
+      if (remote) {
+        const cmd = `git push ${remote} --delete ${spec.branch}`
+        // "always" is the project saying it never wants to be asked, so the push
+        // joins the run-blind list. Everything else keeps it quarantined.
+        if (policy === 'always') commands.push(cmd)
+        else remoteCommands.push(cmd)
+      }
+    }
+  }
+
+  return {
+    blocked: false,
+    reason: null,
+    commands,
+    remoteCommands,
+    backupCommand,
+    backupPath,
+    volumesDropped,
+  }
 }
 
 function blocked(reason) {
@@ -121,6 +178,7 @@ function blocked(reason) {
     blocked: true,
     reason,
     commands: [],
+    remoteCommands: [],
     backupCommand: null,
     backupPath: null,
     volumesDropped: false,