infra-kit 0.1.108 → 0.1.110

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infra-kit",
   "type": "module",
-  "version": "0.1.108",
+  "version": "0.1.110",
   "description": "infra-kit",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/commands/gh-merge-dev/gh-merge-dev.ts

@@ -8,6 +8,7 @@ import { $ } from 'zx'
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { logger } from 'src/lib/logger'
 import { detectReleaseType, formatBranchChoices, getJiraDescriptions, releaseBranchLabels } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
@@ -25,6 +26,8 @@ export const ghMergeDev = async (args: GhMergeDevArgs) => {
 
   commandEcho.start('merge-dev')
 
+  await assertManagementContext({ operation: 'merge dev into release branches', requiredBranch: 'dev' })
+
   // Only merge dev into regular releases (not hotfixes, which target main)
   const allPRs = await getReleasePRsWithInfo()
   const releasePRsList = allPRs

package/src/commands/gh-release-deliver/gh-release-deliver.ts

@@ -10,6 +10,7 @@ import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
 import { formatZxError } from 'src/lib/errors/format-zx-error'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { logger } from 'src/lib/logger'
 import { displayLabel, formatJiraName, formatRcTitle, parseBranchName } from 'src/lib/release-id'
@@ -339,6 +340,10 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs) => {
 
   commandEcho.start('release-deliver')
 
+  // Branch-agnostic (operates on release/RC PRs via gh and self-switches), so
+  // only the worktree + clean-tree legs apply.
+  await assertManagementContext({ operation: 'deliver release' })
+
   const { selectedReleaseBranch, releasePrTitle } = version
     ? await resolveTargetFromVersion(version)
     : await resolveTargetInteractively()

package/src/commands/gh-release-deploy-all/gh-release-deploy-all.ts

@@ -31,7 +31,7 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
 
   commandEcho.start('release-deploy-all')
 
-  let selectedReleaseBranch = '' // "release/v1.8.0" | "release/n/checkout-redesign" | "dev"
+  let selectedReleaseBranch = '' // "release/v1.8.0" | "release/checkout-redesign" | "dev"
 
   if (version) {
     selectedReleaseBranch = version === 'dev' ? 'dev' : resolveReleaseBranch(version)
@@ -143,7 +143,7 @@ export const ghReleaseDeployAllMcpTool = defineMcpTool({
     version: z
       .string()
       .describe(
-        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") — resolves to the release/vX.Y.Z or release/n/<name> branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
+        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") — resolves to the release/vX.Y.Z or release/<name> branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
       ),
     env: z
       .string()

package/src/commands/gh-release-deploy-selected/gh-release-deploy-selected.ts

@@ -232,7 +232,7 @@ export const ghReleaseDeploySelectedMcpTool = defineMcpTool({
     version: z
       .string()
       .describe(
-        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") — resolves to the release/vX.Y.Z or release/n/<name> branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
+        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") — resolves to the release/vX.Y.Z or release/<name> branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
       ),
     env: z
       .string()

package/src/commands/release-create/__tests__/release-create.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from 'vitest'
 import type { z } from 'zod'
 
-import { releaseCreateMcpTool } from '../release-create'
+import { OperationError } from 'src/lib/errors/operation-error'
+import type { ReleaseType } from 'src/lib/release-utils'
+import type { ReleaseEntry } from 'src/lib/version-utils'
+
+import { assertHomogeneousReleaseType, releaseCreateMcpTool } from '../release-create'
 
 /**
  * The MCP `releases[]` entry schema enforces that exactly one of `version` or
@@ -53,3 +57,36 @@ describe('release-create MCP releases[] entry schema', () => {
     }).toThrow(/exactly one of/)
   })
 })
+
+const entryOfType = (type: ReleaseType): ReleaseEntry => {
+  return {
+    id: { kind: 'version', semver: { major: 1, minor: 2, patch: 3 }, raw: '1.2.3' },
+    type,
+  } as ReleaseEntry
+}
+
+describe('assertHomogeneousReleaseType', () => {
+  it('accepts an all-regular batch', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('regular'), entryOfType('regular')])
+    }).not.toThrow()
+  })
+
+  it('accepts an all-hotfix batch', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('hotfix')])
+    }).not.toThrow()
+  })
+
+  it('rejects a mixed regular+hotfix batch with an OperationError', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('regular'), entryOfType('hotfix')])
+    }).toThrow(OperationError)
+  })
+
+  it('mixed-batch error mentions separate invocations', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('regular'), entryOfType('hotfix')])
+    }).toThrow(/separate invocations/)
+  })
+})

package/src/commands/release-create/release-create.ts

@@ -7,9 +7,10 @@ import { question } from 'zx'
 import { loadJiraConfig } from 'src/integrations/jira'
 import { commandEcho } from 'src/lib/command-echo'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { logger } from 'src/lib/logger'
 import { InvalidReleaseNameError, displayLabel, validateName } from 'src/lib/release-id'
-import { createSingleRelease, prepareGitForRelease } from 'src/lib/release-utils'
+import { createSingleRelease, getBaseBranch, prepareGitForRelease } from 'src/lib/release-utils'
 import type { ReleaseCreationResult, ReleaseType } from 'src/lib/release-utils'
 import {
   NoPriorVersionsError,
@@ -212,6 +213,28 @@ const collectEntries = async (
   return interactive
 }
 
+/**
+ * Reject a batch that mixes regular and hotfix releases. They branch off
+ * different bases (dev vs main), so the batch has no single required branch for
+ * the management guard — they must be created in separate invocations.
+ * Exported for unit testing without running the side-effecting handler.
+ */
+export const assertHomogeneousReleaseType = (entries: ReleaseEntry[]): void => {
+  const types = new Set(
+    entries.map((entry) => {
+      return entry.type
+    }),
+  )
+
+  if (types.size > 1) {
+    throw new OperationError(undefined, {
+      operation: 'create release',
+      remediation: 'create regular and hotfix releases in separate invocations',
+      stderrExcerpt: 'mixed regular and hotfix releases in one batch are not supported',
+    })
+  }
+}
+
 const confirmReleases = async (entries: ReleaseEntry[], confirmedCommand: boolean): Promise<void> => {
   const summary = entries.map(formatReleaseSummary).join('\n  - ')
   const answer = confirmedCommand
@@ -284,8 +307,10 @@ const logFinalSummary = (total: number, successCount: number, failureCount: numb
 
 /**
  * Create one or more release branches. Each release carries its own type
- * (regular/hotfix) and optional Jira description, so a single invocation
- * may mix regular and hotfix releases off their respective base branches.
+ * (regular/hotfix) and optional Jira description. All entries in a single
+ * invocation must share the same type — regular and hotfix releases branch off
+ * different bases (dev vs main), so mixed batches are rejected and must be
+ * created separately.
  */
 export const releaseCreate = async (args: ReleaseCreateArgs) => {
   const { releases: inputReleases, confirmedCommand } = args
@@ -311,6 +336,13 @@ export const releaseCreate = async (args: ReleaseCreateArgs) => {
     })
   }
 
+  assertHomogeneousReleaseType(entries)
+
+  await assertManagementContext({
+    operation: 'create release',
+    requiredBranch: getBaseBranch(entries[0]!.type),
+  })
+
   await confirmReleases(entries, Boolean(confirmedCommand))
 
   const created: ReleaseCreationResult[] = []
@@ -347,7 +379,7 @@ export const releaseCreate = async (args: ReleaseCreateArgs) => {
 export const releaseCreateMcpTool = defineMcpTool({
   name: 'release-create',
   description:
-    'Create one or more releases in a single call. Each entry in "releases" carries EITHER a "version" (semver or the literal token "next") OR a "name" (free-form kebab-case identifier) — exactly one is required and they are mutually exclusive. Each entry also has its own type (regular|hotfix, default regular) and optional description, so regular and hotfix releases can be mixed in the same invocation. For each release this tool switches to the appropriate base branch (dev for regular, main for hotfix), cuts the release branch (release/v<semver> for versions, release/n/<name> for names), opens a GitHub release PR, and creates the matching Jira fix version (v<semver> for versions, <name> for names). The literal token "next" auto-increments from the union of remote release branches and Jira fix versions (regular bumps minor + resets patch; hotfix bumps patch on the highest minor); multiple "next" tokens advance sequentially across mixed types. Named releases never auto-bump and "next" is version-only. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. Continues on per-release failure and reports successes/failures.',
+    'Create one or more releases in a single call. Each entry in "releases" carries EITHER a "version" (semver or the literal token "next") OR a "name" (free-form kebab-case identifier) — exactly one is required and they are mutually exclusive. Each entry also has its own type (regular|hotfix, default regular) and optional description; all entries in one call must share the same type — mixed regular+hotfix batches are rejected (create them in separate invocations). For each release this tool switches to the appropriate base branch (dev for regular, main for hotfix), cuts the release branch (release/v<semver> for versions, release/<name> for names), opens a GitHub release PR, and creates the matching Jira fix version (v<semver> for versions, <name> for names). The literal token "next" auto-increments from the union of remote release branches and Jira fix versions (regular bumps minor + resets patch; hotfix bumps patch on the highest minor); multiple "next" tokens advance sequentially. Named releases never auto-bump and "next" is version-only. Must be run from the main repository checkout (not a linked worktree) on the matching base branch with a clean working tree. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. Continues on per-release failure and reports successes/failures.',
   inputSchema: {
     releases: z
       .array(

package/src/commands/release-desc-edit/release-desc-edit.ts

@@ -208,7 +208,7 @@ export const releaseDescEdit = async (args: ReleaseDescEditArgs) => {
 export const releaseDescEditMcpTool = defineMcpTool({
   name: 'release-desc-edit',
   description:
-    "Edit a release's description in Jira and in the matching GitHub release PR body. Accepts a release version or a release name: targets the Jira fix version named `v<version>` (versioned) or `<name>` (named) and the open PR on branch `release/v<version>` or `release/n/<name>`. The PR body is rewritten canonically to `<jiraVersionUrl>\\n\\n<description>` — any prior manual edits to the body are overwritten. Both `version` and `description` are required for MCP calls (the picker/prompt are unreachable without a TTY). Empty `description` clears the description on both sides. Confirmation is auto-skipped for MCP, so the caller is responsible for gating.",
+    "Edit a release's description in Jira and in the matching GitHub release PR body. Accepts a release version or a release name: targets the Jira fix version named `v<version>` (versioned) or `<name>` (named) and the open PR on branch `release/v<version>` or `release/<name>`. The PR body is rewritten canonically to `<jiraVersionUrl>\\n\\n<description>` — any prior manual edits to the body are overwritten. Both `version` and `description` are required for MCP calls (the picker/prompt are unreachable without a TTY). Empty `description` clears the description on both sides. Confirmation is auto-skipped for MCP, so the caller is responsible for gating.",
   inputSchema: {
     version: z
       .string()
@@ -217,7 +217,7 @@ export const releaseDescEditMcpTool = defineMcpTool({
   },
   outputSchema: {
     version: z.string().describe('Release version'),
-    branch: z.string().describe('Release branch name (e.g. "release/v1.2.5" or "release/n/checkout-redesign")'),
+    branch: z.string().describe('Release branch name (e.g. "release/v1.2.5" or "release/checkout-redesign")'),
     jiraVersionUrl: z.string().describe('Jira fix version URL'),
     previousDescription: z.string().describe('The description before the update'),
     newDescription: z.string().describe('The description after the update'),

package/src/commands/worktrees-add/worktrees-add.ts

@@ -17,6 +17,7 @@ import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
@@ -50,6 +51,8 @@ export const worktreesAdd = async (options: WorktreeManagementArgs) => {
 
   commandEcho.start('worktrees-add')
 
+  await assertManagementContext({ operation: 'create worktrees', requiredBranch: 'dev' })
+
   try {
     const currentWorktrees = await getCurrentWorktrees('release')
     const projectRoot = await getProjectRoot()

package/src/commands/worktrees-open/__tests__/open-cmux.test.ts

@@ -25,7 +25,7 @@ vi.mock('src/lib/git-utils', () => {
 
 const REPO = 'hulyo-monorepo'
 const WORKTREE_DIR = '/repos/project-worktrees'
-const BRANCHES = ['release/v1.48.0', 'release/n/checkout-redesign']
+const BRANCHES = ['release/v1.48.0', 'release/checkout-redesign']
 
 const titleFor = {
   versioned: `${REPO} 1.48.0`,
@@ -68,7 +68,7 @@ describe('openCmux dedup', () => {
     expect(result.opened).toEqual([titleFor.named])
     expect(openCmuxWorkspaceWithLayout).toHaveBeenCalledTimes(1)
     expect(openCmuxWorkspaceWithLayout).toHaveBeenCalledWith({
-      cwd: `${WORKTREE_DIR}/release/n/checkout-redesign`,
+      cwd: `${WORKTREE_DIR}/release/checkout-redesign`,
       title: titleFor.named,
     })
   })

package/src/commands/worktrees-remove/worktrees-remove.ts

@@ -8,6 +8,7 @@ import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
@@ -33,6 +34,8 @@ export const worktreesRemove = async (options: WorktreeManagementArgs) => {
 
   commandEcho.start('worktrees-remove')
 
+  await assertManagementContext({ operation: 'remove worktrees', requiredBranch: 'dev' })
+
   try {
     const currentWorktrees = await getCurrentWorktrees('release')
 

package/src/commands/worktrees-sync/worktrees-sync.ts

@@ -9,6 +9,7 @@ import { getReleasePRs } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
@@ -28,6 +29,8 @@ export const worktreesSync = async (options: WorktreeSyncArgs) => {
 
   commandEcho.start('worktrees-sync')
 
+  await assertManagementContext({ operation: 'sync worktrees', requiredBranch: 'dev' })
+
   try {
     const currentWorktrees = await getCurrentWorktrees('release')
     const projectRoot = await getProjectRoot()

package/src/integrations/cmux/__tests__/canonicalize-cmux-title.test.ts

@@ -48,7 +48,7 @@ describe('canonicalizeCmuxTitle', () => {
     })
 
     it('built title canonicalizes to a stable key for a named release', () => {
-      const built = buildCmuxWorkspaceTitle({ repoName: 'hulyo-monorepo', branch: 'release/n/checkout-redesign' })
+      const built = buildCmuxWorkspaceTitle({ repoName: 'hulyo-monorepo', branch: 'release/checkout-redesign' })
 
       expect(canonicalizeCmuxTitle(built)).toBe('hulyo-monorepo checkout-redesign')
     })

package/src/integrations/cmux/workspace-title.ts

@@ -10,7 +10,7 @@ interface BuildCmuxWorkspaceTitleArgs {
  * `worktrees-remove`. Release branches are rendered via their release-id
  * display label so the title reads e.g. `"hulyo-monorepo 1.48.0"` for
  * `"release/v1.48.0"` and `"hulyo-monorepo checkout-redesign"` for
- * `"release/n/checkout-redesign"`. Non-release branches (cmux titles them too)
+ * `"release/checkout-redesign"`. Non-release branches (cmux titles them too)
  * fall back to the raw branch string.
  */
 export const buildCmuxWorkspaceTitle = (args: BuildCmuxWorkspaceTitleArgs): string => {

package/src/integrations/gh/gh-release-prs/__tests__/gh-release-prs.test.ts

@@ -67,33 +67,33 @@ describe('getReleasePRs (discovery + sort)', () => {
 
   it('sorts version branches first by semver ascending (numeric, 1.9.0 < 1.10.0), then names by createdAt', async () => {
     responses.release = [
-      pr({ headRefName: 'release/n/zeta-feature', createdAt: '2026-01-10T00:00:00Z', title: 'Release zeta-feature' }),
+      pr({ headRefName: 'release/zeta-feature', createdAt: '2026-01-10T00:00:00Z', title: 'Release zeta-feature' }),
       pr({ headRefName: 'release/v1.10.0', createdAt: '2026-01-02T00:00:00Z' }),
-      pr({ headRefName: 'release/n/alpha-feature', createdAt: '2026-01-05T00:00:00Z', title: 'Release alpha-feature' }),
+      pr({ headRefName: 'release/alpha-feature', createdAt: '2026-01-05T00:00:00Z', title: 'Release alpha-feature' }),
       pr({ headRefName: 'release/v1.9.0', createdAt: '2026-01-01T00:00:00Z' }),
     ]
 
     await expect(getReleasePRs()).resolves.toEqual([
       'release/v1.9.0',
       'release/v1.10.0',
-      'release/n/alpha-feature',
-      'release/n/zeta-feature',
+      'release/alpha-feature',
+      'release/zeta-feature',
     ])
   })
 
   it('filters out unparseable junk branches instead of throwing or NaN-sorting', async () => {
     responses.release = [
-      pr({ headRefName: 'release/garbage', createdAt: '2026-01-01T00:00:00Z' }),
+      pr({ headRefName: 'release/Bad_Name', createdAt: '2026-01-01T00:00:00Z' }),
       pr({ headRefName: 'release/v1.2.3', createdAt: '2026-01-02T00:00:00Z' }),
       pr({ headRefName: 'totally-not-a-release', createdAt: '2026-01-03T00:00:00Z' }),
       pr({
-        headRefName: 'release/n/checkout-redesign',
+        headRefName: 'release/checkout-redesign',
         createdAt: '2026-01-04T00:00:00Z',
         title: 'Release checkout-redesign',
       }),
     ]
 
-    await expect(getReleasePRs()).resolves.toEqual(['release/v1.2.3', 'release/n/checkout-redesign'])
+    await expect(getReleasePRs()).resolves.toEqual(['release/v1.2.3', 'release/checkout-redesign'])
   })
 
   it('merges hotfix (base main) and release (base dev) sets', async () => {
@@ -119,14 +119,14 @@ describe('getReleasePRsWithInfo (discovery + sort)', () => {
 
   it('returns branch/title/createdAt in the locked order with junk filtered', async () => {
     responses.release = [
-      pr({ headRefName: 'release/n/beta-feature', createdAt: '2026-02-02T00:00:00Z', title: 'Release beta-feature' }),
-      pr({ headRefName: 'release/garbage', createdAt: '2026-02-03T00:00:00Z', title: 'Release garbage' }),
+      pr({ headRefName: 'release/beta-feature', createdAt: '2026-02-02T00:00:00Z', title: 'Release beta-feature' }),
+      pr({ headRefName: 'release/Bad_Name', createdAt: '2026-02-03T00:00:00Z', title: 'Release Bad_Name' }),
       pr({ headRefName: 'release/v3.1.0', createdAt: '2026-02-01T00:00:00Z', title: 'Release v3.1.0' }),
     ]
 
     await expect(getReleasePRsWithInfo()).resolves.toEqual([
       { branch: 'release/v3.1.0', title: 'Release v3.1.0', createdAt: '2026-02-01T00:00:00Z' },
-      { branch: 'release/n/beta-feature', title: 'Release beta-feature', createdAt: '2026-02-02T00:00:00Z' },
+      { branch: 'release/beta-feature', title: 'Release beta-feature', createdAt: '2026-02-02T00:00:00Z' },
     ])
   })
 })

package/src/integrations/gh/gh-release-prs/gh-release-prs.ts

@@ -77,7 +77,7 @@ const fetchAllReleasePRs = async (): Promise<ReleasePR[]> => {
  * (version branches first by semver ascending, then named branches by PR
  * creation date). Unparseable head refs are filtered out.
  *
- * @returns [release/v1.18.22, release/v1.18.23, release/n/checkout-redesign]
+ * @returns [release/v1.18.22, release/v1.18.23, release/checkout-redesign]
  */
 export const getReleasePRs = async (): Promise<string[]> => {
   try {

package/src/lib/git-guard/__tests__/git-guard.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
+
+const mocks = vi.hoisted(() => {
+  return {
+    isInsideLinkedWorktree: vi.fn(),
+    getCurrentBranch: vi.fn(),
+    isWorkingTreeClean: vi.fn(),
+  }
+})
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    isInsideLinkedWorktree: mocks.isInsideLinkedWorktree,
+    getCurrentBranch: mocks.getCurrentBranch,
+    isWorkingTreeClean: mocks.isWorkingTreeClean,
+  }
+})
+
+describe('assertManagementContext', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    // Default: main checkout, on dev, clean tree (the all-pass baseline).
+    mocks.isInsideLinkedWorktree.mockResolvedValue(false)
+    mocks.getCurrentBranch.mockResolvedValue('dev')
+    mocks.isWorkingTreeClean.mockResolvedValue(true)
+  })
+
+  it('resolves when in main checkout, on the required branch, with a clean tree', async () => {
+    await expect(
+      assertManagementContext({ operation: 'create release', requiredBranch: 'dev' }),
+    ).resolves.toBeUndefined()
+  })
+
+  it('throws when inside a linked worktree', async () => {
+    mocks.isInsideLinkedWorktree.mockResolvedValue(true)
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toMatchObject(
+      {
+        message: expect.stringContaining('worktree'),
+      },
+    )
+  })
+
+  it('checks the worktree before the branch', async () => {
+    mocks.isInsideLinkedWorktree.mockResolvedValue(true)
+    mocks.getCurrentBranch.mockResolvedValue('feature/x')
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toThrow(
+      /worktree/,
+    )
+    expect(mocks.getCurrentBranch).not.toHaveBeenCalled()
+  })
+
+  it('throws on the wrong branch when requiredBranch is set', async () => {
+    mocks.getCurrentBranch.mockResolvedValue('main')
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toMatchObject(
+      {
+        message: expect.stringContaining('switch to dev'),
+      },
+    )
+  })
+
+  it('skips the branch check when requiredBranch is omitted', async () => {
+    mocks.getCurrentBranch.mockResolvedValue('main')
+
+    await expect(assertManagementContext({ operation: 'deliver release' })).resolves.toBeUndefined()
+    expect(mocks.getCurrentBranch).not.toHaveBeenCalled()
+  })
+
+  it('throws when the working tree is dirty', async () => {
+    mocks.isWorkingTreeClean.mockResolvedValue(false)
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toMatchObject(
+      {
+        message: expect.stringContaining('commit or stash'),
+      },
+    )
+  })
+
+  it('throws OperationError (not a plain Error) on violation', async () => {
+    mocks.isWorkingTreeClean.mockResolvedValue(false)
+
+    await expect(
+      assertManagementContext({ operation: 'sync worktrees', requiredBranch: 'dev' }),
+    ).rejects.toBeInstanceOf(OperationError)
+  })
+})

package/src/lib/git-guard/git-guard.ts

@@ -0,0 +1,55 @@
+import { OperationError } from 'src/lib/errors/operation-error'
+import { getCurrentBranch, isInsideLinkedWorktree, isWorkingTreeClean } from 'src/lib/git-utils'
+
+export interface AssertManagementContextArgs {
+  /** Operation name surfaced in the failure message, e.g. 'create release'. */
+  operation: string
+  /**
+   * Canonical branch the command must run from (e.g. 'dev' / 'main'). Omit to
+   * skip the branch check for commands that are branch-agnostic or self-switch.
+   */
+  requiredBranch?: string
+}
+
+/**
+ * Guard release- and worktree-management commands so they run only from the
+ * main repository checkout, with a clean working tree, and (where applicable)
+ * on the canonical branch.
+ *
+ * Checks run most-structural-first — worktree, then branch, then clean — so the
+ * operator fixes the most fundamental problem first. The worktree and clean-tree
+ * checks always run; the branch check runs only when `requiredBranch` is set.
+ * Throws {@link OperationError} on the first violation, which surfaces uniformly
+ * to both CLI users and MCP-connected agents.
+ */
+export const assertManagementContext = async (args: AssertManagementContextArgs): Promise<void> => {
+  const { operation, requiredBranch } = args
+
+  if (await isInsideLinkedWorktree()) {
+    throw new OperationError(undefined, {
+      operation,
+      remediation: 'run this from the main repository checkout, not a linked git worktree',
+      stderrExcerpt: 'command run from inside a linked worktree',
+    })
+  }
+
+  if (requiredBranch) {
+    const currentBranch = await getCurrentBranch()
+
+    if (currentBranch !== requiredBranch) {
+      throw new OperationError(undefined, {
+        operation,
+        remediation: `switch to ${requiredBranch} first (git switch ${requiredBranch})`,
+        stderrExcerpt: `current branch is "${currentBranch}", expected "${requiredBranch}"`,
+      })
+    }
+  }
+
+  if (!(await isWorkingTreeClean())) {
+    throw new OperationError(undefined, {
+      operation,
+      remediation: 'commit or stash your changes, then retry',
+      stderrExcerpt: 'working tree has uncommitted changes',
+    })
+  }
+}

package/src/lib/git-guard/index.ts

@@ -0,0 +1,2 @@
+export { assertManagementContext } from './git-guard'
+export type { AssertManagementContextArgs } from './git-guard'

package/src/lib/git-utils/__tests__/git-primitives.test.ts

@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getCurrentBranch, isInsideLinkedWorktree, isWorkingTreeClean } from 'src/lib/git-utils'
+
+// Controllable per-command git output. The mocked `$` dispatches on the command
+// text so a single test can make `--absolute-git-dir` and `--git-common-dir`
+// return DIFFERENT values — which the shared single-stdout mock cannot express.
+const git = vi.hoisted(() => {
+  return {
+    toplevel: '/repo',
+    branch: 'dev',
+    status: '',
+    absoluteGitDir: '/repo/.git',
+    commonDir: '.git',
+  }
+})
+
+vi.mock('zx', () => {
+  const run = (strings: TemplateStringsArray): Promise<{ stdout: string }> => {
+    const command = strings.join('')
+
+    if (command.includes('--show-toplevel')) return Promise.resolve({ stdout: `${git.toplevel}\n` })
+    if (command.includes('--abbrev-ref HEAD')) return Promise.resolve({ stdout: `${git.branch}\n` })
+    if (command.includes('status --porcelain')) return Promise.resolve({ stdout: git.status })
+    if (command.includes('--absolute-git-dir')) return Promise.resolve({ stdout: `${git.absoluteGitDir}\n` })
+    if (command.includes('--git-common-dir')) return Promise.resolve({ stdout: `${git.commonDir}\n` })
+
+    return Promise.resolve({ stdout: '' })
+  }
+
+  // zx's `$` supports both tagged-template form (`$`...``) and an options form
+  // (`$({ cwd })`...``) that returns a fresh tagged-template function.
+  const $ = vi.fn((first: unknown) => {
+    if (!Array.isArray(first)) {
+      return (strings: TemplateStringsArray) => {
+        return run(strings)
+      }
+    }
+
+    return run(first as unknown as TemplateStringsArray)
+  })
+
+  return { $ }
+})
+
+describe('getCurrentBranch', () => {
+  beforeEach(() => {
+    git.branch = 'dev'
+  })
+
+  it('returns the trimmed branch name', async () => {
+    git.branch = 'release/v1.2.3'
+
+    await expect(getCurrentBranch()).resolves.toBe('release/v1.2.3')
+  })
+})
+
+describe('isWorkingTreeClean', () => {
+  it('returns true when porcelain output is empty', async () => {
+    git.status = ''
+
+    await expect(isWorkingTreeClean()).resolves.toBe(true)
+  })
+
+  it('returns true when porcelain output is whitespace only', async () => {
+    git.status = '\n'
+
+    await expect(isWorkingTreeClean()).resolves.toBe(true)
+  })
+
+  it('returns false when there are changes', async () => {
+    git.status = ' M src/foo.ts\n?? new.ts\n'
+
+    await expect(isWorkingTreeClean()).resolves.toBe(false)
+  })
+})
+
+describe('isInsideLinkedWorktree', () => {
+  beforeEach(() => {
+    git.toplevel = '/repo'
+  })
+
+  it('returns false in the main checkout (git dir resolves to the common dir)', async () => {
+    git.absoluteGitDir = '/repo/.git'
+    git.commonDir = '.git'
+
+    await expect(isInsideLinkedWorktree()).resolves.toBe(false)
+  })
+
+  it('returns true in a linked worktree (git dir under .git/worktrees, differs from common dir)', async () => {
+    git.absoluteGitDir = '/repo/.git/worktrees/release-v1.2.3'
+    git.commonDir = '/repo/.git'
+
+    await expect(isInsideLinkedWorktree()).resolves.toBe(true)
+  })
+})