fix: merge conflicts flow (#33)

* docs: add readme

* feat: add slack notifications

* fix: ci

* fix: ticket move after error

* feat: add option to authenticate with claude token

* fix: merge conflicts flow (#32)

Author: kasin-it

e2e/env.ts

@@ -12,9 +12,9 @@ const schema = z.object({
   COLUMN_AI_REVIEW: z.string().min(1),
   COLUMN_BACKLOG: z.string().min(1),
 
-  GITHUB_TOKEN: z.string().min(1),
-  GITHUB_OWNER: z.string().min(1),
-  GITHUB_REPO: z.string().min(1),
+  E2E_GITHUB_TOKEN: z.string().min(1),
+  E2E_GITHUB_OWNER: z.string().min(1),
+  E2E_GITHUB_REPO: z.string().min(1),
 
   CRON_SECRET: z.string().min(1),
 

e2e/helpers/github.ts

@@ -1,15 +1,15 @@
 import { Octokit } from "@octokit/rest";
 import { e2eEnv } from "../env.js";
 
-const octokit = new Octokit({ auth: e2eEnv.GITHUB_TOKEN });
-const ownerRepo = { owner: e2eEnv.GITHUB_OWNER, repo: e2eEnv.GITHUB_REPO };
+const octokit = new Octokit({ auth: e2eEnv.E2E_GITHUB_TOKEN });
+const ownerRepo = { owner: e2eEnv.E2E_GITHUB_OWNER, repo: e2eEnv.E2E_GITHUB_REPO };
 
 export async function findPR(
   branchName: string,
 ): Promise<{ number: number; url: string } | null> {
   const { data } = await octokit.pulls.list({
     ...ownerRepo,
-    head: `${e2eEnv.GITHUB_OWNER}:${branchName}`,
+    head: `${e2eEnv.E2E_GITHUB_OWNER}:${branchName}`,
     state: "open",
   });
   if (data.length === 0) return null;

e2e/tier2/stop-hook-commit.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, afterAll } from "vitest";
+import { e2eEnv } from "../env.js";
+
+/**
+ * Verifies the Stop hook forces Claude Code to commit uncommitted changes
+ * before exiting in --print mode.
+ *
+ * Flow:
+ *   1. Create a sandbox from the e2e repo
+ *   2. Install Claude Code + configure the Stop hook
+ *   3. Create an uncommitted file
+ *   4. Run Claude Code with a simple prompt (--print mode)
+ *   5. Assert git status is clean (hook forced a commit)
+ */
+describe("Stop hook commit guard", () => {
+  let sandbox: any;
+
+  afterAll(async () => {
+    if (sandbox) await sandbox.stop().catch(() => {});
+  });
+
+  it("forces Claude Code to commit uncommitted changes before stopping", async () => {
+    const { Sandbox } = await import("@vercel/sandbox");
+
+    sandbox = await Sandbox.create({
+      source: {
+        type: "git",
+        url: `https://github.com/${e2eEnv.E2E_GITHUB_OWNER}/${e2eEnv.E2E_GITHUB_REPO}.git`,
+        username: "x-access-token",
+        password: e2eEnv.E2E_GITHUB_TOKEN,
+        revision: "main",
+        depth: 1,
+      },
+      runtime: "node24",
+      timeout: 300_000,
+      env: {
+        ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? "",
+        ...(process.env.CLAUDE_CODE_OAUTH_TOKEN
+          ? { CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN }
+          : {}),
+      },
+    });
+
+    // 1. Configure git identity
+    await sandbox.runCommand("bash", [
+      "-c",
+      'git config user.name "test-bot" && git config user.email "test@test.com"',
+    ]);
+
+    // 2. Install Claude Code
+    await sandbox.runCommand("npm", [
+      "install",
+      "-g",
+      "@anthropic-ai/claude-code",
+    ]);
+
+    // 3. Set up the Stop hook (same as SandboxManager.provision)
+    await sandbox.runCommand("bash", [
+      "-c",
+      [
+        `mkdir -p ~/.claude`,
+        `cat > ~/.claude/commit-guard.sh << 'SCRIPT'`,
+        `#!/bin/bash`,
+        `input=$(cat)`,
+        `if echo "$input" | grep -q '"stop_hook_active":true'; then exit 0; fi`,
+        `changes=$(git status --porcelain | grep -v '^.. \\.claude/' | grep -v '^?? \\.claude/' | grep -v 'requirements\\.md')`,
+        `if [ -n "$changes" ]; then`,
+        `  echo '{"decision":"block","reason":"You have uncommitted changes. You MUST either commit all changes with a descriptive message or revert them before stopping."}' >&2`,
+        `  exit 2`,
+        `fi`,
+        `SCRIPT`,
+        `chmod +x ~/.claude/commit-guard.sh`,
+        `cat > ~/.claude/settings.json << 'JSON'`,
+        `{"hooks":{"Stop":[{"matcher":"","hooks":[{"type":"command","command":"bash ~/.claude/commit-guard.sh"}]}]}}`,
+        `JSON`,
+      ].join("\n"),
+    ]);
+
+    // 4. Skip onboarding (if using OAuth token)
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+      await sandbox.runCommand("bash", [
+        "-c",
+        `echo '{"hasCompletedOnboarding":true}' > ~/.claude.json`,
+      ]);
+    }
+
+    // 5. Create an uncommitted file (simulates agent work without committing)
+    await sandbox.runCommand("bash", [
+      "-c",
+      'echo "test content" > test-uncommitted.txt',
+    ]);
+
+    // Verify the file is uncommitted
+    const beforeStatus = await sandbox.runCommand("git", [
+      "status",
+      "--porcelain",
+    ]);
+    const beforeOutput = (await beforeStatus.stdout()).trim();
+    expect(beforeOutput).toContain("test-uncommitted.txt");
+
+    // 6. Run Claude Code — the prompt must instruct it to commit any uncommitted changes
+    const result = await sandbox.runCommand("bash", [
+      "-c",
+      'echo "Commit all uncommitted changes with a descriptive commit message, then exit." | claude --print --dangerously-skip-permissions',
+    ]);
+    const stdout = (await result.stdout()).trim();
+    const stderr = (await result.stderr()).trim();
+
+    console.log("Claude stdout:", stdout);
+    console.log("Claude stderr:", stderr);
+
+    // 7. Check git status — should be clean if the hook worked
+    const afterStatus = await sandbox.runCommand("git", [
+      "status",
+      "--porcelain",
+    ]);
+    const afterOutput = (await afterStatus.stdout()).trim();
+
+    expect(afterOutput).toBe("");
+  });
+});

e2e/vitest.e2e.config.ts

@@ -11,7 +11,10 @@ if (existsSync(envPath)) {
     const idx = trimmed.indexOf("=");
     if (idx === -1) continue;
     const key = trimmed.slice(0, idx).trim();
-    const value = trimmed.slice(idx + 1).trim();
+    let value = trimmed.slice(idx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
     if (!(key in process.env)) process.env[key] = value;
   }
 }

env.test.ts

@@ -59,7 +59,7 @@ describe("env", () => {
 
   it("throws on missing required field", async () => {
     const partial = { ...VALID_ENV };
-    delete (partial as any).ANTHROPIC_API_KEY;
+    delete (partial as any).GITHUB_TOKEN;
     Object.assign(process.env, partial);
     await expect(async () => {
       await import("./env.js");

env.ts

@@ -27,7 +27,8 @@ export const env = createEnv({
     CHAT_SDK_BOT_NAME: z.string().default("blazebot"),
 
     // Agent
-    ANTHROPIC_API_KEY: z.string().min(1),
+    ANTHROPIC_API_KEY: z.string().min(1).optional(),
+    CLAUDE_CODE_OAUTH_TOKEN: z.string().min(1).optional(),
     CLAUDE_MODEL: z.string().default("claude-opus-4-6"),
     COMMIT_AUTHOR: z.string().default("ai-workflow-blazity"),
     COMMIT_EMAIL: z.string().default("ai-workflow@blazity.com"),

src/adapters/vcs/github.ts

@@ -1,4 +1,5 @@
 import { Octokit } from "@octokit/rest";
+import { FatalError } from "workflow";
 import type { VCSAdapter, PullRequest, PRComment } from "./types.js";
 
 export interface GitHubConfig {
@@ -70,17 +71,30 @@ export class GitHubAdapter implements VCSAdapter {
     title: string,
     body: string,
   ): Promise<PullRequest> {
-    const { data } = await this.octokit.pulls.create({
-      ...this.ownerRepo,
-      head: branch,
-      base: this.config.baseBranch,
-      title,
-      body,
-    });
-    return { id: data.number, url: data.html_url, branch };
+    try {
+      const { data } = await this.octokit.pulls.create({
+        ...this.ownerRepo,
+        head: branch,
+        base: this.config.baseBranch,
+        title,
+        body,
+      });
+      return { id: data.number, url: data.html_url, branch };
+    } catch (err: any) {
+      // 422 (validation: PR already exists, branch missing) and 404 are non-retryable.
+      // 401/403 (token expired, rate limit) are transient and should be retried.
+      if (err.status === 422 || err.status === 404) {
+        throw new FatalError(err.message);
+      }
+      throw err;
+    }
   }
 
-  async push(branch: string, files: Array<{ path: string; content: string }>): Promise<void> {
+  async push(
+    branch: string,
+    files: Array<{ path: string; content: string }>,
+    options?: { mergeParentSha?: string },
+  ): Promise<void> {
     const { data: refData } = await this.octokit.git.getRef({
       ...this.ownerRepo,
       ref: `heads/${branch}`,
@@ -114,11 +128,20 @@ export class GitHubAdapter implements VCSAdapter {
       tree: treeItems,
     });
 
+    // When mergeParentSha is set, create a merge commit with two parents.
+    // This tells GitHub the branch histories have been reconciled, clearing
+    // the "has conflicts" status on the PR.
+    const parents = options?.mergeParentSha
+      ? [latestCommitSha, options.mergeParentSha]
+      : [latestCommitSha];
+
     const { data: newCommit } = await this.octokit.git.createCommit({
       ...this.ownerRepo,
-      message: "feat: agent implementation",
+      message: options?.mergeParentSha
+        ? "merge: resolve conflicts with base branch"
+        : "feat: agent implementation",
       tree: tree.sha,
-      parents: [latestCommitSha],
+      parents,
     });
 
     await this.octokit.git.updateRef({
@@ -128,6 +151,14 @@ export class GitHubAdapter implements VCSAdapter {
     });
   }
 
+  async getBranchSha(branch: string): Promise<string> {
+    const { data } = await this.octokit.git.getRef({
+      ...this.ownerRepo,
+      ref: `heads/${branch}`,
+    });
+    return data.object.sha;
+  }
+
   async getPRComments(prId: number): Promise<PRComment[]> {
     const { data: reviewComments } =
       await this.octokit.pulls.listReviewComments({

src/adapters/vcs/types.ts

@@ -13,8 +13,13 @@ export interface PRComment {
 export interface VCSAdapter {
   createBranch(name: string, base: string): Promise<void>;
   createPR(branch: string, title: string, body: string): Promise<PullRequest>;
-  push(branch: string, files: Array<{ path: string; content: string }>): Promise<void>;
+  push(
+    branch: string,
+    files: Array<{ path: string; content: string }>,
+    options?: { mergeParentSha?: string },
+  ): Promise<void>;
   getPRComments(prId: number): Promise<PRComment[]>;
   getPRConflictStatus(prId: number): Promise<boolean>;
   findPR(branch: string): Promise<PullRequest | null>;
+  getBranchSha(branch: string): Promise<string>;
 }

src/lib/dispatch.test.ts

@@ -65,6 +65,7 @@ function makeAdapters(
       getPRComments: vi.fn(),
       getPRConflictStatus: vi.fn(),
       findPR: overrides.findPR ?? vi.fn().mockResolvedValue(null),
+      getBranchSha: vi.fn().mockResolvedValue("abc123"),
     },
     messaging: {
       notify: vi.fn(),

src/lib/prompts.ts

@@ -146,7 +146,7 @@ You have access to **superpowers skills** installed globally. Use them to improv
 
 0. **Restore session memory** — Check if \`blazebot/memory/[TASK_ID].md\` exists (where \`[TASK_ID]\` is the Ticket ID from above, e.g. \`AIW-123\`). If it exists, read it immediately. Use the progress, decisions, and file list to understand prior implementation context and any previous fix attempts.
 1. Read the review feedback carefully.
-2. If merge conflicts exist, merge the target branch and resolve conflicts first.
+2. If merge conflicts exist, the base branch has already been merged into your branch — the repo is in a \`MERGING\` state with conflict markers (\`<<<<<<<\`, \`=======\`, \`>>>>>>>\`) in the affected files. Do NOT run \`git merge\` again. Instead: edit each conflicted file to resolve the markers, then \`git add\` the resolved files, then run \`git merge --continue\` to complete the merge.
 3. Address each review comment — implement the requested changes.
 4. Run all tests to ensure nothing is broken.
 5. Self-review your changes.