@idea1/cli 1.5.2 → 1.6.1

package/README.md

@@ -15,15 +15,19 @@ npm install -g @idea1/cli
 Run commands directly from the command line:
 
 ```bash
-# Start implementing a project item
-idea1 start-project-item https://app.idea1.ai/project/items/590
-idea1 -s https://app.idea1.ai/project/items/590
+# Put a project item under workflow management (branch + metadata, no code changes)
+idea1 start --url https://app.idea1.ai/project/items/590
 
-# Workflow transitions
+# Advance the item to its next workflow state (runs that state's automation)
+idea1 next --url https://app.idea1.ai/project/items/590   # or just `idea1 next` on the item's branch
+
+# Jump straight to Agent Implementation (worktree + Claude) — the "send for implementation" path
+idea1 start-agent-implementation --url https://app.idea1.ai/project/items/590   # alias: start-project-item
+
+# Dedicated transitions (each is one `next` step)
 idea1 start-dev-implementation  # or: idea1 dev
-idea1 ready-for-approval john   # or: idea1 rfa john
+idea1 ready-for-approval        # or: idea1 rfa
 idea1 approve-pr                # or: idea1 approve
-idea1 next-workflow-step        # or: idea1 next
 
 # Show help
 idea1 --help
@@ -37,45 +41,99 @@ Run `idea1` without arguments to enter interactive mode with a searchable comman
 
 ## Workflow Commands
 
-The CLI provides a complete workflow automation system with state tracking. The workflow progresses through these states:
+Every project item moves through the same sequence of workflow states:
 
 ```
-Agent Implementation → Dev Implementation → Needs Approval for Release → Approved and Merged
+Build Spec in Progress → Refinement - Build Spec → Refinement - Implementation → Ready for Agent Implementation
+  → Agent Implementation → Dev Implementation → Needs Approval for Release → Approved and Merged → Released
 ```
 
-These are the CLI-driven stages of the full team workflow sequence: `Build Spec in Progress` → `Refinement - Build Spec` → `Refinement - Implementation` → `Ready for Agent Implementation` → `Agent Implementation` → `Dev Implementation` → `Needs Approval for Release` → `Approved and Merged` → `Released`. The earlier states happen in idea1.ai before implementation starts, and `Released` is set by GitHub automation when the work merges to `main`.
+The state names and their order are defined once, in `shared-config/workflow-states.json`, and shared with the backend and the web client (see `scripts/generate-workflow-states.js`).
+
+### How the workflow engine works
+
+An item **under workflow management** has exactly one branch on origin that carries `.idea1/<branch>.json` with the item's URL and current `workflowState`. That committed file is the durable, shared record: the idea1.ai web client writes the same file when a state is advanced from the browser, and every CLI command first syncs the branch's state from origin (adopting the metadata into local git config and fast-forwarding a local checkout when it is behind) — so the CLI and the web client never disagree.
+
+A transition is "enter state X". Entering a state runs that state's automation (a *handler*), then records the new state in the branch metadata, in local git config and on the idea1.ai item. Most states have no automation; the implementation states do:
+
+| Entering | Automation |
+|----------|-----------|
+| Build Spec in Progress … Ready for Agent Implementation | none — status only |
+| **Agent Implementation** | ensures the branch is checked out locally (worktree or main repo), then **launches Claude** to implement the item. This is the only transition that starts code-writing automation |
+| **Dev Implementation** | commits and pushes the agent's work, creates the PR, removes the worktree if `removeWorktreeAtState` says so |
+| **Needs Approval for Release** | requires the PR, requests reviewers / sets the assignee, removes the worktree if configured |
+| **Approved and Merged** | approves (when you are a requested reviewer), removes the metadata file, merges the PR, deletes the branch and worktree |
+| Released | none — normally set by GitHub automation when the work merges to `main` |
 
-### start-project-item
+`start` begins state management, `next` advances one state, and `start-agent-implementation` jumps to Agent Implementation — all three reduce to the same engine, so branches and items always end up consistent with the state they are in.
 
-Start implementing an Idea1.ai project item, either in an isolated git worktree or directly in the main repository.
+### start
+
+Put a project item under workflow management. An item that has never been started enters **Build Spec in Progress**; an item that already has a state keeps it. The branch is created on origin from the base branch with the metadata file as its first commit — nothing is checked out, no code is written and Claude is not launched. Idempotent: running it again for a managed item just reports the branch and state.
 
 ```bash
-idea1 start-project-item <url> [branch-name] [options]
-idea1 -s <url> [branch-name] [options]
+idea1 start --url <url> [options]
+idea1 start                       # prompts for the URL (blank to create a new item)
+idea1 s --url <url>
 ```
 
-**Arguments:**
-- `<url>` - The Idea1.ai project item URL (required)
-- `[branch-name]` - Custom branch name (optional, auto-generated from item description if not provided)
+**Options:**
+- `-u, --url <url>` - The Idea1.ai project item URL. Leave blank to create a new item (you'll be prompted for a `--title`).
+- `-t, --title <title>` - Title for the new project item (only when no URL is given).
+- `-p, --source-path <path>` - Path to source directory.
+- `-n, --branch-name <name>` - Branch name (auto-generated from the item description if not provided).
+- `-b, --base-branch <branch>` - Base branch / PR target (default: `working/release`).
+- `-w, --workflow-type <type>` - `independent` or `integration`; you also choose any stack branch and (for integration) the integration branch.
+
+### next-workflow-step
+
+Advance a project item to its next workflow state and run that state's automation. On the item's branch no arguments are needed; from anywhere else pass the item URL — the CLI finds the branch on origin (moving into its local checkout when one exists) or, for an item without a branch yet, reads the current state from idea1.ai and creates the branch first.
+
+With `--to <state>` the item advances through every state up to that one in a single run — the same as running `next` once per state, with each state's automation in order. The CLI only moves forward; an item already at or past the requested state is reported as an error.
+
+```bash
+idea1 next                        # on the item's branch
+idea1 next --url <url>            # from anywhere in the repository
+idea1 next --to "Dev Implementation"   # several states at once
+idea1 n
+```
 
 **Options:**
-- `-p, --source-path <path>` - Path to source directory
-- `-b, --base-branch <branch>` - Base branch (default: `working/release`). Use `prompt` to interactively select.
-- `-pm, --permission-mode <mode>` - Claude permission mode (default: `plan`). Valid values: `acceptEdits`, `bypassPermissions`, `default`, `delegate`, `dontAsk`, `plan`
-- `-iso, --isolation <mode>` - Where to work on the branch (default: `worktree`). See [Isolation mode](#isolation-mode).
-- `--claude-entry-point <mode>` - How Claude is invoked after setup (default: `launch`). Valid values: `launch` (start a new Claude session), `inline` (output structured prompt for an already-running Claude session), `none` (do not invoke Claude)
+- `-u, --url <url>` - Project item URL (required when not on the item's branch).
+- `--to <state>` - Workflow state to advance to (default: the next state).
+- `-p, --source-path <path>` - Path to source directory.
+- Any option of the state being entered (for example `--model`/`--effort` for Agent Implementation, `--assignee`/`--reviewers` for Needs Approval for Release). Options that were not supplied are prompted for when that state is reached.
 
 **What it does:**
-1. Sets the item's workflow status to "Agent Implementation"
-2. Generates a branch name from the item description (if not provided)
-3. Creates a new branch from the base branch
-4. Sets up the working environment: a git worktree for isolated development, or the branch checked out in the main repository
-5. Runs any setup hooks defined in `.idea1/settings.json` (worktree mode only)
-6. Launches Claude Code with the implementation prompt
+1. Syncs the branch's workflow state from origin (picking up changes made in the web client).
+2. Puts the item under workflow management if it is not yet (a never-started item enters Build Spec in Progress, which is the whole step).
+3. Runs the automation of every state entered, records the new state on the branch, in git config and on idea1.ai.
+4. Reports "Workflow is complete" at `Released`.
+
+The automation is idempotent, so re-running a transition after the item was moved back in the web client does not repeat work that is already done: an existing PR is reused, an already-merged PR is left alone and the item simply moves on.
+
+### start-agent-implementation
+
+Start implementing a project item: put it under workflow management if needed, move it to **Agent Implementation** (through any intermediate states, which have no automation), set up the working environment and launch Claude Code with the implementation prompt. This is the command behind "Send for Implementation" in the web client; `start-project-item` remains an alias so existing team command templates keep working.
+
+```bash
+idea1 start-agent-implementation --url <url> [options]
+idea1 implement --url <url>
+idea1 start-project-item --url <url>     # alias
+```
+
+**Options:** all `start` options, plus the Agent Implementation options:
+- `-iso, --isolation <mode>` - Where to work on the branch (default: `worktree`). See [Isolation mode](#isolation-mode).
+- `-pm, --permission-mode <mode>` - Claude permission mode (default: `plan`). Valid values: `acceptEdits`, `bypassPermissions`, `default`, `delegate`, `dontAsk`, `plan`
+- `-m, --model <model>` - Claude model for the implementation session (default: `opus`). Valid values: `fable`, `opus`, `sonnet`, `haiku`
+- `-e, --effort <level>` - Claude effort level (default: `high`). Valid values: `low`, `medium`, `high`, `xhigh`, `max`
+- `-im, --claude-entry-point <mode>` - How Claude is invoked once the environment is ready (default: `launch`). Valid values: `launch` (start a new Claude session), `inline` (output a structured prompt for an already-running Claude session), `none` (do not invoke Claude)
+
+An item already in Agent Implementation is not transitioned again: the working environment is set up (or reused) and Claude is launched.
 
 ### Isolation mode
 
-`start-project-item` and `join-project-item` both ask where you want to work on the branch. The prompt is always shown, with `worktree` preselected:
+`start-agent-implementation`, `next` (when entering Agent Implementation) and `join-project-item` all ask where you want to work on the branch. The prompt is always shown, with `worktree` preselected:
 
 - `worktree` (default) - creates/uses a git worktree in a sibling directory (`<repo>-<branch>`), leaving the main repository on its own branch. Runs the `setup-worktree` hook.
 - `main-repo` - checks the branch out in the main repository, in place. Requires a clean working directory and fails if the branch is already checked out in a worktree. The `setup-worktree` hook is skipped, since the main repository is already set up.
@@ -84,62 +142,57 @@ Supply `-iso worktree` or `-iso main-repo` on the command line to skip the promp
 
 ### join-project-item
 
-Join an **in-progress** project item by setting up a working environment on its existing branch — for picking up work started elsewhere (e.g. on another machine or by another developer). Unlike `start-project-item`, it does not create a branch or launch a Claude implementation session.
+Join an **in-progress** project item by setting up a working environment on its existing branch — for picking up work started elsewhere (e.g. on another machine, by another developer, or from the web client). It does not change the workflow state and never launches a Claude implementation session.
 
 ```bash
 idea1 join-project-item --project-item-url <url>
 idea1 join-project-item --branch-name <branch>
-idea1 -j --branch-name <branch>
+idea1 join-project-item --pull-request-url <pr url>
+idea1 j --branch-name <branch>
 ```
 
-**Options (exactly one of the first two must be supplied — they are mutually exclusive):**
+**Options (exactly one of the first three must be supplied — they are mutually exclusive):**
 - `--project-item-url <url>` - The Idea1.ai project item URL; its branch is discovered automatically.
 - `-n, --branch-name <branch>` - The branch to join; its associated project item is discovered automatically.
+- `--pull-request-url <url>` - A GitHub PR URL; its head branch is joined.
 - `-p, --source-path <path>` - Path to source directory.
 - `-iso, --isolation <mode>` - Where to work on the branch (default: `worktree`). See [Isolation mode](#isolation-mode).
-- `-pm, --permission-mode <mode>` - Claude permission mode (default: `plan`).
-- `-e, --effort <level>` - Claude effort level (default: `high`).
-
-In interactive mode, if neither option is supplied you are prompted to choose which to use.
+- `-pm, --permission-mode <mode>`, `-m, --model <model>`, `-e, --effort <level>` - Claude session settings recorded for the environment (defaults: `plan`, `opus`, `high`).
 
 **What it does:**
 1. Resolves the branch from the URL (or the URL from the branch) using the committed branch metadata.
-2. Sets up the working environment on the existing branch — a git worktree, or the branch checked out in the main repository (creating a local tracking branch if it only exists on the remote).
-3. Re-establishes local workflow state (project item URL, base branch, workflow state, dev workflow type, stack/integration branch) from the committed `.idea1/<branch>.json` metadata.
-4. If the branch was never properly set up, seeds the same defaults as `start-project-item` (`Agent Implementation` / `independent`) and pushes the recovered metadata to the remote.
-5. Runs any setup hooks defined in `.idea1/settings.json` (worktree mode only). It does **not** launch a Claude implementation session.
+2. Reuses the checkout that already holds the branch, or sets one up — a git worktree, or the branch checked out in the main repository (creating a local tracking branch if it only exists on origin).
+3. Syncs the workflow state from the metadata committed on origin into local git config, defaulting a legacy branch with no recorded state to `Agent Implementation`, and pushes any recovered metadata back to origin.
+4. Runs any setup hooks defined in `.idea1/settings.json` (newly created worktrees only).
 
-If a project item URL is supplied but no branch exists for it yet (the item was never started), `join-project-item` falls back to the `start-project-item` setup flow, without launching the implementation session.
+If a project item URL is supplied but no branch exists for it yet, `join-project-item` puts the item under workflow management first (as `start` does) and then sets up the environment.
 
 ### attach-project-item
 
-Attach the **current branch** to a project item, wiring it up as if the branch had been created by `start-project-item`. Use this when you already have a branch with work on it and want to bring it into the workflow. Unlike `start-project-item`, it does not create a branch or a worktree and never invokes Claude.
+Attach the **current branch** to a project item, putting it under workflow management at the item's current state (or `Build Spec in Progress` when it has none). Use this when you already have a branch with work on it and want to bring it into the workflow. It does not create a branch or a worktree and never invokes Claude.
 
 ```bash
 idea1 attach-project-item --url <url>
 idea1 attach-project-item                 # prompts for the URL (blank to create a new item)
-idea1 -a --url <url>
+idea1 a --url <url>
 ```
 
 **Options:**
-- `--url <url>` - The Idea1.ai project item URL. Leave blank to create a new item (you'll be prompted for a `--title`).
+- `-u, --url <url>` - The Idea1.ai project item URL. Leave blank to create a new item (you'll be prompted for a `--title`).
 - `-t, --title <title>` - Title for the new project item (only when no URL is given).
 - `-p, --source-path <path>` - Path to source directory.
 - `-b, --base-branch <branch>` - Base branch / PR target for an independent feature (default: `working/release`).
-- `-w, --workflow-type <type>` - Development workflow type: `independent` or `integration`. As with `start-project-item`, you choose any stack branch and (for integration) the integration branch.
+- `-w, --workflow-type <type>` - Development workflow type: `independent` or `integration`. You also choose any stack branch and (for integration) the integration branch.
 
 **What it does:**
 1. Verifies the current branch is not already attached to a project item (errors if it is — use `join-project-item` to resume instead).
-2. Creates the project item if no URL was supplied.
-3. Lets you choose a stack branch and, for integration work, the integration branch — exactly like `start-project-item`.
-4. Sets the item's workflow status to "Agent Implementation".
-5. Records the per-branch metadata (project item URL, base branch, workflow state, dev workflow type, stack/integration branch) in git config and the committed `.idea1/<branch>.json` file.
-6. Commits the metadata and pushes the current branch so it is up to date with its metadata.
-7. Sets up a PR into the base branch (the integration branch for integration work), just like `start-project-item` targets it.
+2. Creates the project item if no URL was supplied, and reads its current workflow state from idea1.ai.
+3. Records the per-branch metadata (project item URL, base branch, workflow state, dev workflow type, stack/integration branch) in git config and the committed `.idea1/<branch>.json` file, and pushes the branch.
+4. Records the branch on the idea1.ai item. If the item is already at `Dev Implementation` or later, makes sure a PR into the base branch exists.
 
 ### start-dev-implementation
 
-Transition from agent implementation to dev implementation - commits, pushes, and creates PR.
+Enter **Dev Implementation** from Agent Implementation — the same step `next` takes from that state.
 
 ```bash
 idea1 start-dev-implementation [options]
@@ -150,39 +203,35 @@ idea1 dev [options]
 - `-p, --source-path <path>` - Path to worktree directory
 
 **What it does:**
-1. Validates current state is "Agent Implementation"
+1. Validates the current state is "Agent Implementation" (after syncing from origin)
 2. Commits and pushes all changes in the branch
 3. Creates a PR of the branch into its base branch
-4. If in a worktree and `removeWorktreeAtState` is set to `Dev Implementation`, removes the worktree. The main repo stays on its current branch; the user can choose to use `join-project-item` as a command to work on the project item in the main repo or a new worktree.
-5. Updates workflow state to "Dev Implementation"
-6. Updates Idea1.ai workflow status
+4. Records "Dev Implementation" in the branch metadata, git config and on Idea1.ai
+5. If in a worktree and `removeWorktreeAtState` is `Dev Implementation`, removes the worktree. The main repo stays on its current branch; use `join-project-item` to work on the item in the main repo or a new worktree.
 
 ### ready-for-approval
 
-Mark a PR as ready for approval and optionally assign a reviewer.
+Enter **Needs Approval for Release** from Dev Implementation — the same step `next` takes from that state.
 
 ```bash
-idea1 ready-for-approval [reviewer] [options]
-idea1 rfa [reviewer] [options]
+idea1 ready-for-approval [options]
+idea1 rfa --assignee octocat --reviewers octocat,hubot
 ```
 
-**Arguments:**
-- `[reviewer]` - GitHub username of reviewer (optional)
-
 **Options:**
-- `-r, --reviewer <username>` - GitHub username of reviewer
+- `-a, --assignee <username>` - Who to assign the PR to (prompted from the repository's assignable users when omitted; choose "(none)" to skip)
+- `-r, --reviewers <user1,user2>` - Who to request a review from (multi-select when omitted)
 
 **What it does:**
-1. Validates current state is "Dev Implementation"
-2. Ensures no uncommitted or unpushed changes
-3. Assigns reviewer to the PR (if provided)
-4. Updates workflow state to "Needs Approval for Release"
-5. Updates Idea1.ai workflow status
-6. If in a worktree and `removeWorktreeAtState` is `Needs Approval for Release` (the default) or earlier, removes the worktree and checks the branch out in the main repo
+1. Validates the current state is "Dev Implementation" (after syncing from origin)
+2. Ensures no uncommitted or unpushed changes in the local checkout
+3. Requires the PR to exist, then requests reviews and sets the assignee
+4. Records "Needs Approval for Release" in the branch metadata, git config and on Idea1.ai
+5. If in a worktree and `removeWorktreeAtState` is `Needs Approval for Release` (the default) or earlier, removes the worktree
 
 ### approve-pr
 
-Approve and merge a PR, completing the workflow.
+Enter **Approved and Merged** from Needs Approval for Release — the same step `next` takes from that state.
 
 ```bash
 idea1 approve-pr [options]
@@ -193,29 +242,11 @@ idea1 approve [options]
 - `-c, --comment <message>` - Custom approval comment (default: "Approved via idea1 CLI workflow")
 
 **What it does:**
-1. Validates current state is "Needs Approval for Release"
-2. Checks if PR is already approved (skips approval if so)
-3. Approves the PR with comment
-4. Merges the PR
-5. Updates workflow state to "Approved and Merged"
-6. Updates Idea1.ai workflow status
-7. Switches to base branch and deletes the feature branch. If still running inside a worktree, removes the worktree instead of switching branches — this always happens, since the base branch can't be checked out in place there
-
-### next-workflow-step
-
-Automatically perform the next workflow transition based on current state.
-
-```bash
-idea1 next-workflow-step
-idea1 next
-idea1 n
-```
-
-**What it does:**
-1. Detects current workflow state
-2. Determines the next valid transition
-3. Executes the appropriate command automatically
-4. If workflow is complete, informs user
+1. Validates the current state is "Needs Approval for Release" (after syncing from origin)
+2. Approves the PR when you are a requested reviewer who has not approved yet
+3. Removes the branch's `.idea1/<branch>.json` so it does not leak into the target branch, then merges the PR (offering an admin override when branch protections block the merge)
+4. Records "Approved and Merged" in git config and on Idea1.ai
+5. Switches to the base branch and deletes the feature branch. If still running inside a worktree, removes the worktree instead of switching branches — this always happens, since the base branch can't be checked out in place there
 
 ## Configuration
 

package/dist/commands/approve-pr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approve-pr.d.ts","sourceRoot":"","sources":["../../src/commands/approve-pr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AASjD,eAAO,MAAM,gBAAgB,EAAE,OAyL9B,CAAC"}
+{"version":3,"file":"approve-pr.d.ts","sourceRoot":"","sources":["../../src/commands/approve-pr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAKjD,eAAO,MAAM,gBAAgB,EAAE,OAW9B,CAAC"}

package/dist/commands/approve-pr.js

@@ -1,171 +1,15 @@
-import { logger } from '../lib/logger.js';
-import * as git from '../services/git.js';
-import * as github from '../services/github.js';
-import * as claude from '../services/claude.js';
-import * as workflow from '../services/workflow.js';
-import { resolveBaseBranch, removeCurrentWorktree } from '../services/worktree.js';
-import { promptConfirm } from '../lib/prompt.js';
+import { WorkflowStates } from '../lib/workflow-states.js';
+import { advanceTo, requireCurrentState, resolveContext } from '../services/workflow-engine.js';
+import { approvePrHandler } from '../services/workflow-handlers/approve-pr.js';
 export const approvePrCommand = {
     name: 'approve-pr',
     aliases: ['approve'],
     description: 'Approve and merge the PR, completing the workflow',
-    options: [
-        {
-            longName: 'comment',
-            shortName: 'c',
-            description: 'Custom approval comment',
-            defaultValue: '',
-            promptWhenDefaultExists: false
-        }
-    ],
+    options: approvePrHandler.options,
     async execute(resolved) {
-        const comment = resolved['comment'] || undefined;
-        // Validate transition
-        const validation = await workflow.validateTransition('approve-pr');
-        if (!validation.valid) {
-            throw new Error(validation.error ?? 'Invalid transition');
-        }
-        // Ensure workflow preconditions
-        await workflow.ensureWorkflowPreconditions();
-        // Get branch info
-        const branchName = await git.getCurrentBranch();
-        const projectItemUrl = await git.getProjectItemUrl();
-        const baseBranch = await git.getBaseBranch() ?? 'working/release';
-        const isWorktree = await git.isInsideWorktree();
-        const mainRepoRoot = await git.getMainRepoRoot();
-        if (!projectItemUrl) {
-            throw new Error('No project item URL found for this branch.');
-        }
-        logger.info(`Current branch: ${branchName}`);
-        logger.info(`Base branch: ${baseBranch}`);
-        // Check PR exists
-        const prInfo = await github.getPrInfo(branchName);
-        if (!prInfo) {
-            logger.warning('No PR found for this branch. Nothing to approve.');
-            return;
-        }
-        logger.info(`PR #${prInfo.number} found`);
-        // Check if the current user should approve (is a reviewer and hasn't approved)
-        const approvalStatus = await github.getUserApprovalStatus(branchName);
-        if (approvalStatus) {
-            if (approvalStatus.hasAlreadyApproved) {
-                logger.dim('You have already approved this PR');
-            }
-            else if (approvalStatus.isRequestedReviewer) {
-                // User is a reviewer and hasn't approved yet - approve
-                const approvalComment = comment ?? 'Approved via idea1 CLI workflow';
-                const approved = await github.approvePr(branchName, approvalComment);
-                if (!approved) {
-                    logger.warning('Failed to approve PR, continuing with merge...');
-                }
-            }
-            else {
-                logger.dim('You are not a requested reviewer on this PR');
-            }
-        }
-        else {
-            logger.dim('Could not determine approval status, skipping approval');
-        }
-        // Remove branch metadata file before merge so it doesn't leak into target branch
-        await git.removeBranchMetadataAndPush(branchName);
-        // Confirm before merging
-        const confirmMerge = await promptConfirm(`Merge PR #${prInfo.number} (${branchName} -> ${baseBranch})?`, { default: true });
-        if (!confirmMerge) {
-            throw new Error('Merge cancelled by user');
-        }
-        // Merge the PR
-        const mergeResult = await github.mergePr(branchName);
-        if (!mergeResult.success) {
-            // Check if failure is due to branch protections / policies. `gh pr merge`
-            // emits a variety of messages depending on the rule that blocked the merge
-            // (branch protection rules, rulesets, repository policies). When admin
-            // privileges can resolve it, gh explicitly suggests the `--admin` flag, so
-            // match on that as the most reliable signal in addition to known wordings.
-            const errorText = mergeResult.error?.toLowerCase() ?? '';
-            const isBranchProtectionError = errorText.includes('branch protection') ||
-                errorText.includes('required status check') ||
-                errorText.includes('required review') ||
-                errorText.includes('pull request review is required') ||
-                errorText.includes('base branch policy') ||
-                errorText.includes('policy prohibits the merge') ||
-                errorText.includes('--admin');
-            if (isBranchProtectionError) {
-                logger.warning('Merge failed due to branch protections');
-                logger.dim(mergeResult.error ?? '');
-                // Ask user if they want to override
-                const override = await promptConfirm('Would you like to override branch protections with admin privileges?', { default: false });
-                if (override) {
-                    const adminMergeResult = await github.mergePrWithAdminOverride(branchName);
-                    if (!adminMergeResult.success) {
-                        throw new Error(`Failed to merge PR with admin override: ${adminMergeResult.error}`);
-                    }
-                }
-                else {
-                    throw new Error('Merge cancelled by user');
-                }
-            }
-            else {
-                throw new Error(`Failed to merge PR: ${mergeResult.error}`);
-            }
-        }
-        // Update workflow state before switching branches
-        await git.storeWorkflowState('Approved and Merged');
-        await claude.setWorkflowStatus(projectItemUrl, 'Approved and Merged');
-        await git.fetchLatest();
-        // If running inside a worktree, the feature branch is checked out here and we
-        // can't switch back to the base branch in place. Remove the worktree instead
-        // and exit so the user can change to whatever folder they need. This happens
-        // regardless of removeWorktreeAtState — 'Approved and Merged' is the last CLI-driven workflow state.
-        if (isWorktree) {
-            const worktreePath = await removeCurrentWorktree(mainRepoRoot);
-            // Delete the feature branch locally and remotely (the worktree no longer holds it)
-            try {
-                await git.deleteBranch(branchName, true);
-            }
-            catch {
-                // Branch might already be deleted on remote after merge
-                logger.dim(`Note: Branch ${branchName} may have been automatically deleted after merge`);
-            }
-            logger.newline();
-            logger.success('Workflow complete!');
-            logger.newline();
-            logger.hint(`PR merged into ${baseBranch}`);
-            logger.hint(`Worktree removed: ${worktreePath}`);
-            logger.hint(`Change to a different folder (e.g. ${mainRepoRoot}) to continue.`);
-            logger.hint(`Project item: ${projectItemUrl}`);
-            return;
-        }
-        // Switch to base branch (it may be in another worktree, e.g. the main repo)
-        const baseWorktreePath = await git.getWorktreePathForBranch(baseBranch);
-        if (baseWorktreePath) {
-            // Base branch (e.g. integration branch) is in another worktree — pull there,
-            // then checkout the settings-level base branch instead
-            logger.step(`Base branch ${baseBranch} is in a worktree at ${baseWorktreePath}, pulling there...`);
-            await git.updateBranchToLatest(baseBranch);
-            const settingsBaseBranch = await resolveBaseBranch();
-            logger.step(`Checking out ${settingsBaseBranch}...`);
-            await git.checkoutAndPullBranch(settingsBaseBranch);
-        }
-        else {
-            logger.step(`Pulling latest from ${baseBranch}...`);
-            await git.checkoutAndPullBranch(baseBranch);
-        }
-        // Delete the feature branch locally and remotely
-        try {
-            await git.deleteBranch(branchName, true);
-        }
-        catch {
-            // Branch might already be deleted on remote after merge
-            logger.dim(`Note: Branch ${branchName} may have been automatically deleted after merge`);
-        }
-        logger.newline();
-        logger.success('Workflow complete!');
-        logger.newline();
-        logger.hint(`PR merged into ${baseBranch}`);
-        if (baseWorktreePath) {
-            logger.hint(`Base branch is in worktree at: ${baseWorktreePath}`);
-        }
-        logger.hint(`Project item: ${projectItemUrl}`);
+        const context = await resolveContext({ options: resolved });
+        requireCurrentState(context, WorkflowStates.NeedsApprovalForRelease, 'approve-pr');
+        await advanceTo(context, WorkflowStates.ApprovedAndMerged);
     }
 };
 //# sourceMappingURL=approve-pr.js.map

package/dist/commands/approve-pr.js.map

@@ -1 +1 @@
-{"version":3,"file":"approve-pr.js","sourceRoot":"","sources":["../../src/commands/approve-pr.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approve-pr.js","sourceRoot":"","sources":["../../src/commands/approve-pr.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAE/E,MAAM,CAAC,MAAM,gBAAgB,GAAY;IACvC,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,WAAW,EAAE,mDAAmD;IAChE,OAAO,EAAE,gBAAgB,CAAC,OAAO;IAEjC,KAAK,CAAC,OAAO,CAAC,QAAgC;QAC5C,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5D,mBAAmB,CAAC,OAAO,EAAE,cAAc,CAAC,uBAAuB,EAAE,YAAY,CAAC,CAAC;QACnF,MAAM,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC7D,CAAC;CACF,CAAC"}

package/dist/commands/attach-project-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attach-project-item.d.ts","sourceRoot":"","sources":["../../src/commands/attach-project-item.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,mBAAmB,CAAC;AAelE,eAAO,MAAM,wBAAwB,EAAE,OA4ItC,CAAC"}
+{"version":3,"file":"attach-project-item.d.ts","sourceRoot":"","sources":["../../src/commands/attach-project-item.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AASjD,eAAO,MAAM,wBAAwB,EAAE,OAwFtC,CAAC"}