PBI-9 + PBI-47: worktree foundation, product-worktrees, P0 fixes, PAUSED flow

Adds two interlocking PBIs:

PBI-9 — Worktree foundation + persistent product-worktrees for idea-jobs
  - src/git/worktree-paths.ts: centralised root + skip-set + lock-path helpers
  - src/git/file-lock.ts: proper-lockfile wrapper, deadlock-safe ordered acquire
  - src/git/product-worktree.ts: detached-HEAD worktree per product, .scratch/
    excluded via git rev-parse --git-path (handles linked .git file)
  - src/git/job-locks.ts: setupProductWorktrees + releaseLocksOnTerminal
  - wait-for-job.ts: idea-branch wires product-worktrees for IDEA_GRILL/MAKE_PLAN
  - update-job-status.ts + pbi-cascade.ts + stale-reset: release on all four
    server-side terminal transitions (DONE/FAILED/CANCELLED/stale)
  - cleanup-my-worktrees: skip _products/ + *.lock
  - README: worktrees section with single-host invariant + advisory-lock path

PBI-47 — Sprint-flow P0 corrections + PAUSED flow with rich pause_context
  - prisma schema: ClaudeJob.{base_sha,head_sha} + SprintRun.pause_context
  - tryClaimJob captures base_sha; prepareDoneUpdate captures head_sha
  - verify-task-against-plan diffs vs base_sha (no more origin/main fallback);
    rejects with MISSING_BASE_SHA when null — fixes per-task verify-scope P0
  - pr.ts: createPullRequest enableAutoMerge default false; new
    enableAutoMergeOnPr with --match-head-commit guard + 5-category typed
    EnableAutoMergeResult — fixes STORY auto-merge timing P0
  - src/flow/{effects,worktree-lease,pr-flow,sprint-run}.ts: pure transition
    modules + idempotent declarative effects executor
  - update-job-status: STORY auto-merge fires only on the last task of the
    story (story.status === DONE), with head_sha as merge guard; MERGE_CONFLICT
    routes to sprint-run flow which produces CREATE_CLAUDE_QUESTION +
    SET_SPRINT_RUN_STATUS effects with rich pause_context

Tests: 31 test files, 242 passing. Pure-transition tests cover STORY 3-tasks
auto-merge timing, SPRINT draft→ready, MERGE_CONFLICT pause/resume, file-lock
deadlock prevention, worktree-lease lifecycle, delete-only verify (ALIGNED),
per-job verify scope (base_sha isolation), 5-category auto-merge errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

__tests__/cleanup-my-worktrees.test.ts

@@ -73,6 +73,17 @@ describe('listWorktreeJobIds', () => {
     mockReaddir.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }))
     expect(await listWorktreeJobIds(WORKTREE_PARENT)).toEqual([])
   })
+
+  it('skips _products/ system dir and *.lock files (PBI-9)', async () => {
+    mockReaddir.mockResolvedValue([
+      makeDirent('job-aaa'),
+      makeDirent('_products'),
+      makeDirent('product-abc.lock'),
+      makeDirent('job-bbb'),
+    ])
+    const ids = await listWorktreeJobIds(WORKTREE_PARENT)
+    expect(ids).toEqual(['job-aaa', 'job-bbb'])
+  })
 })
 
 describe('cleanupWorktrees', () => {

__tests__/flow/effects.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest'
+import { executeEffects } from '../../src/flow/effects.js'
+
+describe('effects executor', () => {
+  it('RELEASE_WORKTREE_LOCKS for unknown jobId is a no-op (no throw)', async () => {
+    const out = await executeEffects([{ type: 'RELEASE_WORKTREE_LOCKS', jobId: 'no-such-job' }])
+    expect(out).toEqual([])
+  })
+
+  it('multiple effects execute in order; failure in one is logged but does not abort', async () => {
+    const out = await executeEffects([
+      { type: 'RELEASE_WORKTREE_LOCKS', jobId: 'a' },
+      { type: 'RELEASE_WORKTREE_LOCKS', jobId: 'b' },
+    ])
+    expect(out).toEqual([])
+  })
+
+  it('empty effects array returns empty outcomes', async () => {
+    const out = await executeEffects([])
+    expect(out).toEqual([])
+  })
+})

__tests__/flow/pr-flow.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import { transition, type PrFlowState } from '../../src/flow/pr-flow.js'
+
+describe('pr-flow STORY-mode 3-tasks scenario', () => {
+  it('opens PR early; auto-merge only fires on the last task', () => {
+    let state: PrFlowState = { kind: 'none', strategy: 'STORY' }
+    const allEffects: Array<Record<string, unknown>> = []
+
+    // Task 1 DONE → PR_CREATED
+    let r = transition(state, { type: 'PR_CREATED', prUrl: 'https://github.com/o/r/pull/1' })
+    state = r.nextState
+    allEffects.push(...r.effects)
+    expect(state.kind).toBe('pr_opened')
+    expect(allEffects.filter((e) => e.type === 'ENABLE_AUTO_MERGE')).toHaveLength(0)
+
+    // Task 2 DONE → no STORY_COMPLETED yet, no transition emitted
+    r = transition(state, { type: 'TASK_DONE', taskId: 't2', headSha: 'abc123' })
+    state = r.nextState
+    allEffects.push(...r.effects)
+    expect(state.kind).toBe('pr_opened')
+    expect(allEffects.filter((e) => e.type === 'ENABLE_AUTO_MERGE')).toHaveLength(0)
+
+    // Task 3 DONE = STORY_COMPLETED → ENABLE_AUTO_MERGE with head guard
+    r = transition(state, { type: 'STORY_COMPLETED', storyId: 's1', headSha: 'def456' })
+    state = r.nextState
+    allEffects.push(...r.effects)
+    expect(state.kind).toBe('waiting_for_checks')
+    const enableEffects = allEffects.filter((e) => e.type === 'ENABLE_AUTO_MERGE')
+    expect(enableEffects).toHaveLength(1)
+    expect(enableEffects[0]).toMatchObject({ expectedHeadSha: 'def456' })
+
+    // CI green + merge OK
+    r = transition(state, { type: 'MERGE_RESULT' })
+    state = r.nextState
+    expect(state.kind).toBe('auto_merge_enabled')
+  })
+
+  it('CHECKS_FAILED → checks_failed (no pause)', () => {
+    const state: PrFlowState = {
+      kind: 'waiting_for_checks',
+      strategy: 'STORY',
+      prUrl: 'x',
+      headSha: 'y',
+    }
+    const r = transition(state, { type: 'MERGE_RESULT', reason: 'CHECKS_FAILED' })
+    expect(r.nextState.kind).toBe('checks_failed')
+  })
+
+  it('MERGE_CONFLICT → merge_conflict_paused', () => {
+    const state: PrFlowState = {
+      kind: 'waiting_for_checks',
+      strategy: 'STORY',
+      prUrl: 'x',
+      headSha: 'y',
+    }
+    const r = transition(state, { type: 'MERGE_RESULT', reason: 'MERGE_CONFLICT' })
+    expect(r.nextState.kind).toBe('merge_conflict_paused')
+  })
+})
+
+describe('pr-flow SPRINT-mode', () => {
+  it('draft stays draft until SPRINT_COMPLETED → MARK_PR_READY effect', () => {
+    let state: PrFlowState = { kind: 'none', strategy: 'SPRINT' }
+    let r = transition(state, { type: 'PR_CREATED', prUrl: 'x' })
+    expect(r.nextState.kind).toBe('draft_opened')
+    expect(r.effects).toHaveLength(0)
+
+    state = r.nextState
+    r = transition(state, { type: 'TASK_DONE', taskId: 't1', headSha: 'a' })
+    expect(r.nextState.kind).toBe('draft_opened')
+    expect(r.effects).toHaveLength(0)
+
+    state = r.nextState
+    r = transition(state, { type: 'SPRINT_COMPLETED', sprintRunId: 'sr1' })
+    expect(r.nextState.kind).toBe('ready_for_review')
+    expect(r.effects.filter((e) => e.type === 'MARK_PR_READY')).toHaveLength(1)
+  })
+})

__tests__/flow/sprint-run.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest'
+import { transition, type SprintRunState } from '../../src/flow/sprint-run.js'
+
+describe('sprint-run pure transitions', () => {
+  it('queued + CLAIM_FIRST_JOB → running with SET_SPRINT_RUN_STATUS effect', () => {
+    const state: SprintRunState = { kind: 'queued', sprintRunId: 'sr1' }
+    const r = transition(state, { type: 'CLAIM_FIRST_JOB' })
+    expect(r.nextState.kind).toBe('running')
+    expect(r.effects).toEqual([
+      { type: 'SET_SPRINT_RUN_STATUS', sprintRunId: 'sr1', status: 'RUNNING' },
+    ])
+  })
+
+  it('running + MERGE_CONFLICT → paused_merge_conflict + 2 effects in order', () => {
+    const state: SprintRunState = { kind: 'running', sprintRunId: 'sr1' }
+    const r = transition(state, {
+      type: 'MERGE_CONFLICT',
+      prUrl: 'https://github.com/o/r/pull/1',
+      prHeadSha: 'abc123',
+      conflictFiles: ['a.ts', 'b.ts'],
+      resumeInstructions: 'Resolve and push',
+    })
+    expect(r.nextState.kind).toBe('paused_merge_conflict')
+    expect(r.effects).toHaveLength(2)
+    expect(r.effects[0].type).toBe('CREATE_CLAUDE_QUESTION')
+    expect(r.effects[1].type).toBe('SET_SPRINT_RUN_STATUS')
+    if (r.effects[1].type === 'SET_SPRINT_RUN_STATUS') {
+      expect(r.effects[1].status).toBe('PAUSED')
+      expect(r.effects[1].pauseContextDraft).toMatchObject({
+        pause_reason: 'MERGE_CONFLICT',
+        pr_url: 'https://github.com/o/r/pull/1',
+        pr_head_sha: 'abc123',
+        conflict_files: ['a.ts', 'b.ts'],
+      })
+    }
+  })
+
+  it('paused + USER_RESUMED → running + CLOSE_CLAUDE_QUESTION + clear pause_context', () => {
+    const state: SprintRunState = {
+      kind: 'paused_merge_conflict',
+      sprintRunId: 'sr1',
+      pauseContext: {
+        pause_reason: 'MERGE_CONFLICT',
+        pr_url: 'x',
+        pr_head_sha: 'y',
+        conflict_files: [],
+        claude_question_id: 'q1',
+        resume_instructions: 'r',
+        paused_at: new Date().toISOString(),
+      },
+    }
+    const r = transition(state, { type: 'USER_RESUMED' })
+    expect(r.nextState.kind).toBe('running')
+    expect(r.effects[0]).toEqual({ type: 'CLOSE_CLAUDE_QUESTION', questionId: 'q1' })
+    expect(r.effects[1]).toMatchObject({
+      type: 'SET_SPRINT_RUN_STATUS',
+      status: 'RUNNING',
+      clearPauseContext: true,
+    })
+  })
+
+  it('running + TASK_FAILED → failed (no PAUSE)', () => {
+    const state: SprintRunState = { kind: 'running', sprintRunId: 'sr1' }
+    const r = transition(state, { type: 'TASK_FAILED', taskId: 't1', error: 'CI red' })
+    expect(r.nextState.kind).toBe('failed')
+    expect(r.effects[0]).toMatchObject({ status: 'FAILED' })
+  })
+
+  it('running + ALL_DONE → done + SET_SPRINT_RUN_STATUS DONE', () => {
+    const state: SprintRunState = { kind: 'running', sprintRunId: 'sr1' }
+    const r = transition(state, { type: 'ALL_DONE' })
+    expect(r.nextState.kind).toBe('done')
+    expect(r.effects[0]).toMatchObject({ status: 'DONE' })
+  })
+
+  it('forbidden transition (running + CLAIM_FIRST_JOB) keeps state and emits no effects', () => {
+    const state: SprintRunState = { kind: 'running', sprintRunId: 'sr1' }
+    const r = transition(state, { type: 'CLAIM_FIRST_JOB' })
+    expect(r.nextState).toEqual(state)
+    expect(r.effects).toEqual([])
+  })
+})

__tests__/flow/worktree-lease.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest'
+import { transition, type WorktreeLeaseState } from '../../src/flow/worktree-lease.js'
+
+describe('worktree-lease pure transitions', () => {
+  it('idle + JOB_CLAIMED → acquiring_lock, no effects', () => {
+    const r = transition({ kind: 'idle' }, { type: 'JOB_CLAIMED', jobId: 'j1', productIds: ['p1'] })
+    expect(r.nextState.kind).toBe('acquiring_lock')
+    expect(r.effects).toEqual([])
+  })
+
+  it('acquiring_lock + LOCK_ACQUIRED → creating_or_reusing', () => {
+    const state: WorktreeLeaseState = {
+      kind: 'acquiring_lock',
+      jobId: 'j1',
+      productIds: ['p1'],
+    }
+    const r = transition(state, { type: 'LOCK_ACQUIRED' })
+    expect(r.nextState.kind).toBe('creating_or_reusing')
+    expect(r.effects).toEqual([])
+  })
+
+  it('acquiring_lock + LOCK_TIMEOUT → lock_timeout', () => {
+    const state: WorktreeLeaseState = {
+      kind: 'acquiring_lock',
+      jobId: 'j1',
+      productIds: ['p1'],
+    }
+    const r = transition(state, { type: 'LOCK_TIMEOUT' })
+    expect(r.nextState.kind).toBe('lock_timeout')
+  })
+
+  it('creating_or_reusing + WORKTREE_READY → syncing', () => {
+    const r = transition(
+      { kind: 'creating_or_reusing', jobId: 'j1', productIds: ['p1'] },
+      { type: 'WORKTREE_READY' },
+    )
+    expect(r.nextState.kind).toBe('syncing')
+  })
+
+  it('syncing + SYNC_DONE → ready (no release effect yet)', () => {
+    const r = transition(
+      { kind: 'syncing', jobId: 'j1', productIds: ['p1'] },
+      { type: 'SYNC_DONE' },
+    )
+    expect(r.nextState.kind).toBe('ready')
+    expect(r.effects).toEqual([])
+  })
+
+  it('syncing + SYNC_FAILED → sync_failed + RELEASE_WORKTREE_LOCKS effect', () => {
+    const r = transition(
+      { kind: 'syncing', jobId: 'j1', productIds: ['p1'] },
+      { type: 'SYNC_FAILED', error: 'boom' },
+    )
+    expect(r.nextState.kind).toBe('sync_failed')
+    expect(r.effects).toEqual([{ type: 'RELEASE_WORKTREE_LOCKS', jobId: 'j1' }])
+  })
+
+  it('ready + JOB_TERMINAL → releasing + RELEASE_WORKTREE_LOCKS effect', () => {
+    const r = transition(
+      { kind: 'ready', jobId: 'j1', productIds: ['p1'] },
+      { type: 'JOB_TERMINAL', jobId: 'j1' },
+    )
+    expect(r.nextState.kind).toBe('releasing')
+    expect(r.effects).toEqual([{ type: 'RELEASE_WORKTREE_LOCKS', jobId: 'j1' }])
+  })
+
+  it('ready + STALE_RESET → stale_released + RELEASE_WORKTREE_LOCKS effect', () => {
+    const r = transition(
+      { kind: 'ready', jobId: 'j1', productIds: ['p1'] },
+      { type: 'STALE_RESET', jobId: 'j1' },
+    )
+    expect(r.nextState.kind).toBe('stale_released')
+    expect(r.effects).toEqual([{ type: 'RELEASE_WORKTREE_LOCKS', jobId: 'j1' }])
+  })
+
+  it('forbidden transition (idle + LOCK_ACQUIRED) keeps state, no effects', () => {
+    const state: WorktreeLeaseState = { kind: 'idle' }
+    const r = transition(state, { type: 'LOCK_ACQUIRED' })
+    expect(r.nextState).toEqual(state)
+    expect(r.effects).toEqual([])
+  })
+})

__tests__/git/file-lock.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { acquireFileLock, acquireFileLocksOrdered } from '../../src/git/file-lock.js'
+
+describe('file-lock', () => {
+  let tmpDir: string
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'file-lock-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('acquires and releases a lock; lockfile is gone after release', async () => {
+    const lockPath = path.join(tmpDir, 'a.lock')
+    const release = await acquireFileLock(lockPath)
+    // proper-lockfile creates a directory at <lockPath>.lock for the actual lock
+    const stat = await fs.stat(`${lockPath}.lock`).catch(() => null)
+    expect(stat).not.toBeNull()
+    await release()
+    // After release, the .lock dir should be gone
+    const after = await fs.stat(`${lockPath}.lock`).catch(() => null)
+    expect(after).toBeNull()
+  })
+
+  it('release is idempotent (second call is no-op)', async () => {
+    const lockPath = path.join(tmpDir, 'b.lock')
+    const release = await acquireFileLock(lockPath)
+    await release()
+    await expect(release()).resolves.toBeUndefined()
+  })
+
+  it('second acquire blocks until first release', async () => {
+    const lockPath = path.join(tmpDir, 'c.lock')
+    const release1 = await acquireFileLock(lockPath)
+
+    let secondAcquired = false
+    const second = acquireFileLock(lockPath).then((r) => {
+      secondAcquired = true
+      return r
+    })
+
+    // Give the second acquire a moment to attempt
+    await new Promise((r) => setTimeout(r, 200))
+    expect(secondAcquired).toBe(false)
+
+    await release1()
+    const release2 = await second
+    expect(secondAcquired).toBe(true)
+    await release2()
+  }, 10_000)
+
+  it('acquireFileLocksOrdered sorts paths alphabetically (deadlock-free for crossed sets)', async () => {
+    const a = path.join(tmpDir, 'A.lock')
+    const b = path.join(tmpDir, 'B.lock')
+
+    // Two concurrent multi-locks with crossed orders both sort to [A, B]
+    const r1Promise = acquireFileLocksOrdered([b, a])
+
+    // First should grab both since paths sort the same
+    const r1 = await r1Promise
+
+    let secondAcquired = false
+    const r2Promise = acquireFileLocksOrdered([a, b]).then((r) => {
+      secondAcquired = true
+      return r
+    })
+
+    await new Promise((r) => setTimeout(r, 200))
+    expect(secondAcquired).toBe(false)
+
+    await r1()
+    const r2 = await r2Promise
+    expect(secondAcquired).toBe(true)
+    await r2()
+  }, 15_000)
+
+  it('partial failure releases held locks', async () => {
+    // Force the second acquire to fail by writing a regular file at the lockfile
+    // location proper-lockfile wants to create as a directory.
+    const a = path.join(tmpDir, 'A.lock')
+    const bPath = path.join(tmpDir, 'B.lock')
+    // Create a regular file at `${bPath}.lock` so proper-lockfile's mkdir fails with EEXIST
+    await fs.writeFile(`${bPath}.lock`, 'blocked')
+
+    await expect(acquireFileLocksOrdered([a, bPath])).rejects.toThrow()
+
+    // After failure, A's lock should be released — re-acquire immediately
+    const r = await acquireFileLock(a)
+    await r()
+  }, 90_000)
+})

__tests__/git/job-locks.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import {
+  registerJobLockReleases,
+  releaseLocksOnTerminal,
+  setupProductWorktrees,
+  _resetJobReleasesForTest,
+} from '../../src/git/job-locks.js'
+
+const exec = promisify(execFile)
+
+describe('job-locks: registerJobLockReleases + releaseLocksOnTerminal', () => {
+  beforeEach(() => _resetJobReleasesForTest())
+
+  it('releaseLocksOnTerminal for unknown job is a no-op', async () => {
+    await expect(releaseLocksOnTerminal('nonexistent')).resolves.toBeUndefined()
+  })
+
+  it('runs registered releases and clears the entry', async () => {
+    const release = vi.fn().mockResolvedValue(undefined)
+    registerJobLockReleases('job-1', [release])
+    await releaseLocksOnTerminal('job-1')
+    expect(release).toHaveBeenCalledTimes(1)
+    // Second call → no-op (cleared)
+    await releaseLocksOnTerminal('job-1')
+    expect(release).toHaveBeenCalledTimes(1)
+  })
+
+  it('failures in one release do not abort others', async () => {
+    const r1 = vi.fn().mockRejectedValue(new Error('boom'))
+    const r2 = vi.fn().mockResolvedValue(undefined)
+    registerJobLockReleases('job-2', [r1, r2])
+    await expect(releaseLocksOnTerminal('job-2')).resolves.toBeUndefined()
+    expect(r1).toHaveBeenCalled()
+    expect(r2).toHaveBeenCalled()
+  })
+
+  it('append-mode: multiple registers accumulate', async () => {
+    const r1 = vi.fn().mockResolvedValue(undefined)
+    const r2 = vi.fn().mockResolvedValue(undefined)
+    registerJobLockReleases('job-3', [r1])
+    registerJobLockReleases('job-3', [r2])
+    await releaseLocksOnTerminal('job-3')
+    expect(r1).toHaveBeenCalledTimes(1)
+    expect(r2).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('job-locks: setupProductWorktrees', () => {
+  let tmpRoot: string
+  let originalEnv: string | undefined
+  let bareRepo: string
+  let originRepo: string
+
+  beforeEach(async () => {
+    _resetJobReleasesForTest()
+    tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'job-locks-'))
+    originalEnv = process.env.SCRUM4ME_AGENT_WORKTREE_DIR
+    process.env.SCRUM4ME_AGENT_WORKTREE_DIR = path.join(tmpRoot, 'agent-worktrees')
+
+    // Set up a bare repo as origin and a clone with origin/main
+    bareRepo = path.join(tmpRoot, 'origin.git')
+    await exec('git', ['init', '--bare', '-b', 'main', bareRepo])
+
+    originRepo = path.join(tmpRoot, 'work')
+    await exec('git', ['init', '-b', 'main', originRepo])
+    await exec('git', ['config', 'user.email', 't@t.local'], { cwd: originRepo })
+    await exec('git', ['config', 'user.name', 'Test'], { cwd: originRepo })
+    await exec('git', ['remote', 'add', 'origin', bareRepo], { cwd: originRepo })
+    await fs.writeFile(path.join(originRepo, 'README.md'), '# init\n')
+    await exec('git', ['add', '-A'], { cwd: originRepo })
+    await exec('git', ['commit', '-m', 'init'], { cwd: originRepo })
+    await exec('git', ['push', '-u', 'origin', 'main'], { cwd: originRepo })
+  })
+
+  afterEach(async () => {
+    if (originalEnv) process.env.SCRUM4ME_AGENT_WORKTREE_DIR = originalEnv
+    else delete process.env.SCRUM4ME_AGENT_WORKTREE_DIR
+    await fs.rm(tmpRoot, { recursive: true, force: true })
+  })
+
+  it('returns empty when productIds is empty', async () => {
+    const result = await setupProductWorktrees('j1', [], async () => null)
+    expect(result).toEqual([])
+  })
+
+  it('creates a product-worktree, registers a lock-release, and releases it', async () => {
+    const result = await setupProductWorktrees('j2', ['prod-a'], async () => originRepo)
+    expect(result).toHaveLength(1)
+    expect(result[0].productId).toBe('prod-a')
+    expect(result[0].worktreePath).toContain('_products/prod-a')
+
+    // Worktree dir exists with detached HEAD on origin/main
+    const stat = await fs.stat(result[0].worktreePath)
+    expect(stat.isDirectory()).toBe(true)
+
+    // Lockfile is held during the job (proper-lockfile creates a .lock dir)
+    const lockDir = path.join(
+      process.env.SCRUM4ME_AGENT_WORKTREE_DIR!,
+      '_products',
+      'prod-a.lock.lock',
+    )
+    const lockStat = await fs.stat(lockDir).catch(() => null)
+    expect(lockStat).not.toBeNull()
+
+    await releaseLocksOnTerminal('j2')
+    const lockAfter = await fs.stat(lockDir).catch(() => null)
+    expect(lockAfter).toBeNull()
+  })
+
+  it('skips products where resolveRepoRoot returns null', async () => {
+    const result = await setupProductWorktrees('j3', ['no-repo'], async () => null)
+    expect(result).toEqual([])
+    // Lock was still acquired and registered — release cleans up
+    await releaseLocksOnTerminal('j3')
+  })
+})

__tests__/git/pr-enable-auto-merge.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// Mock node:child_process before importing the module under test
+vi.mock('node:child_process', () => ({
+  execFile: vi.fn(),
+}))
+
+import { execFile } from 'node:child_process'
+import { enableAutoMergeOnPr } from '../../src/git/pr.js'
+
+const mockExecFile = vi.mocked(execFile) as unknown as ReturnType<typeof vi.fn>
+
+function mockGhFailure(stderr: string) {
+  mockExecFile.mockImplementation(((_cmd: string, _args: string[], _opts: unknown, cb: any) => {
+    cb(Object.assign(new Error('gh exit'), { stderr }))
+  }) as never)
+}
+
+function mockGhSuccess() {
+  mockExecFile.mockImplementation(((_cmd: string, _args: string[], _opts: unknown, cb: any) => {
+    cb(null, { stdout: '', stderr: '' })
+  }) as never)
+}
+
+describe('enableAutoMergeOnPr — typed errors (PBI-47 C2 layer 1)', () => {
+  beforeEach(() => {
+    mockExecFile.mockReset()
+  })
+
+  it('returns ok:true on green merge', async () => {
+    mockGhSuccess()
+    const result = await enableAutoMergeOnPr({ prUrl: 'x', expectedHeadSha: 'sha1' })
+    expect(result.ok).toBe(true)
+  })
+
+  it('classifies GH_AUTH_ERROR for 401/403 / permission strings', async () => {
+    mockGhFailure('gh: HTTP 403: permission denied')
+    const result = await enableAutoMergeOnPr({ prUrl: 'x', expectedHeadSha: 'sha1' })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('GH_AUTH_ERROR')
+  })
+
+  it('classifies AUTO_MERGE_NOT_ALLOWED for repo-setting refusal', async () => {
+    mockGhFailure('auto-merge is not allowed for this repository')
+    const result = await enableAutoMergeOnPr({ prUrl: 'x', expectedHeadSha: 'sha1' })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('AUTO_MERGE_NOT_ALLOWED')
+  })
+
+  it('classifies MERGE_CONFLICT for dirty merge state', async () => {
+    mockGhFailure('pull request is not in a mergeable state (dirty)')
+    const result = await enableAutoMergeOnPr({ prUrl: 'x', expectedHeadSha: 'sha1' })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('MERGE_CONFLICT')
+  })
+
+  it('classifies UNKNOWN for unrecognised stderr', async () => {
+    mockGhFailure('unexpected gh error')
+    const result = await enableAutoMergeOnPr({ prUrl: 'x', expectedHeadSha: 'sha1' })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('UNKNOWN')
+  })
+
+  it('passes --match-head-commit when expectedHeadSha provided', async () => {
+    mockGhSuccess()
+    await enableAutoMergeOnPr({ prUrl: 'pr-url', expectedHeadSha: 'abc123' })
+    const callArgs = mockExecFile.mock.calls[0]
+    expect(callArgs[0]).toBe('gh')
+    const args = callArgs[1] as string[]
+    expect(args).toContain('--match-head-commit')
+    expect(args).toContain('abc123')
+    expect(args).toContain('--auto')
+    expect(args).toContain('--squash')
+  })
+})

__tests__/verify/classify-delete.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest'
+import { classifyDiffAgainstPlan } from '../../src/verify/classify.js'
+
+describe('classify — delete-only commits (PBI-47 C5)', () => {
+  it('returns ALIGNED when the deleted path is in the plan', () => {
+    const diff = `diff --git a/app/todos/page.tsx b/app/todos/page.tsx
+deleted file mode 100644
+index 1234567..0000000
+--- a/app/todos/page.tsx
++++ /dev/null
+@@ -1,3 +0,0 @@
+-export default function TodosPage() {
+-  return null
+-}`
+
+    const plan = '- Verwijder `app/todos/page.tsx`\n- Verwijder gerelateerde imports'
+
+    const result = classifyDiffAgainstPlan({ diff, plan })
+    expect(result.result).toBe('ALIGNED')
+  })
+
+  it('returns ALIGNED for multi-file delete-only when both paths in plan', () => {
+    const diff = `diff --git a/app/todos/page.tsx b/app/todos/page.tsx
+deleted file mode 100644
+--- a/app/todos/page.tsx
++++ /dev/null
+@@ -1,2 +0,0 @@
+-line 1
+-line 2
+diff --git a/components/todo-list.tsx b/components/todo-list.tsx
+deleted file mode 100644
+--- a/components/todo-list.tsx
++++ /dev/null
+@@ -1,1 +0,0 @@
+-line`
+
+    const plan = '- `app/todos/page.tsx`\n- `components/todo-list.tsx`'
+    const result = classifyDiffAgainstPlan({ diff, plan })
+    expect(result.result).toBe('ALIGNED')
+  })
+
+  it('returns PARTIAL when only some plan deletes appear in the diff', () => {
+    const diff = `diff --git a/a.ts b/a.ts
+deleted file mode 100644
+--- a/a.ts
++++ /dev/null
+@@ -1,1 +0,0 @@
+-x`
+
+    const plan = '- `a.ts`\n- `b.ts`' // b.ts missing
+    const result = classifyDiffAgainstPlan({ diff, plan })
+    expect(result.result).toBe('PARTIAL')
+  })
+
+  it('returns EMPTY for a no-op diff', () => {
+    const result = classifyDiffAgainstPlan({ diff: '', plan: 'irrelevant' })
+    expect(result.result).toBe('EMPTY')
+  })
+})

__tests__/verify/verify-scope.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { getDiffInWorktree } from '../../src/tools/verify-task-against-plan.js'
+
+const exec = promisify(execFile)
+
+describe('verify scope per-job (PBI-47 P0)', () => {
+  let tmpRepo: string
+  let baseSha: string
+  let task1Sha: string
+
+  beforeAll(async () => {
+    tmpRepo = await fs.mkdtemp(path.join(os.tmpdir(), 'verify-scope-'))
+    await exec('git', ['init', '-b', 'main'], { cwd: tmpRepo })
+    await exec('git', ['config', 'user.email', 't@t.local'], { cwd: tmpRepo })
+    await exec('git', ['config', 'user.name', 'Test'], { cwd: tmpRepo })
+    await fs.writeFile(path.join(tmpRepo, 'README.md'), '# init\n')
+    await exec('git', ['add', '-A'], { cwd: tmpRepo })
+    await exec('git', ['commit', '-m', 'init'], { cwd: tmpRepo })
+    const baseRev = await exec('git', ['rev-parse', 'HEAD'], { cwd: tmpRepo })
+    baseSha = baseRev.stdout.trim()
+
+    // Simulate task 1: add a.ts
+    await fs.writeFile(path.join(tmpRepo, 'a.ts'), 'task 1\n')
+    await exec('git', ['add', '-A'], { cwd: tmpRepo })
+    await exec('git', ['commit', '-m', 'task 1'], { cwd: tmpRepo })
+    const t1Rev = await exec('git', ['rev-parse', 'HEAD'], { cwd: tmpRepo })
+    task1Sha = t1Rev.stdout.trim()
+
+    // Simulate task 2: add b.ts
+    await fs.writeFile(path.join(tmpRepo, 'b.ts'), 'task 2\n')
+    await exec('git', ['add', '-A'], { cwd: tmpRepo })
+    await exec('git', ['commit', '-m', 'task 2'], { cwd: tmpRepo })
+  })
+
+  afterAll(async () => {
+    await fs.rm(tmpRepo, { recursive: true, force: true })
+  })
+
+  it('diff vs base = origin/main → both task 1 and task 2 visible', async () => {
+    const diff = await getDiffInWorktree(tmpRepo, baseSha)
+    expect(diff).toContain('a.ts')
+    expect(diff).toContain('b.ts')
+  })
+
+  it('diff vs base = task1_sha → only task 2 visible', async () => {
+    const diff = await getDiffInWorktree(tmpRepo, task1Sha)
+    expect(diff).not.toContain('a.ts')
+    expect(diff).toContain('b.ts')
+  })
+})